Claude Certified Architect (CCA) — Exam Study Notes Part 16 of 16
AI & Machine Learning

Key Concepts & Glossary

lex@lexgaines.com · · 11 min read
Quick-reference guide to all major technologies and concepts on the CCA exam: Agent SDK, MCP, Claude Code, Claude API, Message Batches API, JSON Schema, and built-in tools.

This file is a quick-reference guide to all major technologies and concepts covered by the CCA Exam. Use this to look up definitions, key details, and exam-relevant facts about each technology.

Technologies & Concepts

Claude Agent SDK

AgentDefinition: A configuration object that defines an agent's behavior, including its model, system prompt, tools, and execution settings. Use this when you need to create a reproducible agent.

Agentic Loops: The core execution model where an agent calls tools, receives responses, and decides whether to continue (via stop_reason) or end the turn. Loop logic: while stop_reason != "end_turn": call_tool() → process_response() → continue_loop(). Max iterations (e.g., 10-20 calls) prevent infinite loops.

stop_reason: Returned by the API to indicate why Claude stopped generating: - "end_turn": Agent finished its task naturally (most common) - "tool_use": Agent called a tool and is waiting for response (continue the loop) - "max_tokens": Reached token limit (may need more tokens for this task) - "stop_sequence": Hit a manual stop sequence (rare)

Hooks (PostToolUse, etc.): Execution points where custom logic can intercept and modify behavior. Example: PostToolUse hook blocks tool_calls that violate business rules (e.g., refunds > $500) before they execute. Hooks provide deterministic guarantees that prompts alone cannot (prompts are probabilistic).

Task Tool: Enables an agent to spawn and delegate work to subagents. Signature: Task(type: "run", instructions: str, allowedTools?: [tool_names]). Used in multi-agent systems for task decomposition and parallel execution.

allowedTools: Restricts which tools a subagent can access. Example: allowedTools: ["Read", "Grep"] means the subagent can only read and search files, not modify them. Implements principle of least privilege.

Domains: Agentic Architecture & Orchestration

Model Context Protocol (MCP)

MCP Servers: External processes that provide tools and resources to Claude. Communicate over stdio or HTTP. Examples: mcp-server-github (GitHub access), mcp-server-filesystem (file operations), mcp-server-brave-search (web search).

Tools (in MCP context): Definitions of functions that Claude can call. Each tool has: name, description, input schema (JSON Schema), and backend implementation. Good tool descriptions include input formats, examples, edge cases, and boundaries.

Resources: Non-executable data exposed by MCP servers (e.g., "latest GitHub PR list," "customer database schema"). Resources are context, not actions. Claude can read them but not modify them directly.

isError Flag: Set to true in tool responses to indicate an error occurred (vs. a successful response that happens to contain error data). Format: {isError: true, content: "error message"}. Helps coordinator agents understand failures vs. normal results.

.mcp.json: Project-level MCP server configuration. Defines which servers to load and their settings. Supports environment variable expansion: {"servers": [{"env": {"TOKEN": "${MY_TOKEN}"}}]} loads MY_TOKEN from shell environment.

~/.claude.json: Personal MCP server configuration (user's home directory). Merges with project-level config. Use for personal tools that shouldn't be committed to projects.

Environment Variable Expansion: In .mcp.json, use ${VAR_NAME} to substitute environment variables. Example: "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"} reads the GITHUB_TOKEN from the developer's shell before launching the server.

Domains: Tool Design & MCP Integration

Claude Code

CLAUDE.md Hierarchy: A system of context files that configure Claude Code behavior at different scopes: - CLAUDE.md at project root: applies globally to all work - path/.claude/CLAUDE.md or .claude/rules/: applies to specific directories or file patterns - Files at deeper levels override parent levels - Use for: coding conventions, style guides, testing requirements, security policies

Example:

/CLAUDE.md (global context)
├── /frontend/.claude/CLAUDE.md (React-specific)
├── /backend/.claude/CLAUDE.md (Python-specific)
└── /infra/.claude/CLAUDE.md (Terraform-specific)

.claude/rules/ with YAML Frontmatter: Advanced rule system that applies rules based on file path patterns. Each rule file has: - YAML frontmatter with path: "glob pattern" (e.g., path: "frontend/**") - Rule content (conventions, constraints, guidance) - Rules are matched automatically; no manual intervention needed - Multiple rules can apply to one file (all matching rules apply)

Example rule file (.claude/rules/frontend.yaml):

---
path: "frontend/**"
---
All React components must:
1. Use hooks (no class components)
2. Include PropTypes or TypeScript
3. Have tests in __tests__/ folder

.claude/commands/: Directory where slash commands are stored. Commands in this directory are automatically available to all developers in the project. Structure: .claude/commands/review.md creates a /review command.

