Claude Certified Architect Foundations

An agentic loop is plain control flow around the Messages API. You send the conversation plus tool definitions. Claude either asks for tools or finishes. Your code decides what to do by reading stop_reason, never by reading Claude's prose.

messages = [{"role": "user", "content": task}]
while True:
    resp = client.messages.create(model=MODEL, max_tokens=4096,
                                  system=SYSTEM, tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": resp.content})  # keep the full turn

    if resp.stop_reason == "end_turn":
        break                                                    # the model decided it is finished
    if resp.stop_reason == "tool_use":
        results = []
        for block in resp.content:
            if block.type == "tool_use":
                out = run_tool(block.name, block.input)
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": out.text, "is_error": out.failed})
        messages.append({"role": "user", "content": results})    # results go back as a user turn
        continue
    handle_other(resp)   # e.g. max_tokens = output truncated; decide to continue or fail

Key ideas

• Tool results are appended to history. That is how the model "sees" what happened and reasons about the next action. Each tool_result must reference the matching tool_use_id.
• Model-driven vs pre-configured. In an agent, Claude decides which tool to call next from context. A hard-coded decision tree or fixed tool sequence is a workflow, not an agent. Use the agent when the path depends on what is discovered; use fixed code when the path is known.
• A single response can contain text and several tool_use blocks. Execute all of them before the next call.

Hub-and-spoke: one coordinator owns decomposition, delegation, routing between subagents, error handling, and aggregation. Subagents never talk to each other directly. Every message passes through the hub, which gives you one place for observability, consistent error handling and controlled information flow.

Key ideas

• Isolated context. A subagent starts with only what its prompt gives it. It does not inherit the coordinator's history and keeps no memory between invocations.
• Dynamic selection. A good coordinator reads the query and invokes only the subagents it needs. A simple factual question should not run the full five-stage pipeline.
• Partition scope to avoid duplicate work: give each subagent distinct subtopics or source types.
• Iterative refinement. The coordinator evaluates the synthesis for gaps, sends targeted follow-up queries to search and analysis, and re-runs synthesis until coverage is sufficient.

• The Task tool spawns subagents in the Agent SDK. The coordinator's allowedTools must include "Task" or it cannot delegate at all.
• An AgentDefinition configures each subagent type: a description (used to decide when to delegate), a system prompt, and a restricted tools list.
• Context must be explicit. Pass the complete findings of earlier agents inside the subagent's prompt, for example web results and document analysis handed to synthesis.
• Keep metadata separate from content using structured formats (claim, excerpt, URL, document name, page) so attribution survives the hand-off.
• Parallelism happens when the coordinator emits several Task calls in one response. Calls spread across separate turns run sequentially.
• Prompt the coordinator with goals and quality criteria ("cover all major sectors, two independent sources per claim") rather than step-by-step procedures, so subagents can adapt.
• Fork-based sessions let you branch from a shared analysis baseline to explore divergent approaches (see 1.7).

options = ClaudeAgentOptions(
    system_prompt=COORDINATOR_GOALS,              # goals + quality bar, not a procedure
    allowed_tools=["Task"],                        # required to spawn subagents
    agents={
        "web-searcher": AgentDefinition(
            description="Finds and fetches sources for one assigned subtopic.",
            prompt="Return findings as JSON: claim, excerpt, url, published_at.",
            tools=["web_search", "load_document"]),
        "synthesizer": AgentDefinition(
            description="Merges structured findings into a cited draft.",
            prompt="Preserve every claim→source mapping. Flag conflicts.",
            tools=["verify_fact"]),
    })

Two ways to make steps happen in order: prompt guidance (probabilistic, usually works) and programmatic enforcement (hooks, prerequisite gates; deterministic). When a mistake costs money, breaks compliance or touches identity, prompts alone are not enough.

Multi-concern requests

"My order arrived damaged, I was double-charged, and I want to change my email." Decompose into distinct items, investigate each in parallel against shared context (same customer, same session), then synthesize one unified reply.

Structured handoff to a human

The human agent does not see the transcript. The escalation payload must stand alone:

{
  "customer_id": "C-88213",
  "issue_summary": "Charged twice for order #12345 on 2026-09-28",
  "root_cause": "Payment retry created a duplicate capture",
  "evidence": ["capture_id pi_91a", "capture_id pi_91b"],
  "refund_amount": 742.10,
  "why_escalated": "Exceeds $500 autonomous refund limit",
  "recommended_action": "Void duplicate capture pi_91b",
  "customer_expectation": "Refund before Friday"
}

# Illustrative hook logic
async def pre_tool(call, ctx):
    if call.name == "process_refund" and call.input["amount"] > 500:
        return deny("Refunds over $500 need a human. Call escalate_to_human "
                    "with a structured summary.")          # redirect, not just block

async def post_tool(call, result, ctx):
    for k in ("created_at", "shipped_at"):
        result[k] = to_iso8601(result.get(k))               # 1727049600 → 2024-09-23T00:00:00Z
    result["status"] = STATUS_NAMES.get(result["status"], result["status"])  # 3 → "shipped"
    return result

A single pass over many files causes attention dilution: deep comments on some files, shallow ones on others, missed bugs, and contradictory verdicts on identical code.

• --resume <session-name> continues a specific named conversation, for example an investigation spread across days.
• fork_session creates an independent branch from a shared baseline. Analyse the codebase once, then fork to compare two refactoring or testing strategies without them contaminating each other.
• When resuming after code changed, tell the agent which files changed so it re-reads those specifically instead of re-exploring everything or trusting stale results.
• When most earlier tool results are stale, start a new session with a structured summary. That is more reliable than resuming a history full of outdated file contents.

The description is the primary mechanism the model uses to select a tool. Minimal or overlapping descriptions cause misrouting between similar tools.

// before: the model cannot tell these apart
get_customer:  "Retrieves customer information"
lookup_order:  "Retrieves order details"

// after
lookup_order:
  "Look up a single order by order number (format: #12345 or ORD-12345).
   Use when the user mentions an order, shipment, delivery, return or refund
   for a specific purchase. Returns status, items, amounts, ship/delivery dates.
   Do NOT use to find who a customer is; use get_customer for identity,
   contact details or account status. If only a name is given, call
   get_customer first."

A good description states

• What it does and what it returns
• Input formats, with an example query
• Edge cases and limits
• When to use it versus its nearest neighbour

Fixes when tools overlap

• Rename + rescope: analyze_content → extract_web_results with a web-specific description.
• Split generic tools into purpose-specific ones with defined contracts: analyze_document → extract_data_points, summarize_content, verify_claim_against_source.
• Audit the system prompt for keyword-sensitive wording. "Always analyze the content first" can pull the model toward a tool named analyze_content regardless of its description.

MCP tools signal failure with isError: true on the result. The content should tell the agent what kind of failure it is, because the right recovery differs.

{
  "isError": true,
  "content": [{ "type": "text", "text": JSON.stringify({
    "errorCategory": "business",
    "isRetryable": false,
    "code": "RETURN_WINDOW_EXPIRED",
    "message": "Order #12345 was delivered 41 days ago; returns close at 30.",
    "customerMessage": "This order is past our 30-day return window, but I can check warranty options."
  })}]
}

• A uniform "Operation failed" leaves the agent guessing, so it retries things that will never succeed or gives up on things that would.
• Empty is not failure. "Query succeeded, zero matches" and "could not reach the database" must look different.
• Subagents retry transient errors themselves and only propagate what they cannot resolve, with partial results and a list of what was tried.

• Fewer tools, better choices. 18 tools on one agent degrades selection compared with 4–5 focused ones.
• Agents given tools outside their role misuse them. A synthesis agent with web search starts searching instead of synthesizing.
• Constrained alternatives: replace a generic fetch_url with load_document that validates document URLs.
• Scoped cross-role tools: give synthesis a narrow verify_fact for the common simple check; send deep verification through the coordinator.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }   // secret stays out of git
    },
    "orders-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com/orders",
      "headers": { "Authorization": "Bearer ${ORDERS_API_TOKEN}" }
    }
  }
}

• Tools from all configured servers are discovered at connection time and available at once. A project server and a personal server work side by side.
• Tools vs resources. Tools perform actions. Resources expose readable content catalogs (issue summaries, doc hierarchies, database schemas) so the agent can see what exists without exploratory tool calls.
• If the agent keeps using built-in Grep instead of your more capable MCP search, improve the MCP tool's description of what it can do and return.
• Prefer an existing community server for standard systems (Jira, GitHub). Build custom servers only for team-specific workflows.

• Edit fails on non-unique matches. Fallback: Read the file, then Write the full new content.
• Explore incrementally: Grep for entry points, Read to follow imports, trace the flow. Do not read every file up front.
• Wrapper modules: list everything a module exports first, then Grep for each exported name to find all usages, including re-exports under different names.

• Three levels: user (~/.claude/CLAUDE.md), project (CLAUDE.md at root or .claude/CLAUDE.md), directory (a CLAUDE.md in a subfolder).
• User-level is private. Instructions there are not in version control, so teammates never get them.
• @import pulls other files into a CLAUDE.md, e.g. @docs/standards/testing.md. Each package can import only the standards that apply to it.
• .claude/rules/ replaces one huge CLAUDE.md with focused files: testing.md, api-conventions.md, deployment.md.
• /memory shows which memory files are loaded. Use it first when behaviour differs between people or sessions.

# packages/billing/CLAUDE.md
Billing service. Money is integer cents; never floats.
@../../docs/standards/api-errors.md
@../../docs/standards/pci-logging.md

---
name: analyze-module
description: Deep-dive one module and report structure, hotspots and risks.
context: fork                     # run in an isolated sub-agent; only the summary returns
allowed-tools: Read, Grep, Glob   # restrict what the skill may do
argument-hint: <module-path>      # prompts the dev when invoked with no argument
---
Map the module at $ARGUMENTS. Return: entry points, dependencies,
untested paths, and the three riskiest functions with reasons.

• context: fork keeps verbose output (codebase analysis) or exploratory noise (brainstorming) out of the main conversation.
• allowed-tools limits blast radius, for example a skill that may only write files and never run shell commands.
• To customise a team skill for yourself, create a personal copy with a different name in ~/.claude/skills/ so teammates are not affected.

# .claude/rules/testing.md
---
paths: ["**/*.test.tsx", "**/*.test.ts"]
---
Use React Testing Library. Query by role, not test id.
One behaviour per test. Use fixtures from test/fixtures/.

# .claude/rules/terraform.md
---
paths: ["terraform/**/*"]
---
Every resource gets owner and cost-center tags. No inline IAM policies.

• Rules with a paths glob load only when Claude edits matching files, saving tokens and avoiding irrelevant guidance.
• Glob rules beat subdirectory CLAUDE.md files for conventions that span directories, such as test files living next to their components everywhere.

• Plan mode allows safe, read-only exploration and design before any change, which prevents expensive rework.
• Combine them: plan the migration, approve the plan, then execute it directly.
• The Explore subagent isolates verbose discovery and returns a summary, keeping the main context from filling up in multi-phase work.

claude -p "Review this PR diff. Report only bugs and security issues per CLAUDE.md.
Previously reported findings are in prior.json; report only new or still-unaddressed ones." \
  --output-format json \
  --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{
     "type":"object","required":["file","line","severity","issue","fix"],
     "properties":{"file":{"type":"string"},"line":{"type":"integer"},
       "severity":{"enum":["critical","major","minor"]},
       "issue":{"type":"string"},"fix":{"type":"string"}}}}}}'

