Skip to content

Update PRESENTATION-ambient-code-reference.md #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeremyeder merged 1 commit into from
Jan 6, 2026
Merged

Update PRESENTATION-ambient-code-reference.md #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 40 additions & 52 deletions PRESENTATION-ambient-code-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,20 @@
# Ambient Code Reference Repository
# AI-assisted Development Reference Repository

## A Practical Guide for Principal Engineers Evaluating AI-Assisted Development
## A Practical Guide for Engineers Evaluating AI-Assisted Development

---

## The Problem We're Solving

Principal engineers face a difficult question: "My team wants to use Claude/AI coding assistants. How do we do this without creating chaos?"
Engineers face a difficult question: "My team wants to use Claude/AI coding assistants. How do we do this without creating chaos?"

Current approaches often fail:

- **Ad-hoc adoption**: Every engineer uses AI differently, inconsistent results
- **Heavy-handed policies**: Ban it or over-regulate, lose competitive advantage
- **Vendor lock-in fears**: What if we invest in patterns that don't transfer?

This reference repository provides battle-tested patterns you can adopt incrementally.

---

## What This Repository Is

A **documentation-only GitHub template** demonstrating AI-assisted development patterns.

**Key Design Principle**: Standalone patterns approach - adopt what you need, skip what you don't. No prescribed sequence.

**This is NOT**:

- A working application (see demo-fastapi for that)
- A vendor-specific solution
- An all-or-nothing framework

**This IS**:
This reference repository provides useful patterns you can review / adopt incrementally:

- Patterns extracted from production use
- Copy-paste ready configurations
Expand All @@ -43,11 +27,15 @@
### What Is It?

A pre-configured AI agent definition that knows how to work with your codebase safely and consistently.
The idea behind a CBA is to use an agent to eventually proxy 100% of the interaction with a codebase through this agent.

**cba = codebase system prompt**

Check failure on line 32 in PRESENTATION-ambient-code-reference.md

View workflow job for this annotation

GitHub Actions / lint-markdown

Emphasis used instead of a heading 

PRESENTATION-ambient-code-reference.md:32 MD036/no-emphasis-as-heading Emphasis used instead of a heading [Context: "cba = codebase system prompt"] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md036.md

### The Problem It Solves

Without guidance, AI assistants:

- Don't behave like a co-worker
- Make inconsistent style choices
- Don't know your testing conventions
- Miss security requirements
Expand All @@ -64,14 +52,14 @@

### CBA Workflow Example