.claude/skills/ with SKILL.md Frontmatter: Reusable automated workflows. Each skill has a SKILL.md file with frontmatter: - name: The skill's display name - description: What the skill does - context: fork_session | inherit: Whether to create new session (isolated) or inherit current session - allowed-tools: [list]: Which tools the skill can use (principle of least privilege)

Example SKILL.md:

---
name: Code Review
description: Analyze code before PR
context: fork_session
allowed-tools: [Read, Write, Bash, Grep]
---
Perform thorough code review...

Plan Mode: A special execution mode for complex, multi-file architectural decisions. Claude explores the codebase, understands dependencies, and designs an approach before making changes. Prevents costly mistakes in large refactors. Use for: microservices restructuring, major architectural changes, migrating between frameworks.

Direct Execution Mode: Standard mode where Claude makes changes immediately without planning. Fast for straightforward tasks (add a function, fix a bug, update a comment). Use when the task is clear and doesn't require architectural analysis.

Claude Code CLI: - -p or --print flag: Non-interactive mode, suitable for CI/CD. Outputs to stdout and exits without waiting for input. - --output-format json: Formats output as JSON (useful for parsing in scripts) - --json-schema [schema]: Constrains output to a JSON schema - --resume: Resumes an interrupted session - fork_session: Creates an isolated session (used in skills) - Explore subagent: Automatic subagent for exploring and understanding codebases

Domains: Claude Code Architect, Claude Code Configuration & Workflows

Claude API

tool_use: The mechanism Claude uses to call tools. API response includes type: "tool_use" blocks with tool name, ID, and input. You parse these and return results via the API's role: "user" message with type: "tool_result".

tool_choice: Constrains which tools Claude can call: - "auto" (default): Claude chooses tools freely - {"type": "tool", "name": "get_customer"}: Force a specific tool - {"type": "any"}: Require Claude to use some tool (no text-only responses) - Useful for enforcing prerequisites (e.g., force get_customer before lookup_order)

stop_reason Values: - "end_turn": Claude finished naturally (most common) - "tool_use": Claude called a tool, continue loop - "max_tokens": Reached token limit - "stop_sequence": Hit manual stop sequence (rare)

max_tokens: Maximum number of tokens Claude can generate. Higher values allow longer reasoning and responses but increase cost. Default: varies by model. Set higher (4000+) for complex analysis, lower (1000) for simple tasks.

System Prompts: The base instructions Claude follows. In agents, system prompts guide tool selection, escalation decisions, and reasoning. Good system prompts are specific (not "be helpful") and include decision rules ("Escalate refunds > $500").

Domains: Prompt Engineering & Structured Output, Context Management & Reliability

Message Batches API

Purpose: Process multiple requests in a single batch for 50% cost savings. Requests are processed within a 24-hour window (no latency guarantee).

Cost-Benefit: 50% cheaper, but unsuitable for time-sensitive work (pre-merge checks, real-time responses). Use for: overnight reports, periodic analysis, bulk data processing.

Limitations: - No multi-turn tool calling (each request is independent) - No latency guarantee (might take hours or minutes) - Intended for non-interactive, batch workloads

custom_id: User-assigned ID for tracking results. Essential for mapping batch responses back to requests. Format: string, must be unique per batch request.

Failure Handling: Failed requests can be identified by custom_id and retried with updated prompts or parameters.

Example Use Case: Process 1000 invoices overnight; use custom_id (invoice_123) for each to track which ones fail; retry failed invoices next day with enhanced prompts.

Domains: Claude Code Configuration & Workflows, Context Management & Reliability

JSON Schema

required vs. optional: - required: ["name", "email"]: These fields MUST be present - Fields not in required list are optional - Optional fields can still be structured (e.g., type: string, format: email)

nullable: A field can be null or the specified type. - Example: "middle_name": {"type": ["string", "null"]} or "middle_name": {"type": "string", "nullable": true} allows null - Use when a field may be absent from source data

enum: Restricted set of allowed values. Example:

{
  "status": {"type": "string", "enum": ["active", "inactive", "pending"]}
}

"other" + detail Pattern: When you need to handle unexpected values:

{
  "document_type": {"type": "string", "enum": ["invoice", "receipt", "quote", "other"]},
  "document_type_detail": {"type": "string", "description": "If 'other', describe the actual type"}
}

This allows flexibility while capturing unexpected types for future analysis.

Strict Mode: A JSON schema validation mode that rejects schemas with errors and enforces stricter type checking. Useful for ensuring valid extraction schemas.

Domains: Prompt Engineering & Structured Output

Built-in Tools

