The shared vocabulary used across every lesson. Bookmark this.
Agent SDK & agentic loop
Agentic loop
The cycle: send request → Claude responds → inspect stop_reason → if tool_use, run the tool and append its result to history, loop again; if end_turn, finish.
stop_reason
Field telling you why the model stopped. "tool_use" = it wants a tool run; "end_turn" = it's done; "max_tokens" = output was truncated at the cap (NOT a normal completion). Loop control keys off tool_use/end_turn — not natural-language parsing or iteration caps.
max_tokens / system prompt
max_tokens caps generated output (truncation → stop_reason:"max_tokens"); it doesn't change what the model can see or fix attention/memory issues. The system prompt sets role/criteria but is probabilistic — never a substitute for a hook/gate when a guarantee is needed.
Tool result handling
Tool outputs are appended to conversation history so the model reasons over new info next iteration.
Model-driven decisioning
Claude chooses the next tool from context, vs a hard-coded decision tree/sequence.
Task tool
Mechanism to spawn a subagent. The coordinator's allowedTools must include "Task". Emit multiple Task calls in one response to run subagents in parallel.
AgentDefinition
Config for a subagent type: description, system prompt, tool restrictions.
Hooks
Code that intercepts the loop. PostToolUse transforms/normalizes tool results before the model sees them; tool-call interception hooks block policy-violating calls. Hooks give deterministic guarantees; prompts are probabilistic.
fork_session
Branch independent explorations from one shared baseline (e.g., compare two refactors).
--resume <name>
Continue a named prior session. Prefer a fresh session + injected summary when prior tool results are stale.
Multi-agent orchestration
Coordinator (hub-and-spoke)
Central agent that decomposes the task, delegates, routes ALL inter-subagent communication, aggregates results, handles errors. Subagents do NOT talk to each other.
Subagent context isolation
Subagents do not inherit the coordinator's history. Context must be passed explicitly in the prompt.
Narrow-decomposition risk
If the coordinator splits a broad topic too narrowly, coverage gaps result — even when every subagent succeeds at its assigned task. Root cause is upstream.
Iterative refinement loop
Coordinator evaluates synthesis for gaps, re-delegates targeted queries, re-synthesizes until coverage is sufficient.
MCP & tools
MCP
Model Context Protocol. Standard for exposing backend tools/resources to agents.
The PRIMARY signal the LLM uses to pick a tool. Must state purpose, inputs, example queries, edge cases, and when to use vs similar tools.
isError
MCP flag signaling a tool failure to the agent.
Structured error
Return errorCategory (transient/validation/business/permission), isRetryable, human-readable message — not a generic "Operation failed".
Error taxonomy
Transient (timeout — retry); validation (bad input); business (policy violation — not retryable); permission. Distinguish access failure from a valid empty result.
tool_choice
"auto" (may answer in text), "any" (must call some tool), forced {"type":"tool","name":"..."} (must call that tool).
Tool overload
Too many tools (e.g., 18 vs 4–5) degrades selection. Scope each agent's toolset to its role.
MCP scoping
Project .mcp.json (shared via VCS) vs user ~/.claude.json (personal). Use ${ENV_VAR} expansion for secrets.
Built-in tools
Grep = content search; Glob = filename/path patterns; Read/Write = full file; Edit = targeted unique-match change (fall back to Read+Write when match isn't unique); Bash.
Claude Code config
CLAUDE.md hierarchy
User (~/.claude/CLAUDE.md, personal, NOT shared) → project (.claude/CLAUDE.md or root) → directory (subdir CLAUDE.md). Always-loaded universal standards.
@import
Pull external files into CLAUDE.md to keep it modular.
.claude/rules/
Topic rule files; YAML frontmatter paths: globs load rules only when editing matching files. Beats directory CLAUDE.md for files spread across dirs (e.g., **/*.test.tsx).
Slash commands
.claude/commands/ (project, shared) vs ~/.claude/commands/ (personal).
Skills
.claude/skills/ with SKILL.md. Frontmatter: context: fork (isolate verbose output), allowed-tools (restrict), argument-hint. On-demand vs CLAUDE.md (always-on).
Plan mode
For complex/large-scale/architectural/multi-file work; explore + design before changing. Direct execution for simple well-scoped changes.
Explore subagent
Isolates verbose discovery, returns a summary to protect main context.
CLI: -p/--print
Non-interactive mode for CI. --output-format json + --json-schema for machine-parseable findings.
/memory, /compact
Inspect loaded memory files; compress context during long sessions.
Prompting & structured output
Explicit criteria
Specific categorical rules ("flag only when claimed behavior contradicts code") beat vague ones ("be accurate", "be conservative", "high-confidence only").
Few-shot
2–4 targeted examples; most effective for consistency, ambiguous-case handling, false-positive reduction, and generalization to novel patterns.
tool_use for output
JSON-schema tool use = most reliable schema-compliant output; eliminates syntax errors but NOT semantic errors (totals not summing, wrong field).
Nullable/optional fields
Make fields optional so the model returns null instead of fabricating to satisfy "required". Use enum + "other"/"unclear" + detail for extensibility.
Validation-retry
On failure, resend doc + failed extraction + specific error. Works for format/structural errors; useless when info is absent from source.
Semantic-validation fields
Catch errors schemas can't: extract calculated_total vs stated_total to flag mismatches; conflict_detected boolean for inconsistent source data; detected_pattern on findings to analyze which patterns drive false positives when developers dismiss them. Pydantic validators run these checks.
Message Batches API
~50% cheaper, up to 24h, NO latency SLA, NO multi-turn tool calling; custom_id correlates pairs. Good for overnight/weekly; bad for blocking pre-merge.
Independent review
A fresh instance (no generator's reasoning context) beats self-review/extended thinking. Split big reviews into per-file + cross-file integration passes (attention dilution; bigger context window does NOT fix it).
Context & reliability
Lost-in-the-middle
Models reliably use the start and end of long inputs; middle gets dropped. Put key summaries first; use section headers.
Case-facts block
Extract transactional facts (amounts, dates, IDs, statuses) into a persistent block in every prompt, outside summarized history.
Trim tool outputs
Keep only relevant fields before they accumulate (e.g., 5 of 40 order fields).
Escalation triggers
Customer asks for a human (honor immediately); policy gap/ambiguity; cannot progress. Sentiment and self-reported confidence are UNRELIABLE proxies for complexity.
Multiple matches
Ask for more identifiers; don't pick heuristically.
Error propagation
Subagents recover transient errors locally; propagate only unresolved ones with what-was-attempted + partial results. Never silently suppress; never kill the whole workflow on one failure.
Scratchpad files
Persist key findings across context boundaries to counter degradation in long sessions.
Confidence calibration
Field-level scores calibrated on labeled sets; stratified sampling to measure error rate; segment accuracy by document type + field (aggregate 97% can hide a bad segment).
Provenance
Preserve claim→source mappings through synthesis; annotate conflicts with attribution; include publication/collection dates so temporal diffs aren't read as contradictions.