The Engineer + Agent Playbook — Home for Deranged Scientists

A field manual for partnering an engineer with a coding agent. Drawn from real scar tissue accumulated across six very differently-shaped efforts: a full-stack web application shipped over two years, a server built almost entirely by parallel agents against external specs, a high-velocity web app that shipped nine major versions in three days, a community-data web app driven by explicit security and visual audit passes, an epistolary journaling app whose deterministic classifier turned debugging into a laboratory discipline, and a fleet of small single-user apps that share scar tissue across repository boundaries.

Between them: Python and Go and TypeScript backends, React and vanilla frontends, more than eighty narrative retrospectives, teams ranging from one human and one agent to a dozen parallel agents. All six are referenced throughout; you do not need access to any of them — every story this playbook relies on is told in full, right here. Written to be useful to humans and to agents loaded with this file as context — whichever model, whichever harness.

Agents loaded with this file as context: jump to Appendix A for the imperative-only fast path. Humans: read in order.

What changed in the second edition

The first edition was extracted from four projects' retrospectives. Since then the practice kept running: a fifth project was built start-to-finish under these rules and wrote twenty retros of its own, the first case study shipped a new major version in parallel waves, and the fleet grew sideways — small single-purpose apps sharing lessons through cross-project memory. The second edition folds that evidence back in. Concretely:

Three new chapters. §2 The model and the harness — what changes when the reader is a different model (Claude, GPT, GLM, Qwen) or a different harness (Claude Code, Codex, opencode, Cursor), and what never changes. §10 Diagnosis — build the lab — the debugging discipline the fifth case study forced into the open. §15 Audits — promoted from a coda aside to a chapter, because the evidence got too strong to leave it as an afterthought.
New rules where the scars demanded them — exploration before planning, the revert question, wire-level verification, probing your own guardrails, secrets hygiene in agent sessions, pre-registered experiments before touching non-negotiables, two-stage review for delegated work.
Qualifiers where the practice outgrew the first edition's phrasing — retros consolidate at the arc, not the tag; investigation depth follows blast radius; the instructions file is a role, not a filename.

Everything that held, held. The load-bearing pair is still verification (§8) and retros (§16). The thesis didn't move an inch.

The thesis

We can create art and beauty with a computer.

That line is why this playbook exists. Not productivity. Not velocity. Not "shipping faster." Those are byproducts. The point is the art — the thing only a human can decide is worth making — and the new division of labor that frees you to do it.

Here is the division of labor, in three layers:

The pipeline handles mechanics. Build, test, lint, scan, deploy, run, roll back. Boring. Automated. Invisible when it works. The discipline that makes this true is the companion to this playbook — see the DevOps playbook referenced in Appendix C. Its thesis is one line: you are done when the pipeline is boring. Everything below assumes you've reached that line, or are sprinting toward it.
The agent handles elaboration. Breadth, consistency, mechanical translation of intent into code. Fifty call sites updated without a typo. A protocol adapter built from an RFC. A test scaffold written to spec. Fast, literal, tireless, and — crucially — not the craftsperson. The agent is the hands; it is not the taste.
The human handles craft. Intent. Taste. Judgment. Synthesis. The decision of what is worth building and why. The choice of which trade-off is tolerable. The recognition that a "cleanup" is erasing the core use case. The read of whether the work is good. The irreducible part — the part that can't be delegated because the whole reason to do the work at all lives in your head.

Each layer exists to free the next. A flaky pipeline drags the human down into mechanics. An unsupervised agent drags the human up into correcting elaboration errors. A human who has to do laborer's work has no attention left for the art. Every rule in the rest of this playbook is, at root, a maneuver to keep each layer doing its own job so the human can spend attention on the work only a human can do.

If you take two chapters of this playbook seriously, take §8 (Verification) and §16 (Retros). Verification is how you catch the failure. Retros are how you make sure you catch it only once. And if you take one thing seriously before either of those: make your pipeline boring. When the pipeline is boring, verification is cheap. When verification is cheap, retros write themselves. When retros write themselves, the loop learns. When the loop learns, the human gets to be the craftsperson — which is the whole point.

The tagline is the point of the project. The rest of this playbook is the apparatus that serves it.

The six case studies at a glance

Every field note in this playbook comes from one of six real projects. The body refers to them by number — "the second case study," "the fifth case study." This table orients the reader once so the shorthand works everywhere else. Long-form in Appendix C.

