Glossary

Terms used throughout this manual. Definitions are operational: what the term changes in how you run Claude Code (and transferable agents), not dictionary fluff. Linked terms have dedicated pages.

Context and memory

Term	Definition
Context window	The model's working memory for one session: system/steering docs, conversation, tool results, and open files. When it fills, older turns are dropped or summarized — the agent "forgets." See Context and Instruction Hierarchy.
Context reset	Starting a fresh session (or /clear) so the agent loses chat history but still loads repo steering docs. Use after thrash, after a wrong plan, or when the window is polluted with failed attempts.
Instruction hierarchy	Conflict-resolution order among system prompts, CLAUDE.md / AGENTS.md, specs, and the current user prompt. Lower durable layers should win on invariants; the prompt should only add task-local constraints.
CLAUDE.md	Claude Code's repo steering file, loaded at session start. Holds commands, conventions, never-do rules, and pointers to deeper docs. Keep short and accurate — stale rules are executed as diligently as good ones. See CLAUDE.md and AGENTS.md.
AGENTS.md	Tool-agnostic sibling of CLAUDE.md for agents that don't read Claude-specific files. Same content contract: durable repo rules, not task prompts.
Docs as memory	Treating committed docs (ARCHITECTURE.md, ADRs, specs) as the durable shared brain across sessions and teammates. Chat is ephemeral; the repo is not. See Docs as Memory.
Handoff note	A short committed or pasted summary of state for the next session/agent: what was done, what's left, open questions, files touched, commands to verify. Prevents re-derivation after a context reset.
Repo navigability	How quickly an agent can answer "where does X live?" Naming, module boundaries, index files, and anti-duplication conventions. See Navigability.

Control and prompting

Term	Definition
Plan mode	Claude Code mode that produces a plan and waits for approval before editing. Default for non-trivial work; skip only for mechanical, fully-specified edits.
Permission mode	How much the agent may do without asking (read-only, ask-before-write, auto-approve tools, etc.). Tighten for unfamiliar repos and production paths; loosen only with gates and a clear spec.
Control techniques	Prompt patterns that force questions-first, plan-before-code, constrained scope, stop-and-ask, and evidence requirements. See Control Techniques.
Questions-first	Explicit instruction to list ambiguities and open decisions before writing code. Counters the agent's default of silently picking a plausible interpretation.
Stop-and-ask	A hard gate: if a decision isn't in the spec/CLAUDE.md, the agent must pause rather than invent. Pair with a short allowlist of decisions it may make.
Constrained file scope	Naming the directories/files the agent may touch (and those it must not). Primary defense against drive-by refactors and architecture erosion.
Evidence requirement	Requiring the agent to cite file paths, test output, or command results for claims ("tests pass", "no callers left"). Claims without evidence are unverified.
Prompt anatomy	Structure of a high-leverage prompt: goal, constraints, scope, acceptance, out-of-scope, verification. See Prompt Anatomy.
Prompt vs spec	A prompt governs one session; a committed spec governs a feature across sessions. Escalation rule: typed twice in chat → into a file. See Prompts vs Specs.

Specs and architecture

Term	Definition
Spec	Versioned intent for a feature: goal, non-goals, acceptance criteria, constraints, out of scope. The arbiter when agent output is disputed. See Specs over Prompts.
Spec-code drift	Spec and implementation disagree. Either the code is wrong or the spec is stale — both are bugs. Detect in PR review; fix by updating the lagging artifact. See Keeping Specs Alive.
ADR	Architecture Decision Record: context, decision, consequences, alternatives rejected. Agents read ADRs to avoid re-litigating settled choices. See Decision Records.
What not to delegate	Decisions that stay human: stack, threat model, data ownership, irreversible migrations, product tradeoffs. Agents inform; humans decide. See What Not to Delegate.
Architecture erosion	Gradual loss of boundaries via agent drive-bys: duplicated helpers, cross-layer imports, new abstractions beside old ones. Prevent with navigability rules and scoped prompts. See Architecture Erosion.

Agents and roles

Term	Definition
Agent vs assistant	Assistants answer in chat; agents loop with tools (edit, run, search) toward a goal. Supervision model differs: you review artifacts and evidence, not just prose. See Agents vs Assistants.
Subagent	A delegated agent run with a narrower task and often a fresh context. Use for research, review, or isolated implementation slices — not as a substitute for a clear parent plan. See Agent Roles.
Builder / reviewer split	Separate the agent (or session) that writes code from the one that reviews it. Same context that built the change is biased to defend it. See Multi-Agent Patterns.
Agent drift	Progressive divergence from the original goal or constraints within a long session — scope creep, forgotten never-dos, "while I'm here" edits. Detect by re-reading the plan against the diff; fix with reset + tighter scope.
Coordination	How multiple agents share work without colliding: handoff notes, file ownership, sequential vs parallel slices. See Coordination.
Responsibility split	Which work is human-owned vs agent-owned vs shared. Architecture and acceptance stay human; mechanical implementation can be agent. See Responsibility Split.

Verification and failure

Term	Definition
Characterization tests	Tests that lock current behavior before changing it — especially legacy code. Write them first so refactors can't silently change outcomes. See Legacy Refactor.
Mock-only tests	Suites that assert against mocks/stubs without exercising real boundaries. Agents love them; they pass while production paths break. Flag in Reviewing AI Tests.
Shallow implementation	Code that matches the happy path and naming of the request but skips edge cases, error paths, or integration. See Shallow Implementation.
Hallucination / false confidence	Confident claims about APIs, callers, or "tests pass" without evidence. Require command output and path citations. See Hallucination and False Confidence.
Stuck loop / thrash	Repeated failed fix attempts that pollute context. Break with context reset, smaller scope, or human diagnosis. See Stuck Loops and Thrash.
Quality gates	Automated checks (typecheck, lint, test, CI) that must go red on deliberate failure before you trust them green. See Quality Gates.
Verification strategy	Layered proof: static checks → unit/integration → manual smoke → production signals. Agents produce candidates; gates and humans produce confidence. See Verification Strategy.
Recovery	Procedure after bad agent output: isolate, revert or quarantine, characterize, re-spec, re-run narrowly. See Recovery.
Large-task decomposition	Splitting work bigger than a reliable context window into sequenced, verifiable slices with handoffs. See Large Tasks.

Process shorthand

Term	Definition
Walking skeleton	Minimal end-to-end path that proves wiring (one route + one real data path + one test). Scaffold this before features. See New Project.
Rails before cargo	Install governing docs and quality gates before the second feature — agents amplify structure and its absence.
Three-pass review	Structured PR review for agent output: intent/spec → design/boundaries → evidence/tests. See Reviewing AI PRs.
Playbook	Named workflow with objective, inputs, steps, human gates, failure table, and acceptance criteria. Index: Workflows.

Related

• Mental Models — the six models these terms operationalize.
• Context and Instruction Hierarchy — mechanical treatment of context window and conflict resolution.
• Control Techniques — prompts that encode questions-first, stop-and-ask, and evidence.
• Keeping Specs Alive — preventing and repairing spec-code drift.
• Start Here — orientation if you're new to the manual.