• -p / --print = non-interactive: run, print, exit. Without it the job hangs waiting for input.
• CLAUDE.md is the CI context: review criteria, testing standards, fixture conventions.
• Session isolation: the session that wrote the code is a weak reviewer of it. Review in a separate instance.
• On re-runs, include prior findings and ask for new or unresolved issues only, to avoid duplicate comments.
• For test generation, include existing test files so Claude does not propose scenarios already covered, and document valuable-test criteria and fixtures in CLAUDE.md.

• False positives cost more than missed nits. One noisy category makes developers distrust the accurate ones too.
• Tactic: temporarily disable the high-false-positive category to restore trust while you improve its prompt.
• Define severity levels with a concrete code example for each, so classification is consistent.

When detailed instructions still give inconsistent results, few-shot examples are the most effective lever. They teach format and judgment, and they help the model generalise to cases you did not list.

• Use 2–4 targeted examples aimed at the ambiguous cases, each showing why one action beat the plausible alternative.
• Show the exact output format: location, issue, severity, suggested fix.
• Include an example of acceptable code that looks suspicious, to cut false positives.
• For extraction, show varied document structures (inline citations vs bibliography, tables vs narrative). This reduces hallucination and empty fields.

<example>
Request: "I want to return the blender but I also think I was charged twice."
Decision: lookup_order first, then check payments.
Why: both concerns hinge on order #; get_customer is unnecessary because the
session already holds a verified customer_id. Escalation not needed: both are
within policy and tools.
</example>

Define an "extraction tool" whose input_schema is the shape you want. When Claude calls it, the tool_use.input is your structured data. This is the most reliable way to get schema-compliant JSON and removes syntax errors.

{
  "name": "extract_invoice",
  "description": "Record fields from one invoice. Use null when a field is absent.",
  "input_schema": {
    "type": "object",
    "required": ["vendor_name", "line_items", "stated_total", "document_type"],
    "properties": {
      "vendor_name":   { "type": "string" },
      "invoice_date":  { "type": ["string", "null"], "description": "ISO 8601; null if absent" },
      "po_number":     { "type": ["string", "null"] },
      "document_type": { "enum": ["invoice", "credit_note", "receipt", "unclear", "other"] },
      "document_type_detail": { "type": ["string", "null"], "description": "Fill when type is other" },
      "line_items": { "type": "array", "items": { "type": "object",
          "properties": { "desc": {"type":"string"}, "amount_cents": {"type":"integer"} } } },
      "stated_total":     { "type": "integer" },
      "calculated_total": { "type": "integer", "description": "Sum of line_items" },
      "conflict_detected":{ "type": "boolean" }
    }
  }
}

• Nullable fields stop the model inventing values to satisfy a required field.
• "unclear" handles ambiguity; "other" + detail string keeps categories extensible.
• Put normalization rules in the prompt (dates to ISO, amounts to cents) alongside the strict schema.
• tool_choice: "any" when several extraction schemas exist and the document type is unknown; forced {"type":"tool","name":"extract_metadata"} to run one step before enrichment.

• Self-checking fields: extract calculated_total next to stated_total; add conflict_detected when the source contradicts itself.
• Feedback loops for reviews: add a detected_pattern field to each finding so you can analyse which patterns developers dismiss and tune the prompt.

SLA arithmetic

Worst case = waiting for the next submission + up to 24 h processing + a buffer for validation and resubmits. For a 30 h SLA: 4 h windows → 4 + 24 = 28 h, leaving 2 h of slack. A 6 h window would hit 30 h with zero slack.

Failure handling

• Resubmit only failed items, identified by custom_id, with a fix (e.g. chunk documents that exceeded the context limit).
• Refine the prompt on a sample set first to maximise first-pass success before sending 10,000 documents.

