Claude Code Framework

Authoritative reference for Claude Code's behavior and for authoring its extensions. Ground every claim to current behavior at https://code.claude.com/docs. Model IDs, pricing, and "as of version X" specifics rot — re-verify against live docs before relying on them. This file is the index; depth lives in the linked reference files.

---

CORE OPERATING RULES

Apply these directly when working with Claude Code on real tasks:

1. Plan before code on anything non-trivial. Use Plan Mode (or a written plan) to agree on approach before edits. Discussion-then-code catches wrong turns cheaply.
2. Keep CLAUDE.md lean and failure-focused. Document what Claude gets wrong in this repo (build quirks, forbidden paths, naming rules), not what it does right. ~100–200 lines; past ~40k chars Claude Code warns performance degrades — move depth into skills/docs and link them.
3. Clear context aggressively. /clear between unrelated tasks; provide only files relevant to the current task. Don't let one session accumulate stale context.
4. TDD as guardrail. Write/keep failing tests first, let Claude iterate to green. Tests are the objective signal that beats "looks done."
5. Split write vs. review contexts. Have a fresh context or subagent verify code the first context wrote — a single context rationalizes its own mistakes.
6. Checkpoints ≠ version control. /rewind (or double-Esc) restores Claude's edits and conversation, but NOT your bash side effects (migrations, rm, pushes). Commit real milestones to git.

---

EXTENDING CLAUDE CODE — PICK THE RIGHT SURFACE

| You want to… | Use | Lives in | |---|---|---| | Reusable prompt shortcut (/thing) | Slash command | .claude/commands/*.md | | Specialized persona with its own context/tools | Subagent | .claude/agents/*.md | | Auto-loaded domain knowledge (model-triggered) | Skill | .claude/skills/*/SKILL.md | | Deterministic action on an event (lint, guard, sync) | Hook | settings.json + script | | External tool/data integration | MCP server | .mcp.json / claude mcp add | | Repo-wide standing context | CLAUDE.md | ./CLAUDE.md, ~/.claude/CLAUDE.md |

Rule of thumb: command = you invoke on demand; skill = Claude pulls it in when relevant; agent = isolated context for a bounded job; hook = the harness runs it (not the model), so it's the only way to guarantee an automated behavior.

Frontmatter field tables + authoring patterns: reference/authoring.md

---

1. CORE CAPABILITIES

Claude Code is an autonomous coding agent in your terminal: feature implementation (plan → implement → verify), bug fixing, codebase navigation, and task automation.

cd your-project && claude      # Interactive session
claude "explain this project"  # Start with an initial prompt
claude -p "prompt text"        # Print mode: query once, exit (scriptable/pipeable)
claude -c                      # Continue most recent conversation
claude --resume <session-id>   # Resume a specific session
claude mcp serve               # Run Claude Code itself as an MCP server

---

2. MCP INTEGRATION (Quick Reference)

MCP is an open standard connecting Claude Code to external tools, databases, and APIs.

claude mcp add --transport http  <name> <url>              # HTTP remote
claude mcp add --transport sse   <name> <url>              # Server-Sent Events
claude mcp add --transport stdio <name> -- <cmd>           # Local process (fastest)
claude mcp add-json <name> '{"type":"http","url":"..."}'   # From JSON
claude mcp add-from-claude-desktop                         # Import from Desktop
claude mcp list / get <name> / remove <name>               # Manage
/mcp                                                       # Status (in-session)

Scope & precedence

| Scope | File | When | |-------|------|------| | local (default) | ~/.claude.json | Current project only | | project | .mcp.json | Team-shared, version controlled | | user | ~/.claude.json | All projects |

Precedence: Local > Project > User — a same-named local server shadows a project one.

In-session usage

@github:issue://123                 # Reference an MCP resource
/mcp__github__list_prs              # Execute an MCP prompt (no args)
/mcp__jira__create_issue "Bug" high # Execute with args

Context tuning

ENABLE_TOOL_SEARCH=auto:5 claude    # Dynamic tool loading — fires at 5% of context
ENABLE_TOOL_SEARCH=true  claude     # Always dynamic
ENABLE_TOOL_SEARCH=false claude     # Load all tools upfront
export MAX_MCP_OUTPUT_TOKENS=50000  # Warn at 10k; default max 25k tokens

Full MCP details (transports, @-mentions, enterprise managed-mcp.json, popular integrations): reference.md

---

3. CLAUDE.MD — PROJECT MEMORY

Auto-loaded at session start. Commit it so the whole team benefits.

