Courseware / Claude AI / course-071
Claude Certified Architect Foundations (CCA-F) Exam: Comprehensive Guide
Tweet@Harry_The_NerdView Source →

🎙 Podcast Version

2-host dialogue — ALEX & SAM discuss this course.

Claude Certified Architect Foundations (CCA-F) Exam: Comprehensive Guide

Overview

This course provides an exhaustive, technical walk‑through of the five official domains covered in the Claude Certified Architect Foundations (CCA‑F) exam. It explains how to move beyond simple conversational prompts and treat Claude as a deterministic engine that can be orchestrated, secured, and integrated into production‑grade software pipelines. Every concept, example, code snippet, and best practice from the source material is presented in full detail so that learners can architect reliable agentic systems, configure Claude Code for team workflows, and engineer prompts that yield guaranteed structured output.

Key Concepts

Agentic Loop and Stop Reasons

At the heart of any autonomous agent built with Claude is the Agentic Loop, a deterministic interaction pattern between your application and the Claude engine. Unlike a free‑form chat where the model decides when to stop, the Anthropic Messages API returns an explicit stop_reason field on every response envelope. Your application must inspect this field after each API call to decide the next action. The two primary stop reasons are:

  • tool_use – Claude has finished generating conversational text and is waiting for you to execute a piece of code. The response includes the exact tool name and a JSON payload of parameters that your local code must run. After execution, you feed the result back to Claude as a tool_result message.
  • end_turn – Claude has completed its reasoning path and produced its final answer. The loop can safely terminate; no further tool execution is required.

A typical request/response flow looks like this:

[Your Application] --> Sends Payload --> [Claude Engine]
        ▲                                          │
        │                                          ▼
        └─────────── Evaluates stop_reason ────────┘

If stop_reason equals tool_use, your code extracts tool_use_id, name, and input, runs the corresponding function, and then posts a new message with role: "assistant" and a tool_result block containing the output. If it equals end_turn, you display the content to the user and end the loop. This deterministic signaling eliminates guesswork and enables reliable agentic orchestration.

Hub‑and‑Spoke (Orchestrator‑Worker) Architecture

When a single agent receives a large project history, the prompt becomes bloated with irrelevant tokens—a phenomenon called Context Pollution. The prescribed solution is the Hub‑and‑Spoke design, also known as the Orchestrator‑Worker pattern.

  • Orchestrator (Hub) – A master agent that receives the user request, decomposes it into discrete tasks, and dispatches focused Worker subagents.
  • Worker (Spoke) – Hyper‑focused agents that receive only the minimal data they need to accomplish a specific task.

To keep the system fast and token‑efficient, implement a Need‑to‑Know Context Sandboxing strategy:

  1. The orchestrator extracts only the specific variables required by a worker (e.g., a file path, a configuration value, a numeric ID).
  2. Those variables are placed in a clean, miniature payload that is sent to the worker.
  3. The worker runs in an isolated context window; upon returning its structured answer, its sandbox is destroyed immediately.
  4. No conversation history or extraneous data is copied down to the worker, preventing token waste and reducing the risk of prompt leakage.

This pattern scales to arbitrarily complex workflows while maintaining deterministic behavior and low latency.

Securing Pipelines with SDK Lifecycle Hooks

Enterprise‑grade agents must operate inside hard security boundaries. The Anthropic SDK provides Lifecycle Hooks—programmatic code blocks that run outside Claude’s probabilistic reasoning, allowing you to validate inputs and outputs before they touch the model or your infrastructure.

  • Pre‑Execution Input Validation Hooks – Intercept the raw user text before it is sent to the Anthropic API. Inside the hook you can scan for prompt injection attempts, malicious formatting, or prohibited keywords. If a violation is detected, you abort the turn and return an error to the user, preventing the malicious prompt from ever reaching Claude.
  • Post‑Execution Payload Validation Hooks – Capture Claude’s output before it triggers any action in your system (e.g., before a tool call is executed). The hook can inspect generated parameters, verify they conform to your security rules (such as allowed value ranges, permitted file paths, or approved enum members), and cancel the operation if a rule is broken. This keeps your underlying network and services completely safe.

Because these hooks execute in your local runtime (TypeScript, Python, etc.), they are fully deterministic and can be unit‑tested independently of the model.

The 3‑Level CLAUDE.md Hierarchy

Claude Code uses a structured configuration system to map engineering preferences. Settings are organized in three layers, with specificity winning—lower levels override higher levels when there is a conflict.

  1. Global User Level (~/.config/claude/rules.md) – Stores universal personal preferences that apply to every project on your machine.
  2. Repository Project Level (/CLAUDE.md at the repo root) – Contains the core tech stack, build scripts, and team‑wide conventions that should be shared across all contributors.
  3. Local Directory Level (/**/CLAUDE.md in sub‑folders) – Holds targeted microservice‑specific rules, such as overrides for a particular service’s linting or testing commands.

