12 rules for building agents. Notes from prepping for the Anthropic certification
While studying for the Claude Certified Architect exam I built myself a cheat-sheet. What came out was more interesting than a cheat-sheet: a short list of rules that decide whether an agentic system survives production.
This post is a side effect. I was preparing for the Claude Certified Architect Foundations exam and built myself a cheat-sheet of recurring answer patterns. After a few rounds of practice tests I noticed something I did not expect.
The exam barely tests trivia. It tests judgment. Every question has one best answer and three plausible traps, and the same handful of rules decides almost all of them. I learned them to pass. They stuck around because they are simply a description of how you build agents that do not die in week two.
I am laying out the whole cheat-sheet. I start with twelve rules in the shape I actually use them: what to do, and which version of the same decision is the trap. Then I walk through the seven traps that kept coming back, drop down into the five domains, and finish with a table of facts.
You do not need to sit any exam for these to be useful. If you are sitting it, all the better.
The twelve rules
Enforce determinism in code
If a rule must hold every single time (verify identity before a refund, block refunds above a threshold, never touch source files), it is not a job for a prompt.
Do: a hook, a prerequisite gate, an allowed-tools list. Code gives you the guarantee.
Trap: "strengthen the system prompt", "say that it is mandatory". Prompts have a non-zero failure rate.
Pick the cheapest fix that hits the root cause
Before you build a subsystem, check whether a better description, an explicit criterion or a config change already solves it.
Do: the smallest lever that moves the actual cause.
Trap: a classifier, a routing layer or a fine-tune before anyone touched the prompt.
Wrong tool picked? Start with the descriptions
The description is the primary mechanism the model uses to choose a tool. When it chooses badly, the description is usually too thin.
Do: add input formats, example queries, edge cases, and how this differs from the similar tool next to it.
Trap: reaching for few-shot first, or a keyword router.
Over-engineering is almost always the wrong answer
A shiny new subsystem rarely beats a prompt fix or a tighter scope. Match the effort to the problem.
Do: prompt and config first, architecture second.
Trap: an ML classifier, sentiment analysis, training your own model, "let us use a bigger model".
A bigger context window is not better attention
Neither a larger window nor a higher tier fixes attention dilution, losing the middle of the input, or a scattershot review across many files.
Do: decompose, trim, scope, structure.
Trap: "use a model with a larger window so all the files get attention".
Sentiment and self-confidence are not signals
Do not escalate because the customer wrote in sharply. Do not route on the model rating its own confidence from 1 to 10. That number is badly calibrated, and on hard cases the model is confidently wrong.
Do: explicit criteria plus few-shot. Calibrate confidence against a labeled validation set.
Trap: auto-escalation on negative sentiment, a threshold on self-reported confidence.
An independent instance beats self-review
A fresh model that never saw the code being written catches more than the same model asked to check itself.
Do: a second instance with none of the generation context.
Trap: "add a self-review step", "turn on extended thinking so it finds its own bugs".
Least privilege for tools
Every agent gets the tools of its role. Four or five, not eighteen. The more tools, the worse the selection.
Do: scope to the role. Add one narrow cross-role tool when a need keeps coming back.
Trap: "give it everything so it can handle anything".
Structure beats free text. Everywhere
Structured errors (category, retryable, partial result), structured output, structured handoffs between agents, explicit provenance.
Do: give the next actor exactly the fields it needs.
Trap: "Operation failed", or a prose summary that drops ids, amounts, sources and dates.
Do not suppress errors, and do not panic
Two mirror sins. The first is catching an exception and returning emptiness as success. The second is killing the whole workflow because one subagent timed out.
Do: recover locally from what is transient. Propagate the rest with context and let the coordinator decide.
Trap: an empty result posing as success, or one timeout that topples everything.
Match the API to the latency need
The Batch API costs half as much, but it can take up to 24 hours, carries no latency SLA, and does not support tool calls mid-request.
Do: synchronous for whatever blocks a human. Batch for whatever can wait until morning.
Trap: moving a blocking pre-merge check onto the Batch API "for the savings".
Retry fixes format, not missing data
Retrying with error feedback fixes a bad format and broken structure. It will not conjure information that is not in the source.
Do: make the field nullable so the model returns null instead of inventing.
Trap: retrying an extraction against a document you never provided.
Seven traps that keep coming back
Wrong answers have patterns too. These seven kept returning, in different costumes.
"Strengthen the system prompt" / "make it mandatory"
Offered wherever determinism is required.
A prompt is probabilistic, so this is the exact failure the question describes. Enforce it in code.
"Add few-shot examples"
Dangled as the patch for a thin description or a hard rule.
Few-shot is right for ambiguous judgment, format and false positives. Not for tool descriptions, and not for rules that must always hold.
"Train a classifier / model / sentiment / fine-tune"
The heavyweight option off the ML shelf.
Over-engineered before anyone tried the cheap prompt and config levers. And sentiment is not complexity.
"Use a larger context window / higher-tier model"
Sold as the cure for attention spread across many files.
Window size fixes neither attention dilution nor missing decomposition. Split the work.
"Consolidate into one mega-tool"
"Let us just make one tool that handles everything."
When the fix is differentiating descriptions or splitting a tool, merging makes selection worse.
"Generic error / empty success / abort the workflow"
The three bad error shapes.
In order: hides context, suppresses the failure, over-reacts. Return structured error context.
"Rely on ordering / retry blindly / cache speculatively"
Shortcuts around batching and verification.
Correlate with custom_id. Retry only resolvable errors. Do not guess what to cache.
This is what I do hands-on — advising on AI strategy and building agents that survive the demo.
The five exam domains
The rules above settle most questions. The rest of the cheat-sheet goes deeper. I am quoting the weights from the public guide and cutting nothing, because this is the best map I have of what you actually need to know in practice.
Domain 1 · Agentic architecture and orchestration
27% · the heaviest domain
Loop control · stop_reason
Keep going while tool_use comes back (append the tool result), stop on end_turn. Never end the loop by parsing natural language or on an arbitrary iteration cap.
Parallel subagents · you need concurrency
Emit multiple Task calls in ONE assistant response, not across turns. allowedTools must include Task.
Passing context · the subagent "forgot"
Subagents do not inherit context. Pass prior findings explicitly in the prompt, and keep source metadata as structured data.
Coordinator · hub and spoke
Route all communication through the coordinator. A report missing whole subtopics usually means one thing: the decomposition was too narrow.
Enforcement hooks · a must-do or a policy
A prerequisite gate for ordering. An interception hook to block a policy-violating call (a refund above the threshold) and escalate. A PostToolUse hook to normalize time and status formats.
Decomposition · predictable or open-ended
Prompt chaining for predictable multi-aspect work. A dynamic approach (map, prioritize, adapt) for open-ended investigation.
Sessions · resume or start fresh
--resume a named session while the context still holds. fork_session for divergent branches. A fresh start with an injected summary once tool results have gone stale.
Human handoff · escalating to a person
Hand over a structured summary: customer id, root cause, amount, recommended action.
Domain 2 · Tool design and MCP integration
18%
Tool selection · the model picks the wrong one
First expand, rename or split the descriptions.
MCP errors · a tool failed
isError plus structured metadata: errorCategory (transient, validation, business, permission) and isRetryable. Distinguish an access failure from a validly empty result. A business rule means retriable:false plus friendly text.
Distribution · too many tools
Scope to the role. Replace a generic fetch_url with a constrained load_document. Add one narrow cross-role tool for a frequent need.
tool_choice · forcing behavior
auto (may answer with text) · any (must call some tool) · {type:tool,name} (must call that specific one).
MCP scope · where servers live
.mcp.json is project and shared (${ENV} for secrets), ~/.claude.json is personal. Every server's tools are available at once. MCP resources expose catalogs, which cuts exploratory calls. Enrich the descriptions so the agent prefers them over Grep.
Built-in tools · which one
Grep searches content · Glob matches filenames · Read/Write take a whole file · Edit needs a unique match. When the match is not unique, go with Read+Write.
Domain 3 · Claude Code configuration and workflows
20%
CLAUDE.md hierarchy · a teammate never got it
~/.claude/CLAUDE.md is user-scoped and does not travel through VCS. Move conventions into the project's .claude/CLAUDE.md or the repo root so every clone loads them.
Path rules · conventions on scattered files
.claude/rules/ with globs under paths: (**/*.test.tsx) loads by file type across directories. It beats a per-directory CLAUDE.md.
Commands · shared or personal
.claude/commands/ is the project's (shared via VCS), ~/.claude/commands/ is personal. A commands array in .claude/config.json does not exist.
Skills · what the frontmatter buys you
context: fork isolates verbose output · allowed-tools restricts tools deterministically · argument-hint asks for a missing argument. Skills load on demand, CLAUDE.md always.
Plan or direct · how big is it
Plan mode for large, architectural, multi-file and multi-approach work. Direct execution for small and well-scoped. For verbose discovery, use the Explore subagent.
Refinement · how to steer
Concrete input and output examples beat prose. TDD through shared failing tests. The interview pattern. Batch interacting fixes into one message, do independent ones in sequence.
CI integration · automated runs
-p/--print for non-interactive · --output-format json plus --json-schema for deterministic gates. Feed in prior findings so comments do not duplicate. An independent instance reviews better than the author.
Domain 4 · Prompt engineering and structured output
20%
Precision · fewer false positives
Explicit categorical criteria with code examples beat "be conservative" and confidence filters. Temporarily disable a category with a high false-positive rate while you fix its prompt.
Few-shot · 2 to 4 examples
For ambiguous cases, format consistency, cutting false positives and varied document structures. It generalizes to novel patterns.
Structured output · reliable JSON
tool_use plus a JSON schema eliminates syntax errors, but not semantic ones (line items that do not sum). tool_choice:any when the document type is unknown.
Anti-fabrication · missing fields
Make fields optional or nullable so the model returns null instead of inventing. Add an other enum with a detail, or unclear.
Validation retry · self-correction
Append the failed extraction and the specific errors. It works on format and structure, not on information absent from the source.
Batch · large volumes
Half the price, up to 24 hours, no SLA, no tool calls mid-request. Overnight yes, blocking no. Correlate with custom_id. Resubmit only the failed ids, and chunk the oversized ones.
Review architecture · large PRs
A local per-file pass plus a separate cross-file integration pass. An independent instance beats self-review.
Domain 5 · Context management and reliability
15%
Preserve the facts · long conversations
Keep a persistent case-facts block (amounts, dates, ids) outside the summarized history. Trim verbose tool output down to the fields you need. Put the key summary first, with section headers.
Escalation · when to hand off
Honor an explicit request for a human immediately, with no investigation first. Escalate on a policy gap or no progress. On multiple matches, ask for another identifier rather than guessing. Not on sentiment, and not on self-reported confidence.
Error propagation · multi-agent
Structured context: failure type, attempted query, partial results, alternatives. Recover locally from transient failures. Never suppress, and never topple the whole workflow.
Large codebase · context degradation
Scratchpad files · subagent delegation · summarizing between phases · /compact · manifest-based crash recovery.
Human review · calibration
Aggregate accuracy hides per-type and per-field failures. Use stratified random sampling. Calibrate field-level confidence on a labeled set. Route low-confidence and contradictory items to people.
Provenance · multi-source synthesis
Carry claim-to-source mappings through the synthesis. Annotate conflicting figures with their sources rather than picking one. Require publication dates so a gap in time does not masquerade as a contradiction. Render financials as tables, news as prose.
Facts and flags to recognize on sight
Finally, the raw table. Things you either know or guess. I like the last row best: I collected the "features" that do not exist but sound entirely plausible.
| Thing | What to remember |
|---|---|
stop_reason | tool_use means run the tool and loop · end_turn means done. |
| Claude Code CLI in CI | -p/--print non-interactive · --output-format json · --json-schema. |
| Message Batches API | Half the price · up to 24h · NO latency SLA · NO multi-turn tool calling · custom_id correlation. |
tool_choice | auto / any / {"type":"tool","name":"…"}. |
| Claude Code config files | .claude/rules/ (glob under paths:) · .claude/commands/ · ~/.claude/commands/ · .claude/skills/ with SKILL.md. |
| Skill frontmatter | context: fork · allowed-tools · argument-hint. |
| CLAUDE.md hierarchy | ~/.claude/CLAUDE.md (user, not shared) → the project's .claude/CLAUDE.md or root → subdirectory. @import to modularize · /memory to inspect. |
| Session and context | --resume · fork_session · /compact · the Explore subagent. |
| MCP | .mcp.json (project) versus ~/.claude.json (user) · ${ENV} expansion · MCP resources are catalogs · isError · errorCategory · isRetryable. |
| Built-in tools | Read · Write · Edit · Bash · Grep · Glob. |
| Schema patterns | Nullable and optional fields · other/unclear enums · calculated_total versus stated_total · conflict_detected. |
| ⚠ "Features" that DO NOT exist | A CLAUDE_HEADLESS env var · a --batch flag in Claude Code · a commands array in .claude/config.json. |
What is left
Seen from above, the twelve rules fold into three sentences.
Whatever must always hold, write it in code, not in a request. Match the size of the fix to the size of the problem. Pass structure, not prose.
Everything else is a variation on those three. And none of it is exam knowledge. It is a list of the places agentic projects bleed out in production, written down by accident while studying for a test.
Where this comes from. My own notes from preparing for the Claude Certified Architect Foundations exam, based on the public exam guide. This is unofficial material, not affiliated with or endorsed by Anthropic. The rules describe my practice, not the content of the exam.