#	Shape	Scale	Duration	What it added to the rules
1	Full-stack web app (Python/React), production users	~30 releases, small team + agents	2+ years	The baseline. Every rule starts here. The v6.x waves added exploration-before-planning, the revert question, and wire-level verification.
2	Parallel-agent protocol server (Go + Python sidecars)	9 releases, 3 → 70+ adapters, up to 12 parallel agents	~6 months	Interface-as-coordination-protocol, wave pattern, explicit merge points, nested cycles, explicit descoping.
3	High-velocity time-tracking web app (React/TypeScript/Supabase)	9 major versions in 3 days	3 days	Partnership-architecture failure mode (v6→v7 worktree pivot); "right evidence for the wrong claim is theater."
4	Community-data web app with audit cadence (React/Vite/edge functions)	Scheduled security + visual audit releases	Ongoing	Systematic audit as craft work; duplicates-that-drift clause on "write a skill after the third correction."
5	Epistolary journaling PWA with a deterministic classifier (React/TypeScript/Supabase)	~24 tagged releases, 20 retros, 0 → 375 tests	~3 months	The whole of §10 (build the lab); claims-downstream-of-code; probe-the-gate; agent-vocabulary bias; model-tier-by-task; the arc-not-tag retro qualifier.
6	A fleet of small single-user "instrument" apps sharing lessons across repos	4+ apps, one human, one agent at a time	Ongoing	Cross-repo memory (file your neighbor's scars); elicitation as a loop stage; secrets hygiene; pipeline-resilience clause.

A note on names. The conventions this playbook grew up with are Claude Code's — CLAUDE.md, skills, hooks, settings.json. The practice is not. §2 maps every layer onto its equivalents in other harnesses (AGENTS.md is the emerging cross-tool standard for the instructions file; Codex, opencode, Cursor, and Gemini CLI each have their own names for the rest). Throughout the body, read CLAUDE.md as "the instructions file" and settings.json as "the harness config" — the field notes keep the original names because that's what the files were called when the scars formed.

This playbook has a companion

This document has a sibling: the DevOps Playbook, derived from the same case study and the same retro practice. The DevOps Playbook tells you how to build the boring pipeline — the mechanics layer. This one tells you how the human and the agent work inside that pipeline. If the pipeline is flaky, start there; partnership rules only work when the rails underneath them do. See §3 for the pipeline-as-precondition argument in full, and Appendix C for how the two playbooks pair.

How to read this playbook

Every chapter has two layers. The top layer is a rule — one imperative line you could pin above your desk. Under it, a Why (the constraint or the scar that produced the rule) and a How to apply (when it fires). Then a narrative paragraph in the voice of someone who learned it the hard way. At the bottom, a field note — a short inline vignette from the case studies, naming the bug by its nickname and telling you just enough to feel the bruise.

Read the rule. If you believe it, skim. If you don't, read the story — the story is where the rule earned its keep.

You'll also see lines marked *Pin:* scattered through the chapters. A pin is the sentence the whole chapter compresses to — the line worth taping to a monitor, worth extracting into memory, worth handing to an agent when the narrative is too long. Pins are the agent-facing one-liners that survive when everything else is forgotten. When a pin contradicts its surrounding narrative, the pin wins.

Here's the format in action — a worked illustration drawn from a real scar. (This is the scaffolding demonstrated on a single rule; the actual §8 rule it derives from — "Evidence before assertions" — lives in that chapter, and the full story lives in Part V under The Health Check That Wasn't.)

Rule: Ask what's in the response before you diagnose why it's wrong. (format example — not a numbered rule)

Why: You can spend three deploys "fixing" a value that was never in the payload. How to apply: Any time a field reads unknown, null, or empty — dump the raw response before touching the producer.

We spent an evening forcing GIT_REV through three different docker compose mechanisms because git_sha kept coming back unknown. Shell export, env file, compose override, --build-arg. All of it worked. The verification curl was hitting /health, which returns {"status":"ok"} and has no git_sha field at all. The real endpoint was /api/v1/health. We'd been debugging a producer that was never broken.

Field note — case study 1: The Health Check That Wasn't. Three deploys spent chasing a missing build SHA through every Docker mechanism we had. On the fourth round somebody finally dumped the raw response. The verification curl was hitting /health, a status endpoint that has never had a git_sha field. The producer was never broken. We'd been fixing a hole that wasn't there.

All the rules at a glance

The spine of the playbook, listed in one pass so you can see where you're going. Seventy rules across fourteen rule-bearing chapters, plus two chapters (§11 and §12) that carry checklists rather than rules. Rules new in the second edition are marked (v2). The body of the document unpacks each rule with a Why, a How, and a scar. If a rule reads as obvious, skim the chapter. If it reads as strange, read the story underneath it — that's where the rule earned its keep.

§1 Mental models

Brief the agent like a smart colleague who just walked into the room.
Delegate the task, not the understanding.
The agent is good at breadth and consistency. It is bad at judgment under ambiguity.
Agent-authored domain content is a plausible first draft of the world, not the world. (v2)

§2 The model and the harness (new chapter)

The disciplines are model-invariant. Only the calibration moves. (v2)
Pick the model tier by the shape of the work, not the size of the diff. (v2)
The harness is a dependency: map its layers, keep the knowledge portable. (v2)
Trust harness claims the way you trust "tests pass": with evidence. (v2)

§3 The workspace

Your pipeline is a precondition, not a feature — and every automated rail needs a rehearsed manual fallback.
The instructions file is for facts that don't change. Memory is for facts that do.
Skills are for procedures. The instructions file is for facts.
Hooks make automation non-negotiable.
The harness config configures the harness. The instructions file configures the agent. They are different layers.

§4 The first conversation

Bootstrap with the smallest context that contains the answer.
Correct drift in message 2, not message 50.
If the agent doesn't know something, tell it. Don't let it guess.
Make the agent tell you what it thinks you're building — then grill it. (v2)