A common anti‑pattern is placing team instructions in the global user file. Because those settings reside only on your laptop, teammates’ agents lack the required context, leading to broken build loops. The production‑grade fix is to commit a /CLAUDE.md file directly to the root of your remote Git repository, ensuring every clone inherits the exact same ruleset.

Extending Capability via Slash Commands and Skills

To bypass the ambiguity of natural language, you can define Custom Slash Commands inside your CLAUDE.md configuration. Slash commands act as hard‑coded intent routers that instantly inject a predefined system prompt overlay and restrict the model to a whitelist of tools.

Example slash‑command definition (JSON format stored under the commands key):

{
  "commands": {
    "review": {
      "description": "Performs a security audit on code changes.",
      "system_prompt_overlay": "You are a Principal Security Architect. Scan files for OWASP vulnerabilities.",
      "allowed_tools": ["file_read", "file_grep"]
    }
  }
}

When a developer types /review, Claude Code:

  • Ignores the standard classification pipeline.
  • Injects the system_prompt_overlay as the model’s system message.
  • Limits the model to invoking only file_read and file_grep tools.

For maintainability, package these distinct behaviors into modular Agent Skills files located in a dedicated /.claude/skills/ folder. Each skill file contains its own slash‑command definition, system prompt, and tool allowlist. The main CLAUDE.md then references or imports these skills, decoupling workflow logic from core configuration assets.

Headless Automation in CI/CD Pipelines

Running Claude Code inside automated CI/CD environments (e.g., GitHub Actions, GitLab CI) requires a non‑interactive execution profile. Invoking a raw claude command in a headless build node would cause the runner to freeze or throw a fatal terminal error because the command expects an interactive TTY.

The non‑negotiable rule is to launch Claude Code with the -p (or --print) flag. This flag forces headless mode:

  • Takes an input string from stdin or command line.
  • Locks out terminal prompts, preventing any waiting for user input.
  • Executes the task completely autonomously.
  • Dumps telemetry data directly to stdout.
  • Exits with a clear system exit code that CI systems can interpret for success/failure.

Example CI step:

- name: Run Claude Code analysis
  run: |
    echo "Analyze the latest commit for security issues" | claude -p --command review

The -p flag guarantees deterministic, scriptable behavior suitable for pipelines.

Why tool_use Defeats Prompt‑Based JSON

Attempting to force structured output by instructing the model to “Return ONLY a valid JSON object” is unreliable. Claude may:

  • Wrap the JSON in markdown code fences.
  • Insert trailing commas.
  • Append conversational text before or after the JSON.
  • Produce malformed syntax that causes parser crashes in downstream code.

The professional standard is to use the native tool_use (Function Calling) API layer. When you register an explicit tool schema with the Anthropic Messages API, the model’s token probability distribution is physically constrained at the sampling layer. The model can only emit tokens that conform to the supplied JSON schema, guaranteeing:

  • No markdown wrappers.
  • No extra text.
  • No syntax errors.
  • Fully valid JSON that matches the schema exactly.

Thus, tool_use provides deterministic, schema‑enforced structured output.

Restrictive JSON Schema Design

To prevent hallucination of random or inconsistent values within JSON objects, you must write highly restrictive schemas. Instead of relying on generic primitive types, apply strict logical guardrails:

  • enum (Enumerations) – Limits a string field to a precise array of permitted values.
  • minimum and maximum – Sets hard floors and ceilings on numeric fields to block out‑of‑bounds metrics.

Example schema that enforces a status field and a quality score:

{
  "status": {
    "type": "string",
    "enum": ["PENDING", "APPROVED", "REJECTED"]
  },
  "quality_score": {
    "type": "number",
    "minimum": 0.0,
    "maximum": 1.0
  }
}

With this schema, Claude cannot output "status": "UNKNOWN" or "quality_score": 1.5; any attempt would be blocked at the API level, and the model would be forced to regenerate a compliant value.

The 2 to 4 Example Rule for Few‑Shot Learning

Few‑shot prompting teaches Claude complex patterns by providing examples directly in the prompt. However, injecting too many examples harms performance:

  • Each additional example consumes input tokens on every API call, increasing latency and cost.
  • Beyond 4 examples, the model risks overfitting—it memorizes the superficial mechanics of the examples rather than extracting the underlying rule.
  • Worse, wasting few‑shot slots on obvious, easy cases reduces the model’s ability to handle ambiguous scenarios.

The 2 to 4 Example Rule advises you to supply between two and four high‑quality examples, focusing exclusively on The Gray Zone—the boundary where surface‑level cues conflict with true operational logic. These are the cases where a naïve heuristic would fail, forcing the model to learn the deeper pattern.

