Start Here
This is an operating manual for building complex software with AI coding agents — primarily Claude Code, with patterns that transfer to Codex, Cursor, Copilot, and whatever ships next. It is written for engineers who already ship production software and want agents to do most of the typing without degrading the system.
The operating model in one diagram
Everything on this site elaborates one loop:
Five claims behind it, each defended in depth elsewhere:
- The agent is a compiler for intent. Ambiguity in, invented requirements out. Quality of output is bounded by quality of specification, not by prompting tricks. → Prompts vs. Specs
- The repository is the agent's memory. Context windows are ephemeral;
CLAUDE.md,ARCHITECTURE.md, and specs are what persist across sessions and agents. → Docs as Agent Memory - Verification is the human's job, and it must be structural. Reading the diff is necessary but insufficient; you verify scope, architecture fit, and behavior separately. → Verification Strategy
- Failures are predictable. Agents fail in recurring, catalogable ways. Recognizing a failure mode early is worth more than any prompt template. → Failure Catalog
- You own the decisions; the agent owns the diffs. Architecture, tradeoffs, and "is this actually done" never delegate cleanly. → The Responsibility Split
Where to go, by situation
| Your situation this week | Read in this order |
|---|---|
| First serious project with Claude Code | Mental Models → Prompt Anatomy → Starting a New Project |
| Agents produce plausible junk on your large codebase | Why Agents Fail → Repository Structure → CLAUDE.md & AGENTS.md |
| Shipping a feature into production code | Adding a Feature Safely → Reviewing AI Pull Requests → Verification Checklists |
| An agent has made a mess | Failure Catalog → Recovering From Bad Output |
| Scaling beyond one agent | Agent Roles → Coordination Without Chaos → Multi-Agent Feature Delivery |
| Rolling agents out to a team | CTO path or Engineering Manager path |
For a structured curriculum instead of à-la-carte reading, pick a learning path.
What this site refuses to do
- Teach programming, Git, testing, or CI/CD — assumed known.
- Cover prompt-engineering parlor tricks that don't survive contact with a 200-file codebase.
- Pretend agents are senior engineers. They are extremely fast, well-read, literal-minded collaborators with no memory and no stake in the outcome. The entire discipline is engineering around exactly that.
Conventions used throughout
- Prompts appear in fenced code blocks with a copy button. Text in
<angle brackets>is a placeholder you fill in. - Weak → strong examples show the failing version first, then the fix. The delta is the lesson.
- Failure tables use the columns Symptom / Cause / Fix so you can scan them mid-incident.
- Claude Code specifics (e.g.
CLAUDE.md, subagents, plan mode, hooks) are called out by name; everything else is written to survive tool churn.