Jonathon's AI Wiki

CCA-F Technical Reference

15 min read

Source: raw/guide_en.MD

A deep technical reference for the Claude Certified Architect — Foundations exam, extracted from a comprehensive community study guide. While the Official Exam Guide lists task statements and the Study Guide provides study strategy, this article contains the actual technical content, code patterns, and implementation details tested on the exam. Organized by technology rather than domain so you can build understanding from the ground up.

Claude API Fundamentals

Request Structure

Every Claude API request follows this pattern:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hi!"},
    {"role": "assistant", "content": "Hello!"},
    {"role": "user", "content": "How are you?"}
  ],
  "tools": [...],
  "tool_choice": {"type": "auto"}
}

Key fields: model (selection), max_tokens (response limit), system (behavior instructions, separate from messages), messages (full conversation history), tools (available tool definitions), tool_choice (selection strategy).

Critical for exam: You must send the full conversation history on every request. The model does not persist state between calls — each request is independent.

The stop_reason Field

ValueMeaningAction
"end_turn"Model finished its responseShow result to user; terminate agent loop
"tool_use"Model wants to call a toolExecute tool, return result, continue loop
"max_tokens"Token limit reachedResponse is truncated; may need to increase limit
"stop_sequence"Stop sequence encounteredHandle per application logic

For agentic systems, "tool_use" and "end_turn" are the only reliable loop control signals.

System Prompt Behavior

  • Not part of messages array; passed separately in system field
  • Has priority over user messages
  • Loaded once, applies throughout conversation
  • Exam trap: System prompt wording can create unintended tool associations. “Always verify the customer” can cause overuse of get_customer even when unnecessary

Context Window

The context window includes: system prompt + full message history + tool definitions + tool results. Three key problems:

  1. Lost-in-the-middle effect — models reliably process the beginning and end of long inputs but can miss details in the middle. Mitigation: place key information near the start or end
  2. Tool result accumulation — every tool call adds output to context. If a tool returns 40+ fields but only 5 matter, most context is wasted
  3. Progressive summarization loss — when compressing history, numeric values, percentages, and dates degrade into vague language (“about,” “roughly”)

Tool Use (tool_use)

Tool Definition Pattern

{
  "name": "get_customer",
  "description": "Finds a customer by email or ID. Returns the customer profile, including name, email, order history, and account status. Use this tool BEFORE lookup_order to verify the customer's identity. Accepts an email (format: user@domain.com) or a numeric customer_id.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": {"type": "string", "description": "Customer email"},
      "customer_id": {"type": "integer", "description": "Numeric customer ID"}
    },
    "required": []
  }
}

Description is the primary selection mechanism. Minimal descriptions (“Retrieves customer information”) lead to misrouting when tools overlap. Include: what it does and returns, input formats and example values, edge cases, when to use vs similar tools.

The tool_choice Parameter

ValueBehaviorUse case
{"type": "auto"}Model decides tool vs textDefault for most cases
{"type": "any"}Must call some toolGuaranteed structured output
{"type": "tool", "name": "X"}Must call specific toolForced first step / pipeline ordering

JSON Schema Design Rules

  1. Required vs optional — mark fields required only if information is always available. Required fields push the model to fabricate values when data is missing
  2. Nullable fields — use "type": ["string", "null"] for information that may be absent. The model returns null instead of hallucinating
  3. Enums with “other” — add "other" + a detail string to avoid losing data outside predefined categories
  4. Enum “unclear” — for cases where the model cannot confidently pick a category; honest “unclear” beats a wrong category
  5. Syntax vs semantic errors — tool_use with JSON schema eliminates syntax errors but does NOT prevent semantic errors (totals not summing, values in wrong fields). Semantic errors need validation checks, retry with feedback, or self-correction

Claude Agent SDK

The Agentic Loop

1. Send request to Claude with tools
2. Receive response
3. Check stop_reason:
   - "tool_use" -> execute tool, append result to history, go to step 1
   - "end_turn" -> task complete, show result
4. Repeat until completion

This is model-driven: Claude decides which tool to call next. Anti-patterns to avoid:

  • Parsing assistant text to detect completion (“Task completed”)
  • Using arbitrary iteration limits (max_iterations=5) as primary stop condition
  • Checking for textual content as completion signal