• Import other files: @path/to/import (relative to the importing file).
• CLAUDE.local.md — auto-gitignored, private per-machine overrides.
• .claude/rules/*.md — auto-loaded as project memory; support paths globs for file-scoped rules.
• Hierarchy: ~/.claude/CLAUDE.md (global) → ./CLAUDE.md (project) → subdirectory CLAUDE.md (component-specific).

/init      # Bootstrap a CLAUDE.md by analyzing the project
/memory    # Open and edit memory files in your editor (in-session)

Keep it failure-focused, lean (~100–200 lines, hard ceiling ~40k chars), and iterated like a prompt: add the one line that prevents a repeated mistake; delete rules that stop mattering.

---

4. SKILLS SYSTEM

Skills are context-aware capabilities that activate on task context — pure LLM reasoning, no embeddings or classifiers.

1. Discovery — session start scans available skills (~100 tokens of YAML metadata each).
2. Contextual activation — Claude decides which to invoke from the description.
3. Dynamic loading — full skill body loads only when needed.

Locations: ~/.claude/skills/ (user), .claude/skills/ (project), plugin-provided.

name: skill-name
description: When this skill is relevant...    # Auto-trigger matching; put "Use when…" first
disable-model-invocation: true                 # Manual-only: removes description from context
user-invocable: false                          # Hide from / menu but keep in context
argument-hint: "[args]"                         # Autocomplete hint
allowed-tools: Read, Grep                      # Pre-approve tools the procedure runs
context: fork                                   # Run in an isolated subagent context
model: sonnet                                   # Per-skill model override

Progressive disclosure: keep SKILL.md under ~500 lines; move detail into sibling reference/*.md and link it (body content is recurring per-turn token cost).

Skill/agent/command authoring + field tables: reference/authoring.md. Ready-to-copy skill templates: patterns.md.

---

5. PLAN MODE

Use plan mode for complex features before any implementation.

> "Build a task management API with user authentication"
# Claude generates: DB schema, endpoint structure, auth flow, testing strategy
> "Use TypeScript instead of JavaScript"   # Refine the plan
> "Looks good, proceed"                     # Approve → Claude implements

Catch issues in the planning phase, not during debugging — like aligning with a senior architect before execution.

---

6. UNIX PHILOSOPHY — COMPOSABILITY

tail -f app.log | claude -p "Slack me if you see any anomalies"
git diff main   | claude -p "Review changes and generate a commit message"
cat metrics.csv | claude -p "Identify the slowest endpoints"
find . -name "*.py" | xargs -I {} claude -p "Add type hints to {}"

---

7. SETTINGS & CONFIGURATION

Hierarchy (highest → lowest precedence)

1. Organizational policies (managed settings — system-level managed-mcp.json)
2. .claude/settings.json — team conventions (project root, version controlled)
3. .claude/settings.local.json — machine-specific (project root, gitignored)
4. ~/.claude/settings.json / ~/.claude.json — user-level global

{
  "permissions": {
    "allow": ["Read", "Write(src/**)", "Bash(git *)", "Bash(npm *)"],
    "deny":  ["Read(**/.env*)", "Read(**/*.key)", "Bash(rm *)", "Bash(sudo *)"]
  },
  "env": { "MAX_MCP_OUTPUT_TOKENS": "50000", "ENABLE_TOOL_SEARCH": "auto:5" }
}

Permissions: deny overrides allow; patterns are literal globs — Read(.env*) does NOT match config/.env, use Read(**/.env*). Scope Bash narrowly (Bash(git *)), never blanket Bash. Don't pin a dated "model" in a committed settings file — it freezes the team on a rotting model; omit to inherit or use /model at runtime.

settings tiers, hooks wiring, and the full permissions model: reference.md.

---

8. SUBAGENTS & PARALLEL EXECUTION

> "Spawn a subagent to write unit tests while you implement the API endpoints"

• Desktop app / CLI: multiple sessions via git worktrees (or agent isolation: worktree).
• Web interface: built-in parallel task execution.
• tools: Task in agent frontmatter enables spawning subagents.

forge-plugin rule: leaf workers (testing, security, docs) OMIT Task; orchestrators (planner, builder, guardian, detective, orchestrator) INCLUDE Task.

Headless/CI, worktree parallelism, multi-Claude verification: reference/workflows.md.

---

9. MULTI-PLATFORM

| Platform | Notes | |----------|-------| | Terminal (CLI) | claude in any terminal — primary interface | | Web (claude.ai/code) | No local setup, parallel tasks, built-in diff view | | Desktop App | Visual diff, parallel sessions via git worktrees | | VS Code Extension | Inline diffs, @-mentions, plan review UI | | JetBrains Plugin | IntelliJ/PyCharm/WebStorm support | | GitHub Actions | anthropic/claude-code-action@v1 |

---

QUICK REFERENCE CARD

# CLI
claude / claude -p "prompt" / claude -c / claude --resume <id>
claude mcp list | add <config> | serve

# In-session
/mcp        # MCP status        /init      # bootstrap CLAUDE.md
/memory     # edit memory       /clear     # drop context between tasks
/rewind     # restore edits (NOT bash side effects)
@<file>     # reference a file   @<mcp-resource>  # reference an MCP resource

# Config files
CLAUDE.md                     # Project context (auto-loaded)
.mcp.json                     # Project MCP servers (version controlled)
.claude/settings.json         # Team settings
.claude/settings.local.json   # Local overrides (gitignored)
~/.claude.json                # User config