Read: Read a file's contents. Selection criteria: When you need to examine specific file content. Limitations: Might truncate very large files (usually at 2000 lines); for longer files, specify line ranges.

Write: Overwrite a file with new content. Selection criteria: Creating new files or complete file rewrites. Avoid for small edits; use Edit instead.

Edit: Make targeted replacements in a file. Selection criteria: Modifying existing files with specific changes (rename variable, add function, update config). More efficient than Read → Write.

Bash: Run shell commands. Selection criteria: Compiling code, running scripts, file operations, git commands. Limitations: Each bash call has fresh shell environment (use absolute paths, not relative).

Grep: Search file contents for patterns. Selection criteria: Finding code, searching for function names, identifying error patterns. More reliable than bash grep for permissions.

Glob: Search for files by pattern. Selection criteria: Finding files matching a pattern (.js, src//.py). Returns file paths sorted by modification time.

Domains: Tool Design & MCP Integration

In-Scope vs. Out-of-Scope

In-Scope Topics (Study These)

Agentic Architecture: - Agentic loops and stop_reason - Multi-agent systems with Task tool and allowedTools - Tool selection and descriptions - Error handling and escalation patterns - Hooks for business rule enforcement

Tool Design & MCP: - Tool definitions with detailed descriptions (input formats, examples, boundaries) - MCP server configuration (.mcp.json, environment variables) - isError flag in tool responses - Structured error responses

Claude Code Configuration: - CLAUDE.md hierarchies and context files - .claude/rules/ with glob patterns - .claude/commands/ for team commands - .claude/skills/ with context and allowed-tools - Plan mode vs. direct execution

Prompt Engineering & Structured Output: - JSON schema for structured output - tool_use and tool_choice in API calls - System prompts and decision logic - Few-shot examples for consistency - Validation and retry patterns

Context Management & Reliability: - Token budgets and max_tokens - Error propagation and recovery - Batch API for non-time-critical work - Attention and consistency in large tasks - Partial results and fallback mechanisms

API & CLI Basics: - Claude API model selection and parameters - Claude Code CLI flags (-p, --output-format) - Message Batches API for cost optimization - Custom tool implementation (via MCP)

Out-of-Scope Topics (Don't Study These)

  • Fine-tuning Claude models
  • Vision/image processing (not part of CCA)
  • Advanced prompt injection defenses (not the focus)
  • Specific cloud platform architectures (AWS, GCP, Azure)
  • Database design or data warehousing
  • Specific programming language deep dives
  • Anthropic's internal training methods
  • Exact Claude model architectures or internals
  • Third-party tool ecosystems unrelated to Claude/MCP
  • Regulatory compliance (HIPAA, GDPR, etc.) beyond general principles

Quick Reference by Domain

Agentic Architecture & Orchestration

  • Agentic loops, stop_reason, hooks
  • Task tool, allowedTools
  • Multi-agent coordination and error propagation
  • Escalation logic and decision boundaries

Tool Design & MCP Integration

  • Tool descriptions and selection criteria
  • MCP servers and environment variables
  • Structured error responses
  • isError flag usage

Claude Code Architect

  • CLAUDE.md hierarchies
  • Plan mode for complex changes
  • Skill definitions and context

Claude Code Configuration & Workflows

  • .claude/rules/ with glob patterns
  • .claude/commands/ for team automation
  • CLI flags and execution modes
  • Batch API selection criteria

Prompt Engineering & Structured Output

  • JSON schema design (required, optional, enum, nullable)
  • Few-shot examples
  • tool_use and tool_choice
  • Validation and retry patterns

Context Management & Reliability

  • Token management and max_tokens
  • Error handling and recovery
  • Batch vs. synchronous API trade-offs
  • Attention management in large contexts
  • Agent: Software system that makes autonomous decisions, calls tools, and loops until task is complete
  • Hook: Execution point that intercepts and modifies behavior (e.g., PostToolUse for validation)
  • Prerequisite: A tool call or check that must happen before another (e.g., get_customer before lookup_order)
  • Escalation: Routing a task to a human or higher authority when agent cannot decide autonomously
  • Tool Ambiguity: When multiple tools could reasonably be used for the same task; solved by better descriptions
  • Structured Output: Data in a defined format (JSON schema) rather than prose text
  • Validation-Retry: Loop that validates output, and on failure, retries with additional context
  • Batch Processing: Processing multiple requests together for cost savings, sacrificing latency
  • Provenance: Tracking the source/origin of information (important for research systems)
  • Orchestration: Coordinating multiple agents or services to work together toward a goal

Conclusion

None

CCA glossary reference key concepts terminology
Claude Certified Architect (CCA) — Exam Study Notes Part 16 of 16
Previous: Hands-On Preparation Exercises Series Complete