AgentDefinition Configuration

agent = AgentDefinition(
    name="customer_support",
    description="Handles customer requests for returns and order issues",
    system_prompt="You are a customer support agent...",
    allowed_tools=["get_customer", "lookup_order", "process_refund", "escalate_to_human"],
)

Key parameters: name/description (identification), system_prompt (instructions), allowed_tools (principle of least privilege).

Hub-and-Spoke Multi-Agent Architecture

         Coordinator
        /     |      \
   Subagent1  Subagent2  Subagent3
    (search)   (analysis)   (synthesis)

Coordinator responsibilities: task decomposition, dynamic subagent selection, delegation, result aggregation, error handling, user communication.

Critical principle: subagents have isolated context. They do NOT automatically inherit the coordinator’s history. All context must be explicitly passed in the subagent prompt. Communication flows through the coordinator for observability.

The Task Tool

Subagents are spawned via Task. Coordinator’s allowedTools must include "Task".

Bad (no context): Task: "Analyze the document"

Good (full context): Task: "Analyze the following document. Document: [full text] Prior search results: [results] Output format: [schema]"

Parallel spawning: emit multiple Task calls in one coordinator response — subagents run concurrently.

Hooks

PostToolUse — intercepts tool results before the model processes them:

@hook("PostToolUse")
def normalize_dates(tool_result):
    # Convert Unix timestamp -> ISO 8601
    return normalized_result

PreToolUse (interception) — blocks policy-violating actions:

@hook("PreToolUse")
def enforce_refund_limit(tool_call):
    if tool_call.name == "process_refund" and tool_call.args.amount > 500:
        return redirect_to_escalation(tool_call)

Hooks vs prompt instructions:

AttributeHooksPrompt instructions
GuaranteeDeterministic (100%)Probabilistic (>90%, not 100%)
When to useCritical business rules, financial ops, complianceGeneral preferences, formatting

Rule: When failure has financial, legal, or safety consequences — use hooks, not prompts.

Model Context Protocol (MCP)

Three Resource Types

  1. Tools — functions the agent can call (CRUD, API calls, commands)
  2. Resources — data the agent can read for context (docs, schemas, catalogs)
  3. Prompts — predefined prompt templates

MCP Server Configuration

Project-level (.mcp.json) — for teams, version-controlled:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

User-level (~/.claude.json) — personal, not shared via VCS.

Server selection: prefer existing community MCP servers for standard integrations. Build custom only for unique workflows.

The isError Flag

Structured error (good):

{
  "isError": true,
  "content": {
    "errorCategory": "transient",
    "isRetryable": true,
    "message": "Timeout while calling the orders API.",
    "attempted_query": "order_id=12345"
  }
}

Generic error (anti-pattern): {"isError": true, "content": "Operation failed"} — gives the agent no information for recovery decisions.

MCP Resources

Resources provide context without actions: content catalogs, database schemas, documentation, task summaries. The agent does not need exploratory tool calls to understand data structure — a resource provides an immediate “map.”

Claude Code Configuration

CLAUDE.md Hierarchy

1. User-level: ~/.claude/CLAUDE.md (personal, NOT shared)
2. Project-level: .claude/CLAUDE.md or root CLAUDE.md (shared via VCS)
3. Directory-level: CLAUDE.md in subdirectories (local scope)

Common exam trap: New team member does not receive instructions because they were placed in user-level instead of project-level.

@path Syntax (File Imports)

# Project CLAUDE.md
Coding standards are in @./standards/coding-style.md
Test requirements are in @./standards/testing-requirements.md

Rules: @ immediately before path (no space), relative paths resolved from the containing file, max nesting depth is 5.

.claude/rules/ Directory

An alternative to monolithic CLAUDE.md, organized by topic with conditional loading:

---
paths: ["**/*.test.tsx", "**/*.test.ts"]
---
Tests must use describe/it blocks.
Use data factories instead of hardcoding.

Rules load ONLY when Claude Code edits files matching the paths glob pattern. This saves context and tokens.

When to use .claude/rules/ with paths — conventions applying to files spread across many directories (tests, migrations).

When to use directory-level CLAUDE.md — conventions tied to a specific directory.