When CBA receives an issue to fix:
When CBA receives an issue to fix (e.g. a github comment "@cba fix this":

1. Read issue description and acceptance criteria
2. Review relevant code in context files
3. Create implementation plan
4. Show plan to user for approval
5. Implement changes following project standards
6. Run linters (black, isort, ruff)
6. Run any other pre-flight checks, such as linters
7. Run tests (pytest)
8. Create commit with clear message
9. Push and create PR with detailed description
Expand All @@ -83,7 +71,7 @@

Most teams start at Level 1 and graduate to Level 2 after building trust.

### Why This Matters for Principal Engineers
### Why This Matters

- **Consistency**: Every AI-assisted change follows the same process
- **Auditability**: Clear trail of what the agent did and why
Expand Down Expand Up @@ -114,15 +102,22 @@
**security-standards.md** - Input validation, sanitization, secrets management
**testing-patterns.md** - Unit, integration, E2E test structures and conventions

Codebase owners generate these files programmatically. Things like ADRs or hand-tuned context could be used here.
What's important is that your team has collected and agrees upon the context since the idea is it will be shared.

### Loading Context On-Demand

Instead of loading everything, you load what's relevant:
Instead of loading everything, you load what's relevant.

Check failure on line 110 in PRESENTATION-ambient-code-reference.md

View workflow job for this annotation

GitHub Actions / lint-markdown

Trailing spaces 

PRESENTATION-ambient-code-reference.md:110:57 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md009.md

"Load the security-standards context and help me review this authentication PR"

"Load the architecture context and help me add a new endpoint"

### Memory System Benefits for Principal Engineers
For relation between elements, load these files into e.g. the local Anthropic Memory MCP server

"load .claude/context into my local mcp server and add this instruction to claude.md"

### Memory System Benefits

- **Token efficiency**: Only load relevant context
- **Maintainability**: Update one context file, all sessions benefit
Expand All @@ -136,8 +131,9 @@
### Issue-to-PR Overview

A pattern where well-defined GitHub issues can be automatically converted into pull requests by the CBA.
Example: https://github.com/ambient-code/agentready/pull/242

Check failure on line 134 in PRESENTATION-ambient-code-reference.md

View workflow job for this annotation

GitHub Actions / lint-markdown

Bare URL used 

PRESENTATION-ambient-code-reference.md:134:10 MD034/no-bare-urls Bare URL used [Context: "https://github.com/ambient-cod..."] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md034.md

### The Routine Fix Overhead Problem
### Routine Fix Overhead

Routine fixes (linting, formatting, simple bugs) take disproportionate time:

Expand Down Expand Up @@ -168,9 +164,9 @@
- Tests pass
```

2. Add label: `cba:auto-fix`
2. Add label: `cba:auto-fix` or tag @cba on a comment (not the initial comment - github app restriction)

3. CBA picks up the issue, creates a PR
3. CBA picks up the issue, self-review and reflection occurs, then creates a PR

4. Human reviews and merges

Expand All @@ -195,11 +191,11 @@
- Security-sensitive code
- Architecture changes

### Issue-to-PR Benefits for Principal Engineers
### Issue-to-PR Benefits

- **10x productivity** for routine tasks
- **Automation** for routine tasks helps engineers scale
- **Democratized automation**: Team members without Claude access can trigger fixes
- **Consistent quality**: Every auto-fix follows the same process
- **Consistent quality**: Every auto-fix follows the same process with self-review and reflection.
- **Audit trail**: Every change is tracked via GitHub

**Note**: Issue-to-PR is one of four GHA automation patterns. See Feature 9 for the complete set including PR Auto-Review, Dependabot Auto-Merge, and Stale Issue Management.
Expand All @@ -212,6 +208,8 @@

Reference implementations for organizing code in a way that AI assistants can reason about effectively.

See [AgentReady](https://github.com/ambient-code/agentready) for tooling to check and validate your codebase's readiness for agentic development.

### The Spaghetti Code Problem

AI assistants struggle with:
Expand All @@ -220,7 +218,7 @@
- Mixed concerns (business logic in HTTP handlers)
- Implicit dependencies (global state everywhere)

### The Four-Layer Pattern
### The Four-Layer Pattern - used in the [FastAPI]([https://github.com/jeremyeder/fastapi-demo](https://github.com/jeremyeder/demo-fastapi) example

**API Layer** (app/api/)

Expand Down Expand Up @@ -252,7 +250,7 @@
Higher layers depend on lower layers, never the reverse:
API -> Service -> Model -> Core

### Architecture Benefits for Principal Engineers
### Architecture Benefits

- **Predictable AI outputs**: When structure is clear, AI makes better decisions
- **Easier testing**: Each layer is testable in isolation
Expand All @@ -261,7 +259,7 @@

---

## Feature 5: Security Patterns (Light Touch)
## Feature 5: Security Patterns (Light Touch - not comprehensive)

### Security Patterns Overview

Expand Down Expand Up @@ -302,7 +300,7 @@
- No complex encryption for non-sensitive data
- No authentication framework in the reference (separate concern)

### Security Benefits for Principal Engineers
### Security Benefits

- **Practical security**: Focus on actual attack vectors
- **Maintainable**: Simple patterns are followed consistently
Expand Down Expand Up @@ -344,7 +342,7 @@
- Focus on critical paths
- Don't chase 100% (diminishing returns)

### Testing Benefits for Principal Engineers
### Testing Benefits

- **Fast feedback**: Unit tests run in seconds
- **Confidence**: Integration tests catch API contract issues
Expand All @@ -357,7 +355,7 @@

### Documentation CI Overview

GitHub Actions workflows that validate documentation quality automatically.
GitHub Actions workflows that validate documentation quality automatically. Not an AI specific capability - but it leverages AI now.

### Why Documentation CI?

Expand Down Expand Up @@ -386,7 +384,7 @@
- No broken internal links
- No dead external references

### Documentation CI Benefits for Principal Engineers
### Documentation CI Benefits

- **Docs stay current**: CI catches drift
- **Quality floor**: No more "works on my machine" diagrams
Expand Down Expand Up @@ -474,9 +472,9 @@
| Simple lookups | ❌ No | Overhead not worth it |
| Exploratory chat | ❌ No | Low stakes, fast iteration preferred |

**Rule of thumb**: Self-review when the output will be acted upon or when mistakes are costly.
**Note**: Self-review has a monetary cost associated with it. Use your judgement. This is a common pattern though.

### Self-Review Benefits for Principal Engineers
### Self-Review Benefits

- **Higher quality first attempts**: Users rarely say "you missed X"
- **Reduced iteration cycles**: First submission is usually accepted
Expand Down Expand Up @@ -551,7 +549,7 @@
| Dependabot Auto-Merge | Patch versions only, CI must pass |
| Stale Issues | Exempt labels, 7-day warning period |

### GHA Workflow Benefits for Principal Engineers
### GHA Workflow Benefits

- **Reduced toil**: Routine work happens automatically
- **Consistent process**: Every PR gets the same review treatment
Expand Down Expand Up @@ -643,7 +641,7 @@
cat docs/quickstart.md

# Copy to your project
cp -r .claude /path/to/your/project/
#commented out on purpose cp -r .claude /path/to/your/project/
cd /path/to/your/project/.claude/agents/
# Edit codebase-agent.md for your stack
```
Expand All @@ -670,20 +668,10 @@

**Start small, adopt incrementally, measure results.**

The goal isn't to replace engineers - it's to amplify them.

---

## Resources

- Reference Repository: <https://github.com/jeremyeder/reference>
- Working Demo: <https://github.com/jeremyeder/demo-fastapi>
- Claude Documentation: <https://docs.anthropic.com/claude/docs>

---

## About

Created by Jeremy Eder, Distinguished Engineer at Red Hat AI Engineering.

"Stable, Secure, Performant and Boring" - the goal is to make AI assistance invisible through excellence.
Loading