• Self-review is weak. The generating session keeps its reasoning and tends to defend it. Instructions to "double-check" and extended thinking do not fix that.
• Independent instance without the generator's context catches subtler issues.
• Multi-pass: per-file local passes plus an integration pass for cross-file data flow (see 1.6).
• Confidence per finding in a verification pass can route review attention, once calibrated.

Three ways context goes wrong

• Progressive summarization blurs numbers, dates, percentages and what the customer was promised ("refund $742.10 by Friday" becomes "customer wants a refund").
• Lost in the middle: models handle the start and end of long inputs well and can miss findings in the middle.
• Tool-result bloat: an order lookup returns 40+ fields when 5 matter, and every call adds more.

• Extract transactional facts into a persistent case facts block sent with every request, outside the summarized history. For multi-issue sessions keep one structured entry per issue.
• Trim tool output to relevant fields before it enters context (a PostToolUse hook is a good place).
• For aggregated inputs, put a key-findings summary at the top and organise details under explicit section headers.
• Ask upstream agents for structured data (key facts, citations, relevance scores, dates) instead of long prose and reasoning chains when downstream budgets are tight.
• The API is stateless: send the complete conversation history each request to stay coherent.

{
  "status": "partial_failure",
  "failure_type": "timeout",
  "attempted": { "query": "AI music generation royalties 2025", "source": "web_search", "retries": 2 },
  "partial_results": [ { "claim": "...", "url": "...", "published_at": "2025-11-03" } ],
  "alternatives": ["query trade-press archive", "narrow to EU market"],
  "coverage_gap": "Music licensing economics"
}

The final report should carry coverage annotations: which findings are well supported and which areas have gaps because sources were unavailable.

Symptom of degradation: late in a long session the model answers inconsistently and talks about "typical patterns" instead of the specific classes it found earlier.

• Scratchpad files: the agent writes key findings to a file (e.g. notes/refund-flow.md) and re-reads it for later questions.
• Delegate to subagents for focused questions ("find all test files", "trace refund flow dependencies"); the main agent keeps the high-level picture.
• Summarize between phases and inject that summary into the next phase's subagents.
• /compact shrinks context when it fills with verbose discovery output.
• Crash recovery: each agent exports its state to a known location; on resume the coordinator loads a manifest and injects the state into agent prompts.

// state/manifest.json
{ "run_id": "audit-2026-10-04", "phase": "analysis",
  "agents": {
    "mapper":   { "status": "done",    "state": "state/mapper.json" },
    "security": { "status": "running", "state": "state/security.json", "last_file": "src/auth/session.ts" },
    "tests":    { "status": "pending" } } }

• Aggregate accuracy hides weak segments. 97% overall can mean 99% on invoices and 70% on handwritten receipts.
• Before reducing human review, measure accuracy by document type and by field.
• Stratified random sampling of high-confidence output keeps measuring the real error rate and catches new error patterns.
• Field-level confidence is only useful after calibration against labeled data. Spend scarce reviewer time on low-confidence or contradictory cases.

{ "claim": "Generative tools used by 38% of indie musicians",
  "excerpt": "...38 percent of surveyed independent artists...",
  "source": { "url": "https://example.org/survey", "title": "Indie Artist Survey" },
  "published_at": "2025-06-10", "collected": "2025-Q1",
  "method": "online survey, n=1,204",
  "conflicts_with": [{ "value": "21%", "source": "Label Assoc. report", "published_at": "2024-02-01" }] }

• Summaries lose attribution unless each claim keeps its claim → source mapping; synthesis must preserve and merge those mappings.
• Conflicting credible numbers: report both with attribution. Do not pick one arbitrarily. Let the coordinator decide how to reconcile.
• Dates prevent false conflicts: 21% in 2024 and 38% in 2025 may be a trend, not a contradiction.
• Structure the report into well-established vs contested findings, keeping methodological context.
• Render content by type: financial data as tables, news as prose, technical findings as lists.