Custom Slash Commands and Skills

Project commands (.claude/commands/) — shared via VCS, available to all team members.

User commands (~/.claude/commands/) — personal, not shared.

Skills (.claude/skills/SKILL.md) — advanced commands with frontmatter:

---
context: fork
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: "Path to the directory to analyze"
---
ParameterPurpose
context: forkIsolated subagent; verbose output does not pollute main session
allowed-toolsRestricts available tools (security)
argument-hintPrompts for argument when invoked without parameters

Skill vs CLAUDE.md: Skills are on-demand for specific tasks; CLAUDE.md is always-loaded for general standards.

Planning Mode vs Direct Execution

Planning mode: investigation and planning only, no changes. Uses Read, Grep, Glob to explore. Safe exploration with no side effects.

Use for: large changes (dozens of files), multiple plausible approaches, architectural decisions, unfamiliar codebases, 45+ file migrations.

Direct execution: single-file fixes with clear stack trace, adding one validation check, well-understood changes.

Combined approach: plan mode for investigation, user approves, direct execution for implementation.

Explore subagent: isolates verbose output, returns only a summary, prevents context exhaustion.

CI/CD Integration

-p (or --print) flag — non-interactive mode for pipelines:

claude -p "Analyze this pull request for security issues"

Structured output:

claude -p "Review this PR" --output-format json --json-schema '{"type":"object",...}'

Session context isolation: The same session that generated code is less effective at reviewing it (retains reasoning context). Use an independent instance for review.

Duplicate prevention: Include prior review results in context; instruct Claude to report only new or unresolved issues.

/compact and /memory Commands

/compact — compresses context by summarizing prior history. Used in long sessions. Risk: exact numeric values, dates, and specifics can be lost.

/memory — opens CLAUDE.md for editing to save notes, preferences, and context that persists across sessions.

Session Management

--resume <session-name> — continues a named session with saved context. Risk: files may have changed since the prior session.

fork_session — creates independent branches from shared context for comparing approaches:

Investigation -> fork_session -> Approach A (Redux) / Approach B (Context API)

When to start fresh: tool results are stale, significant time has passed. A new session with a summary is more reliable than resuming with old tool data.

Prompt Engineering Techniques

Consolidated reference: Prompt Engineering Essentials — the full write-up of the patterns below, with Try-It steps and open questions. This section is kept as CCA-F exam context.

Few-Shot Prompting

Include 2-4 input/output examples to demonstrate expected behavior. More effective than textual descriptions because examples unambiguously show format and decision logic.

Types: ambiguous scenario handling, output formatting, acceptable vs problematic code, extraction from different document formats, informal measurement normalization.

Format normalization rules: Add alongside strict schemas to prevent semantic errors (dates to ISO 8601, currency to numeric + code, percentages to decimal fractions).

Explicit Criteria vs Vague Instructions

Bad: “Check code comments for accuracy. Be conservative.”

Good: “Flag a comment as problematic ONLY if: (1) described behavior contradicts actual code behavior, (2) references a non-existent function, (3) TODO refers to a fixed bug. Do NOT flag: stylistically outdated, minor wording inaccuracies, missing comments.”

Prompt Chaining

Break complex tasks into sequential focused steps to avoid attention dilution:

Step 1: Analyze auth.ts (local issues) -> list
Step 2: Analyze database.ts (local issues) -> list
Step 3: Integration pass (cross-file) -> cross-cutting issues

Use prompt chaining for predictable tasks; dynamic decomposition for open-ended investigations.

The Interview Pattern

Claude asks clarifying questions before implementation. Useful for unfamiliar domains, tasks with non-obvious implications, multiple viable approaches.

Validation and Retry-with-Feedback

When extracted data fails validation: retry with the original document, the previous extraction, and the specific error message.

Retries are effective for: format errors, structural errors, arithmetic inconsistencies.

Retries are NOT effective for: absent information, required context in external documents.

Pydantic for validation: structural validation (types, requiredness), semantic validation (custom validators), validate-retry loops, JSON Schema generation for tool_use.

Self-Correction Pattern

Extract both stated_total and calculated_total. If they differ, conflict_detected flags the discrepancy for handling.

Message Batches API

