Mental Models for Agentic Engineering
Most agent failures are not model failures — they are operator failures caused by using the wrong mental model. If you treat Claude Code like autocomplete, you under-delegate. If you treat it like a senior colleague, you over-trust. The six models below are the ones that consistently predict outcomes on real codebases. Each one changes at least one concrete decision you make daily.
1. The agent is a fast junior/mid engineer with encyclopedic knowledge and zero memory
The agent writes idiomatic code in any language, knows every public API, and produces a day of work in ten minutes. It also starts every session having never seen your codebase, your incident history, or the reason you banned ORMs in the payment path. It is a new hire, every single morning, forever.
What this changes: You stop explaining things in chat and start writing them down. A human junior internalizes "we never write raw SQL in handlers" after one correction. The agent forgets it the moment the session ends — so the correction belongs in CLAUDE.md, not in the conversation. Onboarding effort goes into the repo, not the session. See Context and Instruction Hierarchy.
Where the analogy breaks: A junior asks questions when confused. The agent, by default, does not — it picks a plausible interpretation and keeps typing. You must explicitly instruct it to surface ambiguity ("list open questions before writing code"), and even then, review for silent assumptions. See Why Agents Fail on Complex Software.
2. The agent is a compiler for intent
A compiler turns source code into machine code deterministically; an agent turns intent into code probabilistically. The critical shared property: garbage in, garbage out — but the output always compiles-looking. Ambiguity in the prompt doesn't produce an error message. It produces invented requirements, rendered in clean, confident, well-formatted code.
"add rate limiting to the API" contains at least six unstated decisions (algorithm, scope, storage, response behavior, exemptions, configurability). The agent will make all six for you, silently. Why Agents Fail walks through that exact example.
What this changes: You review prompts the way you review interfaces — for what they fail to constrain, not just what they say. Before delegating anything non-trivial, ask: "what will the agent have to decide that I haven't decided?" If the answer is more than one or two things, you're not ready to prompt; you're ready to write a spec. See Prompt Anatomy.
3. The repository is shared memory
There is exactly one durable channel between you, the agent today, the agent next week, and every teammate's agent: the repository. Code, tests, docs, CLAUDE.md, specs, ADRs — that's the whole shared brain. Anything that lives only in your head or in a chat transcript is invisible to every future session.
What this changes: Repo quality becomes agent-performance tuning. A confusing directory layout, stale docs, or undocumented invariants aren't just tech debt anymore — they are active misinformation fed into every agent run. The 30 minutes you spend writing docs/architecture.md pays out on every subsequent task. See Repository Structure and Docs as Memory.
4. Documentation is executable context
Traditional docs rot because nothing executes them. Agent-facing docs are executed — Claude Code reads CLAUDE.md at session start and pulls in referenced files as it works. A rule in CLAUDE.md like "all money amounts are integer cents, never floats" gets applied on every task that touches billing. Wrong or stale docs get applied too, with the same diligence.
What this changes: Docs stop being an afterthought and get the same review rigor as code, because they now have runtime behavior. When an agent does something wrong twice, treat it as a failing doc, not a failing agent: fix the file. And prune aggressively — a 600-line CLAUDE.md full of stale rules is worse than a 60-line accurate one, because the agent can't tell which rules still hold. See CLAUDE.md and AGENTS.md.
5. The prompt is a temporary spec
Every prompt is a specification with a lifespan of one session. It governs the next few minutes of agent behavior, then evaporates. That's fine for "rename this function everywhere" and catastrophic for "here's how our billing proration works" — because you will pay the cost of re-explaining proration in every future session, slightly differently each time, with drift.
What this changes: The escalation rule — if you've typed it twice in chat, it belongs in a file. Prompts carry pointers ("implement per specs/billing-proration.md"), files carry truth. Full treatment in Prompts vs Specs.
6. The spec is the persistent source of truth
A committed spec file is the durable counterpart of the prompt: it survives sessions, gets versioned, gets reviewed in PRs, and governs every agent (and human) that touches the feature. When agent output diverges from the spec, you have an objective arbiter — instead of arguing with a chat window about what you meant, you point at a file both of you can read.
What this changes: "Was this built correctly?" becomes a diff between artifact and spec rather than a vibe check. Rework loops shorten: instead of re-prompting from memory, you amend the spec and re-run. And specs make delegation reviewable — a teammate can audit the intent, not just the code. See Specs over Prompts.
The layered control stack
These models compose into a control stack. Each layer constrains the agent with a different scope and lifespan; conflicts resolve downward toward ground truth.
Reading the stack top-down: the prompt is the narrowest and most ephemeral control; the spec governs a feature across sessions; CLAUDE.md and repo docs govern all work in the repo; code and tests are what actually runs. Reading it bottom-up: when layers disagree, the code+tests describe what is, the spec describes what should be, and the prompt only describes what you want right now. Persistent knowledge must migrate downward or it is lost.
Situation → which model to reach for
| Situation | Reach for | Resulting decision |
|---|---|---|
| Agent made the same mistake in two different sessions | Zero-memory junior | Add the rule to CLAUDE.md; stop correcting in chat |
| About to delegate a vaguely-defined feature | Compiler for intent | Enumerate the undecided decisions first; write them down or accept invented requirements |
| Agent output is plausible but subtly wrong | Compiler for intent | Tighten the input, don't just patch the output — the next run will drift again |
| New teammate's agent behaves worse than yours | Repository as shared memory | Your advantage is in your head; move it into repo docs |
| Docs exist but the agent ignores or contradicts reality | Docs as executable context | Treat stale docs as live bugs; fix or delete before the next run |
| Re-explaining the same domain rules each session | Prompt as temporary spec | Apply the escalation rule: twice in chat → into a file |
| Dispute about whether a delegated feature is "done" | Spec as source of truth | Diff the artifact against the spec; if there's no spec, that's the actual root cause |
| Deciding how much detail a prompt needs | Layered control stack | Ask which layer already constrains this; prompt only what nothing below it covers |
Related
- Agents vs Assistants — where the agentic loop sits relative to autocomplete and chat, and why the supervision model differs.
- Why Agents Fail on Complex Software — the failure mechanics these models predict, with a worked example of silent assumptions.
- Context and Instruction Hierarchy — the zero-memory model made mechanical: what enters context and what wins on conflict.
- Prompts vs Specs — models 5 and 6 in depth, with the escalation rule and a weak/strong example.
- Specs over Prompts — how to operationalize the spec layer on a real project.
- Responsibility Split — which decisions stay human regardless of how good the models get.