Mandatory Structural Reasoning Tag

When few‑shot examples are used, each example should be wrapped in a Structural Reasoning Tag that makes the model’s internal reasoning explicit. The tag consists of three child elements:

  • <input> – The raw user query or problem statement.
  • <reasoning> – A step‑by‑step explanation of how the input maps to the desired output, citing relevant facts or domain knowledge.
  • <output> – The exact structured result (usually JSON) that the model should emit.

Example from the source:

<example>
  <input>Error: Timeout encountered during TLS handshake.</input>
  <reasoning>
    1. The error occurs during the TLS handshake phase.
    2. TLS operations exist at the transport network layer, prior to application logic.
    3. Therefore, this must map to the NETWORK infrastructure category.
  </reasoning>
  <output>{"category": "NETWORK"}</output>
</output>
</example>

By providing the reasoning chain, you teach Claude not just the mapping but the logical justification, improving generalization to novel inputs that share similar reasoning patterns.

Deep Dive

Building a production‑grade Claude‑based system requires stitching together the concepts above into a coherent workflow. Begin by defining the overall goal and decomposing it into discrete tasks using the Hub‑and‑Spoke orchestrator. The orchestrator receives the user request, creates a plan, and for each task spawns a worker subagent with a Need‑to‑Know payload.

Each worker operates inside an Agentic Loop. It sends a prompt to Claude, inspects the returned stop_reason, and if it is tool_use, executes the prescribed local function (e.g., reading a file, invoking a microservice, running a security scan). The worker then returns a tool_result containing the function’s output. This loop repeats until Claude returns end_turn, at which point the worker yields its final structured answer.

To guarantee that the worker’s output conforms to a required schema, register the corresponding tool with a restrictive JSON schema (using enum, minimum, maximum). Because the model’s sampling layer is constrained to the schema, you receive valid JSON without any post‑processing cleanup.

Before any user text reaches Claude, run it through a Pre‑Execution Input Validation Hook that blocks prompt injection and disallowed keywords. After Claude produces a tool call, execute a Post‑Execution Payload Validation Hook that verifies the generated arguments against your security policy (e.g., ensuring file paths stay within an allowed directory, confirming numeric values fall within defined ranges). If either hook fails, the turn is aborted and an error is returned to the orchestrator, which can then decide to retry with a corrected prompt or escalate to a human.

When the orchestrator collects all worker answers, it assembles them into the final response. If the final answer must be presented to a user or downstream system, you can optionally wrap it in a Structural Reasoning Tag for transparency, especially in audit‑heavy environments.

For developer‑facing tooling, encode team‑wide preferences in a repository‑level /CLAUDE.md file. Define slash commands for common operations (e.g., /review for security audits) and store each command’s implementation as a skill in /.claude/skills/. In CI/CD pipelines, invoke Claude Code headlessly with the -p flag to run these commands automatically on every pull request, ensuring that security checks, linting, or code generation happen without human intervention.

Throughout this pipeline, the Agentic Loop guarantees deterministic stopping behavior, the Hub‑and‑Spoke architecture prevents context pollution, Lifecycle Hooks enforce hard security boundaries, the 3‑Level CLAUDE.md hierarchy provides consistent configuration, slash commands and skills give repeatable, tool‑restricted workflows, tool_use with restrictive schemas yields reliable structured output, and the 2‑to‑4 Example Rule plus Structural Reasoning Tags ensure few‑shot prompts teach genuine patterns rather than superficial memorization.

Practical Application

Consider a real‑world scenario: a financial services company wants an automated system that, given a user‑submitted trade request, validates the request, checks compliance, and returns a structured decision (APPROVE, REJECT, or NEEDS_MORE_INFO). The system must run inside a secured Kubernetes cluster and be triggered by a GitHub Actions workflow on each pull request that modifies trading logic.

  1. Orchestrator Design – Create an Orchestrator agent that receives the trade request JSON. It splits the request into three subtasks: (a) validate input fields, (b) run compliance checks against a rule engine, (c) calculate risk metrics.
  2. Worker Subagents – For each subtask, spawn a focused worker:

* Validation Worker – Receives only the raw trade fields. Its tool set includes file_read (to load a schema file) and a custom validation function. It uses a restrictive schema that enumerates allowed asset types (["STOCK", "BOND", "OPTION", "FUTURE"]) and sets numeric minima/maxima for quantity and price.

* Compliance Worker – Receives the validated trade and a list of regulatory rules. Its tool set includes file_grep to search rule files and a custom function that returns a compliance status. The output schema uses an enum: ["COMPLIANT", "VIOLATION", "WARNING"].