AttributeValue
Savings50% vs synchronous
Processing windowUp to 24 hours (no latency SLA)
Multi-turn tool callingNOT supported
Correlationcustom_id field

When to use batch: overnight reports, weekly audits, bulk processing (non-blocking).

When to use synchronous: pre-merge checks, interactive review, anything blocking a developer.

Failure handling: identify failures by custom_id, modify strategy (split long docs), resubmit only failed documents.

Error Handling in Multi-Agent Systems

Error Categories

CategoryRetryableAgent action
Transient (timeout, 503)YesRetry with backoff
Validation (bad input)No (fix input)Modify request and retry
Business (policy violation)NoExplain; propose alternative
Permission (access denied)NoEscalate

Anti-Patterns

  • Generic “search unavailable” — coordinator cannot decide recovery
  • Silent suppression (empty result = success) — hides failures
  • Aborting entire workflow on one failure — loses partial results
  • Infinite retries inside subagent — wastes latency and resources

Structured Error Response

{
  "status": "partial_failure",
  "failure_type": "timeout",
  "attempted_query": "AI impact on music industry 2024",
  "partial_results": [{"title": "...", "url": "...", "relevance": 0.8}],
  "alternative_approaches": ["Try narrower query", "Use alternative source"],
  "coverage_impact": "Not covered: AI impact on music production"
}

Coverage Annotations in Synthesis

Mark sections as FULL COVERAGE or PARTIAL COVERAGE with explanations of gaps. Transparency about incomplete data is required.

Context Management Patterns

Case Facts Block

Extract key facts into a persistent structured block included in every prompt, regardless of summarization:

=== CASE FACTS ===
Customer ID: CUST-12345
Order ID: ORD-67890
Amount: $89.99
Issue: Damaged item
Status: Pending manager approval
===

Tool Result Trimming

Use PostToolUse hooks to strip verbose tool responses to relevant fields before they enter context.

Position-Aware Input

Place key findings at the top, detailed results in the middle with section headers, action items at the end. This mitigates lost-in-the-middle effects.

Scratchpad Files

In long investigations, write key findings to a scratchpad file. When context degrades or in a new session, consult the scratchpad instead of re-running discovery.

Subagent Context Delegation

Delegate verbose exploration to subagents. Main agent keeps a one-line summary instead of 15 files worth of context. Subagents get minimal context (specific task + necessary data) and return structured results, not raw dumps.

Structured State Persistence (Crash Recovery)

Each agent exports state to a known location. Coordinator loads a manifest on resume to determine which agents completed, which are in progress, and what to re-run.

Provenance Preservation

The Attribution Loss Problem

During summarization, “claim to source” links get lost. Always preserve structured claim-source mappings:

{
  "claim": "The AI music market is estimated at $3.2B.",
  "source_url": "https://example.com/report",
  "source_name": "Global AI Music Report 2024",
  "publication_date": "2024-06-15"
}

Handling Conflicting Data

Preserve both values with attribution. Do not arbitrarily choose one. Let the coordinator decide.

Include Dates

Without dates, temporal differences get misinterpreted as contradictions. “Source A (2023): 10%, Source B (2024): 15%” is likely growth, not a conflict.

Render by Content Type

Financial data as tables, news as prose, technical findings as structured lists, time series as chronological ordering. Do not force uniform format.

Built-in Tools Reference

TaskTool
Find files by name/patternGlob
Search within filesGrep
Read a fileRead
Write a new fileWrite
Edit existing file preciselyEdit (unique text match)
Run a shell commandBash

Incremental investigation: Grep entry points → Read found files → Grep usages → Read consumers → repeat.

Edit fallback: When Edit fails due to non-unique match, use Read + Write.