§5 The loop

Explore before you plan. The plan is not the codebase. (v2)
Run the whole loop. Skip a step out loud or pay for it silently.
Brainstorm before planning. Plan before code.
Frequent commits are not optional.
Retros feed the next loop.
Cycles nest. Each level needs a theme, a boundary, and all three phases.

§6 Memory hygiene

Memory has four types. Use the right one or it rots.
Stale memory is worse than no memory.
A belief you've never probed is a hypothesis, not a memory. (v2)
Save the why, not just the rule.
Don't memorize what the code already says.
File your neighbor's scars, keyed to the trigger that will make them yours. (v2)

§7 Skills as institutional knowledge

Skills are procedures with discipline. Instructions-file notes are facts you hope get followed.
Rigid skills exist for a reason. Don't adapt the discipline away.
Write a skill after the third correction.
Ship the cheap defense now; schedule the clean refactor for a quiet phase. (v2)

§8 Verification before completion

"Tests pass" is not "feature works." Verify the feature.
Evidence before assertions. Always.
Ask: would these tests pass if the change were reverted? (v2)
Verify in the environment that matters.
When a value crosses a layer boundary, verify the wire, not the fixture. (v2)
Health checks must check health — and observability must be observed.

§9 Trust boundaries

Match the action to its blast radius. Confirm before crossing the line.
Authorization is scoped, not blanket.
When the agent hits an obstacle, it must investigate, not delete.
Secrets never transit the transcript. (v2)
Before touching a non-negotiable, write down what would change your mind. (v2)

§10 Diagnosis — build the lab (new chapter)

Build the diagnostic surface before the fix. (v2)
The ticket's diagnosis is a hypothesis. Read the trace before believing the issue. (v2)
A fixed bug's class is a search query, not a closed ticket. (v2)
Exploration mode is not production mode. (v2)
When the runner wedges, suspect the runner. (v2)

§11 Failure modes & recovery — seven failure modes (five disciplines, one topology, one epistemic), plus a closing note that every agent failure has a human antecedent. See the chapter.

§12 The rescue protocol — next hour, next day, next week. See the chapter.

§13 Parallel agents & worktrees

Fan out only when tasks are independent.
Worktrees are workspaces, not stashes — and they are not a coordination strategy.
Designate merge points explicitly; update them last.
Subagents protect your context window; they don't hide work from you.
Review delegated work in two stages, with reviewers who don't trust the implementer. (v2)
Isolate even the "read-only" agents. (v2)

§14 Plan quality

A plan with placeholders is a wish list.
Each step is one action, two to five minutes long.
The plan must cover the spec — and match the codebase.
Predict the failing output before you run it. (v2)
Descope explicitly. Name what's out, and name why.

§15 Audits (new chapter)

Schedule audits on purpose. (v2 — promoted from the first edition's coda)
Claims must be downstream of code, not upstream. (v2)
The debt is in the seams. Diff what you wrote down against what's true. (v2)
Probe the gate. A protection you've never tested is a protection you don't have. (v2)

§16 The retro habit

Write retros in voice, not in bullet points.
Retros are how the loop learns.
Write a retro at the end of every themed cycle, and right after every surprise.
A retro has an anatomy. Use it as a scaffold, not a template.
A retro has three audiences: you next month, your team, and the agent next time.
The retro unit is the arc, not the tag — and when a retro was wrong, write the reversal down. (v2)

Reader routing

Reader	Where to start
You're struggling and about to give up on agent-assisted work	§11 Failure modes, then §12 The rescue protocol, then loop back to Part I
You're new to this and want the foundations	Part I — Foundations, in order, no skipping
You've been doing this a while and want to level up	Part IV — Leveling Up, then dip into Part II for anything that rings a bell
You use a different model or harness than the one this playbook grew up with	§2 The model and the harness, then read normally — the mapping table translates the rest
You are an AI agent loaded with this file as context	Appendix A — the imperative-only fast path

The premise

Most playbooks lie to you in the first paragraph. They promise the tool will change everything. It mostly doesn't. What changes is you, slowly, and only if you pay attention to the boring parts.

Here is what this partnership actually is: you have an extremely fast, extremely literal colleague who has no memory of yesterday, no stake in tomorrow, infinite patience, and zero judgment about whether the work is worth doing. That combination is strange and powerful and, left unsupervised, will confidently produce nonsense in volume. Managed well, it will ship your work faster than you thought possible and catch bugs you wouldn't have caught alone.

Here is what it isn't: a replacement for thinking. The agent does not know what "done" means on your project until you tell it. It does not know which of the four plausible fixes is the right one until you show it the scar that rules out the other three. It does not know the difference between a deploy that worked and a deploy whose verification endpoint returned {"status":"ok"} and nothing else. You know those things. Your job is to transfer them, one by one, into a form the agent can act on — skills, memory files, plans, checklists — so next time neither of you has to rediscover them.

The rest of this playbook is that transfer, written down. Most of it is boring. All of it is load-bearing. The agent is infinitely patient and infinitely literal; your job is to be specific enough to deserve that.