* Risk Worker – Receives the trade and market data. Its tool set includes a custom pricing model function. It returns a JSON with a risk_score number constrained between 0 and 1 via minimum/maximum.

  1. Agentic Loops – Each worker follows the loop: send prompt → inspect stop_reason → if tool_use, run the local function → feed tool_result back → repeat until end_turn. The orchestrator collects the three JSON outputs.
  2. Security Hooks –

* Pre‑execution hook scans the incoming trade request for strings like ignore previous instructions or system: and blocks them.

* Post‑execution hook validates that any file paths accessed by workers are restricted to /app/data/ and that numeric outputs stay within the declared ranges.

  1. Configuration – Store team‑wide preferences in /CLAUDE.md at the repo root:

* Define a slash command /tradecheck with description “Run full trade validation, compliance, and risk assessment”.

* Set system_prompt_overlay to “You are a Senior Risk Engineer. Follow the orchestration plan and produce a final decision.”

* List allowed_tools as [“file_read”, “file_grep”, “custom_validation”, “custom_compliance”, “custom_risk”].

* Place the implementation of each custom tool in /.claude/skills/validation.ts, /.claude/skills/compliance.ts, /.claude/skills/risk.ts.

  1. CI/CD Integration – In GitHub Actions, add a step:

```yaml

- name: Execute trade check

run: |

echo "${{ github.event.pull_request.body }}" | claude -p --command tradecheck

```

The -p flag ensures headless execution; the step fails if the exit code is non‑zero, blocking the merge if any validation, compliance, or risk issue is detected.

  1. Structured Output & Reasoning – The final decision from the orchestrator is emitted as:

```json

{

"decision": "APPROVE",

"reasoning": [

"All required fields passed validation.",

"No compliance violations detected.",

"Risk score 0.32 is within acceptable threshold (<0.5)."

]

}

```

If you wish to audit the model’s internal reasoning, you can embed each intermediate worker’s output inside a <example> block with <input>, <reasoning>, and <output> tags, following the Structural Reasoning Tag pattern.

This end‑to‑end example demonstrates how every concept from the source material—agentic loops, stop reasons, hub‑and‑spoke, lifecycle hooks, CLAUDE.md hierarchy, slash commands, skills, headless -p flag, tool_use with restrictive schemas, few‑shot example limits, and structural reasoning—can be applied to build a secure, deterministic, and scalable AI‑powered system.

Key Takeaways

  • The Agentic Loop relies on deterministic stop_reason values (tool_use and end_turn) to orchestrate tool execution and termination; your application must inspect this field on every API response.
  • Hub‑and‑Spoke (Orchestrator‑Worker) architecture combined with Need‑to‑Know Context Sandboxing eliminates context pollution and keeps token usage low by passing only essential data to workers.
  • SDK Lifecycle Hooks provide hard security boundaries: pre‑execution hooks block malicious input, post‑execution hooks prevent unsafe tool calls.
  • Claude Code’s configuration follows a three‑level hierarchy (global, repo, local) where specificity wins; team rules belong in /CLAUDE.md at the repo root, not in the user‑level file.
  • Slash commands act as hard‑coded intent routers; pair them with Agent Skills in /.claude/skills/ for maintainable, reusable workflows.
  • Headless execution in CI/CD requires the -p/--print flag to avoid terminal prompts and enable deterministic, scriptable invocations.
  • Use the native tool_use (Function Calling) API instead of prompting for JSON; it guarantees schema‑valid output by constraining the model’s token distribution at the sampling layer.
  • Write restrictive JSON schemas employing enum, minimum, and maximum to prevent hallucinated or out‑of‑bounds values.
  • Follow the 2‑to‑4 Example Rule for few‑shot learning: supply only two to four high‑quality examples that focus on ambiguous Gray‑Zone cases, avoiding obvious or excessive examples.
  • When providing few‑shot examples, wrap each in a Structural Reasoning Tag (<input>, <reasoning>, <output>) to teach the model the logical justification behind mappings.
  • All code snippets from the source (slash‑command JSON, restrictive schema JSON, structural reasoning XML, tool_result error, custom_id example) are directly applicable and should be copied verbatim into your projects where appropriate.
  • Combining these patterns yields production‑grade Claude applications that are secure, efficient, reliable, and easy to maintain across teams and automated pipelines.

Common Pitfalls / What to Watch Out For

  • Assuming Claude will stop generating text based on vague cues; always rely on the explicit stop_reason field returned by the API.
  • Placing team‑specific instructions in the global ~/.config/claude/rules.md file; this prevents teammates from receiving the same configuration and leads to inconsistent agent behavior.
  • Overloading few‑shot prompts with more than four examples, which wastes tokens and encourages overfitting on superficial patterns.
  • Using generic types like string or number in JSON schemas
← Previous