ResourceURL
Messages APIhttps://platform.claude.com/docs/en/api/messages
Tool Usehttps://platform.claude.com/docs/en/build-with-claude/tool-use
Message Batcheshttps://platform.claude.com/docs/en/build-with-claude/message-batches
Agent SDK Overviewhttps://platform.claude.com/docs/en/agent-sdk/overview
Agent SDK Hookshttps://platform.claude.com/docs/en/agent-sdk/hooks
Agent SDK Subagentshttps://platform.claude.com/docs/en/agent-sdk/subagents
Agent SDK Sessionshttps://platform.claude.com/docs/en/agent-sdk/sessions
MCP Spechttps://modelcontextprotocol.io/
MCP Toolshttps://modelcontextprotocol.io/docs/concepts/tools
MCP Resourceshttps://modelcontextprotocol.io/docs/concepts/resources
Claude Code Docshttps://code.claude.com/docs/en/overview
Claude Code Memoryhttps://code.claude.com/docs/en/memory
Claude Code Skillshttps://code.claude.com/docs/en/skills
Claude Code Hookshttps://code.claude.com/docs/en/hooks
Claude Code Sub-agentshttps://code.claude.com/docs/en/sub-agents
Claude Code MCPhttps://code.claude.com/docs/en/mcp
Claude Code GitHub Actionshttps://code.claude.com/docs/en/github-actions
Claude Code Headlesshttps://code.claude.com/docs/en/headless
Prompt Engineering Guidehttps://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview
Extended Thinkinghttps://platform.claude.com/docs/en/build-with-claude/extended-thinking
Anthropic Cookbookhttps://github.com/anthropics/anthropic-cookbook

Out-of-Scope Topics

The following are explicitly NOT on the CCA-F exam:

  • Fine-tuning Claude models or training custom models
  • API authentication, billing, or account management
  • Detailed implementation in specific programming languages (beyond tool/schema config)
  • Deploying or hosting MCP servers (infrastructure, networking, containers)
  • Claude’s internal architecture, training process, or model weights
  • Constitutional AI, RLHF, or safety training methodologies
  • Embedding models or vector database implementation details
  • Computer use (browser automation, desktop interaction)
  • Image analysis capabilities (Vision)
  • Streaming API or server-sent events
  • Rate limiting, quotas, or detailed API cost calculations
  • OAuth, API key rotation, or authentication protocol details
  • Cloud-provider-specific configurations (AWS, GCP, Azure)
  • Performance benchmarks or model comparison metrics
  • Prompt caching implementation details (beyond knowing it exists)
  • Token counting algorithms or tokenization specifics

Practical Exercises

The source guide includes 4 hands-on exercises that map to exam domains:

  1. Multi-tool Agent with Escalation Logic (Domains 1, 2, 5) — Define 3-4 MCP tools with detailed descriptions, implement agentic loop with stop_reason checking, add structured error responses and interception hooks for threshold-based escalation
  2. Claude Code Team Configuration (Domains 3, 2) — Create project-level CLAUDE.md, .claude/rules/ with YAML frontmatter paths, .claude/skills/ with context: fork and allowed-tools, .mcp.json with env vars + personal override
  3. Structured Data Extraction Pipeline (Domains 4, 5) — JSON schema extraction tool, validation/retry loops, few-shot examples, batch processing with custom_id failure handling, field-level confidence routing
  4. Multi-agent Research Pipeline (Domains 1, 2, 5) — Coordinator with Task tool, parallel subagents, structured claim-source output, simulated timeout with partial results, conflicting data preservation

Key Takeaways

  • The Claude API is stateless — you must send full conversation history on every request; stop_reason is the only reliable loop control signal
  • Tool descriptions are more important than implementations — the model selects tools based on descriptions, not capability
  • tool_use with JSON schemas eliminates syntax errors but NOT semantic errors; validation and self-correction are still required
  • Hooks provide deterministic enforcement; prompts are probabilistic — use hooks for anything with financial, legal, or safety consequences
  • Subagents have isolated context that must be explicitly passed; all communication routes through the coordinator
  • Context management is an active discipline: trim tool results, use case-facts blocks, position key info at start/end, delegate verbose work to subagents
  • The out-of-scope list is as valuable as the in-scope content — it narrows study focus significantly

Try It

  1. Work through each exercise above sequentially — they are designed to build on each other and cover all 5 domains
  2. Memorize the official doc links — the exam may reference specific documentation sections
  3. Use the out-of-scope list to eliminate study time on topics that will not appear
  4. For each code pattern, implement it yourself rather than just reading — the exam tests whether you understand the pattern well enough to recognize correct implementations
  5. Cross-reference each section against the Official Exam Guide task statements to verify your coverage is complete

Graph View

Backlinks