---

WORKED EXAMPLE — an agent that won't auto-trigger

Symptom: you built .claude/agents/db-migrator.md but Claude never delegates to it.

1. Read the frontmatter name. name: DB_Migrator → invalid (uppercase + underscore). Rename to db-migrator. The name is the wiring key, not a label.
2. Read the description. "Handles database stuff." → no trigger signal. Rewrite: "Plans and applies database schema migrations with rollback. Use when the user adds a column, changes a table, writes an Alembic/Prisma migration, or mentions schema drift." Add a realistic <example> block.
3. Check for disable-model-invocation: true on any skill/agent you expected to preload — it removes the description from context, so auto-trigger can never fire. Remove it if you need routing.
4. Confirm color is in the allowed palette, reload the session, and test with a prompt that matches the new trigger phrases.

---

GOTCHAS

Real, non-obvious traps — verified against this plugin's own source (agents/*.md, servers/governance-mcp/) and current Claude Code behavior.

• A weak description is the #1 reason an agent/skill won't fire. Routing is decided purely from description text. Write "<what it does>. Use when <concrete phrases users say>." with the key case first; <example> blocks in agent descriptions sharpen delegation.
• disable-model-invocation: true removes the description from context entirely and blocks subagent preload — it's not merely "manual-only." This skill uses it; it's reachable only by explicit invocation. Never set it on a skill you want Claude to auto-route to.
• Agent name must be lowercase-hyphens, ≤64 chars — no uppercase, no underscores. A display-cased name (NXTG-CEO-LOOP) silently fails discovery; the fix was nxtg-ceo-loop.
• color accepts ONLY purple|cyan|green|orange|blue|red. Any other value is ignored.
• Leaf-worker agents must OMIT Task; orchestrators must INCLUDE it. Give Task to a leaf and you invite unintended recursion; withhold it from an orchestrator and delegation silently no-ops.
• Invalid frontmatter fields are silently dropped, not errored. shortname, avatar, whenToUse (camelCase), exampleQueries, when_to_use on an agent look accepted but do nothing. Verify names against the valid set; never assume a field "took."
• model in an agent/skill overrides the session model — an agent pinned to sonnet will NOT inherit an Opus session. Omit to inherit; set only for a deliberately fixed tier.
• Hooks are the harness, not the model — and can block. A PreToolUse hook exiting code 2 denies the tool call (stderr goes to Claude); advisory hooks must exit 0. A slow SessionStart/UserPromptSubmit hook delays every turn — set a timeout.
• Use ${CLAUDE_PLUGIN_ROOT}, never absolute paths, in plugin command/hook bodies. Absolute paths break when the plugin installs to a different machine/location.
• An MCP entry file that runs server.connect() at import time breaks test harnesses. governance-mcp/index.mjs guards it (if (!process.env.FORGE_TEST_MODE) server.connect(...)) and dropped its #!/usr/bin/env node shebang because the shebang blocked vitest's ESM transform. Gate the transport connect behind an env flag if you import the module in tests.
• allowed-tools pre-approves; it does NOT restrict. It only suppresses permission prompts. To actually limit reach, use permissions.deny / disallowedTools in settings.
• Pinned model IDs and version numbers rot. Don't hardcode claude-sonnet-4-... in a committed settings.json unless you mean to; treat any "as of version X" claim as needing re-verification against live docs.
• CLAUDE.md hard ceiling is ~40k characters. Past it Claude Code warns and recall degrades. Move deep detail into .claude/rules/*.md (path-scoped) or linked docs.
• Many skills can exceed the ~15k-char command budget and get their descriptions dropped from context. Raise it: export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000.

---

LIMITATIONS & BEST PRACTICES

• Use .claudeignore to exclude large irrelevant files from context.
• Never commit API keys to .mcp.json — use environment variables.
• Local stdio servers are faster than remote HTTP/SSE; audit third-party MCP servers first.
• Keep MCP Tool Search's auto:N threshold consistent with the ENABLE_TOOL_SEARCH value.
• Enterprise: use managed-mcp.json for exclusive policy control.

---

ADDITIONAL RESOURCES

• reference.md — MCP transports/@-mentions/enterprise, settings & hooks schema, session management, install, platform integration, practical examples.
• reference/authoring.md — commands, subagents, skills, MCP: authoring patterns + complete valid-frontmatter field tables.
• reference/workflows.md — CLI flags, headless/CI automation, git worktree parallelism, checklist-driven and multi-Claude verification, checkpoints & rewind.
• patterns.md — copy-ready CLAUDE.md / rules / skill / agent / hook / MCP templates.

| Doc | URL | |-----|-----| | Overview | https://code.claude.com/docs/en/overview | | MCP | https://code.claude.com/docs/en/mcp | | Skills | https://code.claude.com/docs/en/skills | | Hooks | https://code.claude.com/docs/en/hooks | | Settings | https://code.claude.com/docs/en/settings | | Best Practices | https://www.anthropic.com/engineering/claude-code-best-practices |