# The Claude Anatomy Library > 21 anatomies. One system. Endless improvement. This file contains all documentation content in a single document following the llmstxt.org standard. ## Anatomy of CLAUDE.md > Team memory, conventions, patterns, and living architecture. ![CLAUDE.md](/posters/05-claude-md.png) > The project memory and "contract" that tells Claude how your project really works. --- ## TL;DR - `CLAUDE.md` is a markdown file at the **repo root** that Claude reads first. - It encodes your **stack, conventions, architecture, and guardrails**. - Keep it **short (≤ 300 lines), specific, and current**. - Treat it like a **living onboarding doc** — for humans *and* the AI. - Update it whenever a real-world decision changes. --- ## Why this matters Think of `CLAUDE.md` as the **employee handbook** you hand to a brilliant new hire on day one. Without it, they guess. With it, they ship like a senior teammate. > **Bottom line:** A great `CLAUDE.md` is the single highest-leverage file in your repo. --- ## The Big Picture ```mermaid flowchart LR A[Claude Code starts] --> B[Loads CLAUDE.md first] B --> C[Loads .claude/settings.json] C --> D[Loads skills / agents / MCP] D --> E[Better, faster, safer outputs] ``` > **Bottom line:** Context flows top-down — `CLAUDE.md` sets the tone for everything else. --- ## Ideal Structure (sections to include) | Section | Purpose | |---|---| | **Project overview** | One paragraph: what this repo is | | **Tech stack** | Languages, frameworks, versions | | **Project layout** | Folder responsibilities | | **Conventions** | Naming, commits, style | | **Workflows & commands** | How to build/test/deploy | | **Testing strategy** | What "done" means | | **Security & data handling** | Non-negotiables | | **Do's & don'ts** | Quick guardrails | | **Integrations & MCP servers** | External tools available | | **Known issues / gotchas** | Save future-debug time | | **Pitfalls to avoid** | Past mistakes encoded | | **Important project history** | Why things are the way they are | --- ## Step-by-Step Setup ### 1. Create the file ```bash touch CLAUDE.md ``` ### 2. Drop in the skeleton ```markdown # Project: > One-line summary of what this project does. ## 1. Tech Stack - Next.js 14 (App Router) · TypeScript · Tailwind CSS - Supabase (Auth, Postgres, Storage) - Prisma ORM · tRPC API · Zod validation ## 2. Project Layout - `src/app/` → Routes (App Router) - `src/components/` → Reusable UI components - `src/services/` → Business logic - `src/utils/` → Helpers & utilities - `prisma/` → Schema & migrations - `tests/` → Unit & integration tests ## 3. Conventions - Use TypeScript strict mode. - Prefer server components; use client only when needed. - Use functional components & hooks. - File names: kebab-case. Components: PascalCase. - Export types explicitly. ## 4. Workflows - Dev: `npm run dev` - Build: `npm run build` - Test: `npm test` - MCP: GitHub, Postgres, Slack (see `.mcp.json`) ## 5. Testing - Vitest for units; Playwright for e2e. - Min 80% line coverage on `src/services`. - Write tests **before** implementation. ## 6. Security - No secrets in code or logs. - Validate all user input with Zod. - Parameterized queries only. ## 7. Git - Conventional commits (`feat:`, `fix:`, `chore:`). - Never commit directly to `main`. - PRs require: green CI + 1 reviewer. ## 8. Known Issues - Prisma migrations must be applied before deploy. - Tailwind purges class names built dynamically — use safelist. ## 9. Do / Don't ✅ Be specific and concrete. ✅ Reference docs/ for depth. ❌ Don't include vague statements. ❌ Don't put secrets here. ``` ### 3. Commit it ```bash git add CLAUDE.md && git commit -m "docs: add CLAUDE.md" ``` ### 4. Iterate every sprint Add one section each time you notice Claude getting something wrong. --- ## Variants for Different Team Settings ### 👤 Solo developer Keep it ≤ 100 lines. Skip "Git" rules; focus on stack + conventions. ### 👥 Small team (2–10) Add **Workflows**, **Testing**, and **Git** rules. Reference `docs/onboarding.md` for depth. ### 🏢 Enterprise / regulated - Add **Security**, **Compliance**, and **Data classification** sections. - Link to internal policy docs. - **Lock changes** behind a code-owner review. ```markdown ## Compliance - All PRs must pass `policy-check.sh`. - PII access requires `@security-auditor` review. - Data residency: EU only. ``` ### 🌍 Open-source - Include **Contribution guide** + **Code of Conduct** links. - Make examples newcomer-friendly. - Mark **decisions** (`[DECISION]`) so contributors don't relitigate them. > **Bottom line:** Same skeleton, escalating depth. --- ## Anatomy of a Single Section (zoom-in) ```markdown ## Conventions - **Language:** TypeScript strict mode (`"strict": true`). - **Style:** Prettier defaults + ESLint recommended. - **Naming:** files `kebab-case`, components `PascalCase`, vars `camelCase`. - **Imports:** absolute paths via `@/` alias. - **Comments:** only "why", never "what". ``` Notice: **concrete**, **enforceable**, **terse**. --- ## Common Patterns & Recipes ### Pattern 1 — Reference external docs ```markdown > For deep architecture details, see `docs/architecture.md`. ``` ### Pattern 2 — Encode a non-negotiable ```markdown > ⛔ **NEVER** call third-party APIs without a retry + timeout wrapper. ``` ### Pattern 3 — Few-shot a convention ```markdown ### Commit messages — examples ✅ `feat(auth): add magic-link login` ✅ `fix(api): handle 429 from Stripe` ❌ `update stuff` ``` ### Pattern 4 — Decision log ```markdown ## Decisions - [2026-03-12] Chose tRPC over REST for type safety. (Owner: @vk) - [2026-04-08] Adopted Prisma migrations as the source of truth. ``` --- ## Best Practices ✅ - **Be specific & concrete** — examples over adjectives. - **Show examples** for every convention. - **Keep it concise** (< 300 lines). - **Update when things change.** - **Link to docs** for depth instead of inlining everything. ## Anti-Patterns ❌ - Vague statements ("write clean code"). - Outdated info (last edited 9 months ago). - Secrets or tokens. - Walls of text with no structure. - Internal jokes nobody outside the team understands. --- ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | Claude ignores rules | File too long / vague | Trim to bullets, add examples | | Wrong stack assumed | Stack section missing | Pin versions explicitly | | Repeated mistakes | No "anti-patterns" section | Add it; cite real examples | | Drift over time | Not updated | Add to PR checklist: "Updated CLAUDE.md?" | | Sensitive leak risk | Secrets in file | Remove; reference env vars | --- ## Starter Template (the bare minimum) ```markdown # Project: > One-line summary. ## Tech Stack - ## Workflows - Dev: - Build: - Test: ## Conventions - ## Security - ## Notes - ``` > 💡 **Tip:** Treat `CLAUDE.md` like a README for Claude. Keep it living & true. --- ## Glossary - **CLAUDE.md** — Root-level memory file Claude reads first. - **Convention** — A rule the team agrees to follow consistently. - **Decision log** — A dated record of architectural choices. - **Guardrail** — A non-negotiable safety/quality rule. --- ## Further Reading - Search: **"Claude Code project memory CLAUDE.md best practices"** - Search: **"awesome-claude-md examples GitHub"** - Search: **"AI coding agent prompt engineering for repositories"** --- ## Anatomy of Hook Lifecycles > Pre/Post/Stop hooks, matchers, lifecycles, and automation. ![Hook Lifecycles](/posters/04-hook-lifecycles.png) > Automate guardrails, quality, and workflows with lifecycle hooks in Claude Code — the silent guardians that turn AI suggestions into AI-with-policy. --- ## TL;DR - A **hook** is a command, script, webhook, or built-in action that Claude Code runs automatically at lifecycle events. - Defined in `.claude/settings.json` under the `hooks` key. - Core events: `SessionStart`, `PreToolUse`, `PostToolUse`, `PreCommit`, `Notification`, `SessionEnd`, `Error`. - Use **`PreToolUse` to prevent problems** and **`PostToolUse` to improve quality**. - **Fail closed for safety**, **fail open for convenience**. --- ## Why this matters Hooks are **seat belts for your AI teammate**. You don't think about them every drive, but the one time you need them, they save the trip. They turn AI suggestions into AI-with-policy. > **Bottom line:** Hooks make AI agents enterprise-ready — by making guardrails invisible. --- ## The Big Picture ```mermaid flowchart LR S[SessionStart] --> P1[PreToolUse] P1 -->|exit 0| T[Tool Execution] P1 -->|exit ≠ 0| X[Blocked] T --> P2[PostToolUse] P2 --> L{More?} L -- yes --> P1 L -- no --> PC[PreCommit] PC --> N[Notification] N --> E[SessionEnd] T -.error.-> ER[Error hook] ``` > **Bottom line:** Events flow; hooks intercept. Any hook can block the action by returning non-zero. --- ## Hook Lifecycle Overview Hooks fire at key points during a Claude Code session and workflow: | Order | Event | Phase | |---|---|---| | 1️⃣ | `SessionStart` | Session opens | | 2️⃣ | `PreToolUse` | Before any tool call | | 3️⃣ | *Tool execution* | (the actual action) | | 4️⃣ | `PostToolUse` | After tool completes | | 5️⃣ | `PreCommit` | Before a git commit | | 6️⃣ | `Notification` | On important events | | 7️⃣ | `SessionEnd` | Session closes | Plus the cross-cutting `Error` event whenever a hook or tool fails. > 💡 **Tip:** Any hook can **block the action** if it exits with a non-zero status. --- ## Built-in Lifecycle Events | Event | When it fires | Typical uses | |---|---|---| | `SessionStart` | When Claude Code session opens | Load context, env summary, welcome message | | `PreToolUse` | Before **any** tool call is executed | Block unsafe actions, secret scan, policy checks | | `PostToolUse` | After **any** tool call completes | Auto-lint, tests, format, notify, audit | | `PreCommit` | Before a git commit is created | Secret scan, licence check, policy enforcement | | `Notification` | Important events (errors, approvals, etc.) | Slack/webhook alerts, emails, dashboards | | `SessionEnd` | When session is closing | Persist summary, cleanup, audit log flush | | `Error` | When a hook or tool fails | Alert, rollback, capture diagnostics | > 💡 **Tip:** Use **PreToolUse to prevent** problems. Use **PostToolUse to improve** quality. --- ## Hooks Configuration (`.claude/settings.json`) ```json { "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "./scripts/pre-tool.sh", "timeoutMs": 5000 } ], "concurrency": "sequential" }, { "matcher": "Bash", "hooks": [ { "type": "command", "command": "./scripts/policy-check.sh" }, { "type": "webhook", "url": "https://hooks.slack.com/...", "timeoutMs": 3000 } ], "concurrency": "parallel" } ], "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "npm run lint" }, { "type": "command", "command": "npm test --silent", "timeoutMs": 60000 } ] } ] } } ``` > 💡 **Tip:** Hooks run in the order listed. The **first failure (non-zero exit) blocks the event.** --- ## Hook Entry Format | Field | Description | |---|---| | `matcher` | Regex-like pattern that filters which tool / event triggers this hook | | `hooks` | Array of hook entries to run | | `type` | `command` · `webhook` · `script` · `builtin` · `custom` | | `command` | Shell command to execute (`type: command`) | | `script` | Path to script file (`type: script`) | | `url` | Webhook URL (`type: webhook`) | | `timeoutMs` | Max time (ms) before the hook times out | | `concurrency` | `sequential` (default) or `parallel` | --- ## Hook Types | Type | What it does | Best for | |---|---|---| | `command` 💻 | Runs a shell command | Scripts, linters, scans, formatters | | `script` 📄 | Runs a script file (bash, node, python) | Complex logic | | `webhook` 🌐 | Sends an HTTP request | APIs, Slack, Datadog | | `builtin` ⚙️ | Executes a built-in Claude action | Lint, format, compact | | `custom` 🧩 | Calls a registered custom integration | Org-specific tools | --- ## Matchers — What Can They Match? Matchers are **regex-like patterns** matched against the tool or event name: | Matcher | Matches | Examples | |---|---|---| | `*` | Everything | All tools | | `Read` | Read operations | Read, Glob, Grep (read) | | `Write` | Write operations | Write, CreateFile, DeleteFile | | `Edit` | Edits to existing files | Edit, Patch, ApplyDiff | | `Write\|Edit` | Write OR Edit | Either Write or Edit | | `Bash` | Any Bash command | Bash, Bash(git *) | | `Bash(git *)` | Git commands | `git status`, `git commit` | | `Bash(npm *)` | NPM commands | `npm test`, `npm run build` | | `Bash(rm -rf *)` | Dangerous deletes | `rm -rf /tmp/*` | | `WebSearch` | Web search | `WebSearch(...)` | | `WebFetch` | HTTP fetch | `WebFetch(url)` | | `MCP:*` | Any MCP tool call | `MCP:github`, `MCP:postgres` | | `MCP:github` | GitHub MCP only | Issues, PRs, repos | | `Tool:browser` | Browser automation | navigate, click, screenshot | > 💡 **Tip:** Specific patterns override wildcards. **Order matters.** --- ## Concurrency & Flow Control Control how multiple hooks under the same matcher run. ### `sequential` (default) Run hooks one after another. Use when **order matters** or hooks **share state**. ```text 1 → 2 → 3 ``` ### `parallel` Run hooks at the same time. **Faster**, but be careful with **shared resources**. ```text ┌─ 2 1 ─┤ └─ 3 ``` ```json "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "npm run lint" }, { "type": "command", "command": "npx prettier --write ." } ], "concurrency": "parallel" } ] ``` --- ## Example Hook Scripts ### `scripts/pre-tool.sh` — block unsafe commands ```bash #!/usr/bin/env bash case "$CLAUDE_TOOL_NAME" in Bash) if echo "$CLAUDE_TOOL_INPUT" | grep -Eq "rm -rf|sudo|curl .*\|.*sh"; then echo "❌ Blocked: $CLAUDE_TOOL_INPUT" >&2 exit 1 fi ;; esac exit 0 ``` ### `scripts/secret-scan.sh` — pre-commit ```bash #!/usr/bin/env bash if git diff --cached | grep -Eiq "(api[_-]?key|secret|password|token)\s*=\s*['\"][^'\"]+['\"]"; then echo "❌ Possible secret detected." >&2 exit 1 fi exit 0 ``` ### `scripts/notify-slack.sh` — webhook ```bash #!/usr/bin/env bash curl -s -X POST -H "Content-Type: application/json" \ --data "{\"text\":\"🤖 $CLAUDE_EVENT at $PWD\"}" \ "$SLACK_WEBHOOK_URL" ``` ### `scripts/save-summary.sh` — session end ```bash #!/usr/bin/env bash DATE=$(date +%Y-%m-%d_%H-%M) mkdir -p docs/sessions echo "# Session $DATE" > "docs/sessions/$DATE.md" echo "_Auto-saved summary placeholder._" >> "docs/sessions/$DATE.md" ``` --- ## Step-by-Step Setup ### 1. Create the scripts folder ```bash mkdir -p scripts && chmod 755 scripts ``` ### 2. Drop in a starter `pre-tool.sh` (see above) ```bash chmod +x scripts/pre-tool.sh ``` ### 3. Wire it into `.claude/settings.json` ```json { "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/pre-tool.sh", "timeoutMs": 5000 }] } ], "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm run lint" }] } ] } } ``` ### 4. Restart Claude Code ```bash /exit claude ``` ### 5. Test Ask Claude to edit a file → `npm run lint` should fire automatically. ### 6. Iterate Add more matchers as the team's pain points show up. --- ## Variants for Different Team Settings ### 👤 Solo developer (lightweight) Lint-on-write only. Skip strict blocking. ```json "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm run lint -- --fix" }] }] ``` ### 👥 Small team (2–10) (shared standards) Add secret scan + tests on PR. ```json "PreCommit": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/secret-scan.sh" }] }], "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm test --silent" }] }] ``` ### 🏢 Enterprise / regulated (fail closed + audit) - Central audit log, SIEM webhook, code-review required for `settings.json` changes. ```json "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "./scripts/policy-check.sh" }, { "type": "webhook", "url": "https://siem.corp/audit", "timeoutMs": 3000 } ] } ], "SessionEnd": [ { "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/audit-flush.sh" }] } ] ``` ### 🌍 Open-source / community - Document every hook in `CONTRIBUTING.md`. - Make hooks **opt-in** for contributors (avoid surprise blocks on first clone). - Provide a `bootstrap.sh` to set them up explicitly. > **Bottom line:** Same hook engine, escalating strictness. --- ## Anatomy of a Single Hook — Zoomed In ```json { "matcher": "Write|Edit", // when it fires "hooks": [ { "type": "command", // hook type "command": "./scripts/post-write.sh", // what runs "timeoutMs": 10000, // safety cap "env": { "STRICT": "1" } // env vars passed in } ], "concurrency": "sequential" // order matters } ``` Available env vars inside the script: - `$CLAUDE_TOOL_NAME` — tool that triggered the hook - `$CLAUDE_TOOL_INPUT` — the input passed to that tool - `$CLAUDE_EVENT` — lifecycle event name - `$CLAUDE_SESSION_ID` — current session id - `$PWD` — workspace root --- ## Common Patterns & Recipes ### Pattern 1 — Auto-format after writes ```json "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npx prettier --write ." }] }] ``` ### Pattern 2 — Slack alert on errors ```json "Error": [{ "matcher": "*", "hooks": [{ "type": "webhook", "url": "https://hooks.slack.com/services/..." }] }] ``` ### Pattern 3 — Session summary on close ```json "SessionEnd": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/save-summary.sh" }] }] ``` ### Pattern 4 — Matcher scoping ```text "matcher": "Write|Edit" // only file mutations "matcher": "Bash" // only shell calls "matcher": "MCP:*" // only MCP server calls "matcher": "*" // everything (sparingly) ``` ### Pattern 5 — Conditional fail-open ```bash #!/usr/bin/env bash ./scripts/policy-check.sh RC=$? if [ $RC -ne 0 ] && [ "$STRICT" = "1" ]; then exit $RC # fail closed in strict mode fi exit 0 # fail open otherwise ``` ### Pattern 6 — Webhook with timeout guard ```json { "type": "webhook", "url": "https://hooks.slack.com/...", "timeoutMs": 2000 } // never hang the session ``` ### Pattern 7 — Idempotent post-write ```bash #!/usr/bin/env bash # Safe to run repeatedly with the same effect npx prettier --write . >/dev/null exit 0 ``` ### Pattern 8 — Compose with slash commands ```json "PostToolUse": [ { "matcher": "manual:command", "hooks": [{ "type": "command", "command": "./scripts/log-command.sh" }] } ] ``` --- ## Gotchas ⚠️ - Hooks run with **your user's permissions** — audit script contents. - A failed `PreToolUse` hook **blocks the tool call** (`exit 1` to deny). - **Timeouts protect you** — always set `timeoutMs` for webhooks (1–5 s). - **Order of hooks matters** — first non-zero exit stops execution. - Avoid network calls in `PreCommit` if offline work is possible. - Logs may contain **paths & args** — review before sharing. - `concurrency: parallel` is faster but unsafe if hooks share state. - Matchers are **case-sensitive**. - A `*` matcher fires on **every** event — use sparingly. --- ## Best Practices ✅ - **Keep hooks fast** (< 5 seconds). - **Fail closed** for security checks; **fail open** for cosmetics. - **Be idempotent** — safe to run repeatedly. - **Log to files** for an audit trail. - **Use matchers to limit scope** and reduce noise. - **Test locally** before committing. - **Version-control** and **review** hook changes. - **Never hard-code secrets** in the command. ## Anti-Patterns ❌ - **Long-running hooks** (60-second test suites in `PostToolUse`). - **Hooks that modify repo files blindly**. - **Over-broad matchers** (`*` everywhere). - **Hard-coded secrets or tokens.** - **Swallowing errors silently** (`|| true`). - **No timeouts on webhooks.** - **Relying on network in `PreCommit`** for offline workflows. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | Hook not running | Wrong matcher regex | Test with `"matcher": "*"` first | | Command failed | Script error | Check `exit` codes & local run | | Too slow | Heavy script in hot path | Move work off the hot path / async | | Infinite loop | Hook triggers itself | Add guard condition / matcher exclude | | No logs | Not logging | Write to `.claude/logs/` | | Webhook hangs session | Missing `timeoutMs` | Set `timeoutMs: 3000` | | Hook runs twice | Multiple matchers overlap | Tighten matcher patterns | | Works locally, not in CI | Missing env var | Pass via `env:` in entry | --- ## Getting Started (5 steps) 1. **Identify what should be automated** (lint, scan, notify…). 2. **Write or choose a hook script.** 3. **Add to `.claude/settings.json`** under the right event. 4. **Test with a small task.** 5. **Monitor, log, and iterate.** --- ## Starter Template (copy-paste) ```json { "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "./scripts/pre-tool.sh", "timeoutMs": 5000 } ] } ], "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "npm run lint" } ] } ], "PreCommit": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "./scripts/secret-scan.sh" } ] } ] } } ``` > 💡 **Tip:** Start with `PreToolUse` + `PostToolUse`. Add more events as the team grows. --- ## Glossary - **Hook** — A shell command, script, webhook, or built-in action bound to a Claude lifecycle event. - **Event** — A point in the session lifecycle (`PreToolUse`, etc.). - **Matcher** — Regex-like pattern that scopes hook execution to specific tools/events. - **Fail closed** — Block on error (safe default for security). - **Fail open** — Continue on error (safe default for cosmetics). - **Sequential vs parallel** — Run hooks one-by-one or all at once. - **Idempotent** — Safe to run repeatedly with the same effect. --- ## Further Reading - Search: **"Claude Code hooks documentation"** - Search: **"git pre-commit hooks examples"** - Search: **"shell hook patterns idempotent"** - Search: **"webhook timeout best practices"** --- ## 🪙 Golden Rules - 🎯 **Curate ruthlessly** — keep context small & relevant. - ⚙️ **Automate wisely** — hook the right events. - 🛡️ **Be safe by default** — least privilege. - 👁️ **Observe everything** — logs, alerts, audits. - 🔁 **Iterate & improve** — feedback makes it better. > **Remember:** Hooks are your silent guardians. They prevent problems and enforce quality — automatically. --- ## Anatomy of MCP Servers > Model Context Protocol servers, capabilities, security, and setup. ![MCP Servers](/posters/02-mcp-servers.png) > The building blocks that connect Claude Code to the outside world — GitHub, databases, Slack, files, browsers — through one open protocol. --- ## TL;DR - **MCP (Model Context Protocol)** is Anthropic's open standard so Claude can talk to *any* external tool through one common language. - An **MCP server** is a small program that exposes **Tools, Resources, and Prompts** to Claude. - You configure them in **`.mcp.json`** at your project root — Claude auto-discovers them on launch. - Transports: **stdio** (local, default), **HTTP/HTTPS** (remote), **WebSocket** (real-time). - Treat MCP servers like signed-in employees: **least privilege, scoped tokens, audit logs**. --- ## Why this matters Think of Claude as a brilliant consultant locked in a glass office. **MCP servers are the doors and badges** that let it reach the file cabinet, the database, the Slack channel — without you copy-pasting context. One protocol replaces a dozen bespoke integrations. > **Bottom line:** MCP is to AI tools what USB is to hardware — plug it in and it works. --- ## The Big Picture ```mermaid flowchart LR A[Claude CodeClient] -- JSON-RPC 2.0 --> B[MCP ServerTool Host] B --> C[(GitHub)] B --> D[(PostgreSQL)] B --> E[(Slack)] B --> F[(Filesystem)] B --> G[(Web APIs)] subgraph Lifecycle H[Discover] --> I[Call Tool] I --> J[Execute] J --> K[Respond] end ``` > **Bottom line:** One client, many servers, one protocol. --- ## Core Concepts | Concept | Plain English | |---|---| | **Client** | Claude Code itself | | **Server** | A small program that exposes tools/data | | **Protocol** | JSON-RPC 2.0 messages over a transport | | **Tool** | A callable function with a JSON Schema | | **Resource** | Read-only data exposed via a URI | | **Prompt** | A reusable prompt template the server provides | | **Transport** | How bytes flow: stdio / HTTP / WebSocket | | **Capability** | A feature flag the server advertises at handshake | --- ## `.mcp.json` Reference ```json { "mcpServers": { "github": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }, "postgres": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-postgres"], "env": { "DATABASE_URL": "${DATABASE_URL}" } }, "slack": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-slack"], "env": { "SLACK_BOT_TOKEN": "${SLACK_TOKEN}" } }, "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-filesystem", "./src", "./tests"] } } } ``` > 💡 **Tip:** Use `${ENV_VAR}` interpolation — never paste raw tokens. --- ## Building an MCP Server (TypeScript) ```bash npm i @modelcontextprotocol/sdk ``` ```typescript // src/server.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer({ name: "hello-server", version: "1.0.0", capabilities: { tools: {} } }); // Register a tool with input schema server.tool( "create_pr", { title: z.string(), body: z.string(), head: z.string(), base: z.string() }, async ({ title, body, head, base }) => { // ... actual GitHub API call here return { content: [{ type: "text", text: `PR opened: ${title}` }] }; } ); const transport = new StdioServerTransport(); await server.connect(transport); console.error("MCP server running on stdio"); ``` Then register it in `.mcp.json`: ```json "hello": { "type": "stdio", "command": "node", "args": ["./dist/server.js"] } ``` --- ## Calling a Tool (raw JSON-RPC example) ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_pr", "arguments": { "title": "Add user analytics", "body": "Adds dashboard and events.", "head": "feature/analytics", "base": "main" } } } ``` You'll rarely write this yourself — Claude does it for you. But knowing the wire format is gold when debugging. --- ## Transport Options | Transport | When to use | Tradeoff | |---|---|---| | **stdio** | Local servers (default) | Simple, fast, secure — but one process per client | | **HTTP / HTTPS** | Remote / shared servers | Easy to deploy & scale, needs auth | | **WebSocket** | Real-time, bidirectional | Long-lived connections; more ops overhead | --- ## Common Server Types You'll Actually Use - **Code hosting** — GitHub, GitLab, Bitbucket - **Databases** — PostgreSQL, MySQL, MongoDB, Redis - **Communication** — Slack, Discord, email - **Search & docs** — Notion, Confluence, Google Drive - **DevOps & cloud** — AWS, Docker, Kubernetes - **Utilities** — Filesystem, shell, generic web APIs --- ## Variants for Different Team Settings ### 👤 Solo developer - One `.mcp.json`, GitHub + Filesystem only. - Tokens in `~/.env`, sourced before `claude` launch. ### 👥 Small team (2–10) - Commit `.mcp.json` with env-var placeholders. - Add a `.env.example` so teammates know what to set. - Shared Slack/GitHub bot tokens with scoped permissions. ### 🏢 Enterprise / regulated - Host MCP servers behind **HTTPS + mTLS**. - Tokens injected from a **secrets vault** (Azure Key Vault, AWS Secrets Manager). - Add a **gateway** server that audits every call. - Whitelist tools per team in `settings.json`. ### 🌍 Open-source / community - Publish your server to **npm / PyPI / crates.io**. - Ship a `README` with copy-paste `.mcp.json` snippet. - Provide a Docker image so contributors avoid local installs. > **Bottom line:** Same protocol, different deployment posture as risk grows. --- ## Anatomy of a Single Unit — One MCP Server | Part | Purpose | |---|---| | **Identity** | name, version, description, advertised capabilities | | **Transport** | stdio / HTTP / WebSocket | | **Tools** | callable functions with input/output JSON Schemas | | **Resources** | URI-addressable read-only data | | **Prompts** | reusable prompt templates with variables | | **Auth & Security** | tokens, scopes, allowed origins | | **Lifecycle** | `initialize` → `ready` → `running` → `shutdown` | | **Error handling** | standard MCP error codes for predictable client UX | | **Logging** | structured logs for debugging & audit | --- ## Lifecycle Events | Event | What happens | |---|---| | `initialize` | Client connects, exchanges capabilities | | `tools/list` | Server returns its callable tools | | `tools/call` | Client invokes a tool | | `notifications/*` | Server pushes async events | | `shutdown` | Graceful close | | `terminated` | Connection ended | --- ## Common Patterns & Recipes ### Pattern 1 — Scoped filesystem access ```json "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-filesystem", "./src", "./tests"] } ``` Only those two folders are exposed — Claude cannot escape. ### Pattern 2 — Read-only database ```json "postgres-readonly": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-postgres", "--readonly"], "env": { "DATABASE_URL": "${RO_DATABASE_URL}" } } ``` ### Pattern 3 — Remote HTTP server with bearer token ```json "analytics": { "type": "http", "url": "https://mcp.mycorp.com/analytics", "headers": { "Authorization": "Bearer ${ANALYTICS_TOKEN}" } } ``` ### Pattern 4 — Per-environment overrides via `settings.local.json` ```json { "mcpServers": { "postgres": { "env": { "DATABASE_URL": "postgres://localhost/dev" } } } } ``` ### Pattern 5 — Healthcheck command before Claude starts ```bash # scripts/check-mcp.sh npx -y @anthropic/mcp-github --healthcheck || { echo "MCP github not ready"; exit 1; } ``` --- ## Best Practices ✅ - **Least privilege** — give each server only the scopes it needs. - **Never hard-code secrets** — always `${ENV_VAR}`. - **Validate all inputs** at the server boundary. - **Use scoped tokens** (e.g., GitHub fine-grained PATs). - **Audit logs** for sensitive actions (writes, deletes). - **Isolate untrusted servers** in containers or VMs. - **Fail safely & loudly** — return clear error codes. ## Anti-Patterns ❌ - One "god" MCP server with full admin rights. - Tokens committed to the repo. - Servers that silently ignore unknown args. - Exposing the entire filesystem (`/`). - No timeout on long-running tool calls. --- ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | "Server not found" | Wrong `command` or `npx` not on PATH | Check `which npx`; install package | | "No tools listed" | Server never finished `initialize` | Run server standalone; verify logs | | Tool call fails | Schema mismatch | Compare args against `tools/list` schema | | "Permission denied" | Token scope too narrow | Re-issue with required scopes | | Random hangs | No timeout configured | Set `timeoutMs` on the client side | | Timeouts | Slow upstream (e.g., DB) | Add caching or increase timeout | | Wrong results | Server reads stale data | Validate data-source mapping | --- ## Starter Server Skeleton (TypeScript, full) ```typescript // my-mcp-server/src/server.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer({ name: "hello-server", version: "1.0.0", capabilities: { tools: {}, resources: {}, prompts: {} } }); server.tool( "hello", { name: z.string() }, async ({ name }) => ({ content: [{ type: "text", text: `Hello, ${name}!` }] }) ); const transport = new StdioServerTransport(); await server.connect(transport); console.error("MCP server running on stdio"); ``` Template layout: ``` my-mcp-server/ ├── src/server.ts ├── tools/*.ts ├── schemas/*.json ├── utils/*.ts ├── tests/*.test.ts ├── README.md ├── package.json ├── tsconfig.json ├── .env.example ├── Dockerfile # optional └── LICENSE ``` --- ## Security Checklist - [x] Least privilege scopes - [x] No hard-coded secrets - [x] Validate all inputs - [x] Scope tokens per environment - [x] Audit logs on writes - [x] Fail safely with standard error codes --- ## Glossary - **MCP** — Model Context Protocol, Anthropic's open spec. - **JSON-RPC 2.0** — Lightweight remote-procedure-call format. - **Transport** — How JSON-RPC bytes are moved (stdio, HTTP, WS). - **Tool** — A server-exposed function Claude can call. - **Resource** — Read-only data a server exposes via a URI. - **Prompt** — A reusable prompt template provided by the server. - **Capability** — A feature flag exchanged during `initialize`. --- ## Further Reading - Search: **"Model Context Protocol spec"** - Search: **"@modelcontextprotocol/sdk GitHub"** - Search: **"awesome MCP servers list"** - Search: **"Anthropic MCP quickstart"** --- ## Anatomy of Claude Code Project Structure > The complete .claude project anatomy and recommended layout. ![Claude Code Project Structure](/posters/01-project-structure.png) > A production-ready layout, conventions, and best practices for building software with Claude Code — explained in plain English, with copy-paste-ready snippets. --- ## TL;DR - **Claude Code** is Anthropic's terminal-based AI coding agent; a good project structure makes it 10× more reliable. - The heart of the setup is a `CLAUDE.md` file (project memory) + a `.claude/` folder (config, commands, skills, agents). - Use **MCP servers** (`.mcp.json`) to plug Claude into GitHub, JIRA, Slack, your DB, etc. - Use **Hooks** to enforce safety (lint, secret-scan, tests) automatically. - Tailor the layout to your team size: **solo, small team, enterprise, or open-source**. --- ## Why this matters Think of Claude Code like a brilliant new hire. Without an onboarding doc, a desk layout, and access permissions, they wander. **`CLAUDE.md` is the onboarding doc**, **`.claude/` is the desk**, **MCP servers are the building access badges**, and **hooks are the safety policies**. Get this right once, and every future task goes faster. > **Bottom line:** Structure isn't bureaucracy — it's how you make an AI agent trustworthy. --- ## The Big Picture ```mermaid flowchart LR A[Developer] -->|prompts| B[Claude Code CLI] B --> C[CLAUDE.mdproject memory] B --> D[.claude/ settings,commands, hooks] B --> E[skills/reusable workflows] B --> F[agents/specialized subagents] B --> G[.mcp.jsonexternal tools] G --> H[(GitHub)] G --> I[(PostgreSQL)] G --> J[(Slack)] D -->|PreToolUse| K[Safety hookslint, secret scan] D -->|PostToolUse| L[Auto lint / tests] ``` > **Bottom line:** Six moving parts, one source of truth (`CLAUDE.md`). --- ## Core Components | Name | Purpose | When to use | |---|---|---| | `CLAUDE.md` | Project memory: conventions, stack, rules | **Always.** Day 1 file. | | `.claude/settings.json` | Shared team config (permissions, hooks, env) | When ≥ 2 people share the repo | | `.claude/settings.local.json` | Personal overrides (gitignored) | Per-developer tweaks | | `.claude/commands/` | Custom slash commands (`/review`, `/deploy`) | Repeated multi-step workflows | | `skills/` | Auto-activated reusable capability packs | When a workflow has docs + scripts + assets | | `agents/` | Specialized subagents (code-reviewer, test-writer) | Parallel or domain-specific work | | `.mcp.json` | External tool connections (GitHub, DB, Slack) | When Claude needs to *do* things outside your repo | | `plugins/` | Bundled, distributable extension packs | When sharing setups across many repos | > **Bottom line:** Start with `CLAUDE.md` + `.claude/settings.json`. Add the rest only when you feel the pain. --- ## Step-by-Step Setup ### 1. Install Claude Code ```bash npm i -g @anthropic-ai/claude-code ``` ### 2. Initialize in your project ```bash cd your-project claude # first launch creates baseline scaffolding /init # built-in slash command bootstraps CLAUDE.md ``` ### 3. Create your `CLAUDE.md` (project memory) ```markdown # Project: My App ## Tech Stack - Next.js 14, TypeScript, Tailwind - Supabase for auth & database - Prisma ORM, tRPC API layer ## Conventions - Always write tests before code (TDD). - Use conventional commits (feat:, fix:, chore:). - Never commit directly to `main`. - Run lint + typecheck before opening a PR. ## Architecture - `src/components/` → React components - `src/services/` → Business logic - `src/utils/` → Shared helpers ## Security - No secrets in code or logs. - Validate all user inputs. - Use parameterized queries only. ``` ### 4. Add shared settings — `.claude/settings.json` ```json { "permissions": { "allow": ["Read", "Bash(npm run *)", "WebSearch"], "deny": ["WriteOutsideWorkspace", "Bash(rm -rf *)"] }, "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "./scripts/pre-tool.sh" } ] } ], "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "npm run lint" } ] } ] }, "env": { "MAX_THINKING_TOKENS": "100000", "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" } } ``` ### 5. Wire up external tools — `.mcp.json` ```json { "mcpServers": { "github": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }, "postgres": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-postgres"], "env": { "DATABASE_URL": "${DATABASE_URL}" } } } } ``` ### 6. Add a custom slash command — `.claude/commands/review.md` ```markdown --- description: Run a full code review on the current branch --- You are a senior code reviewer. Diff against `main`, then: 1. List risky changes. 2. Flag missing tests. 3. Suggest concrete fixes with file:line refs. ``` > 💡 **Tip:** Anything in `.claude/commands/*.md` becomes `/filename` inside Claude. --- ## Variants for Different Team Settings ### 👤 Solo developer (the minimalist) Keep it tiny — you are the convention. ``` my-project/ ├── CLAUDE.md # your personal style guide ├── .claude/ │ └── settings.json # 1–2 hooks, generous permissions └── .mcp.json # GitHub only ``` **Decision:** Skip `skills/`, `agents/`, `plugins/` until you repeat a workflow 3+ times. ### 👥 Small team (2–10) Add shared commands and a code-review subagent. ``` .claude/ ├── settings.json # committed, shared rules ├── settings.local.json # gitignored, personal └── commands/ ├── review.md └── deploy.md agents/ └── code-reviewer.yml ``` **Decision:** Adopt **conventional commits** + **PR template** so Claude has predictable patterns to follow. ### 🏢 Enterprise / regulated Lock down permissions, add audit hooks, isolate environments. ```jsonc // .claude/settings.json { "permissions": { "allow": ["Read", "Bash(npm test)"], "deny": ["WebSearch", "Bash(curl *)", "WriteOutsideWorkspace"] }, "hooks": { "PreCommit": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "./scripts/secret-scan.sh" }, { "type": "command", "command": "./scripts/audit-log.sh" } ] } ] } } ``` **Decisions:** Centralize MCP tokens in a vault, require human approval for `Write`, ship a corporate `plugins/` pack. ### 🌍 Open-source / community Optimize for contributors who don't know your stack. - Ship a **`CLAUDE.md` with onboarding script**. - Add `docs/onboarding.md` linked from the README. - Provide a `bootstrap.md` command that runs `npm i && npm test`. - Mark `settings.local.json` in `.gitignore` so forks stay clean. > **Bottom line:** Same skeleton, different dials. **Tighten permissions as team size and risk grow.** --- ## Anatomy of a Single Unit — A Skill A "skill" is a self-contained capability folder. ``` skills/code-review/ ├── SKILL.md # what it does + when it activates ├── scripts/ │ └── analyze.sh # executable automation ├── references/ │ └── style.md # loaded on demand └── assets/ └── template.md # static files ``` ```markdown --- name: code-review description: Activates when user asks to review code, audit a PR, or check quality. triggers: ["review", "audit", "lint", "quality"] --- Use scripts/analyze.sh to diff and lint. Reference references/style.md for conventions. ``` > 🧪 **Try this:** Ask Claude *"review my last commit"* — the skill auto-activates. --- ## Lifecycle / Hook Events | Event | Fires when | Common use | |---|---|---| | `PreToolUse` | Before any tool call | Block dangerous commands, secret scan | | `PostToolUse` | After every tool call | Auto-lint, run tests | | `SessionStart` | Claude session opens | Load project context, env summary | | `SessionEnd` | Session closes | Save summary to `docs/sessions/` | | `PreCommit` | Before a git commit | Secret detection, policy checks | | `Notification` | Special events | Slack / webhook alerts | --- ## Common Patterns & Recipes ### Pattern 1 — Auto-lint after every write ```json "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm run lint -- --fix" }] } ] ``` ### Pattern 2 — Block secrets before commit ```bash #!/usr/bin/env bash # scripts/secret-scan.sh if git diff --cached | grep -E "(api[_-]?key|secret|password)\s*=" ; then echo "❌ Possible secret detected. Commit blocked." exit 1 fi ``` ### Pattern 3 — Specialized subagent (`agents/code-reviewer.yml`) ```yaml name: code-reviewer description: Reviews PRs against project conventions. model: claude-opus-4 tools: [Read, Bash, WebSearch] system_prompt: | You are a strict senior reviewer. Follow CLAUDE.md conventions. Output: 1) Risks 2) Missing tests 3) Concrete fixes (file:line). ``` ### Pattern 4 — Context budget guardrail ```json "env": { "MAX_THINKING_TOKENS": "100000", "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" } ``` ### Pattern 5 — MCP server with scoped filesystem ```json "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-filesystem", "./src", "./tests"] } ``` --- ## Best Practices ✅ - **Iterate** — start tiny, evolve as pain shows up. - **Document skills** — future-you will forget what they do. - **Modular skills** — one job per skill. - **Secrets in env vars**, never in `settings.json`. - **Test hooks locally** before committing. - **Compact context at 70–80 %** to keep responses sharp. ## Anti-Patterns ❌ - One mega-skill that does everything. - Hard-coded API tokens in `.mcp.json`. - Permissive `allow: ["*"]` in production repos. - Editing `settings.json` without telling the team. - Skipping `CLAUDE.md` ("Claude will figure it out") — it won't. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | Claude ignores conventions | `CLAUDE.md` too long or vague | Trim to ≤ 200 lines, use bullets | | Hooks not firing | Wrong `matcher` regex | Test with `matcher: "*"` first | | MCP server fails to start | Missing env var | `echo $GITHUB_TOKEN` to verify | | Context fills too fast | No autocompact | Set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | | Skill never activates | Trigger words mismatch | Add synonyms to `triggers:` list | | Permission denied on write | Sandbox blocked path | Add path to `allow` or move into workspace | --- ## Starter Template (full, copy-paste) ``` my-project/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── settings.local.json # gitignored │ └── commands/ │ ├── review.md │ ├── deploy.md │ ├── test-all.md │ └── bootstrap.md ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ ├── references/ │ │ └── assets/ │ ├── text-writer/ │ │ └── SKILL.md │ ├── security-audit/ │ │ └── SKILL.md │ └── refactor/ │ └── SKILL.md ├── agents/ │ ├── code-reviewer.yml │ ├── test-writer.yml │ ├── security-auditor.yml │ └── devops-sre.yml ├── plugins/ │ ├── manifest.json │ └── my-plugin/ ├── .mcp.json ├── .env.example ├── .gitignore └── README.md ``` `.gitignore` essentials: ```gitignore .claude/settings.local.json .env .env.local node_modules/ ``` --- ## Glossary - **Agent / Subagent** — A specialized Claude persona with its own prompt and tools. - **CLAUDE.md** — A markdown file Claude reads first; the project's "memory". - **Hook** — A shell command Claude runs automatically on lifecycle events. - **MCP (Model Context Protocol)** — Anthropic's open protocol that lets Claude talk to external tools. - **Plugin** — A bundled, shareable pack of skills/commands/hooks. - **Skill** — A reusable workflow folder Claude auto-activates by trigger words. - **Slash command** — A user-defined shortcut like `/review` defined in `.claude/commands/`. - **PreToolUse / PostToolUse** — Hook events firing before/after a tool call. --- ## Further Reading - Search: **"Claude Code official docs"** (Anthropic site) - Search: **"Model Context Protocol spec"** - Search: **"awesome-claude-code GitHub"** for community templates - Search: **"Claude Code hooks examples"** --- ## Anatomy of Subagents > Specialized subagents, patterns, orchestration, and best practices. ![Subagents](/posters/03-subagents.png) > Specialized AI teammates that handle focused work in parallel — so your main agent stays sharp and your team ships faster. --- ## TL;DR - A **subagent** (a.k.a. agent) is a lightweight, purpose-built Claude persona with its own **prompt, tools, permissions, and triggers**. - They run under the **main orchestrator** (Claude Code) to complete parts of a larger goal — sequentially or in parallel. - Defined as **one YAML file per agent** under `agents/`. - Best when each subagent does **one job, really well**. - Right governance turns them from "neat demo" into **auditable, reusable teammates**. --- ## Why this matters Think of a film set. Instead of one person doing direction, lighting, sound, and editing, you hire specialists. **Subagents are your AI film crew** — each focused, predictable, and replaceable. > **Bottom line:** Specialization beats genius generalists. Decompose the problem, delegate to specialists, combine the best. --- ## The Big Picture ```mermaid flowchart TB U[You / Claude Code] --> O[Orchestrator] O --> A1[code-reviewer] O --> A2[test-writer] O --> A3[security-auditor] O --> A4[docs-writer] O --> A5[devops-sre] A1 --> R[Merged Result] A2 --> R A3 --> R A4 --> R A5 --> R R --> U ``` > **Bottom line:** One orchestrator plans and delegates; many specialists deliver in parallel; results merge back. --- ## When to Use Subagents - Tasks can run **independently** or in parallel. - Each task needs **different expertise or tools**. - You want **predictable, repeatable outputs**. - Complex workflows need **focus and safety boundaries**. - **Consistent quality and auditability** matter. > 💡 **Tip:** If a single prompt keeps drifting, that's the signal to split the work into subagents. --- ## Directory Structure ``` agents/ ├── code-reviewer.yml ├── test-writer.yml ├── security-auditor.yml ├── docs-writer.yml └── devops-sre.yml ``` - One file (YAML) per subagent. - Shared folder, **checked into the repo**. - Versioned and peer-reviewed like code. - Document **purpose, triggers, and examples** in each file. - Keep examples up to date. > 💡 **Tip:** Store agents in the repo so the whole team benefits. --- ## Subagent Anatomy (zoom in) ```yaml # agents/code-reviewer.yml name: code-reviewer # unique id (use kebab-case) description: Reviews PRs for quality, security, & tests. # used for routing & discovery model: claude-opus-4 # which model to use system_prompt: | You are a senior engineer and strict code reviewer. Follow project conventions in CLAUDE.md. Output must include: summary, risks, missing tests, and concrete fixes with file:line references. tools: # allowed tools - Read - Bash - Grep - WebSearch permissions: # sandbox boundary allow: ["Read", "Bash(npm test)", "WebSearch"] deny: ["WriteOutsideWorkspace", "Bash(rm -rf *)"] triggers: ["review", "audit", "pr", "quality", "code-reviewer"] timeout_ms: 120000 # safety cap max_tokens: 8000 # output budget tags: ["quality", "review"] # categorization version: 1.0.0 # version for tracking notes: | Optional additional instructions, examples, or rules below. ``` --- ## Common Fields Reference | Field | Type | Required | Purpose | |---|---|---|---| | `name` | string | ✅ Yes | Unique id for the agent | | `description` | string | ✅ Yes | One-line summary (used for auto-routing) | | `model` | string | No | Which model to use | | `system_prompt` | string | ✅ Yes | The persona, rules, and examples | | `tools` | array | No | Allowed tools | | `permissions` | object | No | Allow / deny lists | | `triggers` | array | No | Keywords for auto-activation | | `timeout_ms` | number | No | Max runtime in milliseconds | | `max_tokens` | number | No | Output token budget | | `tags` | array | No | Categorization metadata | | `version` | string | No | SemVer for change tracking | --- ## Step-by-Step Setup ### 1. Create the agents directory ```bash mkdir -p agents ``` ### 2. Create your first agent ```bash cat > agents/code-reviewer.yml <<'EOF' name: code-reviewer description: Reviews PRs for quality, security, and tests. model: claude-opus-4 system_prompt: | You are a strict senior reviewer. Follow CLAUDE.md. Output: 1) Risks 2) Missing tests 3) Concrete fixes. tools: [Read, Bash, Grep] permissions: allow: ["Read", "Bash(npm test)"] deny: ["WriteOutsideWorkspace"] triggers: ["review", "audit", "pr"] timeout_ms: 120000 max_tokens: 8000 EOF ``` ### 3. Register agents in `CLAUDE.md` ```markdown ## Available subagents - `@code-reviewer` — PR & code reviews - `@test-writer` — unit + integration tests - `@security-auditor` — vulnerability scans - `@docs-writer` — API docs & READMEs - `@devops-sre` — CI/CD, infra, deploys ``` ### 4. Invoke it ```text "Use @code-reviewer on this PR." ``` Or let auto-activation pick it up via triggers ("review this PR"). ### 5. Iterate Refine `system_prompt` after each real run; commit the change with a SemVer bump. --- ## Design Patterns ### 1. Sequential Pipeline ```text A → B → C → D ``` One after another. Use when steps depend on each other. ### 2. Parallel Fan-out ```text ┌─ B A ──────┼─ C └─ D ``` Multiple specialists run independently, results merge. ### 3. Router / Selector ```text A ──► [router] ──► B | C | D ``` Orchestrator picks the best specialist by intent. ### 4. Reflect & Retry ```text A ──► critic ──► (fail) ──► improve ──► A ``` Specialist + critic loop until quality threshold met. ### 5. Plan & Act (ReAct) ```text Think → Act → Observe → Repeat ``` Iterate small actions guided by reasoning. > 💡 **Tip:** Start simple. Add parallelism only when it demonstrably helps. --- ## Invocation & Triggers ### Explicit invoke ```text @code-reviewer — review this PR. Use @test-writer to add unit tests. Ask @security-auditor for a risk check. ``` ### Auto-activation When the user says: - **"review"** / **"audit"** / **"pr"** → routes to `@code-reviewer` - **"test"** / **"unit"** / **"coverage"** → routes to `@test-writer` - **"security"** / **"vulnerability"** / **"secret"** → routes to `@security-auditor` > 💡 **Tip:** Keep trigger words **realistic and unambiguous** — synonyms the team actually uses. --- ## How Subagents Work Together 1. **Break the goal into steps** (orchestrator plans). 2. **Delegate to the right specialists**. 3. **Run in parallel or sequence** based on dependencies. 4. **Merge, critique, and return the result**. 5. **Iterate** if quality thresholds aren't met. --- ## Popular Subagents (real-world examples) | Subagent | Best for | Key tools | Typical output | |---|---|---|---| | `code-reviewer` | PR reviews, quality gates | Read, Bash, Grep | Review report | | `test-writer` | Unit & integration tests | Read, Edit, Bash | Tests + coverage | | `security-auditor` | Vulnerabilities, secrets | Read, WebSearch, Bash | Risk report | | `docs-writer` | Docs, READMEs, API refs | Read, Edit | Markdown docs | | `refactor` | Code cleanup & design | Read, Edit, Bash | Refactored code | | `bug-triage` | Issue classification | Read, WebSearch | Triage summary | | `devops-sre` | CI/CD, infra, deploys | Bash, Read, WebSearch | Runbook / plan | | `release-manager` | Changelogs, version bumps | Read, Edit, Bash | Release notes | --- ## Permissions & Safety ### ✅ DO - Grant **least-privilege** access. - **Limit write operations**. - **Deny destructive commands** (`rm -rf`, `sudo`). - Use **specific tool names**, not wildcards. - **Review subagent changes** like production code. - **Log sensitive actions** to an audit trail. ### ❌ DON'T - Allow `WriteOutsideWorkspace`. - Allow `Bash(rm -rf *)`. - Use `allow: ["*"]`. - Hard-code secrets in the YAML. - Skip reviews & audits. - Ignore `timeout_ms`. > 💡 **Tip:** Safe by default. **Escalate only when needed**, with a paper trail. --- ## Common Patterns & Recipes ### Pattern 1 — Self-check loop ```yaml # orchestrator pseudocode - @claude-code: write code - @code-reviewer: review - if review.fails && attempts < 3: goto write code ``` ### Pattern 2 — Fan-out review ```text on PR open: parallel: - @code-reviewer - @security-auditor - @test-writer merge: combined report ``` ### Pattern 3 — Strict reviewer persona ```yaml system_prompt: | Be ruthless. Reject any change without tests. Never approve secrets in code. Output format: Risks | Missing Tests | Fixes (file:line). ``` ### Pattern 4 — Cost-aware fallback ```yaml model: claude-haiku-4 # cheap default escalate_to: claude-opus-4 escalate_when: "risk == high || diff_lines > 500" ``` ### Pattern 5 — Auditable subagent ```yaml hooks: on_invoke: ["./scripts/audit-agent.sh start"] on_complete: ["./scripts/audit-agent.sh end"] ``` ### Pattern 6 — Domain-specific persona ```yaml name: hipaa-reviewer system_prompt: | You are a HIPAA compliance reviewer. Flag any PHI handling without proper encryption or access controls. Cite specific HIPAA rules in your findings. tags: ["compliance", "healthcare"] ``` --- ## Variants for Different Team Settings ### 👤 Solo developer One agent: `@code-reviewer`. Run it before every commit. ```yaml name: code-reviewer description: Quick PR check before commit. model: claude-haiku-4 system_prompt: | Quick review. Focus on bugs and missing tests. tools: [Read, Bash] permissions: { allow: ["Read", "Bash(npm test)"] } triggers: ["review", "check"] ``` ### 👥 Small team (2–10) Add `@test-writer` and `@docs-writer`. Wire into PR templates. ```text PR Checklist: - [ ] Ran @code-reviewer - [ ] Updated tests (@test-writer if missing) - [ ] Updated docs (@docs-writer if API changed) ``` ### 🏢 Enterprise / regulated - **Pin model versions** for reproducibility. - Add `@security-auditor` with **deny-by-default**. - **Log every invocation** to SIEM. - **PR review required** on every agent change. - Run agents in **isolated containers** when handling sensitive data. ```yaml permissions: allow: ["Read"] deny: ["Bash", "Write", "WebFetch"] hooks: on_invoke: ["./scripts/audit-siem.sh"] timeout_ms: 60000 ``` ### 🌍 Open-source - Share `agents/` in the repo so forks inherit them. - Document each agent's purpose, triggers, and tools. - Keep prompts **generic** (no internal jargon). > **Bottom line:** Same YAML, escalating governance. --- ## Anatomy of a Single Run — Zoomed In ```text 1. User: "Audit our auth flow." 2. Orchestrator routes to @security-auditor (trigger: "audit"). 3. Agent loads CLAUDE.md + reads src/auth/**. 4. Runs scripts/secret-scan.sh. 5. Generates risk report: - 🔴 Critical: missing rate limit on /login - 🟡 Concern: JWT secret rotation overdue - 🟢 Info: CSRF protection in place 6. Returns structured output to orchestrator. 7. Orchestrator hands off fixes to @refactor. ``` --- ## Best Practices ✅ - **One job per subagent.** - **Write clear, concrete prompts** — include examples. - **Provide examples & output format.** - **Limit tools** to only what's needed. - **Define triggers with synonyms** the team actually uses. - **Set `timeout_ms` & `max_tokens`** — runaway costs hurt. - **Version like code** (SemVer). - **Measure & improve continuously** based on feedback. ## Anti-Patterns ❌ - **Mega-agent** that does everything. - **Vague prompts** ("be helpful"). - **Too many tools or permissions.** - **No triggers** or poor triggers. - **No timeouts or budgets.** - **Hard-coded secrets or paths.** - **No review or change control.** - **Forgetting to update examples** when behavior drifts. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | Agent not used | Triggers don't match | Add synonyms to `triggers:` | | Poor / generic output | Prompt too vague | Add examples & strict format rules | | Tool error | Missing permission | Grant the specific tool | | Runs too long | No timeout | Set `timeout_ms` | | Too much text | No `max_tokens` budget | Set `max_tokens` | | Repeats itself | No critic step | Add a self-check or reviewer agent | | Wrong agent picked | Router logic weak | Tighten descriptions & triggers | | Costs spike | High-end model on cheap tasks | Add cost-aware fallback | --- ## Getting Started (6 steps) 1. **Identify recurring, focused tasks** in your team's day. 2. **Sketch the subagent prompt** in plain English. 3. **Define triggers & permissions** (deny by default). 4. **Set timeouts & token budgets.** 5. **Test & refine iteratively** on real tasks. 6. **Share with your team** via the repo + `CLAUDE.md`. --- ## Starter Template (copy & adapt) ```yaml name: my-agent description: Do one thing really well. model: claude-sonnet-4 system_prompt: | You are a helpful expert. Be concise and specific. tools: [Read] permissions: allow: ["Read"] deny: ["WriteOutsideWorkspace"] triggers: ["mytask"] timeout_ms: 60000 max_tokens: 4000 version: 1.0.0 tags: ["generic"] notes: | Add notes or references here. ``` > 💡 **Tip:** Start with one agent. Clone & specialize as patterns emerge. --- ## Glossary - **Subagent / Agent** — A scoped Claude persona invoked by the main session. - **Orchestrator** — The top-level Claude that plans and delegates. - **Trigger** — A keyword or phrase that auto-activates an agent. - **Tool** — A capability the agent may call (Read, Bash, etc.). - **System prompt** — The fixed persona/rules text. - **Router** — Logic (or a model) that picks which agent runs. - **Critic** — A subagent or rule that validates another's output. - **Fan-out** — Parallel execution of multiple subagents on the same input. - **Reflect & retry** — Iteratively improve via self-critique. --- ## Further Reading - Search: **"Claude Code subagents documentation"** - Search: **"agentic workflows orchestrator pattern"** - Search: **"awesome-claude-agents GitHub"** - Search: **"multi-agent LLM coordination patterns"** --- ## 🪙 Golden Rules - 🧠 **Specialize ruthlessly** — one job per agent. - 🎯 **Delegate deliberately** — right agent, right task. - 🛡️ **Be safe by default** — least privilege always. - 🔁 **Iterate & improve** — feedback makes better agents. - 📝 **Document everything** — future-you will thank you. > **Remember:** Great subagents are like great teammates — focused, trustworthy, and easy to work with. --- ## The Claude Anatomy Library import Callout from '@site/src/components/Callout'; import AnatomyGrid from '@site/src/components/AnatomyGrid'; # The Claude Anatomy Library > **21 anatomies. One system. Endless improvement.** > > Your complete blueprint for building, operating, and continuously improving AI-powered software teams with **Claude Code**. New here? Jump straight to **Project Structure →** or browse all **/posters**. --- ## What you'll learn - **Ship faster** with high quality — structured AI workflows that don't cut corners - **Lower cost** & higher efficiency — optimize token usage, batching, and reuse patterns - **Reduce risk** & increase trust — safeguards, governance, and observability baked in - **Better onboarding** & knowledge retention — new engineers productive in days, not months - **A self-improving** engineering system — feedback loops that continuously refine outcomes --- ## The Library at a Glance ```mermaid flowchart LR F[Foundation5 anatomies] --> R[Reusability2] R --> O[Orchestration2] O --> W[Workflows2] W --> M[Management3] M --> P[People1] P --> Q[Quality1] Q --> Op[Operations3] Op --> T[Trust1] T --> Me[Meta1] Me -.feedback loop.-> F ``` **Ten themes. Twenty-one anatomies. One self-improving loop.** --- ## The 21 Anatomies — Browse by Theme ### Foundation — The building blocks The structural blueprint for any AI-augmented codebase. ### Reusability — Make expertise repeatable ### Orchestration — Coordinate complex work ### Workflows — Day-to-day execution ### Management — Rhythm, quality & efficiency ### People — Get your team productive ### Quality — Ship with confidence ### Operations — Run & improve ### Trust — Govern with care ### Meta — The system that makes the library better --- ## How to use this library 1. **Pick your starting point** — use the roadmap below. **Start small.** 2. **Read the anatomy** — concepts, patterns, examples. 3. **Implement incrementally** — adopt one pattern at a time. Ship small. 4. **Measure & iterate** — use the loops. Improve continuously. 5. **Share & teach** — document learnings. Help others grow. The roadmap below is opinionated for a reason — each phase builds on the last. --- ## Recommended Adoption Roadmap ```mermaid gantt title 3-Month Adoption Path dateFormat YYYY-MM-DD axisFormat Week %V section Phase 1 · Foundation Anatomies 1-5 :p1, 2026-01-01, 14d section Phase 2 · Workflows Anatomies 6-12 :p2, after p1, 14d section Phase 3 · Quality Anatomies 13,14,16,17 :p3, after p2, 30d section Phase 4 · People & Ops Anatomies 15,18,19 :p4, after p3, 30d section Phase 5 · Trust & Loop Anatomies 20,21 :p5, after p4, 30d ``` ### Phase 1 — Foundation _(Weeks 1–2)_ Adopt anatomies **1 · 2 · 3 · 5** (and a starter **4**). **Goal:** a working `.claude/` setup with project memory, one subagent, one MCP server. ### Phase 2 — Core Workflows _(Weeks 3–4)_ Adopt **6 · 7 · 8 · 9 · 10 · 11 · 12**. **Goal:** reusable skills/plugins + daily dev-loop rhythm + clean context management. ### Phase 3 — Quality & Efficiency _(Month 2)_ Adopt **13 · 14 · 16 · 17**. **Goal:** prompt patterns at scale, cost guardrails, PR-quality system, observability baseline. ### Phase 4 — People & Operations _(Months 2–3)_ Adopt **15 · 18 · 19**. **Goal:** new hires productive week 1; incidents and postmortems become learning fuel. ### Phase 5 — Trust & Continuous Learning _(Month 3+)_ Adopt **20 · 21**. **Goal:** regulated-team trust + the **[self-improving Knowledge Loop](/meta/knowledge-loop)**. --- ## Three ways to start right now ### I'm a solo developer Start with **[`CLAUDE.md`](/foundation/claude-md)** and **[Slash Commands](/workflows/slash-commands)**. Skip MCP and subagents until you feel the friction. ### I'm leading a small team (2–10) Lay down **---| | **Docusaurus 3.10.1** | Last v3.x line; future-flag ready for v4 | | **`future.v4: true`** | All v4 breakers enabled — zero-effort migration when v4 ships | | **`experimental_faster: true`** | SWC + Lightning CSS + Rspack → 2–5× faster rebuilds | | **Mermaid native** | Every anatomy diagrams its own loop | | **GitHub Pages CI** | Auto-deploy on push to `main` with build-cache preserved | The **[`README.md`](https://github.com/vamsi713061/claude-anatomy-library#readme)** has the full Docusaurus 3.10.1 + GH Pages walkthrough, including the `--v4` modes and Faster pipeline. --- ## Golden Rules - **Be specific** in prompts - **Keep context** lean & relevant - **Automate** with hooks - **Review** everything - **Document** as you go - **Measure** & iterate - **Share** & learn together --- ## What's next ```mermaid flowchart LR A[Start withFoundation] --> B[Adopt oneanatomy/week] B --> C[Measureimpact] C --> D[Improve viaKnowledge Loop] D --> A ``` **[Begin with Anatomy #1 — Claude Code Project Structure →](/foundation/project-structure)** Or skim the **[full poster gallery](/posters)** first. --- ## Closing thought > **The goal is not perfection. The goal is a system that improves every day.** > > **The mantra:** Observe → Analyze → Improve → Validate → Share → Repeat --- --- ## Anatomy of AI Cost & Token Economics > Models, context, batching, caching, and cost guardrails. ![Cost Economics](/posters/14-cost-economics.png) > How to ship without burning the budget — pick the right model, feed the right context, batch & cache aggressively, and measure relentlessly. --- ## TL;DR - **Total cost** = `(input tokens × input price) + (output tokens × output price)` — every layer scales with this formula. - The biggest savings come from **less context** and **shorter outputs**, not just cheaper models. - **Tier your models**: Haiku for routing & summaries, Sonnet for everyday code, Opus only when accuracy *really* matters. - **Batch · cache · stream · parallelize** — four levers that compound. - **Instrument first.** What you don't measure, you can't reduce. --- ## Why this matters LLM costs scale with *use*, not seats. A team that ships 50 PRs/week with AI assistance can easily 10× its bill in a month if no one is watching the meter. The fix isn't to use less AI — it's to use AI **deliberately**. > **Bottom line:** Token discipline is the difference between a $200/mo magic teammate and a $20,000/mo budget surprise. --- ## The Big Picture — The Cost Formula ```mermaid flowchart LR A[Input Tokenswhat you send] --> M((Model)) P1[Input Price$/1M tokens] --> M M --> B[Output Tokenswhat model returns] M --> P2[Output Price$/1M tokens] A & P1 & B & P2 --> T[Total Cost] ``` ```text Total Cost = (Input Tokens × Input Price) + (Output Tokens × Output Price) ``` Cost varies by: - 🧠 **Model** (Haiku < Sonnet < Opus) - 📦 **Context size** (every token you send) - 📝 **Output length** (often the bigger half!) - 🛠️ **Tool calls** (each round-trip = more tokens) - 💾 **Caching** (huge multiplier when reused) - 🌍 **Region / provider** > 🪙 **Golden rule:** Optimize the **product** of tokens × price at every step. --- ## Model Price Guide (USD per 1M tokens) > 💡 Prices are **indicative** and change frequently. Always confirm with the provider's pricing page before locking in a budget. | Model (as of mid-2025) | Input | Output | Best for | |---|---|---|---| | **Claude Opus 4** | $15.00 | $75.00 | Complex reasoning, critical tasks | | **Claude Sonnet 4** | $3.00 | $15.00 | Balanced quality & cost ⭐ | | **Claude Haiku 4** | $0.80 | $4.00 | Simple tasks, summaries, routing | | **GPT-4.1** | $10.00 | $30.00 | General-purpose, code, analysis | | **GPT-4o mini** | $0.15 | $0.60 | High-volume, simple tasks | | **Gemini 1.5 Pro** | $3.50 | $10.50 | Large context, multimodal | > 💡 **Rule of thumb:** Start with **Haiku/mini → escalate to Sonnet → only then Opus.** --- ## How Context Drives Cost Typical cost breakdown for a medium coding session: | Source | % of cost | Why | |---|---|---| | **Context (input)** | ~55% | Files, history, system prompts | | **Output (generation)** | ~30% | Responses, code, explanations | | **Tools & misc** | ~15% | Tool calls, retries, overhead | ### Costs spike when you: - ❌ Attach large files blindly - ❌ Paste long logs / stack traces - ❌ Keep old conversation history forever - ❌ Ask for verbose outputs ("explain everything") - ❌ Run many tool calls per task > 💡 **Tip:** **Trim input. Constrain output. Compact early.** --- ## Token Budgeting Framework Estimate **before** you run. Measure **after** you run. Refine. | Task type | Recommended model | Est. input tokens | Est. output tokens | Est. cost (USD) | |---|---|---|---|---| | Quick answer / lookup | Haiku 4 | 500 | 300 | ~$0.001 | | Summarization | Haiku 4 | 2,000 | 600 | ~$0.003 | | Code generation (small) | Sonnet 4 | 2,000 | 1,500 | ~$0.028 | | Code review (medium) | Sonnet 4 | 8,000 | 2,000 | ~$0.054 | | Architecture / design | Opus 4 | 12,000 | 3,000 | ~$0.405 | | Multi-file refactor | Opus 4 | 20,000 | 4,000 | ~$0.600 | > 💡 **Tip:** Multiply expected daily runs to forecast monthly burn. A 200× factor between Haiku and Opus is *normal*. --- ## Choose the Right Model — Decision Tree ```mermaid flowchart TB Q[What is the task?] Q --> R[Route / classify / extract] Q --> C[Code / reason / analyze] Q --> D[Complex design / deep reasoning] Q --> H[High-volume / batch jobs] R --> R2{Simple logic &short output?} R2 -- yes --> Hk[🟢 Haiku 4 / GPT-4o mini] C --> C2{Need higheraccuracy?} C2 -- yes --> Sn[🟡 Sonnet 4 / GPT-4.1] D --> D2{High risk ornovel problem?} D2 -- yes --> Op[🔴 Opus 4 / top-tier] H --> H2{Throughput > quality?} H2 -- yes --> Hk2[🟢 Haiku 4 / mini + batching] ``` > 💡 **Tip:** **Start cheap. Escalate only when the cost of being wrong is high.** --- ## Context Management = Cost Management ### ✅ Do this - Load **only needed files** (`@path/to/file`). - Use **summaries**, not full logs. - Keep earlier conversation **short**. - Enable **auto-compact** (50% threshold). - Use **structured outputs** (JSON) — fewer wasted tokens. - **Drop irrelevant context** between turns. ### ❌ Avoid - ❌ Dumping entire codebases - ❌ Pasting huge logs / traces - ❌ Asking for essays when bullets do - ❌ Repeating the same info - ❌ Keeping solved threads alive - ❌ Verbose explanations by default > 💡 **Tip:** Every token in **saves 1–10 tokens out** (and dollars). --- ## Batching & Parallelism ### Batch similar tasks ```text Summarize 10 PRs at once → one call → return JSON list Extract metadata from files → one prompt, batched files Classify tickets in bulk → one prompt, many inputs Generate changelogs → one prompt, multiple commits ``` Why it wins: **shared system prompt + amortized overhead** across N tasks. ### Parallelize independent tasks ```mermaid flowchart LR Start[Trigger] --> A[Task A] Start --> B[Task B] Start --> C[Task C] A --> Merge[Merge results] B --> Merge C --> Merge ``` Wins on **wall-clock time** (faster sessions, smaller context per agent). ### Cache aggressively - **Prompt caching:** Reuse identical system prompts at fraction price. - **Embedding caching:** Don't re-embed unchanged docs. - **Tool-output caching:** Cache deterministic tool results. - **Invalidate** when underlying data actually changes. > 💡 **Tip:** A **90%+ cache hit rate on system prompts** is achievable and pays for itself in days. --- ## Reduce Output Cost (often the bigger half) | Instead of this… | …say this | |---|---| | "Write a long explanation with examples." | "Explain in 3 bullets with one example." | | "Give me full docs." | "Give me an outline then fill key parts." | | "List all edge cases." | "List top 5 critical edge cases." | | "Verbose code review." | "Summarize findings by severity." | ### Output-shaping tactics - 📋 Ask for **JSON or bullet points**. - 🪶 Set `max_tokens` / `max_length`. - ✂️ Use a concise tone: **"Be brief."** - 🪜 **Break into steps** with small outputs each. - 🧪 Summarize **before** deep dives. > 💡 **Tip:** Output discipline = **huge savings**. Often 30–60% off a bill. --- ## Instrument, Measure & Alert ### Track these metrics | Metric | Why it matters | |---|---| | Input tokens | Detect bloated prompts | | Output tokens | Detect verbose responses | | **Total cost (USD)** | The bottom line | | Cost per task | Right-size your unit economics | | **Cache hit rate** | Caching effectiveness | | Model usage mix | Are you over-using premium tiers? | ### Sample logging payload ```json { "ts": "2025-05-20T10:30:00Z", "model": "claude-sonnet-4", "input_tokens": 5421, "output_tokens": 812, "cost_usd": 0.0189, "task": "code_review", "cache_hit": false, "user": "alice", "session_id": "abc123" } ``` ### Alert when - 🚨 **Cost per day > budget** - 🚨 **Single request > threshold** (e.g., $1) - 🚨 **Token usage > 90%** of context window - 🚨 **Cache hit rate drops** suddenly (regression) > 💡 **Tip:** What gets measured gets optimized. Send these to your existing dashboard (Datadog, Grafana, etc.). --- ## Budgets & Guardrails ### Daily / monthly budget config ```json { "budgets": { "daily_usd": 50.00, "monthly_usd": 1000.00 }, "enforcement": { "mode": "soft", // soft | hard "warn_at_pct": 80, "block_at_pct": 100 } } ``` ### Guardrail playbook | Threshold | Action | |---|---| | **80% of budget** | Warn user + team channel | | **50% context used** | Auto-compact | | **80% context used** | Downshift to cheaper model | | **Request > $X** | Require human approval | | **100% budget** | Hard block + escalation | > 💡 **Tip:** Budget pain **today** = budget automation **tomorrow**. Codify thresholds early. --- ## Step-by-Step Setup ### 1. Classify your tasks and map to models Create `docs/model-routing.md`: ```markdown | Task | Model | Why | |---|---|---| | Triage / routing | Haiku | Cheap, fast, simple | | Code review | Sonnet | Balanced quality/cost | | Critical refactor | Opus | Accuracy worth the cost | ``` ### 2. Enable auto-compact in `.claude/settings.json` ```json { "env": { "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" }, "features": { "autoCompact": true, "autoCompactMode": "balanced" } } ``` ### 3. Add a cost-logging hook `scripts/log-cost.sh`: ```bash #!/usr/bin/env bash # Append per-call metrics to a daily file DATE=$(date +%Y-%m-%d) mkdir -p .claude/logs echo "{\"ts\":\"$(date -Iseconds)\",\"model\":\"$CLAUDE_MODEL\",\"in\":$CLAUDE_INPUT_TOKENS,\"out\":$CLAUDE_OUTPUT_TOKENS,\"cost\":$CLAUDE_COST_USD}" \ >> ".claude/logs/cost-$DATE.jsonl" ``` `.claude/settings.json`: ```json "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/log-cost.sh" }] } ] } ``` ### 4. Add a `/budget` slash command `.claude/commands/budget.md`: ```markdown --- description: Show today's spend, top tasks, cache hit rate usage: /budget [--month] --- Read `.claude/logs/cost-*.jsonl` and report: - Spend today vs daily budget (with % bar) - Top 5 costliest tasks - Model usage mix - Cache hit rate - Suggestion: any task to downshift? ``` ### 5. Start cheap, escalate deliberately Default model = Sonnet. Switch to Opus **only** via explicit `/escalate` command. ### 6. Review weekly Weekly retro: which tasks blew the budget? Re-route them. --- ## Variants for Different Team Settings ### 👤 Solo developer - Default to **Haiku** for everything except complex refactors. - One JSON log, one weekly glance. - Budget: **$20–50/mo** typical. ### 👥 Small team (2–10) - Shared `model-routing.md`. - Per-user daily soft-cap, team monthly hard-cap. - Slack alert at 80%. - Cache shared system prompts repo-wide. ### 🏢 Enterprise / regulated - **Hard budgets per project**. - **Cost attribution** by team/cost-center via metadata in every call. - **Approval workflow** for Opus / large-context requests. - Centralized **FinOps dashboard**. - **Quarterly model re-tiering** as prices change. ### 🌍 Open-source / community - **Cap per-contributor session** to prevent abuse. - Document recommended models in `CONTRIBUTING.md`. - Provide a **free-tier-friendly** default config. > **Bottom line:** Same formula, escalating discipline. --- ## Common Patterns & Recipes ### Pattern 1 — Two-pass cheap-then-deep ```text Pass 1 (Haiku): classify and triage the diff. Pass 2 (Sonnet): only deep-review files flagged risky. ``` ### Pattern 2 — Summarize-then-act ```text Step 1: Summarize the 20 files into a 200-line plan. Step 2: Hand only the plan + 3 files to Opus. ``` ### Pattern 3 — Hierarchical routing ```yaml router: default: haiku if_keyword: ["refactor", "architecture", "design"] → opus if_size > 5000_tokens → sonnet ``` ### Pattern 4 — Cached system prompt ```text Reuse identical "You are a senior reviewer..." block. Cache hit = ~10× cheaper input tokens. ``` ### Pattern 5 — Budget-aware retry ```text On model error or timeout: - First retry: same model - Second retry: downshift one tier - Then: surface to human ``` ### Pattern 6 — JSON-mode for parsability ```text Return ONLY this JSON: { "summary": "...", "issues": [...], "fixes": [...] } ``` Outputs shrink ~30% and your code can parse without LLM glue. --- ## Best Practices ✅ - **Use the smallest model that works.** - **Feed only what's essential.** - **Batch, cache, reuse, summarize.** - **Measure, alert, iterate.** - **Codify budgets & approvals.** - **Right-tier weekly** as prices and quality evolve. - **Document model routing** so the team makes the same call. ## Anti-Patterns ❌ - 🚫 Defaulting to Opus "to be safe". - 🚫 Pasting entire codebases into context. - 🚫 Asking for verbose explanations by default. - 🚫 No caching of system prompts. - 🚫 No metrics, no budgets, no alerts. - 🚫 Treating context length as free. - 🚫 Hardcoding model names in every script (impossible to retier). --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | Sudden cost spike | New chatty prompt / large file attached | Audit recent diffs to prompts | | Slow + expensive | Wrong tier (Opus on simple tasks) | Add router rule, downshift | | Cache hit rate drops | Prompt changed slightly each call | Stabilize boilerplate; parameterize variants | | Output too long | No format / `max_tokens` | Enforce JSON or bullets + cap | | Token usage > 90% | Context bloat | Enable auto-compact (50%) | | One user dominates spend | No per-user budget | Per-seat soft caps + Slack alert | | Repeated tool errors | Retries on premium model | Budget-aware retry + downshift | --- ## Quick-Start Checklist - ✅ Classify tasks and map them to models. - ✅ Write prompts that are concise & structured. - ✅ Enable auto-compact (50%). - ✅ Cache what you can (system prompts, embeddings, tool outputs). - ✅ Instrument & set budgets (daily + monthly). - ✅ Review metrics weekly and iterate. > 🧠 **Mantra:** **Right model. Right context. Right pattern. Right time. Right results.** --- ## Starter Configs ### `.claude/settings.json` — cost-savvy defaults ```json { "model": { "default": "claude-sonnet-4", "fallback": ["claude-haiku-4"] }, "env": { "MAX_THINKING_TOKENS": "60000", "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" }, "features": { "autoCompact": true, "autoCompactMode": "balanced" }, "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/log-cost.sh" }] } ] } } ``` ### `model-routing.md` — your team's rule book ```markdown # Model Routing | Task | Model | Rationale | |---------------------|----------|----------------------| | Routing / classify | Haiku | Cheap, fast | | Summarization | Haiku | Output is short | | Daily code work | Sonnet | Balanced | | Architecture | Opus | Accuracy matters | | Bulk transforms | Haiku | Batch + parallelize | ## Escalation Use `/escalate` to bump the next tier with a 1-line reason (logged for the weekly review). ``` --- ## Glossary - **Token** — Roughly ~4 characters of text; the LLM's unit of work and cost. - **Context window** — Max tokens the model can "see" per call. - **Input tokens** — What you send (prompt + system + history + tools). - **Output tokens** — What the model returns. Often **5× the price** of input. - **Prompt caching** — Reusing identical prompt prefixes at a discount. - **Auto-compact** — Automatic summarization to keep context lean. - **Routing / tiering** — Picking the cheapest model that meets the bar. - **Batching** — Combining many tasks into one call. - **FinOps** — Discipline of managing cloud / AI costs. --- ## Further Reading - Search: **"Anthropic prompt caching docs"** - Search: **"OpenAI pricing & batch API"** - Search: **"LLM cost optimization patterns 2026"** - Search: **"FinOps for AI workloads"** --- ## 🪙 Golden Rules - 🛑 **Never attach what you don't need.** - 🌱 **Start small. Scale only when needed.** - 📊 **Measure everything. Optimize relentlessly.** - 🤖 **Automate the boring. Focus on the multiplier.** > **Remember:** The cheapest token is the one you **don't use**. --- ## Anatomy of AI-Powered Dev Loop > Daily/weekly rhythms (plan → pair → review → retro) for AI-augmented teams. ![Dev Loop](/posters/12-dev-loop.png) > Daily & weekly rhythms for AI-augmented teams — **Plan → Pair → Review → Retro** — to ship better software, faster, together. --- ## TL;DR - The **AI-powered dev loop** has four phases: **Plan · Pair · Review · Retro**. - Run the full loop **every day** at small scale; **every week** at larger scale. - Use AI as a **multiplier**, not a replacement: clarify intent, generate options, accelerate execution, raise the quality bar. - **Treat AI like a senior teammate** — give it context, review everything, iterate. - The loop's job is **continuous learning**: every retro improves the next plan. --- ## Why this matters Most teams have *tools* but no *rhythm*. They adopt AI ad hoc — one engineer uses it brilliantly, the rest don't. **A loop turns AI into a team practice**: same cadence, same artifacts, same feedback signals. That's how AI moves from "neat trick" to "compound advantage." > **Bottom line:** Without rhythm, AI is a toy. With rhythm, AI is a multiplier. --- ## The Big Picture ```mermaid flowchart LR P[PlanClarify goals & scope] --> Pa[PairBuild together with AI] Pa --> R[ReviewQuality gates & feedback] R --> Re[RetroLearn, improve, evolve] Re --> P ``` > **Bottom line:** Four phases. One loop. Daily inside, weekly outside. --- ## The Four Phases | Phase | Purpose | AI's role | Output | |---|---|---|---| | 🎯 **Plan** | Clarify goals & scope | Brainstorm, decompose, propose alternatives | Tasks with acceptance criteria | | 🤝 **Pair** | Build together | Pair programmer: scaffold, refactor, test | Working code + tests | | 🔍 **Review** | Quality gates | Reviewer: lint, tests, risk analysis | Approved (or fixed) PR | | 🔁 **Retro** | Learn & improve | Coach: surface signals, suggest tweaks | Updated playbook | --- ## 1. Plan — Clarify & Align **Goal:** Convert intent into well-formed tasks **before** any code is written. ### Checklist - ✅ Define the problem & user value - ✅ Break down into tasks (**vertical slices**) - ✅ Write acceptance criteria (Given / When / Then) - ✅ Identify risks, dependencies, unknowns - ✅ Ask AI to **propose plan & alternatives** - ✅ Estimate effort & set the daily goal ### Example prompt ```text Act as a tech lead. Help me break down this feature into tasks with acceptance criteria, risks, and dependencies: Return: 1. Tasks (≤4 hours each), vertical slices. 2. Acceptance criteria per task (Given/When/Then). 3. Risks & unknowns to investigate first. 4. Suggested order of work + critical path. ``` ### Output example ```text Tasks (vertical slices, ≤4 hrs each): 1. [auth] Magic-link request endpoint AC: Given anonymous, When POST /auth/magic, Then 200 + email queued 2. [auth] Magic-link verify endpoint 3. [auth] Session cookie issued 4. [ui] Login page redirect after verify Risks & unknowns: - Email deliverability in regions X, Y - Token TTL strategy (15 min vs 1 hr) Dependencies: - SendGrid sandbox creds - JWT signing key rotation policy Suggested order: 2 → 1 → 3 → 4 (de-risk verify first) ``` > 💡 **Tip:** A good Plan is one where you could hand the tasks to **any teammate** (or any AI session) and they'd ship the right thing. --- ## 2. Pair — Build with AI **Goal:** Write code together with AI as a **pair programmer**, not a vending machine. ### Checklist - ✅ Write code together (AI as pair, you as driver) - ✅ Use AI for **scaffolding, refactors, edge cases** - ✅ Run tests often, fix fast - ✅ Keep context clean (see Context Management playbook) - ✅ Commit **small, meaningful changes** - ✅ Document **as you go** ### AI pairing patterns | Pattern | Use AI to… | |---|---| | 🏗️ **Scaffold** | Generate structure, boilerplate, configs | | 🛠️ **Implement** | Core logic, algorithms, transformations | | 🔄 **Refactor** | Improve readability, simplify complexity | | 🧪 **Test** | Unit, integration, mocks, fixtures | | 📚 **Docs** | README, comments, API docs | | 🐞 **Debug** | Logs, errors, root cause, fixes | ### Example daily pairing session ```text You: "Implement task #2 — magic-link request endpoint. Use Zod for input validation. Tests first." AI: [proposes test cases + implementation plan] You: "Tests look good. Generate them. Then implement." AI: [writes tests, then implementation] You: "Run npm test." AI: [runs, reports green] You: "Commit as: feat(auth): magic-link request endpoint" ``` > 💡 **Tip:** Your job in Pair mode is **driver + reviewer**, not stenographer. Read every line. --- ## 3. Review — Quality Gates & Feedback **Goal:** Verify quality before merge. Use AI to **augment**, not replace, human review. ### Checklist - ✅ Run automated checks (lint, test, type, security) - ✅ AI review for code quality & best practices - ✅ Check tests, coverage, edge cases - ✅ Validate docs & changelog - ✅ Peer review (human + AI) - ✅ Approve & merge ### Quality gate checklist | Gate | ✅ Pass criteria | |---|---| | All tests pass | CI green | | Lint & format clean | Zero warnings | | Type check passes | Zero errors | | Security scan clean | No high/critical findings | | Coverage meets threshold | ≥ team baseline (e.g. 80%) | | Docs updated | README / API docs / changelog | | Changelog added | Conventional entry | | Performance acceptable | No regression | ### Example `/review` output ```markdown ## Summary Looks good overall. Found a few issues. ### Risks & Issues - 🔴 **Critical:** SQL injection risk in user query (line 42) - 🟡 **Medium:** Missing null check in auth flow - 🟢 **Low:** Unused variable in utils.ts ### Missing Tests - Login with invalid credentials - Rate limiting on /login ### Suggestions - Use parameterized queries (line 42) - Add guard clause for null user (line 87) - Remove unused variable (line 23) ``` > 💡 **Tip:** Pair the AI review with at least one human reviewer for **anything that touches money, auth, or data**. --- ## 4. Retro — Reflect & Improve **Goal:** Close the loop. Capture wins, blockers, learnings → improve tomorrow. ### Daily mini-retro (15 min) — template ```markdown # Daily Retro — 2026-06-26 ## ✅ Wins - What are we proud of today? ## ⚠️ Challenges - What slowed us down? ## 💡 Learnings - What did we learn? (about the system, the prompts, the workflow) ## 🎯 Next Actions - What will we do tomorrow? ## 📝 Updates - Docs, processes, prompts, agents to change? ``` ### Checklist - ✅ What went well? What didn't? - ✅ Capture learnings & decisions - ✅ Update backlog & priorities - ✅ Improve **prompts, commands, agents** based on what you saw - ✅ Share wins & blockers with the team - ✅ Plan tomorrow > 💡 **Tip:** A retro that doesn't change at least **one thing** is a retro that didn't happen. --- ## Daily Rhythm — Repeat Every Day | Time | Phase | Activities | |---|---|---| | **10–20 min** | 🎯 Plan | Clarify goals, break down tasks, identify acceptance criteria | | **2–4 hrs** | 🤝 Pair | Code with AI, test, document, commit often | | **45–90 min** | 🔍 Review | Run quality gates, fix issues, prepare PR | | **15–30 min** | 🔁 Retro | Reflect, capture learnings, update docs & backlog | > 💡 **Tip:** **Time-box each phase.** Protect flow time. Don't let Review eat Plan. --- ## Weekly Rhythm — Level Up The daily loop ships features. The **weekly loop** raises the team's ceiling. ### Weekly checklist - ✅ Review metrics & trends - ✅ Refine coding standards & guardrails - ✅ Improve agents, commands, hooks (your AI fleet) - ✅ Update docs, templates, examples - ✅ Share knowledge & run demos - ✅ Plan next week's priorities ### Weekly metrics to track | Metric | Why it matters | |---|---| | Cycle time (idea → prod) | Speed of delivery | | PRs merged | Throughput | | Defect rate | Quality | | Test coverage | Confidence | | AI suggestion acceptance | AI effectiveness | | Rework % | Process improvement | | Context resets needed | Efficiency signal | > 💡 **Tip:** Pick **3 metrics max** for any quarter. Tracking everything tracks nothing. --- ## Tools That Power the Loop | Tool | Role | |---|---| | **Claude Code** | AI pair programmer & orchestrator | | **Slash commands** | Repeatable workflows (`/review`, `/deploy`) | | **Subagents** | Specialists for focused tasks | | **Hooks** | Automation & guardrails | | **MCP servers** | Connect tools & data | | **Context management** | Keep the right context | > Each one has its own anatomy in this library — use them together as a coherent system. --- ## Variants for Different Team Settings ### 👤 Solo developer - **Cadence:** Daily loop = 1 morning ritual. Weekly = Friday 30-min retro. - **Stack:** `/plan`, `/review`, `/deploy` slash commands. - **Metrics:** 2 max (cycle time, AI acceptance). ### 👥 Small team (2–10) - **Cadence:** Daily standup includes a "Plan + AI" segment. Weekly demo every Friday. - **Stack:** Shared `.claude/commands/`, shared `CLAUDE.md`, code-reviewer subagent. - **Metrics:** PR throughput, defect rate, AI suggestion acceptance. ### 🏢 Enterprise / regulated - **Cadence:** Sprint-aligned. Daily loops inside sprints. Sprint retros capture AI signals. - **Stack:** Org-wide plugin packs. Audit hooks on every tool call. Human gate before prod. - **Metrics:** Cycle time, escaped defects, audit findings, AI policy violations. ### 🌍 Open-source / community - **Cadence:** Weekly maintainer sync. Async daily. - **Stack:** Public `agents/`, contributor `/onboard` command, AI-assisted triage. - **Metrics:** First-response time, time-to-merge, contributor activation. > **Bottom line:** Same loop, different drum. --- ## Design Patterns for Success ### 🗂️ Vertical Slice Deliver end-to-end thin slices early (UI → API → DB) instead of horizontal layers. ### ✅ Definition of Done (DoD) A clear, shared bar for "done" — tests + docs + changelog + monitoring. ### 📦 Small Batches Small changes, small PRs. Easier to review, easier to revert. ### 🔁 Continuous Validation Test & review **all-day**, not at the end of the week. ### 📚 Knowledge Capture Capture learnings **as you go** — `CLAUDE.md`, session summaries, retros. ### 📈 Feedback Loop Measure, learn, improve weekly. The loop never ends. --- ## Step-by-Step Setup ### 1. Define your daily loop - Phases, time-boxes, owners. - Document in `docs/dev-loop.md`. ### 2. Set up `.claude/` - `settings.json` with permissions + hooks. - `commands/review.md`, `commands/deploy.md`, `commands/plan.md`, `commands/retro.md`. - `agents/code-reviewer.yml`. ### 3. Define quality gates & DoD - Codify in `CLAUDE.md` under `## Definition of Done`. ### 4. Start small (one feature, one day) - Run the loop end-to-end on a tiny slice. Note friction. ### 5. Measure your metrics - Pick 2–3. Track weekly. ### 6. Iterate & improve your setup weekly - Tune prompts, agents, hooks. Document what changed and why. ### 7. Share your learnings with the team - Lunch-and-learn, demo, internal blog. --- ## Anti-Patterns ❌ (Avoid These) - 🗑️ **Dumping huge context** at once instead of curating. - 🙈 **Skipping review** because "AI wrote it." - 🤖 **Over-trusting AI outputs** blindly. - 🧪 **No tests or weak test coverage**. - 🐘 **Huge PRs & long-lived branches**. - 😶 **Poor prompts & unclear goals**. - 📉 **Ignoring metrics & feedback**. - 📜 **No documentation or changelog**. --- ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | Loop feels slow | Phases run too long | Tighter time-boxes | | AI suggestions ignored | Poor prompts / no DoD | Improve prompts, codify DoD | | Quality drops | Skipping Review | Make `/review` mandatory in PR template | | Reviews take forever | PRs too big | Smaller batches, vertical slices | | Retros are noise | No actions tracked | Convert each insight to a backlog item | | Team disengaged | Top-down loop | Co-design with the team, iterate | | Metrics gamed | Too many metrics | Pick 2–3 outcome metrics | --- ## Minimal Starter Setup ``` .claude/ ├── settings.json # hooks, permissions, env ├── commands/ │ ├── plan.md │ ├── review.md │ ├── retro.md │ └── deploy.md agents/ └── code-reviewer.yml scripts/ ├── pre-tool.sh └── save-summary.sh docs/ ├── dev-loop.md # the loop itself, documented └── sessions/ # auto-saved session summaries ``` **Your first commands:** ```text /plan — clarify goals & decompose /review — run quality gates /retro — capture wins, blockers, learnings /deploy — ship safely ``` > 💡 **Tip:** Start lean. Evolve as you grow. --- ## Getting Started (7 steps) 1. **Define your daily loop** (Plan → Pair → Review → Retro). 2. **Set up `.claude/`** (settings, hooks, commands, agents). 3. **Define your quality gates & DoD**. 4. **Start small** — one feature, one day. 5. **Measure your metrics** — pick 2–3. 6. **Iterate & improve your setup weekly.** 7. **Share your learnings with the team.** --- ## Glossary - **Dev loop** — The recurring cycle a team uses to plan, build, review, and improve. - **Pair programming** — Two collaborators (human + AI) building together. - **Definition of Done (DoD)** — Shared bar for what "complete" means. - **Quality gate** — A check that must pass before code progresses. - **Vertical slice** — End-to-end thin slice that touches all layers. - **Retro (retrospective)** — Structured reflection to improve the next cycle. - **Cycle time** — Time from idea to production. - **AI suggestion acceptance** — % of AI proposals adopted (signal of AI fit). --- ## Further Reading - Search: **"continuous delivery dev loop best practices"** - Search: **"agile retrospectives techniques"** - Search: **"AI-augmented engineering productivity metrics"** - Search: **"definition of done examples software"** --- ## 🪙 Golden Rules - 🧭 **Be specific in prompts** — context is leverage. - 🧹 **Keep context lean & relevant.** - ⚙️ **Automate with hooks** — let the loop run itself where it can. - 👀 **Review everything** — AI makes great suggestions, not great commits. - 📝 **Document as you go** — future-you needs the trail. - 📊 **Measure & iterate** — what gets measured improves. - 🤝 **Share & learn together** — AI advantage compounds in teams. > **Remember:** The loop never ends. Keep improving, ship value, and make your AI teammate **better every day**. --- ## Anatomy of Prompt Engineering for Repos > System prompts, few-shots, CLAUDE.md interplay, and design patterns. ![Prompt Engineering](/posters/13-prompt-engineering.png) > System prompts, few-shots, and `CLAUDE.md` interplay — the art of giving AI the right context, at the right time, to produce reliable results across your codebase. --- ## TL;DR - Prompt engineering for repos isn't writing one clever prompt — it's **layering context** across the stack. - The hierarchy: **System Prompt → `CLAUDE.md` → Skills/Commands → Few-Shots → User Prompt**. - Lower layers set defaults; **upper layers override and specialize**. - **Few-shots beat instructions** for nuanced behavior — show, don't just tell. - **Keep rules consistent across layers.** Less conflict = better results. --- ## Why this matters A great prompt for a one-off task is a clever trick. A great **prompt system for a repo** is leverage that compounds — every team member, every session, every PR benefits. > **Bottom line:** Prompt engineering at the repo level turns a raw model into a **domain expert your team can trust**. --- ## The Big Picture — The Prompt Stack ```mermaid flowchart TB L1[System PromptBuilt-in policies & capabilities] --> L2[CLAUDE.mdProject memory & conventions] L2 --> L3[Skills / CommandsDetailed playbooks & automation] L3 --> L4[Few-Shots / ExamplesShow desired patterns] L4 --> L5[User PromptSpecific request, files, constraints] L5 --> R[AI Response] ``` > **Bottom line:** Five layers. Each one feeds the next. Most teams only think about layer 5. --- ## The Five Layers (top of stack = highest specificity) | # | Layer | What it sets | Who owns it | |---|---|---|---| | 5 | **User Prompt** | The specific ask | The person at the keyboard | | 4 | **Few-Shots / Examples** | Patterns to emulate | Skill / command author | | 3 | **Skills / Commands** | Reusable instructions | Team | | 2 | **`CLAUDE.md`** | Project memory, conventions | Repo maintainers | | 1 | **System Prompt** | Base capabilities & safety | Anthropic | > 💡 **Tip:** Lower layers set the defaults. **Upper layers override and specialize.** --- ## Layer 1 — System Prompt (Built-in) You don't edit this directly, but it defines core behaviors Claude always follows. ### What it includes - 🛡️ Safety & alignment policies - 🔧 Tool use rules - 🧠 Reasoning & planning behavior - ✍️ Response formatting defaults - 🧰 Memory & context management ### Conceptual (not editable) ```text You are Claude, an AI assistant. Be helpful, harmless, and honest. Use tools responsibly. Explain your reasoning. If unsure, say so. Follow user & project rules. ``` > 💡 **Tip:** You specialize the system prompt by **adding layers above it**, not by fighting it. --- ## Layer 2 — `CLAUDE.md` (Project Memory) Loaded first. Sets the ground truth for your codebase. (See the dedicated *Anatomy of `CLAUDE.md`* for the full spec.) ### What to include - ✅ Project overview & goals - ✅ Tech stack & versions - ✅ Architecture & structure - ✅ Conventions & style - ✅ Workflows & commands - ✅ Testing strategy & DoD - ✅ Security & data handling - ✅ Decisions & rationale - ✅ Known gotchas - ✅ Integration & tools (MCP) ### Example skeleton ```markdown # Project: Acme App ## Tech Stack - Next.js 14 (App Router) · TypeScript - Postgres · Prisma · tRPC - Tailwind CSS · shadcn/ui ## Conventions - Use TypeScript strict mode. - Prefer server components. - File names: kebab-case. Components: PascalCase. - Tests: Vitest + React Testing Library. ## Workflows - Dev: npm run dev - Test: npm test - Lint: npm run lint ## Security - Never log secrets. - Validate all inputs with Zod. - Use parameterized queries only. ``` > 💡 **Tip:** Keep `CLAUDE.md` **concise (≤ 300 lines) and up to date.** Reference, don't repeat. --- ## Layer 3 — Skills & Commands (Reusable Playbooks) These encode **repeatable workflows** so the team doesn't reinvent them each session. (See the *Skills* and *Slash Commands* anatomies for full detail.) ### What they provide - 📈 Task success rate - 🎯 First-pass correctness - ⏱️ Time to completion - 🔁 Rework / revisions - 💰 Token usage / cost - 😊 User satisfaction ### Improvement loop 1. **Define the task & success criteria.** 2. **Run prompt & measure.** 3. **Analyze gaps & failure modes.** 4. **Refine prompt / examples / rules.** 5. **Re-run & compare.** 6. **Document what changed.** 7. **Repeat.** > 💡 **Tip:** Treat prompt tweaks like code changes — review, version, and measure. --- ## Layer 4 — Few-Shots: Show, Don't Just Tell Examples teach faster than rules. For tricky formats, **2–5 high-quality examples beat 20 low-quality ones**. ### When to use few-shots - ✅ Complex formatting - ✅ Code style & patterns - ✅ Edge cases - ✅ Multi-step reasoning - ✅ Domain-specific tone ### Few-shot example ```markdown # Task: Create a Zod schema for a user # Example 1 Input: name (string), email (string) Output: userSchema = z.object({ name: z.string().min(1), email: z.string().email(), }); # Example 2 Input: name, age (number where >= 18) Output: userSchema = z.object({ name: z.string().min(1), age: z.number().int().min(18), }); # Now do: Input: name, email, role (enum: admin | user | guest) ``` > 💡 **Tip:** Order examples from **simple → complex**. The last example shapes behavior most. --- ## Layer 5 — User Prompt (The Specific Ask) This is where the magic — or the chaos — happens. The other four layers exist to make this layer **short, specific, and effective**. ### A great user prompt - States the **role** (when useful): "Act as a senior reviewer." - States the **goal** in one sentence. - Gives **constraints** (must / must not). - References **files** (`@src/auth/login.ts`). - Asks for a **specific output format**. ### Anti-prompt → Better ```text ❌ "Fix the bug" ✅ "Act as a senior backend engineer. The /login endpoint returns 500 for valid creds (logs attached). Find the root cause and propose a minimal fix with a test. Output: 1) root cause, 2) patch (diff), 3) test." ``` --- ## The Interplay — How They Work Together Each layer feeds the next. Conflicts are resolved by **specificity and recency**. ### Precedence rules 1. **Specific > General** — Specific instructions override generic ones. 2. **Recent > Old** — Latest instructions in the conversation win. 3. **User > Repo > System** — Lower layers set defaults; upper layers override. 4. **Consistency matters** — Conflicting rules confuse the model. > 💡 **Tip:** Keep rules **consistent across layers**. Less conflict = better results. --- ## Prompt Design Patterns | Pattern | What it does | |---|---| | 🎭 **Role + Goal** | Define who AI is and the objective | | 🛡️ **Constraints** | Rules, limits, guardrails | | 🪜 **Step-by-Step** | Break tasks into numbered steps | | 📋 **Output Format** | Specify structure: tables, JSON, etc. | | 💡 **Examples (Few-Shot)** | Show input → desired output | | 📚 **References** | Point to docs, files, links | | ✅ **Check Before Final** | Self-verify & ask clarifying questions | | 🔁 **Reflect & Improve** | Critique and refine before answering | --- ## Common Prompt Templates ### A) Task Execution ```text Role: {{role}} Goal: {{goal}} Context: {{context}} Steps: 1. {{step1}} 2. {{step2}} ... Output: {{output_format}} ``` ### B) Code Generation ```text Task: {{task}} Requirements: - {{req1}} - {{req2}} Tech stack: {{stack}} Constraints: - {{constraint1}} - {{constraint2}} Output: {{format}} ``` ### C) Review / Audit ```text Role: {{role}} What to review: {{scope}} Standards: - {{standard1}} - {{standard2}} Report format: - Summary - Issues (Critical / Medium / Low) - Suggestions (file:line) ``` ### D) Refactor ```text Goal: {{goal}} Original code: {{code}} Constraints: - {{constraint1}} - {{constraint2}} Output: Refactored code + brief explanation of changes. ``` > 💡 **Tip:** **Parameterize with `{{variables}}`** for reuse across slash commands and skills. --- ## Variables & Placeholders | Syntax | Meaning | Example | |---|---|---| | `{{var}}` | Required variable | `{{scope}}` | | `{{var?}}` | Optional variable | `{{scope?}}` | | `{{var=default}}` | Default value | `{{base=main}}` | | `{{a\|b\|c}}` | Choose-from list | `{{env\|dev\|stg\|prod}}` | | `{{var:type}}` | Typed variable | `{{count:number}}` | | `{{env:NAME}}` | Environment variable | `{{env:GITHUB_TOKEN}}` | > 💡 **Tip:** Validate inputs and handle missing values gracefully — never assume the caller filled them in. --- ## Step-by-Step Setup ### 1. Write or update `CLAUDE.md` Start with the skeleton above. Keep it crisp. ### 2. Create a slash command for a common task `.claude/commands/review.md`: ```markdown --- description: Review the current branch arguments: - name: base default: main permissions: allow: ["Read", "Bash(git *)"] --- Act as a senior reviewer. Diff vs `{{base}}`. Report: Risks (Critical/Medium/Low) · Missing tests · Suggestions (file:line). Follow conventions in CLAUDE.md. # Example output format ## Risks - 🔴 SQL injection in src/users.ts:42 - 🟡 Missing null check in src/auth.ts:91 ## Missing tests - /login with invalid creds ## Suggestions - Parameterize the query in src/users.ts:42 ``` ### 3. Add 2–3 few-shot examples Inline in the command, or in `references/` of a skill. ### 4. Define output format & success criteria Be explicit: bullet points, headings, code blocks, JSON, etc. ### 5. Test on a real task Run, observe, capture failure modes. ### 6. Refine based on results Tighten constraints; add/remove examples. ### 7. Share with the team Commit, demo, document the *why*. --- ## Variants for Different Team Settings ### 👤 Solo developer - Minimal `CLAUDE.md` (≤ 100 lines). - 1–2 slash commands. - Personal style baked into prompts. ### 👥 Small team (2–10) - Shared `CLAUDE.md` + shared `.claude/commands/`. - Conventional commits, PR template referencing `/review`. - One few-shot library in `docs/examples/`. ### 🏢 Enterprise / regulated - Pin model versions. - **Approved prompt templates** committed and code-reviewed. - Audit hooks log prompt + response hashes. - Inject compliance reminders via layer 2/3 (`CLAUDE.md` + skills). ### 🌍 Open-source / community - Generic, jargon-free prompts. - Contribution guide for new commands & few-shots. - Examples for the most common contributor tasks (file an issue, open a PR, write a test). > **Bottom line:** Same stack, escalating governance. --- ## Common Patterns & Recipes ### Pattern 1 — Self-check ```text Before finalizing, list any assumptions you made. Re-check each assumption against CLAUDE.md. If any conflict, ask before proceeding. ``` ### Pattern 2 — Clarifying question gate ```text If the task is ambiguous, ask up to 3 clarifying questions BEFORE writing code. Otherwise, proceed. ``` ### Pattern 3 — Output in two passes ```text Pass 1: Write the code. Pass 2: Critique your own code as a senior reviewer. Pass 3: Apply fixes from your critique. ``` ### Pattern 4 — Constrained format ```text Return ONLY this JSON: { "summary": string, "risks": [{"level": "critical|medium|low", "file": string, "line": number, "note": string}], "tests_missing": string[] } ``` ### Pattern 5 — Anchor with references ```text Read CLAUDE.md and docs/architecture.md before answering. Cite the section you're following in your response. ``` ### Pattern 6 — Anti-hallucination ```text If you don't know, say "I don't know" and propose how to find out (a test, a doc to read, a person to ask). ``` --- ## Best Practices ✅ - **Be specific & concrete** — vague prompts → vague outputs. - **Provide context deliberately** — load what's needed, no more. - **Show examples** — few-shots are gold. - **Define success criteria** — what does "done" look like? - **Review everything** — AI is fast, not infallible. - **Iterate weekly** — prompts are code; refactor them. - **Keep layers consistent** — no contradictions between `CLAUDE.md` and a command. ## Anti-Patterns ❌ - 🗯️ Walls of vague instructions. - 🤖 "Just be smart" prompts. - 🥪 Stacking 20 examples (more isn't better). - 🎭 Contradictory rules across layers. - 🙈 No output format → unpredictable parsing. - ❓ No clarifying-question option. - 📜 Mega prompts that ignore `CLAUDE.md`. --- ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | Output ignores conventions | `CLAUDE.md` too long / vague | Trim to bullets, add examples | | Wrong format | No format spec | Provide explicit format + 1 example | | Hallucinated APIs | No grounding | Reference docs; add anti-hallucination rule | | Inconsistent style | Conflicting layers | Audit & align rules across layers | | Repeats itself | No constraints | Add length caps & "no repetition" rule | | Skips safety checks | Few-shots show bad patterns | Replace examples with good patterns | | Over-cautious | Too many constraints | Trim guardrails; allow proposal mode | --- ## Mini Starter Kit ``` .claude/ ├── settings.json # hooks, permissions, env ├── commands/ │ ├── review.md # slash commands │ ├── plan.md │ ├── deploy.md │ └── status.md agents/ ├── code-reviewer.yml # reusable playbooks ├── test-writer.yml └── docs-writer.yml hooks/ ├── pre-tool.sh ├── post-tool.sh └── pre-commit.sh CLAUDE.md # project memory (layer 2) docs/ └── examples/ # few-shot library ``` > 💡 **Tip:** Start small. Evolve. Share. Repeat the loop. --- ## Quick Start (7 steps) 1. **Write or update `CLAUDE.md`** with stack, conventions, security. 2. **Create a slash command** for one common task (e.g., `/review`). 3. **Add 2–3 few-shot examples** to that command. 4. **Define output format & success criteria.** 5. **Test on a real task.** 6. **Refine based on results.** 7. **Share with the team** — commit + demo + document. --- ## Glossary - **System prompt** — Anthropic-built base instructions; not user-editable. - **`CLAUDE.md`** — Project-level memory & conventions (layer 2). - **Skill / Command** — Reusable playbook (layer 3). - **Few-shot** — Examples that demonstrate desired input → output. - **Zero-shot** — Prompt with no examples (relies on layers 1–3 + 5). - **Chain-of-thought** — Encouraging the model to reason step-by-step. - **Role prompting** — "Act as a senior reviewer" — sets persona/context. - **Output format** — Explicit structure for the response. - **Self-critique / reflection** — Asking the model to evaluate its own output. --- ## Further Reading - Search: **"Anthropic prompt engineering guide"** - Search: **"few-shot vs zero-shot LLM examples"** - Search: **"prompt patterns catalog 2026"** - Search: **"prompt versioning & evaluation"** --- ## 🪙 Golden Rules - 🎯 **Be specific.** - 📂 **Provide context deliberately.** - 💡 **Show examples.** - ✅ **Define success.** - 🔍 **Review everything.** - 🔁 **Iterate & improve.** > **Remember:** Good prompts **compound over time**. Your future self (and your team) will thank you. --- ## Anatomy of AI Knowledge Loop > The self-improving loop that ties it all back together. ![Knowledge Loop](/posters/21-knowledge-loop.png) > The self-improving system that turns every postmortem, eval, review, incident, and policy update — back into better **prompts, agents, docs, and `CLAUDE.md`**. This is the **meta-anatomy** that ties all 20 prior anatomies in the Living Library together. Without it, each piece works in isolation; with it, the whole library compounds. --- ## TL;DR - AI systems learn best from **real-world feedback**. Without a loop, we repeat mistakes. - Six steps: **Capture → Connect → Codify → Apply → Measure → Share** — then repeat. - Sources: **postmortems, evals, code reviews, incidents, user feedback, telemetry, policy & compliance, research**. - Sinks: **prompts, agents, slash commands, docs, `CLAUDE.md`, runbooks, policies**. - Govern with **change-management rules**: every change has a signal, an owner, a PR, and an evaluation. - The mantra: **Observe → Analyze → Improve → Validate → Share → Repeat**. --- ## Why this matters You can buy better models. You can hire smarter people. But the **only** durable advantage is a team that **gets better every week** at using AI — because every postmortem updates a runbook, every eval failure updates a prompt, every incident updates a hook, and every policy change updates `CLAUDE.md`. > **Bottom line:** Every loop makes us smarter. **Better quality · faster shipping · lower cost · higher trust.** --- ## The Big Picture — The Self-Improving Loop ```mermaid flowchart LR C[1. CaptureCollect signals from everywhere] --> N[2. ConnectCorrelate, classify, extract insights] N --> K[3. CodifyTurn insights into knowledge artifacts] K --> A[4. ApplyUpdate prompts, agents, docs, policies] A --> M[5. MeasureTrack impact, quality, outcomes] M --> S[6. ShareDistribute, teach, compound] S --> C ``` > **Bottom line:** Six steps. One loop. Run it daily, weekly, monthly, quarterly — at different cadences for different signals. --- ## The Six Steps at a Glance | # | Step | Question it answers | |---|---|---| | 1️⃣ | **Capture** | What did we just learn? | | 2️⃣ | **Connect** | What does it mean? | | 3️⃣ | **Codify** | How do we save it? | | 4️⃣ | **Apply** | Where does it change behavior? | | 5️⃣ | **Measure** | Did it actually help? | | 6️⃣ | **Share** | How do we make it stick? | --- ## 1. Capture — Sources of Learning Pull signal from **every** AI-adjacent activity. If it's not captured, it can't compound. | Source | What you learn | |---|---| | 📒 **Postmortems** | Root causes, actions, learnings | | 🧪 **Evaluations** | Quality scores, failure cases, edge cases | | 🔍 **Code Reviews** | Findings, patterns, anti-patterns | | 🚨 **Incidents** | Alerts, timelines, mitigations | | 💬 **User feedback** | Ratings, comments, support tickets | | 📊 **Usage & telemetry** | Metrics, prompts, costs, adoption | | 📜 **Policy & compliance** | Updates, audits, exceptions | | 🌍 **Research & external** | New models, papers, best practices | ### Capture principles - ✅ **Collect automatically** where possible — humans are unreliable scribes. - ✅ **Be structured** — consistent formats unlock query and analysis. - ✅ **Include context** — *who*, *what*, *when*, *why*. - ✅ **Keep raw + immutable** — don't lose the truth. - ✅ **Tag by domain & impact** — so we can find it later. > 💡 **Tip:** If a learning isn't in a system, it doesn't exist. **Capture early, capture often.** --- ## 2. Connect — Correlate & Extract Raw signals are noise. Insights emerge when you **connect** them across systems and time. ### What "connect" looks like - 🆔 **Trace-ID joins** — link logs, evals, PRs, incidents, postmortems by one ID. - 🧭 **Theme clustering** — group similar failure modes ("missing null check", "auth edge cases"). - 📈 **Trend analysis** — what's increasing, what's decreasing, what's drifting? - 🌊 **Cross-source correlation** — postmortem says "X" + eval drift on "Y" → likely same root pattern. - 🧠 **Root-cause synthesis** — which 20% of patterns drive 80% of pain? ### The AI Copilot for this stage A **Knowledge Synthesizer** subagent reads postmortems, evals, reviews, and incidents nightly and emits: 1. Top recurring themes. 2. Recommended changes to prompts, agents, runbooks, `CLAUDE.md`. 3. New or revised eval cases. 4. Risks and mitigations. (See the Knowledge Update Template below for the exact output shape.) > 💡 **Tip:** **Connection is where insight lives.** Without it, you have data; with it, you have knowledge. --- ## 3. Codify — What We Produce Insights die unless they become **artifacts** the system can use. | Artifact | Purpose | Owner | Example | |---|---|---|---| | 🧩 **Prompt patterns** | Reusable prompts that work | AI Platform | `prompt-patterns/code-reviewer.md` | | 🤖 **Agent playbooks** | How agents should behave | AI Platform | `agents/code-reviewer.yml` | | ⚡ **Skills / commands** | Repeatable workflows | Engineering | `.claude/commands/review.md` | | 🧠 **`CLAUDE.md` updates** | Team memory, conventions, decisions | Tech Lead | `CLAUDE.md` | | 📒 **Runbooks** | Operational how-to | SRE | `runbooks/db-connection.md` | | 📚 **Postmortem library** | Incident learnings | SRE | `docs/postmortems/` | | ⭐ **Eval cases** | Quality guardrails | AI Platform | `evals/cases/` | | 📜 **Policy updates** | Governance & compliance | Governance | `policies/` | ### Properties - 🔖 **Version-controlled.** - 🔎 **Searchable.** - 🔁 **Reusable.** - 🆔 **Cross-linked** (every artifact references its source signals). > 💡 **Tip:** **Everything version-controlled. Everything searchable. Everything reusable.** --- ## 4. Apply — Where Knowledge Flows Codified knowledge has to **change behavior** somewhere in the stack. ```mermaid flowchart LR P[PromptsNew patterns → better instructions] --> A[AgentsRefined playbooks, guardrails] A --> C[CommandsSmarter workflows] C --> D[DocsLiving documentation and examples] D --> M[CLAUDE.mdTeam memory stays current & accurate] M --> Po[PoliciesGovernance evolves with experience] ``` ### What good "apply" looks like - 🎯 **Intentional.** Every change cites the signal it came from. - 🧪 **Tested.** Every change has at least one eval case attached. - 👀 **Reviewed.** Every change goes through normal PR review. - 📈 **Measured.** A baseline + post-change metric is captured. - ♻️ **Reversible.** Easy to roll back if it makes things worse. > 💡 **Tip:** **Apply with intention.** Each change must have a reason **and** a test. --- ## 5. Measure — System Quality, Velocity, Cost Measure the impact so the loop doesn't drift into ritual. ### System quality (going up) - ⭐ **Eval score trend** ↑ - 🛡️ **Hallucination rate** ↓ - 🔄 **Regression rate** ↓ - 😊 **User satisfaction** ↑ ### Engineering velocity - ⏱️ **Cycle time** ↓ - ✅ **PR acceptance rate** ↑ - 🔁 **Rework rate** ↓ - 🚀 **Lead time to fix** ↓ ### Cost & efficiency - 💰 **Cost per request** ↓ - 🔢 **Token usage** ↓ - 💾 **Cache hit rate** ↑ - 🧠 **Context resets** ↓ ### Example dashboard (one glance) ```text Eval Score (↑) Hallucination Rate (↓) Cost / Request (↓) PR Cycle Time (↓) ``` > 💡 **Tip:** **Measure what matters. Iterate relentlessly.** A loop that doesn't measure becomes a loop that doesn't improve. --- ## 6. Share — Make It Stick Knowledge only compounds when it's **distributed and adopted**. ### How to share - 📢 **Weekly knowledge digest** — top 5 learnings + what changed. - 🎓 **Demo Friday** — show the new prompt/agent in action. - 📝 **Changelogs** for prompts, agents, commands, and `CLAUDE.md`. - 📚 **Internal wiki / handbook** updated by the synthesizer agent. - 🤝 **Onboarding kit** auto-updated (see the Onboarding Kit anatomy). - 🌍 **External:** blog posts, talks, OSS contributions where appropriate. > 💡 **Tip:** A knowledge artifact is only as valuable as the next person who finds and uses it. --- ## Loop Cadence Different signals deserve different rhythms. | Cadence | Activities | |---|---| | ⏰ **Continuous** | Capture from logs, traces, evals, alerts, chat | | 🌅 **Daily triage** (15–30 min) | Synthesizer agent draft; quick scan | | 📅 **Weekly review** (60 min) | Approve changes, ship updates, publish digest | | 📆 **Monthly deep-dive** (90 min) | Cross-source patterns, OKR alignment | | 🗓️ **Quarterly strategy** (½ day) | Policy updates, library cleanup, roadmap | > 💡 **Tip:** **Pick one cadence and run it religiously** before adding the next. --- ## AI Copilots in the Loop Just like the rest of the library, AI is your force multiplier — but never the decision-maker. | Copilot | Role | |---|---| | 🔗 **Collector** | Pulls data from all sources (postmortems, evals, reviews, incidents) | | 🧩 **Synthesizer** | Summarizes and connects patterns | | 💡 **Insight Finder** | Finds anomalies, trends, root causes | | ✍️ **Draftsman** | Writes timelines, mitigations, drafts | | ❓ **Critic** | Challenges assumptions and gaps | | 🎓 **Teacher** | Suggests training and learning content | ### AI Copilot prompt — the Knowledge Synthesizer ```text You are the Knowledge Synthesizer. Given the following inputs: - Postmortems (last N days) - Eval failures (last N days) - Code reviews / findings (last N days) - Incident updates (last N days) - Policies (recently changed) Extract: 1. Key themes and recurring issues. 2. Recommended changes to prompts, agents, runbooks, CLAUDE.md. 3. New or revised eval cases. 4. Risks and mitigations. Return the Knowledge Update Template. For every recommendation, cite the source signal(s) by id. Mark hypotheses vs facts. Do not invent sources. ``` --- ## Knowledge Update Template This is the **single document** the synthesizer produces and humans review weekly. ```markdown # Knowledge Update — {{date}} ## Signals In - Postmortems: {{ids}} - Eval failures: {{ids}} - Reviews: {{ids}} - Incidents: {{ids}} - Policy updates: {{ids}} ## Key Themes 1. ... 2. ... 3. ... ## Recommended Changes ### Prompts - {{file}} — {{change}} (why: {{signal_ids}}) ### Agents - {{agent}} — {{change}} (why: {{signal_ids}}) ### Commands / Skills - {{file}} — {{change}} (why: {{signal_ids}}) ### Docs / CLAUDE.md - {{file}} — {{change}} (why: {{signal_ids}}) ### Runbooks - {{file}} — {{change}} (why: {{signal_ids}}) ## New Eval Cases - {{name}} — {{purpose}} ## Risks & Mitigations - {{risk}} → {{mitigation}} ``` ### Change management rules Every recommended change must include: - 📡 **Signal** — *why* - 👤 **Owner** — *who* - 🔗 **PR / link** — *where* - 🧪 **Evaluation** — *how we'll verify* > 🥇 **Golden rule:** **No silent changes.** Everything in code → everything reviewed. --- ## Audit Trail & Traceability Every artifact change is provable end-to-end. ```json { "ts": "2025-05-20T14:03:47Z", "trace_id": "c7f3wabu2", "actor": "u_123", "action": "prompt_update", "artifact": "agents/code-reviewer.yml", "change_type": "update", "reason": "Recurring 'NPE findings in reviews' theme", "sources": [ "postmortem:inc-2025-05-18", "eval:case-041-fail" ], "PR": "https://github.com/org/repo/pull/512", "approved_by": ["ai-platform-lead", "tech-lead"], "status": "merged" } ``` ### Traceability must-haves - ✅ Who did what, when - ✅ What changed - ✅ Why it changed - ✅ Where the signal came from - ✅ Who approved it - ✅ Link to PR / commit - ✅ Immutable & searchable - ✅ Retained per policy > ⚠️ **If it isn't logged, it didn't happen.** --- ## Step-by-Step Setup ### 1. Pick your sources & sinks - Sources: postmortems, evals, reviews, incidents, telemetry, policy, feedback, research. - Sinks: prompts, agents, commands, docs, `CLAUDE.md`, runbooks, policies. ### 2. Standardize the log schema Adopt the audit-trail JSON shape above. One `trace_id` everywhere. ### 3. Stand up the Synthesizer agent `agents/knowledge-synthesizer.yml`: ```yaml name: knowledge-synthesizer description: Synthesizes weekly learnings from all AI signals. model: claude-sonnet-4 tools: [Read, WebSearch] permissions: allow: ["Read", "WebSearch"] deny: ["Write"] system_prompt: | You are the Knowledge Synthesizer. Be precise, cited, and honest about uncertainty. Output the Knowledge Update Template exactly. triggers: ["weekly digest", "knowledge update", "synthesize"] timeout_ms: 180000 max_tokens: 12000 ``` ### 4. Add a `/digest` slash command `.claude/commands/digest.md`: ```markdown --- description: Generate this week's Knowledge Update digest usage: /digest [--from ] [--to ] permissions: allow: ["Read", "WebSearch", "MCP:datadog", "MCP:github", "MCP:slack"] deny: ["Write"] --- Run @knowledge-synthesizer against signals between {{from?}} and {{to?}}. Emit the Knowledge Update Template. Open a draft PR titled "Knowledge Update: ". ``` ### 5. Wire the weekly review meeting 30–60 minutes. Approve, reject, or revise each recommendation. Ship the PR. ### 6. Connect to the eval suite Every applied change creates or updates at least one eval case. Block the merge if safety evals fail. ### 7. Publish the digest Slack/Teams + wiki. Onboarding kit auto-imports the latest themes. ### 8. Run a monthly deep-dive Cross-source patterns, library cleanup, retire stale artifacts. --- ## Variants for Different Team Settings ### 👤 Solo developer - Capture: a single `notes/learnings.md` + Git history. - Cadence: weekly 30-min self-debrief. - Sinks: one `CLAUDE.md`, one prompt library. ### 👥 Small team (2–10) - Capture: shared `docs/`, eval suite in CI, postmortem template. - Cadence: weekly 60-min review + Demo Friday. - Sinks: shared `agents/`, `.claude/commands/`, `CLAUDE.md`. ### 🏢 Enterprise / regulated - Capture: SIEM-grade audit trail, signed model cards. - Cadence: weekly digest, monthly deep-dive, quarterly governance. - Sinks: model registry, policy library, training program. - **Every change links to a control** in the governance framework. ### 🌍 Open-source / community - Public digest with anonymized sources. - Community PRs to prompts / agents. - Public eval cases & rubrics. > **Bottom line:** Same loop, escalating rigor. --- ## Common Patterns & Recipes ### Pattern 1 — Source → Sink mapping ```text postmortem.action_items → runbook updates eval.failing_cases → prompt / agent updates review.findings → CLAUDE.md conventions incident.timeline → alert + runbook tuning policy.update → permission / hook changes telemetry.drift → eval suite expansion ``` ### Pattern 2 — Hypothesis-driven change ```markdown **Hypothesis:** Adding a "cite sources" instruction to code-reviewer will reduce hallucination rate by ≥ 20%. **Change:** agents/code-reviewer.yml **Eval:** add 5 fact-checking cases **Baseline:** 4.2% hallucination **Target:** ≤ 3.4% over 7 days ``` ### Pattern 3 — Retire stale artifacts Monthly: list unused prompts/commands/skills > 90 days, archive with reason. ### Pattern 4 — Cross-incident pattern detection ```text Across last 10 postmortems, find recurring root-cause categories. For top 3, propose system-level mitigations + eval coverage. ``` ### Pattern 5 — Knowledge graph (lightweight) Tag every artifact with `topic:`, `risk:`, `domain:` so the synthesizer can cluster. ### Pattern 6 — Onboarding feedback → kit New hires file friction notes in week 1; kit updates monthly. ### Pattern 7 — External knowledge ingest Weekly: synthesizer reads team's saved research links and proposes 1 update. ### Pattern 8 — Quarterly "loop on the loop" Apply the loop to **itself**: what's working, what's noise, what to retire? --- ## Best Practices ✅ - 🧷 **Capture by default**, manually only as backup. - 🆔 **One `trace_id`** ties signals to artifacts. - 🧪 **Every change has an eval.** - 👀 **Every change has a reviewer.** - 📦 **Smallest useful change** — easier to attribute impact. - 🕯️ **Retire ruthlessly** — fewer, better artifacts. - 📡 **Share widely** — the more eyes, the faster the compound. - 📐 **Measure both quality and velocity** — never optimize one alone. ## Anti-Patterns ❌ - 🚫 **No capture pipeline** — learnings die in Slack threads. - 🚫 **No connection step** — raw data, no insight. - 🚫 **Silent changes** to prompts/agents (no PR, no signal). - 🚫 **Changes without evals** — can't tell if you helped or hurt. - 🚫 **One-shot "retrospectives"** that never produce artifacts. - 🚫 **Library sprawl** — too many stale artifacts. - 🚫 **No share step** — knowledge stays in one team. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | Same issues repeat | Capture missing or unmonitored | Wire missing sources; add tags | | Digest is noise | No theme clustering | Improve synthesizer prompt + tagging | | Changes don't help | No baseline / eval | Require baseline + eval per change | | Library bloated | No retirement policy | Quarterly retire-stale review | | Adoption is low | No share step | Add weekly digest + Demo Friday | | Trust erodes | Silent changes | Enforce PR + audit trail on every artifact | | Loop becomes ritual | No measurement | Tie the loop to outcome metrics | --- ## Quick-Start Checklist - ✅ Source list defined (postmortems, evals, reviews, incidents, telemetry, policy) - ✅ Sink list defined (prompts, agents, commands, docs, `CLAUDE.md`, runbooks, policies) - ✅ Audit-log schema standardized - ✅ Synthesizer agent shipped - ✅ `/digest` command live - ✅ Weekly review on the calendar - ✅ Eval-gated change process - ✅ Quarterly "loop on the loop" > 🧠 **Mantra:** **Observe → Analyze → Improve → Validate → Share → Repeat.** --- ## Maturity Path ### 🌱 Week 1 — Start small - Capture key signals (postmortems + evals). - Standard log schema. - One eval suite. - One Knowledge Update digest. ### 🪴 Month 1 — Level up - Full traces end-to-end. - Governance policies live. - Model cards for all systems. - Dashboards & alerts. ### 🌳 Quarter 1+ — Scale - Auto-synthesizer in CI. - Red teaming cadence. - Exception process. - Quarterly review. --- ## Success Looks Like - 🔻 **Fewer incidents** - 🚀 **More confidence** - 💸 **Lower cost** - 😊 **Happier teams** --- ## How This Anatomy Ties the Library Together | Library piece | Feeds the loop with… | Receives back… | |---|---|---| | **Claude Code Project Structure** | A consistent home for artifacts | Updated layout patterns | | **MCP Servers** | Tool usage telemetry | Tighter scopes, new servers | | **Subagents** | Agent performance signals | Refined playbooks | | **Hook Lifecycles** | Hook outcomes & blocks | New / tuned hooks | | **CLAUDE.md** | Convention drift | Updated conventions & decisions | | **Skills** | Skill success / failure rates | Refined skills, new triggers | | **Plugins** | Plugin adoption & issues | New plugin versions | | **Agentic Workflows** | Workflow telemetry | Better plans & critics | | **`.claude/settings.json`** | Permission / hook regressions | Tighter defaults | | **Slash Commands** | Command usage patterns | Better commands, retired ones | | **Context Management** | Context drift, compaction wins | Better defaults & rituals | | **AI-Powered Dev Loop** | Cycle-time signals | Process refinements | | **Prompt Engineering for Repos** | Prompt quality scores | Better prompt patterns | | **AI Cost & Token Economics** | Cost anomalies | Routing & batching tactics | | **AI Onboarding Kit** | New-hire friction | Updated kit & buddy guidance | | **AI Code Review Workflows** | Review acceptance + escape rate | Better review subagents | | **AI Observability** | Drift & alerts | New evals & dashboards | | **AI-Powered Postmortem** | Root causes & actions | Runbook + policy updates | | **AI Incident Response Playbook** | MTTR & timelines | Better paging & runbooks | | **AI Governance & Risk** | Policy violations & approvals | Updated controls & training | > 💡 **Tip:** The Knowledge Loop is the **operating system**. Every other anatomy is an **app** running on it. --- ## Glossary - **Capture** — Collecting raw signals across the AI system. - **Connect** — Correlating signals across sources and time. - **Codify** — Turning insights into versioned artifacts. - **Apply** — Changing real behavior (prompts, agents, docs, policies). - **Measure** — Tracking impact, quality, and outcomes. - **Share** — Distributing artifacts so they compound. - **Knowledge artifact** — A versioned, reusable piece (prompt, agent, runbook, etc.). - **Synthesizer** — The AI copilot that drafts the weekly Knowledge Update. - **Knowledge Update** — The weekly digest of signals → recommended changes. - **Loop on the loop** — Periodically improving the loop itself. --- ## Further Reading - Search: **"learning organizations Peter Senge"** - Search: **"knowledge management for AI teams"** - Search: **"continuous improvement DORA metrics"** - Search: **"retrospective antipatterns"** --- ## 🪙 Remember > **The goal is not perfection. The goal is a system that improves every day.** **The mantra:** Observe → Analyze → Improve → Validate → Share → Repeat ∞ --- ## Anatomy of AI Incident Response Playbook > Runbooks, paging, mitigation, comms, war-room with AI copilots. ![Incident Response](/posters/19-incident-response.png) > Runbooks, paging, mitigation, comms, war-room with AI copilots — the **Detect → Contain → Recover** twin of the Postmortem anatomy. --- ## TL;DR - An incident response playbook turns chaos into a **calm, repeatable process**. - Seven phases: **Detect → Declare → Contain → Mitigate → Recover → Resolve → Learn**. - **Severity drives behavior** — P0 pages everyone, P4 waits for backlog. - **AI copilots** act as Investigator, Correlator, Hypothesis Generator, Runbook Assistant, Comms Drafter, and Scribe — **not** the decision-maker. - **Runbooks beat memory.** Short, actionable, tested, kept up to date. - Every incident closes with a blameless postmortem (see the Postmortem anatomy). --- ## Why this matters The first 15 minutes of an incident decide whether you're back in 30 minutes or 6 hours. Without a playbook you improvise, page the wrong people, miss the runbook, and the comms get worse than the outage. With one — and an AI copilot stitching signals together — your team **detects faster, contains safely, recovers quickly, and learns continuously**. > **Bottom line:** We improve the system, not the person. **Curiosity over blame. Always.** --- ## The Big Picture — Incident Lifecycle ```mermaid flowchart LR D[DetectSignals fire · alert triggers · triage begins] --> Dec[DeclareAcknowledge · assess impact · set severity] Dec --> C[ContainStabilize · stop the bleeding · limit blast radius] C --> M[MitigateApply fix · work the playbook · communicate] M --> R[RecoverRestore service · verify health · monitor] R --> Res[ResolveService normal · close incident] Res --> L[LearnPostmortem · actions · improve systems] L --> D ``` ### Principles - 🛡️ **Safety first** - 🤝 **Blameless** - 📊 **Data-driven** - 🪟 **Transparent** - ⏱️ **Timely** - ♻️ **Continuous** > **Bottom line:** Move from first signal to full recovery with a calm, repeatable process — every time. --- ## Incident Severity Matrix Severity drives **who, when, and how loud**. Define it once, apply it consistently. | Severity | Definition | Examples | Response | |---|---|---|---| | 🔴 **P0** | Major outage or severe data/security risk | Total outage, data loss, security breach | Page all, war-room, exec aware, 5 m | | 🟠 **P1** | Severe outage, high customer impact | Partial outage, major performance degradation | Page team, comms, 15 m target | | 🟡 **P2** | Degraded service, medium impact | Minor features down, elevated errors | Triage & fix, within 1 hour | | 🟢 **P3** | Minor impact, limited scope | Cosmetic issues, non-critical bugs | Normal process, same day | | 🔵 **P4** | Low impact, informational | Docs, small bugs, improvements | Backlog / regular | ### Severity decision factors - 👥 **# of users affected** - 💰 **Business impact** (revenue, safety, SLAs) - 🔐 **Data integrity & security** - 🌐 **Blast radius** (systems, regions, services) - ⏱️ **Time sensitivity** / escalation risk ### Escalation rule of thumb - 🚀 **Start conservative** (declare higher). - ⚡ **Escalate fast**, de-escalate slow. - 📢 **Communicate every change** in severity. > ⚠️ **When in doubt, treat it as the next higher severity.** --- ## On-Call & Paging Flow ```mermaid flowchart LR A[🚨 Alert] --> P[PagerDuty / Opsgenie] P --> O[On-call] O --> Q{Ack in 5 min?} Q -- Yes --> E[Escalation steps] Q -- No --> X[Escalate] X --> E ``` ### Escalation steps 1. **Escalate to next on-call** 2. **Notify team channel** 3. **Notify IC / Tech lead** 4. **Exec notified** (P0/P1) ### Paging policy (starter) - **P0:** Primary on-call + secondary + tech lead + incident commander (IC). - **P1:** Primary on-call + team channel + tech lead. - **P2:** Primary on-call + team channel. - **P3/P4:** Team channel only. > 💡 **Tip:** Codify this in PagerDuty/Opsgenie escalation policies; do **not** rely on memory. --- ## Runbook Template & Example A great runbook is **short, actionable, tested, and kept up to date**. ### Runbook template ```markdown # Runbook: ## Name & Symptom What is happening? (one line) ## Impact Who / what is affected, severity, business impact. ## Severity P0 | P1 | P2 | P3 | P4 ## Detection How we know it's happening (alerts, dashboards). ## Immediate Actions First 3 steps (5 minutes). ## Mitigation How to stop the bleeding. ## Recovery How to restore service. ## Verification How to confirm it's fixed. ## Roll Forward / Back Options & commands. ## Escalation Who to escalate to, when. ## Comms What to communicate, where, how often. ## References Dashboards · PRs · tickets · related runbooks. ``` ### Example runbook — "Database errors" ```markdown # Symptom High 5xx errors, DB connection errors. ## Impact ~50% of checkout users impacted; ~$5k/min revenue loss. ## Severity P1 ## Detection - Datadog: error_rate > 5% for 2m - Postgres: "too many connections" in logs ## Immediate Actions (first 5 min) 1. Check dashboard: ai-overview 2. Check DB connections: `psql -c "select count(*) from pg_stat_activity;"` 3. Enable connection pool protection. ## Mitigation 1. Disable `new_checkout_flow` flag (LaunchDarkly). 2. Restart app pods (rolling). 3. Increase DB pool size (if safe; cap at 200). ## Recovery 1. Gradually re-enable flag: 5% → 25% → 100%. 2. Monitor metrics for 10 min at each step. ## Verification - 5xx < 1% - P95 latency < 500 ms - No new errors in app logs ## Escalation Page @sre lead after 15 min if not mitigated. ## References - Dashboard: ai-overview - Tickets: DB-123, INC-2025-05-20 ``` > 💡 **Tip:** **Short. Actionable. Tested.** Keep commands up to date. --- ## AI Copilots in the War-Room AI is your **force multiplier** during an incident — for speed, scale, and signal. Humans own **judgment and empathy**. | Copilot | Role | What it does | |---|---|---| | 🔬 **Investigator** | Evidence gatherer | Pulls logs, metrics, traces, events | | 🔗 **Correlator** | Pattern finder | Links signals; builds timeline; finds patterns | | 💡 **Hypothesis Generator** | Likely-cause proposer | Ranks likelihood; asks clarifying questions | | 📒 **Runbook Assistant** | Right-runbook router | Finds matching runbooks; suggests next actions | | 💬 **Comms Drafting** | Update writer | Drafts updates for incident channel, status page | | 🖊️ **Scribe** | Memory keeper | Captures decisions, actions, timeline events | ### Sample war-room AI commands ```text /incident start /timeline — show evolving timeline /hypotheses — top 5 likely causes with evidence /runbook — find matching runbook /comms draft — draft update text /scribe note — record a decision in the ledger /postmortem draft — auto-draft after resolution ``` > 💡 **Tip:** **AI accelerates. Humans decide.** Every AI suggestion must be reviewable, with sources. --- ## Detection Signals We Monitor Correlate signals to **reduce noise, alert on impact**. | Signal | Why it matters | |---|---| | ❌ **Error rate** (↑ 5xx, 4xx) | Most direct user-pain proxy | | ⏱️ **Latency** (P95, P99) | UX & timeout cliffs | | 🎯 **SLO / SLA burn rate** | Compliance & promises | | 🚦 **Traffic** (surges / drops) | Capacity / outage hints | | 🗄️ **DB / infra** (CPU, mem, I/O) | Resource exhaustion | | 📨 **Queues** (backlog, lag) | Pipeline health | | ⭐ **AI quality** (eval score) | Silent quality drift | | 🛡️ **Security** (alerts, scans) | Breach indicators | > 💡 **Tip:** Pair every alert with a runbook link **in the alert itself**. --- ## AI-Augmented Timeline (example) | Time (UTC) | Event | Source | Detail | |---|---|---|---| | 🔴 14:02:18 | Error rate spike | Datadog | 5xx from 0.2% → 12% | | 🟡 14:02:21 | Latency increase | Datadog | P95 latency 120ms → 2.3s | | 🔴 14:02:34 | DB connection errors | Postgres | "too many connections" | | 🔵 14:03:05 | Deploy started | GitHub Actions | Release 2025.05.20-1 | | 🟠 14:03:47 | Feature flag enabled | LaunchDarkly | `new_checkout_flow=true` | | 🟣 14:04:02 | DB CPU > 95% | Datadog | `db-primary-01` | | 🟢 14:05:10 | Rollback deploy | GitHub Actions | Reverted to 2025.05.19-4 | | 🟢 14:07:12 | Error rate normalizing | Datadog | 5xx < 1% | | 🟢 14:10:45 | Incident stabilized | Ops | Monitoring stable for 10 m | > 💡 **Tip:** AI stitches logs, metrics, deploys, flags, and chat into **a clear shared timeline** — within seconds. --- ## Root Cause & Contributing Factors (preview) The handoff to the postmortem starts **during** the incident. ### 5 Whys (example) ```text 1. Why did checkout fail? → DB connections exhausted. 2. Why? → Connections not returned. 3. Why? → Code missed release on error path. 4. Why? → Recent change covered error path poorly. 5. Why? → No test covering error path. → Root cause: missing connection release on error path. ``` ### Contributing factors (Ishikawa) - **People:** On-call not familiar with new feature. - **Process:** No pre-prod load test. - **Technology:** Pool size too small; no pool-usage alert. - **Environment:** Traffic surge. - **Tools:** Limited visibility in flags dashboard. - **Measurement:** No alert on connection utilization. > **Focus on systems. Improve systems.** (Full treatment lives in the Postmortem anatomy.) --- ## Actions, Tracking & Closeup Every incident closes with **specific, owned, time-bound** actions. | # | Action | Owner | Priority | Due | Status | Success metric | |---|---|---|---|---|---|---| | 1 | Add connection-release | @eng/auth | P0 | May 25 | In progress | No leaks in 7d | | 2 | Add integration test | @eng/test | P0 | May 23 | Todo | Test covers error path | | 3 | Add pool-usage alert | @eng/obs | P1 | May 26 | Todo | Alert fires in staging | | 4 | Load test new flow | @eng/perf | P1 | May 27 | Todo | Load test passes | | 5 | Runbook update | @sre | P1 | May 23 | Done | Runbook v1.2 | > 💡 **Tip:** **Verify fixes. Measure impact. Close the loop.** --- ## Communications Templates ### Internal — incident channel (first 5 minutes) ```text 🚨 INCIDENT DECLARED — P1 Title: Started: