Anthropic's Terminal-Native AI Coding Agent · Claude Sonnet 4.5 / Opus 4.7

CLAUDE
CODE
DEEP DIVE

The complete reference for Claude Code — Anthropic's command-line coding agent. Covers installation, CLAUDE.md, SKILL.md, hooks, MCP, subagents, plan mode, worktrees, plugins, the Agent SDK, GitHub Actions, 30+ battle-tested prompts, chained workflows, and 2 full app blueprints (RAG AI + FastAPI internal tool) with copy-paste-ready code.

30+ Slash Commands 3 Config Files 7 Hook Types 30+ Prompts 2 Full Blueprints C# · Python · TS · Mobile

Fundamentals

Overview & Architecture

Claude Code is Anthropic's terminal-native coding agent — a CLI tool that runs inside your shell and has direct access to your filesystem, git, shell commands, and any MCP servers you connect. It is NOT the same as Claude.ai in a browser.

✅ What Claude Code IS

CLI agentRuns in your terminal, reads/writes files directly
Shell-enabledCan run bash, git, npm, tests, builds natively
ExtensiblePlugins, skills, hooks, MCP servers, subagents
Multi-fileEdits entire projects, not single files in isolation
AgenticPlans, executes, verifies, iterates autonomously
Git-awareCommits, branches, PRs, worktrees built-in

❌ What Claude Code is NOT

Not Claude.aiDifferent product, different capabilities
Not a chatIt's an agent — it DOES things, not just talks
Not auto-safeCan delete files, push commits — review carefully
Not free foreverUses API tokens; costs scale with usage
Not a replacementYou still drive the ship; it's a force multiplier
Not magicNeeds good CLAUDE.md + good prompts to shine

The Four Layers

Claude Code is built on a layered architecture. Understanding this helps you configure it properly:

Layer 1 — CLI Core

The claude binary, session loop, tool execution, model routing. This is the engine.

Layer 2 — Configuration

CLAUDE.md (per-project + user), AGENTS.md (multi-agent), settings.json (permissions), keybindings.json

Layer 3 — Extensions

Skills (SKILL.md), Slash Commands, Subagents, Hooks, Plugins, Output Styles

Layer 4 — External

MCP servers (Context7, Exa, Playwright...), GitHub Actions, Agent SDK, Dispatch API

Key Insight

Most Claude Code problems aren't about the model — they're about Layer 2 (configuration). A good CLAUDE.md and well-scoped skills will 10× your effectiveness. This tutorial focuses heavily on those layers.

Setup

Installation

Prerequisites

Claude Code requires Node.js 18+ and either an Anthropic API key or a Claude Pro/Max subscription. On Windows, use PowerShell or WSL2 — Git Bash has known issues with some subagent operations.

Step 01 — Install Node.js

Install Node.js 18 or later

# Windows (winget) winget install OpenJS.NodeJS.LTS # macOS (Homebrew) brew install node # Linux (nvm recommended) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash nvm install --lts # Verify node --version # should be v18.x or higher

Step 02 — Install Claude Code

Install the Claude Code CLI globally

# Global install via npm npm install -g @anthropic-ai/claude-code # Alternative: pnpm pnpm add -g @anthropic-ai/claude-code # Alternative: Bun bun add -g @anthropic-ai/claude-code # Verify installation claude --version

Step 03 — Authenticate

Log in via browser or API key

# Option A: Browser login (Claude Pro/Max/Team) claude login # opens browser, handles OAuth # Option B: API key (pay-per-token) export ANTHROPIC_API_KEY="sk-ant-..." // macOS/Linux $env:ANTHROPIC_API_KEY="sk-ant-..." # PowerShell # Option C: Via 1Password / keychain (recommended) export ANTHROPIC_API_KEY=$(op read "op://Private/Anthropic/key")

Never Commit Keys

If you set ANTHROPIC_API_KEY in a .env file, add .env to .gitignore FIRST. Claude Code reads the env var automatically.

Step 04 — First Run

Navigate to a project and launch Claude Code

cd C:\MyProject # Windows cd ~/my-project # macOS/Linux # Launch Claude Code claude # First run will ask: # - Trust this directory? (y/N) # - Create .claude/ folder for config?

Step 05 — Optional: IDE Integration

Install the VS Code extension (or Cursor / JetBrains)

# VS Code marketplace search code --install-extension anthropic.claude-code # Or from inside Claude Code CLI /install-github-app # for GitHub integration

The VS Code extension adds inline chat, code lens buttons, and file context. JetBrains plugin is in beta at this writing.

Install Verification

Run claude --version. If you see a version number (e.g. 1.x.y), you're good. If you see "command not found", add your global npm bin path to PATH: npm config get prefix shows where it lives.

Onboarding

First-Time Setup

Setup 01 — Run /init

Auto-generate your project's CLAUDE.md

# Inside Claude Code session /init # What it does: # - Scans your repo # - Detects tech stack (package.json, requirements.txt, *.csproj, etc.) # - Creates a starter CLAUDE.md with project conventions # - Suggests skills, hooks, and MCP servers relevant to your stack

Setup 02 — Review the Generated CLAUDE.md

The file will look something like this

# Generated CLAUDE.md example ## Project Overview This is a Next.js 15 + TypeScript app using Postgres and Prisma ORM. ## Tech Stack - Frontend: Next.js 15 App Router, React 19, Tailwind CSS 4 - Backend: Next.js API routes, tRPC, Zod - Database: Postgres 16, Prisma ORM - Testing: Vitest (unit), Playwright (E2E) ## Conventions - Use TypeScript strict mode always - Zod schemas for all API boundaries - Prisma migrations via `pnpm prisma migrate dev` - Components in PascalCase, hooks in camelCase ## Commands - Dev: `pnpm dev` - Test: `pnpm test` + `pnpm e2e` - Build: `pnpm build` - Lint: `pnpm lint --fix`

Setup 03 — Configure Global Preferences

Create your user-level CLAUDE.md

# Global preferences that apply to ALL projects mkdir -p ~/.claude code ~/.claude/CLAUDE.md # Example content for ~/.claude/CLAUDE.md: ## My Preferences - Default package manager: pnpm (fallback npm) - Git commit style: Conventional Commits - Always ask before running destructive commands - Prefer verbose over clever code - Never use `any` in TypeScript without comment explaining why

Setup 04 — Permission Profile

Configure what Claude Code can and cannot do

# ~/.claude/settings.json { "permissions": { "allow": [ "Bash(git:*)", "Bash(pnpm:*)", "Bash(npm:*)", "Bash(node:*)", "Read(**)", "Write(**)" ], "deny": [ "Bash(rm -rf /)", "Bash(curl:* | sh)", "Bash(sudo:*)", "Read(.env)", "Read(**/*.key)" ] } }

Critical

The deny list is your safety net. Always include it. See Section 13 (Rejected Commands) for more things to block.

Setup 05 — Verify Setup with /doctor

Run the health check

/doctor # Checks: # ✓ Node version # ✓ API key / login # ✓ CLAUDE.md exists # ✓ settings.json valid # ✓ MCP servers reachable # ✓ Git configured

Reference

Core Slash Commands

Type / inside a Claude Code session to see the command picker. These are the built-in commands — plugins and skills add more.

Command	Purpose	Notes
/help	List all available commands	Shows both built-in and plugin commands
/init	Auto-generate CLAUDE.md for current project	Run once per new project
/clear	Clear conversation context	Preserves plan files and CLAUDE.md
/compact	Compress long context into summary	Great for long sessions to reclaim tokens
/resume	Resume a previous session	Lists recent sessions by date
/sessions	Manage session history	List, rename, delete saved sessions
/model	Switch model mid-session	Opus 4.7 / Sonnet 4.6 / Haiku 4.5
/effort	Set reasoning effort level	`low / medium / high` for next turn
/review	Review recent changes	Built-in code review, runs as subagent
/security-review	Security-focused review	Scans for secrets, injection, unsafe patterns
/agents	List and manage subagents	See active agents, kill runaway ones
/mcp	Manage MCP servers	Add/remove/test servers
/plugin	Manage plugins	Install, update, list, marketplace
/memory	View/edit persistent memory	Cross-session memory via MCP
/config	Edit Claude Code config	Opens settings.json in $EDITOR
/cost	Show token usage + cost	Current session + rolling totals
/status	Show session status	Model, context used, active hooks
/doctor	Health check	Verify setup is working
/bug	Report a bug to Anthropic	Auto-includes session metadata
/keybindings	Edit keyboard shortcuts	Saves to `~/.claude/keybindings.json`
/upgrade	Update Claude Code	Runs npm update behind scenes
/exit	Exit Claude Code	Also: Ctrl+C twice, or Ctrl+D
/vim	Toggle vim mode	Input mode with vim bindings
/terminal-setup	Configure terminal integration	Sets up shell hooks for better UX
/install-github-app	Install GitHub App integration	For automated PR reviews
/pr_comments	Fetch PR review comments	Pulls comments from current PR branch

Bundled Skills (also act as slash commands)

These are built-in skills that behave like slash commands:

/simplify

3-agent review pipeline — detects architectural issues, duplicate logic, perf issues

/batch

Run parallel changes across worktrees, auto-creates PRs

/debug

Systematic debugging — root cause → hypothesis → test → fix

/loop

Autonomous loop — runs task repeatedly until success criteria met

/claude-api

Help writing code against the Anthropic API

Configuration

CLAUDE.md Deep Dive

CLAUDE.md is the single most important file in your Claude Code setup. It's the system prompt for every session — Claude reads it first, every time. A great CLAUDE.md means Claude already knows your conventions before you type a single prompt.

Precedence Order (highest to lowest)

1. User message (your prompt) · 2. Project CLAUDE.md (.claude/CLAUDE.md) · 3. User CLAUDE.md (~/.claude/CLAUDE.md) · 4. Imported @files · 5. Built-in system prompt

Concept — @imports

Keep CLAUDE.md small by importing other files

# Inside CLAUDE.md, use @ to pull in other files ## Architecture See @docs/architecture.md for system design. ## API Conventions Read @docs/api-conventions.md before touching any route. ## Coding Standards @docs/standards/typescript.md @docs/standards/react.md

Why This Matters

A CLAUDE.md over 300 lines bloats every session's context. Use @imports to keep the root file under 150 lines, then import detailed docs only when needed.

Example A — TypeScript / Next.js Project

Real-world CLAUDE.md for a Next.js 15 app

# .claude/CLAUDE.md — Next.js 15 App Router project # Project: Acme SaaS Dashboard ## Stack - Next.js 15.2 (App Router, Server Components by default) - React 19, TypeScript 5.6 (strict mode) - Tailwind CSS 4 + shadcn/ui - Prisma 6 + Postgres 16 - tRPC 11 for API, Zod for validation - Auth: better-auth (email + OAuth) - Testing: Vitest + React Testing Library + Playwright ## Conventions - **Server Components by default.** Only use `"use client"` when absolutely necessary. - **Data fetching in Server Components.** Mutations via Server Actions or tRPC. - **Zod schemas for ALL external boundaries** — API routes, env vars, form inputs. - **No `any`.** Use `unknown` + narrowing or proper types. - **Folder structure:** `app/` for routes, `components/` for UI, `lib/` for utils, `server/` for backend-only code. - **Imports:** Use `@/` alias for all absolute imports. ## Commands - Dev: `pnpm dev` - Test: `pnpm test` (unit) + `pnpm e2e` (Playwright) - Type check: `pnpm tsc --noEmit` - Lint: `pnpm lint --fix` - DB: `pnpm db:migrate` (dev) · `pnpm db:deploy` (prod) - Build: `pnpm build` ## Do Not - Do not use `fetch` in Server Components — use the tRPC caller instead. - Do not modify `prisma/schema.prisma` without running `pnpm db:migrate`. - Do not commit directly to `main` — always via PR. - Do not add new dependencies without confirming with the team. ## Imports @docs/architecture.md @docs/auth-flow.md @docs/deployment.md

Example B — Python / FastAPI Project

Real-world CLAUDE.md for a Python API

# .claude/CLAUDE.md — FastAPI backend service # Project: Acme Data Platform API ## Stack - Python 3.12 + FastAPI 0.115 - SQLModel (SQLAlchemy 2.x + Pydantic v2) - PostgreSQL 16 with asyncpg - Redis 7 (caching, rate limits, Celery broker) - Celery 5 for async jobs - Pytest + httpx for testing - Ruff for lint/format, mypy strict mode ## Conventions - **Async everywhere** — all DB, HTTP, file I/O must be async. - **Pydantic v2 models for ALL I/O** — request bodies, responses, config. - **Dependency injection via FastAPI's Depends()** — never global state. - **Type hints mandatory.** `mypy --strict` must pass. - **One route = one function.** No router methods with 200 lines. - **Repository pattern** — business logic never talks to SQLAlchemy directly. ## Project Layout ``` app/ ├── api/v1/routes/ # FastAPI routers ├── core/ # config, security, middleware ├── models/ # SQLModel / Pydantic models ├── repositories/ # DB access layer ├── services/ # business logic ├── tasks/ # Celery tasks └── tests/ ├── unit/ └── integration/ ``` ## Commands - Dev: `uv run fastapi dev app/main.py` - Test: `uv run pytest -xvs` - Lint: `uv run ruff check --fix && uv run ruff format` - Type: `uv run mypy app/ --strict` - Migrations: `uv run alembic upgrade head` · make: `alembic revision --autogenerate -m "msg"` ## Never Do - Never use `datetime.now()` — use `datetime.now(timezone.utc)`. - Never use `json.dumps` on Pydantic models — use `.model_dump_json()`. - Never commit without running tests + ruff. - Never use bare `except:` — always catch specific exceptions. - Never use synchronous libraries in async code (requests, psycopg2 — use httpx, asyncpg).

Example C — C# / ASP.NET Core Project

Real-world CLAUDE.md for an ASP.NET Core API

# .claude/CLAUDE.md — ASP.NET Core 9 minimal API # Project: Acme Orders Service ## Stack - .NET 9 / ASP.NET Core Minimal API - Entity Framework Core 9 with Postgres (Npgsql) - MediatR for CQRS pattern - FluentValidation for request validation - Serilog for structured logging - xUnit + FluentAssertions + Testcontainers for tests - Docker for local Postgres ## Conventions - **C# nullable reference types enabled.** Always. Every project. - **Record types** for DTOs, immutable data. - **CQRS via MediatR** — no controllers touching DbContext directly. - **Result<T> pattern** — never throw for expected failures; return Result. - **Minimal APIs, not MVC controllers** — endpoints grouped by feature. - **One feature folder = one vertical slice.** Command + Handler + Validator + Endpoint together. ## Project Layout ``` src/ ├── Acme.Api/ # minimal API endpoints ├── Acme.Application/ # commands, queries, handlers ├── Acme.Domain/ # entities, value objects ├── Acme.Infrastructure/ # EF Core, external services └── Acme.Contracts/ # shared DTOs tests/ ├── Acme.UnitTests/ └── Acme.IntegrationTests/ ``` ## Commands - Run: `dotnet run --project src/Acme.Api` - Test: `dotnet test` (all) · `dotnet test tests/Acme.UnitTests` (unit only) - Build: `dotnet build -c Release` - Format: `dotnet format` - Migrations: `dotnet ef migrations add <Name> -p src/Acme.Infrastructure -s src/Acme.Api` - Apply: `dotnet ef database update -p src/Acme.Infrastructure -s src/Acme.Api` ## Testing Conventions - Arrange / Act / Assert blocks clearly labeled - One assertion per test (use FluentAssertions for compound checks) - Integration tests use Testcontainers for real Postgres - Test naming: `Should_DoX_When_Y()` ## Never - Never use `Task.Result` or `.Wait()` — always await. - Never catch `Exception` — catch specific types or let it bubble. - Never use `DateTime.Now` — use `DateTimeOffset.UtcNow`. - Never return IQueryable from public APIs — materialise with `ToListAsync()`. - Never use EF Core migrations on production DB — use SQL scripts.

CLAUDE.md Anti-Patterns

What to NEVER put in CLAUDE.md

❌ Secrets / API keys — CLAUDE.md gets committed. Use env vars.
❌ Walls of prose — keep it scannable. Claude reads lists better than paragraphs.
❌ Conflicting conventions — "use tabs" + "use 2 spaces" confuses the model.
❌ Stale commands — outdated commands make Claude hallucinate failures.
❌ Over 300 lines — use @imports to break it up.
❌ Opinions without justification — "no classes" works better than "hate OOP".
❌ Every possible rule — focus on what's non-obvious. Claude knows TypeScript basics.

Concept — AGENTS.md (the newer file)

CLAUDE.md vs AGENTS.md — which to use?

AGENTS.md is the newer open standard (used by multiple AI coding tools — Codex, OpenCode, Cursor). It serves the same purpose as CLAUDE.md but is tool-agnostic.

Use CLAUDE.md if your team only uses Claude Code
Use AGENTS.md if you share the project across Codex / Cursor / OpenCode / Claude Code
You can have both — Claude Code reads both, with CLAUDE.md winning conflicts

# Symlink pattern — one file, both names ln -s CLAUDE.md AGENTS.md # macOS/Linux mklink AGENTS.md CLAUDE.md # Windows (admin)

Configuration

Skills (SKILL.md) Deep Dive

Skills are Claude Code's killer feature. A skill is a folder with a SKILL.md file that teaches Claude how to do a specific task. Skills can be auto-invoked by Claude when the context matches, or manually via /skill-name. They replaced the old "slash commands" system as the primary extension mechanism.

Skill Locations (precedence order)

1. Project: .claude/skills/<name>/SKILL.md · 2. User: ~/.claude/skills/<name>/SKILL.md · 3. Plugin: <plugin-dir>/skills/<name>/SKILL.md

Anatomy — Skill Structure

Every skill is a directory with a SKILL.md plus optional support files

.claude/skills/deploy-to-vercel/ ├── SKILL.md # REQUIRED — the skill itself ├── reference/ │ ├── vercel-cli.md # progressive disclosure │ └── troubleshoot.md ├── scripts/ │ └── pre-deploy.sh └── templates/ └── vercel.json

Anatomy — SKILL.md Frontmatter

All available frontmatter options

--- name: deploy-to-vercel description: Deploys the current Next.js app to Vercel production. Runs tests, builds, checks env vars, then deploys. Use when user says "deploy to vercel" or "ship to prod". allowed-tools: Bash(vercel:*), Bash(pnpm:*), Read(**), Write(vercel.json) disable-model-invocation: true user-invocable: true model: claude-sonnet-4-6 context: fork agent: general-purpose --- # Skill body goes here — markdown instructions Claude follows when this skill is invoked

name

Required. The slash command — e.g. /deploy-to-vercel

description

Required. Tells Claude when to auto-invoke. Be specific.

allowed-tools

Optional. Pre-authorised tools, no permission prompts

disable-model-invocation

If true, only the user can invoke. Claude can't auto-call it.

user-invocable

If false, only Claude invokes (hidden from / menu)

model

Pin a model — claude-opus-4-7, claude-sonnet-4-6, etc.

context: fork

Run in a separate context window (no pollution)

agent

Explore / Plan / general-purpose or custom

Example Skill A — Deploy to Vercel

Full skill with safety gates

# .claude/skills/deploy-to-vercel/SKILL.md --- name: deploy-to-vercel description: Deploys the current Next.js app to Vercel production after running gates. Use when user says "deploy", "ship to prod", or "push to vercel". allowed-tools: Bash(vercel:*), Bash(pnpm:*), Bash(git:*), Read(**) disable-model-invocation: true --- # Deploy to Vercel Run these steps in order. ABORT on any failure. ## 1. Pre-deploy Gates - Run `git status` — must be clean - Run `pnpm test` — all tests must pass - Run `pnpm build` — must succeed locally - Verify `vercel.json` exists - Check required env vars exist on Vercel via `vercel env ls production` ## 2. Confirm with User Print summary: branch, commit SHA, changed files count, estimated impact. Ask: "Deploy commit <sha> to vercel production? (yes/no)" If response is not an exact "yes", ABORT. ## 3. Deploy - Run `vercel --prod` from repo root - Capture deployment URL - Tag the commit: `git tag -a v$(date +%Y%m%d-%H%M%S) -m "prod deploy"` - Push tag: `git push origin --tags` ## 4. Verify - Curl deployment URL `/api/health` — expect 200 - Print deployment URL + tag to user - Done. ## Abort Protocol If any step fails, print exactly what failed, do NOT proceed.

Why disable-model-invocation?

Deploys have real consequences. We don't want Claude to accidentally deploy when it "thinks" the user asked for it. Only an explicit /deploy-to-vercel triggers this.

Example Skill B — Code Review

Auto-invoking review skill

# ~/.claude/skills/code-review/SKILL.md --- name: code-review description: Reviews recently changed code for bugs, security issues, and style violations. Use when user says "review this", "check my code", or after completing a feature task. allowed-tools: Bash(git diff:*), Bash(git log:*), Read(**) context: fork agent: general-purpose --- # Code Review Perform a thorough review of uncommitted changes OR the current feature branch. ## Scope - If working tree has uncommitted changes → review `git diff` - Else → review `git diff main...HEAD` ## Review Checklist Go through each category. Report findings as a structured list. ### Bugs - Off-by-one errors - Null/undefined handling - Race conditions - Incorrect error handling - Wrong API contract ### Security - SQL injection, XSS, path traversal - Secrets/keys hardcoded - Insecure randomness (Math.random for crypto) - Missing input validation - Auth bypass patterns ### Style / Maintainability - Violations of project CLAUDE.md conventions - Dead code - Excessive complexity (cyclomatic > 10) - Missing tests for new code - Inconsistent naming ## Output Format ``` ## Review Summary X issues found (Y critical, Z warnings) ### Critical - file.ts:42 — <description> ### Warnings - ... ### Suggestions - ... ``` Do NOT make changes — only report. User decides what to fix.

Example Skill C — Commit with Convention

Structured git commit skill

# ~/.claude/skills/commit/SKILL.md --- name: commit description: Create a conventional-commit style git commit from current changes. Use when user says "commit", "commit this", or "save progress". allowed-tools: Bash(git:*) disable-model-invocation: true --- # Git Commit (Conventional) ## 1. Inspect - Run `git status` and `git diff --staged` (or `git diff` if nothing staged) - Identify the dominant change type: - `feat:` new feature - `fix:` bug fix - `refactor:` no behavior change - `perf:` performance - `docs:` docs only - `test:` tests only - `chore:` build/config - `ci:` pipeline ## 2. Draft Message Format: ``` <type>(<scope>): <imperative subject, lowercase, no period, ≤ 72 chars> <body — what changed and why, wrapped at 72 chars> <footer — Closes #123 etc.> ``` ## 3. Confirm Show the drafted message. Ask "Commit with this message? (yes/edit/no)". - yes → stage all, commit, print SHA - edit → user rewrites, then commit - no → abort, don't touch git ## 4. Never - Never commit without asking first - Never force-push - Never commit to main directly (check branch first)

Configuration

Hooks System

Hooks are scripts that fire at specific points in Claude Code's lifecycle. They let you inject context, block dangerous actions, or automate workflows. Every hook communicates via JSON on stdin / stdout.

Hook Types (7 total)

Hook	Fires When	Use Case
PreToolUse	Before Claude calls any tool	Block dangerous commands, inject context
PostToolUse	After tool completes	Log actions, notify, post-process output
UserPromptSubmit	User hits Enter on prompt	Rewrite prompts, add metadata, audit
Stop	Session ends	Cleanup, summary, cost report
SessionStart	New session begins	Auto-load context, check env, run linter
Notification	Claude needs user attention	Desktop notify, sound, Slack webhook
PermissionRequest	Claude asks for tool permission	Auto-approve safe patterns, deny risky ones

Hook Config — hooks.json Format

Where and how to define hooks

# .claude/hooks/hooks.json — project level # ~/.claude/hooks/hooks.json — user level { "hooks": { "PreToolUse": [ { "matcher": "Bash(rm -rf:*)", "command": "python .claude/hooks/block-rm-rf.py" } ], "PostToolUse": [ { "matcher": "Edit(*.ts)", "command": "pnpm lint --fix $FILE" } ], "SessionStart": [ { "command": "echo 'Claude Code session started at $(date)' >> .claude/session.log" } ], "UserPromptSubmit": [ { "command": "python .claude/hooks/audit-prompt.py" } ] } }

Hook Example — Block rm -rf

PreToolUse hook that blocks dangerous deletions

# .claude/hooks/block-rm-rf.py import sys, json, re data = json.load(sys.stdin) # data has shape: {"tool": "Bash", "tool_input": {"command": "..."}} cmd = data.get("tool_input", {}).get("command", "") dangerous = [r"rm\s+-rf\s+/", r"rm\s+-rf\s+~", r":\{"] for pattern in dangerous: if re.search(pattern, cmd): print(json.dumps({ "hookSpecificOutput": { "decision": { "behavior": "deny", "message": f"Blocked dangerous command: {cmd}" } } })) sys.exit(0) # Allow by default print(json.dumps({"hookSpecificOutput": {"decision": {"behavior": "allow"}}}))

Hook Example — Auto-lint on Edit

PostToolUse hook that lints files after Claude edits them

# .claude/hooks/auto-lint.sh #!/bin/bash # Reads JSON from stdin with edited file info FILE=$(jq -r '.tool_input.file_path') case "$FILE" in *.ts|*.tsx) pnpm eslint --fix "$FILE" ;; *.py) ruff format "$FILE" && ruff check --fix "$FILE" ;; *.cs) dotnet format --include "$FILE" ;; *.go) gofmt -w "$FILE" ;; *.rs) rustfmt "$FILE" ;; esac # Always signal success so Claude continues exit 0

Hook Example — Session Summary

Stop hook that logs session cost + summary

# .claude/hooks/stop-summary.sh #!/bin/bash # Runs when session ends DATE=$(date '+%Y-%m-%d %H:%M') INPUT=$(cat) TOKENS=$(echo "$INPUT" | jq -r '.session.tokens_used // 0') COST=$(echo "$INPUT" | jq -r '.session.cost_usd // 0') echo "$DATE | tokens=$TOKENS | cost=\$$COST" >> ~/.claude/session-log.txt # Slack webhook if cost over $1 if (( $(echo "$COST > 1.0" | bc -l) )); then curl -X POST -H 'Content-type: application/json' \ --data "{\"text\":\"High-cost session: \\$$COST\"}" \ $SLACK_WEBHOOK_URL fi

Hook Security — The JSON Contract

How hooks return decisions

Hooks communicate via JSON on stdout. To deny an action:

{ "hookSpecificOutput": { "decision": { "behavior": "deny", "message": "Explanation shown to user and Claude" } } }

To allow:

{ "hookSpecificOutput": { "decision": { "behavior": "allow" } } }

To inject context (UserPromptSubmit):

{ "hookSpecificOutput": { "additionalContext": "Current git branch: feature/auth-v2\nUncommitted files: 3" } }

Configuration

MCP (Model Context Protocol)

MCP is Anthropic's open protocol for connecting external tools to AI agents. An MCP server exposes tools (functions) that Claude Code can call. Think of them as "plugins for data and actions" — access databases, browse the web, control browsers, send emails, query APIs.

MCP Concepts

How MCP works

MCP Server — a process that exposes tools. Runs locally or remotely.
MCP Client — Claude Code is the client. It discovers and calls server tools.
Transport — stdio (local subprocess), SSE (HTTP Server-Sent Events), or WebSocket
Config — added via claude mcp add or in ~/.claude/mcp.json

MCP Setup — Adding a Server

Use `claude mcp add` command

# Add Context7 (library docs lookup) — via npx claude mcp add context7 -- npx -y @upstash/context7-mcp # Add Playwright (browser automation) claude mcp add playwright -- npx -y @modelcontextprotocol/server-playwright # Add GitHub (requires GITHUB_TOKEN env) claude mcp add github -e GITHUB_TOKEN=$GH_TOKEN -- npx -y @modelcontextprotocol/server-github # List configured MCP servers claude mcp list # Test a server claude mcp test context7 # Remove a server claude mcp remove context7

Top MCP Servers for Daily Use

The essential toolkit

Context7

Up-to-date library docs. Claude fetches real API references before writing code.

Exa

Research-first web search. Better than Google for code docs.

Playwright

Browser automation. Claude can test UIs, scrape, screenshot.

GitHub

PRs, issues, repos, workflows — all via natural language.

Postgres

Query your DB directly. Schemas, sample data, query tuning.

Memory

Persistent cross-session memory. Remember user prefs, project context.

Sequential Thinking

Structured multi-step reasoning for complex problems.

Scheduled Tasks

Cron-based agent scheduling. "Review PRs every morning at 9am"

Supabase

DB + auth + storage for Supabase projects.

Figma

Read design files, convert mockups to code.

MCP Config — mcp.json

Manual config file format

# ~/.claude/mcp.json { "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }, "playwright": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-playwright"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "$DATABASE_URL"] }, "scheduled-tasks": { "command": "npx", "args": ["-y", "@anthropic/scheduled-tasks-mcp"] } } }

MCP Power Move — Scheduled Tasks

Turn Claude Code into an autonomous background agent

# Inside a Claude Code session, ask: Set up a scheduled task: every weekday at 9 AM, review open PRs on my repo, check CI status, flag blocking issues, and write a summary to memory. # Claude calls the MCP tool: # mcp__scheduled-tasks__create_scheduled_task({ # name: "daily-pr-review", # schedule: "0 9 * * 1-5", # prompt: "...", # project_dir: "/path/to/repo" # })

Unlocks Serious Power

Combined with claude -p headless mode + dispatch API, this effectively replaces tools like Hermes or AutoGPT. Your agent becomes self-directing.

MCP Security — The Risks

MCP servers are arbitrary code — treat them accordingly

⚠️ Review before installing. MCP servers have full access to whatever their code does.
⚠️ Known CVEs exist. There's a database of 25+ known MCP vulnerabilities.
⚠️ Scope env vars. Pass only what's needed — don't export your whole .env to every MCP.
⚠️ Audit with AgentShield. Run npx ecc-agentshield scan periodically.
⚠️ Prefer official servers. @modelcontextprotocol/* are maintained by Anthropic and partners.

Advanced

Subagents & Parallel Execution

Subagents are isolated Claude instances spawned by the main session to handle specific tasks in parallel. Each runs in its own context window, returns results to the orchestrator, and doesn't pollute the main conversation. This is how Claude Code handles complex multi-file work.

Built-in Subagent Types

Explore — fast codebase navigation & search · Plan — design implementation strategies · general-purpose — catch-all for research & multi-step tasks

Concept — When Subagents Fire

Two ways subagents launch

Automatic (Task tool) — Claude's main session calls the Task tool with a prompt + agent type. A fresh subagent runs, returns a summary.
Manual (via skill frontmatter) — A skill with agent: Explore runs in that agent's context.

Custom Subagents — .claude/agents/ Directory

Write your own subagent

# .claude/agents/security-reviewer.md --- name: security-reviewer description: Dedicated security review. Triggers on any security finding, before deploys, or when user says "security check". tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*) model: claude-opus-4-7 --- ## Role You are a paranoid security reviewer. Your job is to find vulnerabilities. Be skeptical. Assume the code has issues. Investigate before accepting. ## Review Scope - Recent changes: `git diff main...HEAD` - Focus on: input validation, auth, secrets, injection, deserialization ## Output Format Return a structured JSON-like block: ``` CRITICAL: <file:line> — <issue> HIGH: ... MEDIUM: ... LOW: ... ``` Never modify files. Only report.

Parallel Execution — The Pattern

Dispatch multiple subagents in one message

When the main session calls Task multiple times in a single message, they run in parallel. Use this for independent workstreams.

# Example prompt that triggers 3 parallel subagents: For the user auth feature, launch 3 parallel subagents: 1. Research agent: find best practices for JWT + refresh tokens in Node.js 2026 2. Explorer agent: map all existing auth code in /src/auth 3. Test agent: identify gaps in current auth test coverage Aggregate findings and propose a plan.

Why Parallel

Three 30-second subagent calls serially = 90s. In parallel = 30s. For research-heavy tasks this is a huge speedup.

Subagent Pattern — Two-Stage Review

Spec compliance + code quality as separate subagents

Battle-tested pattern from Superpowers & ECC: never trust a single-agent review.

# In orchestrator's prompt: Stage 1: Dispatch spec-reviewer subagent. - Reads spec + reads actual code - Does NOT trust implementer's "I did it" report - Returns: ✓ complies / ✗ gaps (list specific) If Stage 1 passes: Stage 2: Dispatch code-quality-reviewer subagent. - Style, patterns, test coverage, complexity - Returns structured report Only mark task complete if BOTH pass.

Context Isolation — Critical Pattern

Subagents see ONLY what you send them

A subagent starts with a fresh context. It doesn't see your main conversation. This is a feature, not a bug:

✅ No context pollution — subagent outputs don't clog your main session
✅ Focused work — subagent has a clear single task
⚠️ But you must send context — paths, spec, constraints all go in the prompt

# BAD subagent prompt (missing context): "Review the auth code" # GOOD subagent prompt (self-contained): "Review /src/auth/**/*.ts against the spec in /docs/auth-spec.md. Constraints: Node 18+, no new deps, must preserve session-based flow. Output: structured list of findings by severity."

Anti-Pattern — Recursion

Don't let subagents spawn subagents unchecked

A subagent that spawns 3 more subagents that each spawn 3 more = runaway costs. Many frameworks (Superpowers v5, ECC) have anti-recursion guards. Your custom subagents should too:

# Add to custom subagent's SKILL.md: ## Subagent Policy You are a subagent. You MUST NOT spawn additional subagents. If a task would require a subagent, report it back to the orchestrator.

Advanced

Plan Mode & Git Worktrees

Plan mode forces Claude to produce a written plan before touching any code. Git worktrees isolate parallel tasks in separate branches. Together they enable complex multi-step work without chaos.

Plan Mode — How to Enter

Three ways to activate

# Method 1: Keyboard shortcut Shift+Tab × 2 # cycles: normal → auto-accept → plan mode # Method 2: Explicit command in prompt Plan how you would add OAuth to this app. Do not write code yet. # Method 3: Via skill frontmatter # In SKILL.md: agent: Plan

Plan Mode — The Flow

What Claude does in plan mode

Reads context — relevant files, CLAUDE.md, git state
Researches — may dispatch Explore subagent, MCP queries (Context7, Exa)
Drafts plan — structured markdown: goals, approach, files, steps, risks
Calls ExitPlanMode tool — submits plan for approval
Awaits user decision — approve / request changes / deny
On approve — proceeds to implement

Pair with Plannotator

The Plannotator plugin (see sibling tutorial) gives you a visual browser UI to annotate plans before approving. Massive upgrade over terminal-only.

Git Worktrees — Parallel Isolation

Use `--worktree` flag to isolate tasks

# Launch Claude in a fresh worktree on a new branch claude --worktree feature-auth # What this does: # 1. Creates git worktree at ../myrepo-feature-auth/ # 2. Creates branch feature-auth (or checks out existing) # 3. Starts Claude Code in that directory # 4. Auto-cleans if no changes are made

Why Worktrees Matter

You can have 3 Claude sessions running in parallel — one on feature-auth, one on feature-billing, one on bug-fix-42. They don't collide. Combined with /batch skill, Claude can ship multiple features autonomously.

Checkpoints

File snapshots for rollback

# Create a checkpoint at any time /checkpoint # Saves current state of all tracked files to .claude/checkpoints/ # Then if things go wrong: Restore to checkpoint <id> # revert files only, not git

Shift+Tab Mode Reference

The 3-state cycle

Press	Mode	Behavior
Shift+Tab (1×)	Auto-accept	Claude skips permission prompts — for non-destructive tools only
Shift+Tab (2×)	Plan mode	Claude MUST plan before acting; no file writes until approved
Shift+Tab (3×)	Normal	Default — Claude asks before each tool call

Advanced

Plugins & Marketplaces

Plugins package skills, subagents, hooks, and commands into installable bundles. A marketplace is a GitHub repo that lists multiple plugins. Claude Code discovers and installs them via the /plugin command.

Plugin Workflow

Install a plugin from a marketplace

# Step 1: Register a marketplace /plugin marketplace add obra/superpowers-marketplace # Step 2: Browse what's available /plugin # opens interactive browser # Step 3: Install a plugin /plugin install superpowers@superpowers-marketplace # Step 4: List installed plugins /plugin list # Step 5: Update /plugin update superpowers # Step 6: Uninstall /plugin remove superpowers

Essential Plugins to Know

Battle-tested plugins worth installing

superpowers (obra)

TDD, brainstorming, subagent-driven dev, systematic debugging

everything-claude-code (affaan-m)

183 skills, 48 agents, 79 commands, AgentShield security

plannotator (backnotprop)

Visual plan review in browser before code execution

claude-code-commands

Productivity shortcuts — test-runner, deploy, bundle-size

trail-of-bits security skills

Professional security audit skills (CodeQL, Semgrep integration)

frontend-design

Polished, non-generic UI patterns with shadcn/ui

Creating Your Own Plugin

The structure of a plugin repo

my-plugin/ ├── .claude-plugin/ │ ├── plugin.json # REQUIRED — plugin manifest │ └── README.md ├── commands/ # Slash commands (legacy, prefer skills/) │ └── my-command.md ├── skills/ # Modern skill definitions │ └── my-skill/ │ └── SKILL.md ├── agents/ # Custom subagents │ └── my-reviewer.md ├── hooks/ # Hook definitions │ └── hooks.json └── README.md

plugin.json Format

The plugin manifest

{ "name": "my-awesome-plugin", "displayName": "My Awesome Plugin", "version": "1.0.0", "description": "Adds superpowers for <your domain>", "author": "Your Name", "repository": "https://github.com/you/my-plugin", "claude_code_version": ">=1.0.0", "components": { "skills": ["skills/*/SKILL.md"], "agents": ["agents/*.md"], "commands": ["commands/*.md"] } }

Do NOT add "hooks" to plugin.json

Claude Code v2.1+ auto-loads hooks/hooks.json. Explicit declaration causes duplicate-hook errors. This is the #1 plugin authoring gotcha.

Marketplace Format

How to build a marketplace

my-marketplace/ ├── marketplace.json # REQUIRED └── README.md # marketplace.json format: { "name": "my-marketplace", "plugins": [ { "name": "plugin-one", "source": "github.com/me/plugin-one", "description": "..." }, { "name": "plugin-two", "source": "github.com/me/plugin-two", "description": "..." } ] } # Users install your marketplace: /plugin marketplace add github.com/me/my-marketplace

Advanced

Claude Agent SDK & Headless Mode

Claude Code's underlying engine is exposed via the Claude Agent SDK (@anthropic-ai/claude-agent-sdk). You can embed agent functionality in scripts, CI jobs, webhooks, and custom tools. Same loop, same tools, no interactive UI.

Headless Mode (-p flag)

Run Claude Code non-interactively

# Simple one-shot prompt claude -p "List all TODO comments in the codebase and tag them by priority" # With project context claude -p "Fix the failing tests in tests/" --project /path/to/repo # Pipe output to file claude -p "Analyze security of auth module" > security-report.md # Use in a shell script #!/bin/bash for repo in ~/repos/*; do claude -p "Run tests and report failures" --project "$repo" done

SDK Install

TypeScript/Node SDK

npm install @anthropic-ai/claude-agent-sdk # or pnpm add @anthropic-ai/claude-agent-sdk

SDK Basic Usage

Programmatic agent calls

import { query } from "@anthropic-ai/claude-agent-sdk"; // Simple prompt-response loop for await (const msg of query({ prompt: "Add a health check endpoint to the API", options: { maxTurns: 5, cwd: "./my-api", model: "claude-sonnet-4-6" } })) { if (msg.type === "assistant") { console.log("Claude:", msg.message); } if (msg.type === "tool_use") { console.log("Tool:", msg.tool_name, msg.input); } if (msg.type === "result") { console.log("Result:", msg.result); } }

SDK with Subagents

Inline subagent configuration

import { query } from "@anthropic-ai/claude-agent-sdk"; const result = query({ prompt: "Audit the auth module for OWASP Top 10", options: { maxTurns: 10, agents: { "security-auditor": { description: "Paranoid security reviewer", prompt: "You find OWASP vulnerabilities. Return structured JSON.", tools: ["Read", "Grep", "Bash"], model: "claude-opus-4-7" } } } }); for await (const msg of result) { // Handle messages }

SDK with MCP Servers

Load MCP inside an SDK call

const result = query({ prompt: "Browse example.com and summarize the pricing page", options: { mcpServers: { playwright: { command: "npx", args: ["-y", "@modelcontextprotocol/server-playwright"] } } } });

Dispatch API — Remote Triggering

Trigger Claude Code from webhooks / CI

# HTTP POST to dispatch endpoint curl -X POST https://api.anthropic.com/dispatch \ -H "Authorization: Bearer $ANTHROPIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Build failed on main. Diagnose and open PR with fix.", "project": "/repos/myapp", "model": "claude-opus-4-7" }' # Use cases: # - GitHub webhook → dispatch → Claude reviews PR # - CI failure → dispatch → Claude fixes + opens PR # - Sentry alert → dispatch → Claude investigates

Advanced

GitHub Actions Integration

Claude Code can run inside GitHub Actions to auto-review PRs, respond to mentions, fix CI failures, and more. The official action is anthropics/claude-code-action@v1.

Setup — Install GitHub App

Two options for auth

Option A: Install the Claude GitHub App — uses OAuth, no tokens to manage
Option B: Set ANTHROPIC_API_KEY as a repo secret — pay-per-use via API

# From inside a Claude Code session: /install-github-app # Opens browser to install, guides you through secret setup

Example Workflow — PR Review

Auto-review on pull request

# .github/workflows/claude-review.yml name: Claude PR Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | Review the changes in this PR. Focus on: correctness, security, test coverage. Post findings as inline PR comments. Don't approve unless all critical issues are addressed. model: claude-opus-4-7 max_turns: 10

Example Workflow — Fix CI Failures

Auto-fix on CI failure

# .github/workflows/claude-autofix.yml name: Auto-fix CI on: workflow_run: workflows: ["CI"] types: [completed] jobs: fix: if: ${{ github.event.workflow_run.conclusion == 'failure' }} runs-on: ubuntu-latest permissions: contents: write pull-requests: write steps: - uses: actions/checkout@v4 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | The CI pipeline failed. Read the logs from the previous workflow run, diagnose the failure, and open a PR with a fix. Branch name: autofix/<run_id>

Example Workflow — Respond to Mentions

Claude responds when @claude-code is mentioned in issues/PRs

name: Claude Mention on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: respond: if: contains(github.event.comment.body, '@claude-code') runs-on: ubuntu-latest permissions: contents: write issues: write pull-requests: write steps: - uses: actions/checkout@v4 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | A user mentioned you in a comment: "${{ github.event.comment.body }}" Respond helpfully. If they asked to fix something, open a PR.

Security in GitHub Actions

Critical safeguards

⚠️ Use permissions: block — grant minimum needed, never default
⚠️ Fork PRs run with different permissions — Claude cannot commit to forks automatically
⚠️ Secret masking — never echo secrets; Claude never outputs them
⚠️ Cost caps — set max_turns to avoid runaway costs
⚠️ Branch protection — require human review on Claude-authored PRs
⚠️ Review the action version — pin to @v1 or a SHA, never @main

Quick Reference

Cheat Sheet

🛠 Install Commands

npm i -g @anthropic-ai/claude-codeInstall CLI globally
claude loginOAuth login (Pro/Max/Team)
claude --versionVerify install
claudeLaunch in current dir
claude --project /pathLaunch for specific project
claude --worktree <branch>Launch in isolated worktree
claude --resumeResume previous session
claude -p "prompt"Headless (non-interactive)
npm update -g @anthropic-ai/claude-codeUpdate to latest

⚡ Core Slash Commands

/helpList all commands
/initGenerate CLAUDE.md
/clearClear conversation
/compactCompress context
/resumeResume session
/sessionsManage session history
/modelSwitch model
/effortSet reasoning effort (low/med/high)
/reviewCode review subagent
/security-reviewSecurity-focused review
/agentsManage subagents
/mcpManage MCP servers
/pluginPlugin manager
/doctorHealth check
/costToken usage + $$$
/bugReport bug to Anthropic
/exitExit session

⌨ Keyboard Shortcuts

Shift+Tab × 1Auto-accept mode
Shift+Tab × 2Plan mode
Shift+Tab × 3Back to normal
Ctrl+BSend current subagent to background
Ctrl+RSearch command history
Ctrl+C (once)Cancel current operation
Ctrl+C (twice)Exit Claude Code
Ctrl+DExit (EOF)
EscCancel tool prompt
@filenameReference a file
# topicAdd inline context tag
ultrathinkForce high-effort reasoning (1 turn)

📄 CLAUDE.md Patterns

## StackEnumerate tech stack
## ConventionsNon-obvious project rules
## CommandsDev/test/build/lint commands
## Do NotExplicit blacklist
## Imports@file references to other docs
@docs/api.mdImport another markdown file
## Project LayoutFolder structure overview
## TestingTest conventions and commands

🧠 SKILL.md Frontmatter

name:Slash command name
description:When to auto-invoke
allowed-tools:Pre-authorised tools
disable-model-invocation: trueUser-only invocation
user-invocable: falseHidden from / menu
model: claude-opus-4-7Pin model
context: forkSeparate context window
agent: ExploreRun in agent type

🪝 Hook Triggers

PreToolUseBefore tool call
PostToolUseAfter tool completes
UserPromptSubmitUser hits Enter
StopSession ends
SessionStartNew session begins
NotificationClaude needs attention
PermissionRequestTool permission asked

🔌 MCP Setup

claude mcp add <name> -- <cmd>Add server
claude mcp listList configured servers
claude mcp test <name>Test connection
claude mcp remove <name>Remove server
@upstash/context7-mcpLibrary docs
@modelcontextprotocol/server-playwrightBrowser automation
@modelcontextprotocol/server-githubGitHub API
@anthropic/scheduled-tasks-mcpCron agent scheduling

🤖 Subagents

ExploreFast codebase navigation
PlanDesign implementation strategies
general-purposeCatch-all
.claude/agents/*.mdCustom subagents
Task toolOrchestrator dispatches
Parallel dispatchMultiple Task() in one msg
context: forkIsolated context window

⛔ Rejected / Never Do This

API keys in CLAUDE.md❌ CLAUDE.md is committed — use env vars
--dangerously-skip-permissions❌ In untrusted repos — instant RCE risk
Commit .claude/ with secrets❌ Add .claude/local/ to .gitignore
CLAUDE.md over 500 lines❌ Bloats every session; use @imports
Skipping plan mode on complex tasks❌ Leads to wasted tokens, bad code
Subagents spawning subagents❌ Runaway cost; add anti-recursion guard
claude -p on prod DB❌ Use read-only creds + --dry-run
"hooks" field in plugin.json❌ Duplicate-hook error — auto-loaded now
MCP from unknown source❌ Audit first; 25+ known CVEs exist
Installing all plugins at once❌ Context bloat; install as needed
Auto-approving git push❌ Always require human confirmation
Hardcoding prod URLs in skills❌ Use env vars; skills are committed
Disabling security-reviewer hook❌ Core safety layer — keep enabled
Running unknown .sh hooks❌ Read every hook script before install
Sharing sessions with secrets❌ /sessions export may leak creds

🚦 Troubleshooting

Problem	Fix
claude: command not found	Add npm global bin to PATH: `export PATH="$(npm config get prefix)/bin:$PATH"`
CLAUDE.md not being read	Check file is at repo root OR `.claude/CLAUDE.md`. Run `/doctor` to verify.
Skill not auto-invoking	Description too vague. Be specific: "Use when user says X" with exact trigger phrases.
Hook not firing	Check `hooks.json` syntax, make script executable (`chmod +x`), check matcher glob.
MCP server timeout	Run `claude mcp test <name>`. Check network/env vars. Some servers need API keys.
Costs too high	Run `/compact` mid-session. Use `/effort low` for simple tasks. Prefer Sonnet over Opus for code gen.
Subagent context lost	You must send all context in the prompt — subagent doesn't see main conversation.
Plugin not found after install	Restart Claude Code. Plugins load at session start, not mid-session.
Plan mode not activating	Shift+Tab cycles modes; terminal may eat the signal — use explicit "do not write code, just plan."
Worktree remains after session	Only cleans if no changes. Run `git worktree remove <path>` manually.
Permissions prompts every time	Add patterns to settings.json `allow` list, or use skill's `allowed-tools` frontmatter.
GitHub Action runs but does nothing	Check `permissions:` block — needs `contents: write` + `pull-requests: write`.

Power User

Hidden Commands & Power Tips

Things Most Users Don't Know

Deep features that don't appear in the /help menu. Discovered through source code, Anthropic blog posts, and community experimentation.

Hidden #01 — The ultrathink Keyword

Force high-effort reasoning for a single turn HIDDEN

Type the word ultrathink anywhere in your prompt. Claude will use maximum reasoning effort for that turn only, then revert to your default.

ultrathink — debug this tricky race condition in the payment handler

When to Use

Tricky algorithms, race conditions, obscure bugs, architectural decisions. Costs more per turn but often saves overall by getting it right the first time.

Hidden #02 — @file and # Reference Syntax

Inline file references in prompts

# @ references a file - Claude reads it fully Review @src/auth/login.ts for security issues # # is a context tag — Claude prioritises related knowledge Add rate limiting #security #performance # Combine them Refactor @src/payments/stripe.ts for better error handling #testing

Hidden #03 — /effort high Before Complex Tasks

Pin effort level for the whole session

/effort high # maximum reasoning, higher cost /effort medium # default /effort low # fast, cheaper, less reasoning # Tip: for Max/Team plans, default changed from high → medium in 2026 # Explicitly request /effort high when tackling gnarly problems

Hidden #04 — Ctrl+B Background Mode

Send a running task to the background

# While Claude is running a long task: Ctrl+B # Effect: # - Task continues running in a subagent # - You get the prompt back immediately # - Task output arrives as a notification when done # - Keep working on other things in the meantime

Great For

Long test runs, migrations, big refactors. Kick it off, work on something else, get notified when done.

Hidden #05 — Bundled Built-in Skills

Skills you already have but may not know about

/simplify

3-agent quality review pipeline — runs before PR submission

/batch

Parallel execution across multiple worktrees with auto-PR creation

/debug

Systematic 4-phase debugging — root cause → pattern → hypothesis → fix

/loop

Autonomous retry loop — keeps trying until success criteria met

/claude-api

Writing code against the Anthropic API with latest docs context

Hidden #06 — --dangerously-skip-permissions

The YOLO flag DANGEROUS

# Bypass ALL permission prompts for the session claude --dangerously-skip-permissions

Use ONLY If

1. You're in a trusted container/sandbox · 2. No production credentials are accessible · 3. You've reviewed the prompt/task carefully · 4. You understand Claude can now delete everything.

Never use on your main dev machine or in repos with secrets.

Hidden #07 — /compact with Decisions Preserved

Smart context compression

When you run /compact, you can tell Claude what to preserve:

/compact preserve decisions, file paths, and open questions /compact keep plan file contents /compact summarize but keep any failing test output

Hidden #08 — /clear Doesn't Touch Plan Files

Safe to clear mid-project

/clear wipes the conversation but preserves:

CLAUDE.md and AGENTS.md
Skill definitions
Plan files in docs/plans/ or .claude/plans/
Session checkpoints

This lets you "start fresh" without losing the work-in-progress plan. Resume with: Let's continue the plan in docs/plans/feature-auth.md

Hidden #09 — Output Styles

Customise how Claude formats responses

# Built-in output styles /output-style concise # minimal, short answers /output-style verbose # detailed explanations /output-style code-only # skip prose, return code /output-style json # structured JSON responses # Custom style — create ~/.claude/output-styles/my-style.md

Hidden #10 — Custom Status Line

Make the bottom bar useful

# ~/.claude/statusline.sh #!/bin/bash branch=$(git branch --show-current 2>/dev/null) cost=$(echo "$1" | jq -r '.cost_usd // 0') tokens=$(echo "$1" | jq -r '.tokens_used // 0') echo "[$branch] tokens=$tokens cost=\$$cost" # Register it: /statusline ~/.claude/statusline.sh

Hidden #11 — /vim Mode

Vim bindings in the input field

/vim # toggle — Esc to switch to normal mode, etc. # In normal mode: # hjkl move, w/b word jumps, dd delete line, yy yank, p paste # Escape twice to exit vim mode permanently for that session

Hidden #12 — /config Opens in $EDITOR

Edit settings without leaving Claude Code

/config # Opens ~/.claude/settings.json in your $EDITOR # When you save + close, Claude Code reloads it live # Sister command: /keybindings # edits ~/.claude/keybindings.json

Hidden #13 — Session History & Aliases

Name and reuse sessions

# Save current session with an alias /sessions save feature-auth-refactor # Resume by name later claude --resume feature-auth-refactor # List all named sessions /sessions list # Delete old sessions /sessions clean --older-than 30d

Hidden #14 — Commands Claude SHOULD Add

Feature wishlist

🔍 /explain-last — have Claude explain its own last action in detail
📊 /cost-breakdown — token cost per tool / per subagent
🎯 /replay — re-run the last session on a fresh branch
🏷️ /tag — tag a moment in the session for later retrieval
📝 /snapshot — save full session state + files as ZIP
🔀 /branch — fork the session at this point, explore alternate path
📨 Submit as issues to github.com/anthropics/claude-code

The Playbook

30+ Battle-Tested Prompts

Copy-pasteable prompts organized by task type. Each includes when to use it, expected output, and a follow-up chain. The single biggest leverage in Claude Code is prompt quality — these have been field-tested in production work.

🐛 BUG FIXING PROMPTS (8)

Prompt 1 · Reproduce First

Force reproduction before touching any code

Before fixing anything, reproduce this bug. Show me: 1. The exact command that triggers it 2. The observed output (actual) 3. The expected output 4. Relevant log lines 5. The minimal input that causes it Do NOT propose a fix yet. Only reproduce and report.

Use WhenUser reports a bug. Any ambiguity in the symptom.

Next Prompt"Now form 2-3 hypotheses about the root cause, ranked by likelihood."

Prompt 2 · Root Cause Hunt

Systematic root cause analysis

We've reproduced the bug. Now find the root cause: 1. Trace the code path from the entry point to the failure 2. Identify every function involved 3. For each function, state what it expects vs what it gets 4. Point to the EXACT line where wrong behaviour starts 5. Explain WHY it's wrong at that line Don't fix it yet. Just pinpoint the cause with evidence.

Use WhenAfter reproducing, before fixing.

Next Prompt"Propose a minimal fix. List 2 alternatives with tradeoffs."

Prompt 3 · Hypothesis Testing

When root cause isn't obvious

I have 3 hypotheses about why this fails: H1: [your hypothesis 1] H2: [your hypothesis 2] H3: [your hypothesis 3] Design a minimal test for each that will definitively confirm or rule it out. Run each test. Report which hypothesis is correct with evidence. Do not write fix code until exactly one hypothesis is confirmed.

Use WhenIntermittent bugs, race conditions, unclear causes.

Next Prompt"Given H2 is confirmed, design the smallest possible fix."

Prompt 4 · Minimal Incremental Fix

Force minimal changes

Fix this bug with the SMALLEST possible change. Rules: - Change no more than 10 lines of production code - Do not refactor anything adjacent - Do not "improve" other code while you're there - One concept = one commit If the fix requires >10 lines, stop and explain why before proceeding. Add a regression test that would have caught this bug.

Use WhenYou need a fast fix without scope creep.

Next Prompt"Run the regression test + full test suite. Show output."

Prompt 5 · Regression-Proof Fix

Fix + test + prove not broken elsewhere

Fix this bug. For each file you touch: 1. Add at least one test that fails before your fix, passes after 2. Run the full test suite — show me if ANYTHING else regressed 3. If anything regressed, roll back your fix and try a different approach 4. Only mark done when the specific bug is fixed AND nothing else breaks Final output: diff of the fix + test outputs before/after.

Use WhenFixing production bugs, customer-facing issues.

Next Prompt"Now look for similar patterns elsewhere — scan for sibling bugs."

Prompt 6 · Flakey Test Debugging

For non-deterministic failures

This test fails intermittently. Investigate: - Run it 20 times in a loop. Record pass/fail ratio. - Look for: timing dependencies, shared state, non-deterministic ordering, test isolation issues, external dependencies. - Identify the source of flakiness with evidence. - Propose a fix that removes the non-determinism (not just retries). If you can't reproduce flakiness in 20 runs, report that + likely triggers.

Use WhenCI is flaky, tests pass locally but fail in CI.

Next Prompt"Apply the fix. Run the loop again to prove it's stable."

Prompt 7 · Production Hotfix (Surgical)

Under pressure, maximum safety

🚨 PRODUCTION HOTFIX mode. Rules: - This goes to prod in minutes. Do not refactor. - One-line fix preferred. Max 5 lines. - Do not touch any other file. - Add one test that asserts the fix. - Explain in one sentence what you changed and why it's safe. Bug: [describe bug] Error: [paste error] Affected file: [path]

Use WhenProduction is down. Time is critical.

Next Prompt"Open hotfix PR with the diff. Follow up with full fix next sprint."

Prompt 8 · Sibling Bug Scan

Find similar bugs after fixing one

I just fixed this bug: [paste diff]. Now scan the codebase for similar patterns that might have the same bug. Look for: - Same function called with same wrong args elsewhere - Same copy-paste logic without the fix applied - Related code paths that might share the vulnerability Report each finding with file:line + why you suspect it + suggested test.

Use WhenCommon bug patterns (off-by-one, null handling, etc.)

Next Prompt"For finding #1, apply the same fix pattern + test."

📋 PLANNING PROMPTS (8)

Prompt 9 · Feature Planning (Brainstorm)

Turn vague ideas into specs

I want to build: [rough idea in 1-2 sentences] Before any code, ask me clarifying questions ONE AT A TIME: - What users benefit from this? - What's the key metric of success? - What's the smallest version that would prove value? - What happens if it fails silently? - What does the happy path look like end to end? - What constraints exist (budget, timeline, tech)? After I answer, write a 1-page spec I can sign off on. Do not write code yet.

Use WhenStarting any new feature. Ambiguous requirements.

Next Prompt"Approved. Now write the implementation plan as file-by-file tasks."

Prompt 10 · Implementation Plan

Convert spec to actionable tasks

Given this approved spec [link or paste], produce an implementation plan. Format: ## Files to Create - [path] — [purpose, ~line count] ## Files to Modify - [path] — [what changes] ## Tasks (each 5-15 minutes) 1. [task] — acceptance criteria: [test] 2. ... ## Risks - [risk] — mitigation: [plan] ## Success Criteria - [measurable outcome] DO NOT WRITE CODE. Just the plan.

Use WhenAfter spec approval, before coding.

Next Prompt"Approved. Execute task 1. Show test output before moving on."

Prompt 11 · Migration Planning

Safe migration of large systems

Plan the migration from [old system] to [new system]. Include: 1. Pre-migration audit — what uses the old system? (exact file:line list) 2. Compatibility layer — can both coexist during migration? 3. Feature flags — how to toggle per-user? 4. Data migration — script + verification + rollback 5. Cut-over plan — how and when to flip 6. Rollback plan — exact steps if we need to revert 7. Monitoring — what to watch for 24/48 hours 8. Success criteria — when is migration "done"? Phase it: prep → dual-write → flip reads → flip writes → remove old.

Use WhenDB migrations, library upgrades, infra changes.

Next Prompt"Begin phase 1 (prep). Show gates before moving to phase 2."

Prompt 12 · Refactor Planning

Strategic refactor without breaking everything

The code at [path] is messy. Plan a safe refactor. Deliverables: 1. **Current state** — describe what it does + smell list with examples 2. **Target state** — post-refactor structure (files, modules, interfaces) 3. **Step plan** — each step makes code BETTER and TESTS STILL PASS 4. **Test safety net** — what tests cover this? Gaps? 5. **Escape hatches** — how to bail mid-refactor if it goes wrong Constraint: No big-bang rewrites. Refactor must be merge-able in small PRs.

Use WhenLegacy code, tech debt sprints.

Next Prompt"First add the missing tests from 'Test safety net'. Run them."

Prompt 13 · Architecture Design

High-level design for a new system

Design the architecture for [system]. Constraints: - Scale: [users/QPS/data size] - Budget: [$/month target] - Team: [size/expertise] - Tech preferences: [e.g. Python + Postgres, or empty for your recommendation] Deliver: 1. C4 Level 1 (context) + Level 2 (containers) diagrams in Mermaid 2. Key decisions with rationale (DB choice, sync vs async, monolith vs services) 3. Three alternatives considered + why rejected 4. Scaling plan (2x, 10x, 100x load) 5. Failure modes + mitigations 6. Observability strategy This is a design doc, not code.

Use WhenGreenfield projects, major rewrites.

Next Prompt"Now zoom into the [component] — detail its internal design."

Prompt 14 · API Design

Design a REST/GraphQL/tRPC API

Design the [public API] for [feature]. For each endpoint: - Method + path + description - Request schema (Zod / Pydantic / types) - Response schema (success + error shapes) - Error codes + when each fires - Auth requirement (public / user / admin) - Rate limits - Caching behavior - Example curl Also list: - Versioning strategy - Breaking change policy - Deprecation process - Test plan (unit, contract, integration) DO NOT implement. Design doc only.

Use WhenNew APIs, platform expansion.

Next Prompt"Approved. Implement endpoint 1 with full tests."

Prompt 15 · Database Schema Planning

Relational schema design

Design the DB schema for [domain]. Deliverables: 1. ERD in Mermaid 2. Table definitions (SQL or Prisma/SQLModel) 3. Indexes: which columns? why? expected query patterns? 4. Constraints: PKs, FKs, uniques, checks 5. Partitioning strategy if tables get large 6. Migration strategy (can we add these tables online?) 7. Seed data + fixtures for tests 8. Common query patterns with EXPLAIN ANALYZE expectations Flag any fields likely to become performance issues at 10x scale.

Use WhenNew features requiring new tables.

Next Prompt"Write the first migration. Apply it in dev + show schema diff."

Prompt 16 · Test Plan Before Code

TDD planning

For this feature spec, write ONLY the test cases (not impl) first. Format each test as: - Name: should_DoX_When_Y - Arrange: [setup] - Act: [action] - Assert: [expected] Coverage: - Happy path (1-2) - Edge cases (list ALL you can think of: empty input, max input, null, boundary values, concurrent, etc.) - Error paths (each error class) - Security tests (injection, auth bypass, etc.) Aim for 15-25 test cases. Output them as actual test file code, with TODO comments for the impl we'll write next.

Use WhenTDD workflow, critical features.

Next Prompt"Now implement minimally to pass test 1. Red → Green → Refactor."

🔍 PROBLEM IDENTIFICATION (8)

Prompt 17 · Code Smell Audit

Find anti-patterns and smells

Scan @[path or module] for code smells. Report each with file:line + category. Check for: - God functions (>50 lines) - Deeply nested logic (>3 levels) - Duplicate code (same logic in 2+ places) - Magic numbers (hardcoded values without names) - Poorly named identifiers (x, tmp, data) - Mixed abstraction levels in one function - Comments that explain WHAT instead of WHY - Dead code (unused imports, vars, functions) - Primitive obsession (passing 5 strings vs a value object) - Shotgun surgery signals (one change requires edits in many places) For each: severity (high/med/low) + suggested refactor in ONE sentence.

Use WhenPre-merge, tech debt sprints, code review.

Next Prompt"Fix the 3 highest-severity smells. Preserve all tests."

Prompt 18 · Security Audit

OWASP-aligned security scan

Audit @[path] for security issues. Find and report: 1. **Injection** — SQL, NoSQL, command, LDAP, template 2. **Broken auth** — weak crypto, exposed tokens, session issues 3. **Sensitive data** — logs with PII, secrets in code, weak encryption 4. **XXE / SSRF** — external input to XML parsers, URL fetches 5. **Broken access** — IDOR, privilege escalation, missing auth checks 6. **Misconfigurations** — default creds, verbose errors, CORS * 7. **Known-vulnerable deps** — outdated packages with CVEs 8. **Unsafe deserialization** — pickle, YAML load, Java ObjectInputStream 9. **Logging gaps** — security events not logged 10. **Rate limiting** — endpoints without it Format: CVE-style severity, file:line, proof of concept, mitigation.

Use WhenPre-launch, security reviews, incident response.

Next Prompt"Fix issues 1-3 (critical). Add regression tests."

Prompt 19 · Performance Bottlenecks

Find slow code with evidence

Find performance bottlenecks in @[path]. Investigate: - N+1 queries (ORM loops, missing .include/.eager) - Unnecessary fetching (SELECT *, missing pagination) - Sync blocking calls in async code - Unbatched API calls (loop making individual requests) - Missing caches (repeated identical computations) - O(n²) or worse algorithms - Memory allocations in hot paths (string concat in loops) - Large payloads (missing compression, over-fetching) - Blocking the event loop (Node/browser) For each finding: file:line, estimated impact (ms/QPS/memory), fix approach, test to verify improvement.

Use WhenSlow app, high cloud bills, SLO misses.

Next Prompt"Fix the top-3. Benchmark before/after with real data."

Prompt 20 · Dead Code Hunt

Find unused code to delete

Find dead code in @[path]. Categories: - Unused exports (nothing imports them) - Unused function params - Unused imports - Unreachable code (after return/throw) - Dead conditional branches (unreachable if/else) - Feature flags never toggled - Commented-out code blocks - Files never referenced - DB columns never read/written For each: file:line, confidence (99% vs 60%), how you verified it's dead. Do NOT delete. Only report. I'll decide what to remove.

Use WhenTech debt, reducing bundle size, pre-refactor.

Next Prompt"Delete items with 99% confidence. Open PR per category."

Prompt 21 · Dependency Audit

Check deps for problems

Audit package.json / requirements.txt / *.csproj / Gemfile for: 1. **Known CVEs** — run npm audit / pip-audit / dotnet list package --vulnerable 2. **Outdated majors** — packages >1 major behind 3. **Unused deps** — installed but never imported 4. **Heavy deps** — bundle size >100KB, check alternatives 5. **Deprecated packages** — flagged by registry 6. **Duplicate deps** — multiple versions of same package 7. **License issues** — GPL/AGPL in proprietary code 8. **Maintenance signals** — last publish >2 years, few maintainers Output: table with package, issue category, severity, recommended action.

Use WhenQuarterly audits, pre-release, supply chain reviews.

Next Prompt"Plan upgrade PRs — one per major version bump, grouped safely."

Prompt 22 · Test Quality Audit

Find bad tests

Audit the test suite in @tests/ for: - **Tests that always pass** — no real assertion, or asserting constant - **Flaky tests** — tests with retries, sleeps, network calls without mocks - **Duplicate tests** — same coverage, different name - **Tests that test the mock** — asserting `mock.called` without checking args - **Over-mocked tests** — so mocked they don't test real code - **Tests with unclear names** — can't tell what's being tested - **Giant setUp blocks** — >30 lines of arrange - **Asserting implementation** — test breaks on refactor even though behavior unchanged - **Missing edge cases** — no test for null, empty, max, error Report each with file + reason + fix suggestion.

Use WhenBefore scaling team, sprints with flaky CI.

Next Prompt"Rewrite tests flagged as 'testing implementation' to assert behavior instead."

Prompt 23 · Accessibility Audit (a11y)

WCAG-aligned UI audit

Audit @components/ for accessibility issues aligned with WCAG 2.2 AA. Check: - **Semantic HTML** — divs where button/nav/main/article should be - **Alt text** — images without alt, decorative marked as alt="" - **ARIA** — redundant, wrong role, missing labels - **Keyboard nav** — focus traps, skip links, tab order - **Color contrast** — text below 4.5:1 (3:1 for large) - **Focus indicators** — removed with outline:none and no replacement - **Forms** — labels missing, errors not associated with field - **Motion** — no prefers-reduced-motion respect - **Screen reader** — announcements missing for async updates - **Touch targets** — under 44×44px on mobile Each finding: component:line, WCAG rule, fix.

Use WhenPre-launch, compliance audits, enterprise sales.

Next Prompt"Fix the 5 critical items. Add Playwright a11y tests (axe-core)."

Prompt 24 · Error Handling Audit

Find gaps in error handling

Audit @[path] for error handling problems: - **Swallowed errors** — catch blocks that do nothing - **Catch all exceptions** — `catch (e)` / `except:` too broad - **Logged but not handled** — console.error but no user feedback - **Missing error paths** — happy path only, no else/error branch - **Inconsistent error shapes** — some endpoints return 500 with text, others JSON - **No retry for transient failures** — network, DB connection blips - **Wrong HTTP codes** — 500 for user errors, 200 for failures - **Leaked internals** — stack traces in production responses - **Missing timeouts** — network calls with no timeout - **Unbounded queues** — no backpressure/circuit breakers Each: file:line, category, severity, fix approach.

Use WhenStability sprints, production incidents.

Next Prompt"Propose a consistent error envelope. Refactor top-5 offenders to use it."

🔨 REFACTORING PROMPTS (8)

Prompt 25 · Simplify Without Breaking

Safe simplification

Simplify @[file or function] without changing behaviour. Safety rules: 1. Run tests BEFORE — record pass/fail baseline 2. Make ONE simplification at a time 3. Run tests AFTER each change — must match baseline 4. Commit each passing simplification separately 5. If any test fails, revert that change and try a different approach Target: reduce cognitive complexity, NOT just line count. Prefer: early returns, extract method, replace nested ifs with guard clauses, remove dead branches. Avoid: introducing new abstractions, changing public API, reordering statements that have side effects.

Use WhenBefore adding features to messy code.

Next Prompt"Now that it's simpler, add the new feature cleanly."

Prompt 26 · Extract Module

Pull out a cohesive unit

Extract a new module from @[file] that groups related functionality. Process: 1. Identify functions/types that form a cohesive unit (analyze call graph) 2. Propose the new module's name + exports 3. Show me the proposed boundary — list what moves and what stays 4. Wait for approval 5. Move them with explicit imports 6. Update all call sites 7. Add a barrel file if needed 8. Run the tests — MUST all pass Criteria: new module should have high internal cohesion, low coupling back to origin.

Use WhenLarge files, growing modules.

Next Prompt"Add unit tests for the new module in isolation."

Prompt 27 · Decouple Tight Coupling

Break hard dependencies

The code in @[file] is tightly coupled to @[other]. Decouple it. Use these techniques as applicable: - Dependency injection (pass via constructor/args, don't import directly) - Repository/interface pattern (abstract data access) - Event emitter (publish events, don't call consumers directly) - Adapter pattern (wrap the dependency) - Pure functions (remove hidden state) Output: 1. Current coupling map (what depends on what) 2. Proposed boundary 3. Incremental refactor plan (small commits) 4. Migration path for call sites 5. Test strategy (mock the new interface) DO NOT change behaviour. Only structure.

Use WhenTesting is hard, changes ripple everywhere.

Next Prompt"Execute step 1 (introduce interface). Run tests. Commit."

Prompt 28 · Test-First Refactor

Pin behavior with tests before refactoring

Before refactoring @[file], write characterization tests that PIN its current behaviour (including any bugs). Steps: 1. Identify the PUBLIC interface of this module (what outsiders call) 2. For each public function: write tests for happy path + edge cases, asserting actual current output 3. Include "weird but works" behaviors — any quirks callers might rely on 4. Run — all must pass before we touch anything 5. Commit tests as "characterize: <module> current behaviour" After this, we can refactor aggressively knowing the safety net catches regressions.

Use WhenLegacy code with no tests, before any refactor.

Next Prompt"Characterization tests pass. Now refactor — tests must stay green."

Prompt 29 · Remove Duplication (DRY)

Careful deduplication

Find and remove duplicated code in @[path]. Safety first. Process: 1. List all duplicates with file:line pairs + similarity % 2. For each: is it REALLY the same, or coincidentally similar? - Different meanings that look alike SHOULD stay duplicated - "Three strikes" rule: only dedupe after 3rd occurrence 3. For true duplicates: propose shared location (utility, base class, hook, mixin) 4. Show the extracted version + all call sites updated 5. Run tests — all pass 6. One commit per dedup (easy to revert if wrong) Avoid: premature abstraction, making code LESS readable to save LOC.

Use WhenCleaning up copy-paste code.

Next Prompt"Scan the new shared module — does it need tests? Add them."

Prompt 30 · Modernize Legacy Code

Bring old code to current standards

Modernize @[file] to match current project conventions (see CLAUDE.md). Apply incrementally — one concept per commit: 1. Typing: add types to untyped code (infer from usage) 2. Async: callbacks → promises → async/await 3. Deprecated APIs: replace with modern equivalents 4. ES features: var → const/let, IIFE → modules, require → import 5. Error handling: align with project's Result/exception strategy 6. Naming: align with style guide 7. Formatting: run formatter Rules: - Tests must pass after every commit - Keep public API stable (or deprecate + migrate in separate PR) - Don't add new features; only modernize

Use WhenLegacy modules, onboarding old projects.

Next Prompt"Next commit: typing. Show me the plan before executing."

Prompt 31 · Replace Primitives with Types

Fix primitive obsession

Fix primitive obsession in @[path]. Find cases where primitives carry meaning: - `string userId` (just any string?) → `type UserId = string & { _brand: 'UserId' }` - `number price` (in cents? USD?) → `type Money = { cents: number; currency: 'USD' }` - 3+ primitives passed together → value object/record - `boolean shouldRetry` + `number retryCount` → `type RetryConfig = ...` For each: 1. Propose the new type + validation 2. Show migration plan (gradual, not big-bang) 3. Update high-traffic call sites first 4. Keep interop functions for still-primitive callers 5. Tests prove nothing changed behaviorally

Use WhenBugs from wrong-type passing, fragile contracts.

Next Prompt"Migrate the `UserId` first. All call sites. Tests green."

Prompt 32 · Convert to Immutable

Remove mutation

Refactor @[file] to avoid mutation. Current issues: - Data structures being mutated in place - Functions with side effects on inputs - Shared mutable state Change to: - Return new objects with spread/copy - Use `readonly` / `Final` / `const` / `record` / `frozen` - Extract pure functions; move side effects to edges - Use immutable collections where the language supports them Safety: - Keep same public behaviour - Benchmark before/after — perf shouldn't regress meaningfully - Tests must pass - Commit per function converted

Use WhenState management bugs, concurrency issues.

Next Prompt"Now that it's immutable, enable parallel processing for X."

⛔ ANTI-PATTERNS (What NOT to Prompt)

Anti-pattern 1 · The Vague Request

Bad prompt — Claude fills gaps with assumptions

❌ BAD: "Make the auth better" ❌ BAD: "Fix the database" ❌ BAD: "Refactor this" ❌ BAD: "Add some tests" ✅ GOOD: "Replace session-based auth with JWT in @src/auth/. Preserve the /login and /logout endpoints' behavior. Add tests. Do not touch user model."

Why It FailsClaude invents requirements. Wastes tokens exploring wrong paths. Output doesn't match intent.

The FixAlways include: WHAT + WHERE + CONSTRAINTS + ACCEPTANCE.

Anti-pattern 2 · Jump to Code

Skipping the plan

❌ BAD: "Build a multi-tenant SaaS with billing and webhook delivery" → Claude writes code for 30 mins, gets it wrong, wastes $10 ✅ GOOD: "Plan (don't code) a multi-tenant SaaS design. Ask clarifying questions first. Produce a 1-page spec I approve before any code."

Why It FailsComplex tasks without a plan = guaranteed wasted effort.

The FixAlways start with "Plan. Do not write code."

Anti-pattern 3 · No Acceptance Criteria

Claude doesn't know when it's done

❌ BAD: "Make the search faster" → Claude makes something faster but is it enough? You don't know. ✅ GOOD: "Make the search return in <200ms at p95 for queries over 1M rows. Measure with benchmark.ts. Show before/after numbers."

Why It FailsWithout criteria, Claude optimises for "something" not "the right thing".

The FixState measurable outcomes. Numbers, tests, or specific behaviors.

Anti-pattern 4 · Missing Context

Assumes Claude remembers

❌ BAD: "Finish what we started yesterday" → Claude has no memory of yesterday. ✅ GOOD: "Resume work on @docs/plans/auth-refactor.md. We finished steps 1-3 (commits: abc, def, ghi). Continue with step 4: 'Add password reset flow.' Constraints in the plan file still apply."

Why It FailsNo cross-session memory. Context from yesterday is gone.

The FixReference plan files, previous commits, use @file imports.

Anti-pattern 5 · No Verification Loop

Trusting Claude claimed success

❌ BAD: "Add the feature" → Claude: "Done!" → Reality: tests fail. ✅ GOOD: "Add the feature. Then: run all tests. Report which passed/failed. If any failed, fix them and re-run. Only say 'done' when output is green."

Why It FailsClaude may claim "done" without running tests.

The FixAlways force "verify with command X. Show output."

Anti-pattern 6 · Asking for Too Many Things

Monster prompt with 10 goals

❌ BAD: "Refactor auth, add tests, update docs, migrate DB, add rate limiting, improve errors, fix that weird bug" → Claude does 2 things poorly, forgets the rest. ✅ GOOD (split it): Phase 1: "Refactor auth. That's it." Phase 2: "Now add tests for the refactor." Phase 3: "Now update docs to match."

Why It FailsContext dilution. Claude can't focus on everything.

The FixOne concern per prompt. Chain them.

Battle-Tested

Chained Workflows

Real tasks rarely fit in one prompt. These are proven multi-prompt chains for common scenarios. Copy the whole chain; run each step; use the output of one as input to the next.

🐛 Workflow A — Full Bug Fix (6 prompts)

Reproduce

→

Root Cause

→

Hypothesis

→

Fix

→

Verify

→

Sibling Scan

The gold standard for production bugs. Never skip a step — each one catches issues the others miss.

# Step 1 — Reproduce Before fixing anything, reproduce this bug. Show me: exact command, actual output, expected output, relevant logs, minimal input that triggers it. Do NOT propose a fix yet. # Step 2 — Root Cause We've reproduced. Now find the root cause: trace the code path, identify every function involved, state what each expects vs gets, point to the EXACT line where behaviour goes wrong, explain WHY. Don't fix yet. # Step 3 — Hypothesis Testing (if unclear) I have 3 hypotheses: [list]. Design a minimal test for each to confirm/rule out. Run them. Report winner with evidence. # Step 4 — Minimal Fix Apply the SMALLEST possible fix. Max 10 lines. No refactoring adjacent code. Add a regression test that would have caught this. # Step 5 — Verify Run the regression test + full test suite. Show output. If anything regressed, roll back and try a different approach. # Step 6 — Sibling Bug Scan Scan the codebase for similar patterns that might have the same bug. Report each with file:line + why you suspect it + suggested test.

✨ Workflow B — New Feature End-to-End (8 prompts)

Brainstorm

→

Spec

→

Plan

→

Tests

→

Impl

→

Review

→

Docs

→

# Step 1 — Brainstorm (ask clarifying Qs) I want to build [feature]. Ask clarifying questions ONE at a time: user benefit, success metric, MVP scope, failure modes, happy path, constraints. Then write a 1-page spec for approval. # Step 2 — Spec Approval Approved. Save spec to docs/specs/[feature].md. # Step 3 — Implementation Plan Convert spec to plan: Files to Create/Modify, Tasks (5-15min each w/ acceptance tests), Risks+mitigations, Success Criteria. DO NOT WRITE CODE. # Step 4 — Test Plan First (TDD) Write ONLY the test cases (not impl). Cover: happy path, edge cases, error paths, security. 15-25 tests as actual code with TODO comments for impl. # Step 5 — Implement Task-by-Task Execute task 1. Make test 1 pass. Show output. Commit. STOP. Wait for my go-ahead for task 2. # Step 6 — Review Dispatch code-review subagent on all changes. Report findings. Fix any critical issues. # Step 7 — Documentation Update README.md + relevant docs to reflect the new feature. Add example usage. Update CHANGELOG. # Step 8 — Open PR Open PR. Title: feat(scope): summary. Body: what changed, why, screenshots if UI, testing done, migration notes if any. Request review from [team].

🔨 Workflow C — Legacy Code Refactor (7 prompts)

Map

→

Characterize

→

Plan

→

Decouple

→

Simplify

→

Modernize

→

Measure

# Step 1 — Map the Legacy Code Analyze @[legacy module]. Produce: public API list, dependency graph (imports/imported-by), complexity hotspots (cyclomatic > 10), test coverage %. No changes. # Step 2 — Characterize Current Behavior Before any refactor, write characterization tests pinning current behavior including quirks. Aim for every public function. These must pass — they're our safety net. # Step 3 — Refactor Plan Plan safe refactor: current state, target state, step-by-step, test safety net, escape hatches. Mergeable in small PRs. No big-bang rewrites. # Step 4 — Decouple Break the tight coupling to @[other]. Use DI/interfaces/events. Characterization tests must still pass after. # Step 5 — Simplify Simplify without behavior change. Early returns, extract method, remove dead branches. Tests green. One commit per simplification. # Step 6 — Modernize Align with current CLAUDE.md: typing, async patterns, naming, deprecated APIs. Incremental. Tests green. # Step 7 — Measure Improvement Compare before/after: complexity, test coverage, LOC, runtime perf on benchmark. Write a report.

🔒 Workflow D — Security Audit & Hardening (6 prompts)

Scan

→

Triage

→

Fix Critical

→

Deps

→

Tests

→

Runbook

# Step 1 — Scan Dispatch security-reviewer subagent. OWASP Top 10 scan across @src/. Report by severity with file:line + PoC + mitigation. # Step 2 — Triage Group findings: must-fix-now (exploitable in prod), fix-this-sprint, fix-this-quarter, won't-fix-with-justification. Assign priority. # Step 3 — Fix Critical Fix must-fix-now items. Each fix: add regression test, verify test fails before fix, passes after. No scope creep. # Step 4 — Dependencies Run npm audit / pip-audit / dotnet list --vulnerable. Triage results. Propose upgrade PRs per major version bump. # Step 5 — Add Security Tests For each vuln class found, add automated tests: SQL injection fuzzer, auth bypass tests, XSS probes. Integrate into CI. # Step 6 — Incident Runbook Write docs/runbooks/security-incident.md: detection steps, containment, investigation, comms template, post-mortem template.

🚀 Workflow E — Deploy Pipeline Setup (5 prompts)

Audit

→

Rollback

→

Observability

# Step 1 — Audit Current State Audit @.github/workflows/ (or equivalent). Map what runs when, what's missing. Report: build gaps, test gaps, deploy gaps, rollback capability. # Step 2 — Set Up CI Design CI pipeline: lint + typecheck + unit tests + integration tests + security scan. Run on PR. Block merge on failure. Cache deps. # Step 3 — Set Up CD Design CD: deploy to staging on main merge, deploy to prod on tag. Include: smoke tests post-deploy, canary rollout, env var validation. # Step 4 — Rollback Plan Design rollback: atomic deploys, previous version tags, one-command revert, DB migration reversibility rules. # Step 5 — Observability Add observability: structured logs, metrics for key SLOs, alert on deploy failure, error budget burn rate. Dashboards.

Blueprint 1

RAG AI App — Chat with Your Docs

Full build blueprint for a RAG (Retrieval-Augmented Generation) chat app. Users upload docs, ask questions, get answers grounded in their content with citations. This is the archetypal AI app.

📦 Tech Stack

FrontendNext.js 15 + TS + Tailwind 4 + shadcn/ui
BackendPython FastAPI 0.115 (async)
Vector DBPostgres 16 + pgvector (or Pinecone)
Embeddingsvoyage-3 (Anthropic) or OpenAI text-embedding-3
LLMClaude Sonnet 4.6 via Anthropic SDK
StreamingServer-Sent Events (SSE)
MobilePWA with offline cache
DeployVercel (FE) + Railway/Fly.io (BE)

🤖 Subagents to Deploy

indexer-agentChunks + embeds uploaded docs
retrieval-agentHybrid search (vector + keyword + rerank)
evaluator-agentMeasures retrieval quality on golden queries
citation-agentValidates all citations map to real chunks

Phase 1 — Setup & CLAUDE.md

Initialize the project

# Start in an empty dir mkdir rag-chat-app && cd rag-chat-app claude # First prompt: Plan a monorepo RAG chat app. Do not write code yet. Stack: Next.js 15 + FastAPI + Postgres/pgvector + Claude Sonnet + SSE streaming. Structure: apps/web (Next), apps/api (FastAPI), packages/shared (types). Ask clarifying questions, then show me the top-level layout.

Phase 1.5 — The CLAUDE.md to Use

After `/init`, replace with this

# .claude/CLAUDE.md # RAG Chat Application ## Mission Production-grade RAG app. Users upload docs, ask questions, get grounded answers with citations. ## Monorepo Structure ``` apps/ ├── web/ Next.js 15 frontend (SSE chat, auth, upload) ├── api/ Python FastAPI — RAG pipeline, embeddings, retrieval packages/ ├── shared/ TS + Python types (via Zod + Pydantic codegen) └── eval/ Golden eval queries + retrieval benchmarks ``` ## Stack - Next.js 15 App Router, React 19, TS strict, Tailwind 4, shadcn/ui - Python 3.12, FastAPI, SQLModel, asyncpg, httpx - Postgres 16 + pgvector, Redis (cache + rate limit) - voyage-3 embeddings, Claude Sonnet 4.6 for generation - Vercel (frontend) + Fly.io (backend) ## Conventions - **All RAG answers MUST cite sources** (chunk_id + page + excerpt). - **Never hallucinate citations.** If no evidence, say "I don't know." - **Hybrid retrieval** — never pure vector. Always vector + BM25 + rerank. - **Streaming responses** — never buffer and dump at end. - **Idempotent ingestion** — re-uploading same doc = no-op via content hash. - **Chunk strategy** — semantic splitter, target 400-800 tokens, 15% overlap. ## Commands - Web dev: `pnpm --filter web dev` - API dev: `uv run fastapi dev apps/api/src/main.py` - Tests: `pnpm test` (web) + `uv run pytest` (api) - Eval: `uv run python packages/eval/run.py` — retrieval quality benchmark - Migrate: `uv run alembic upgrade head` - Docker: `docker compose up -d` (postgres + redis locally) ## Never - Never answer without retrieval — even simple Qs go through the pipeline. - Never embed user queries without first redacting PII. - Never truncate retrieved context silently — if too large, summarize first. - Never return raw vectors to the client. - Never skip eval — every retrieval change must be measured. ## Imports @docs/rag-pipeline.md @docs/retrieval-strategy.md @docs/eval-methodology.md

Phase 2 — Build the API Backend

Prompt sequence

# Prompt 1: Scaffolding Scaffold apps/api — FastAPI project with: - main.py, settings.py (pydantic-settings), routes/, services/, models/, tasks/ - SQLModel for DB, alembic for migrations - pgvector extension migration - Docker compose for Postgres + Redis - .env.example with all needed vars - pytest + httpx setup Do not implement endpoints yet. Just scaffolding + health check. # Prompt 2: Ingestion endpoint Implement POST /v1/ingest. Multipart upload (PDF, TXT, MD). Pipeline: 1. Save file to object storage (minio locally, S3 prod) 2. Compute SHA-256; if exists, return existing doc_id (idempotent) 3. Extract text (pypdf for PDF, plain read for others) 4. Chunk via langchain RecursiveCharacterTextSplitter (400 tokens, 60 overlap) 5. Embed chunks in batches of 100 via voyage-3 6. Insert into docs + chunks tables 7. Return doc_id + chunk count + status Tests: upload PDF, assert chunks exist, assert re-upload is no-op. # Prompt 3: Retrieval endpoint Implement POST /v1/retrieve. Body: {query, doc_ids?, top_k=10}. Hybrid retrieval: 1. Embed query 2. Vector search via pgvector (cosine), top 30 3. BM25 via Postgres tsvector, top 30 4. Merge + dedup 5. Rerank via Cohere rerank-3 (or simple cross-encoder) 6. Return top_k with scores + chunks + source metadata Tests: golden query set returns expected doc_ids in top_5. # Prompt 4: Chat endpoint (streaming) Implement POST /v1/chat. Body: {conversation_id, message, doc_ids?}. SSE stream. Flow: 1. Load conversation history 2. Call /v1/retrieve internally, get top_k chunks 3. Build prompt: system + history + retrieved context + user msg 4. Call Claude Sonnet 4.6 with streaming 5. Parse citations from output [doc:chunk_id] format 6. Stream tokens as SSE events: {type:"token"|"citation"|"done"} 7. Persist assistant message + citations on done Tests: real PDF → real question → streamed tokens → citations valid.

Phase 3 — Build the Frontend

Prompts for Next.js UI

# Prompt 1: Scaffold Scaffold apps/web — Next.js 15 App Router with: - TS strict, Tailwind 4 + shadcn/ui initialized - better-auth for email + OAuth - API route proxy to FastAPI backend - Zod schemas mirroring Pydantic models in apps/api - layout.tsx with header, theme toggle, auth guard Just scaffolding + auth. No RAG UI yet. # Prompt 2: Upload UI Build the upload page: drag-drop dropzone, file list with progress, "Process" button → POST /v1/ingest. Show chunk count on success. Error handling for file too big, wrong type, backend down. Use useOptimistic for snappy UX. Add Playwright test for happy path. # Prompt 3: Chat UI with streaming Build the chat page: conversation list sidebar, message thread, input at bottom. Use SSE client (EventSource or fetch streaming) for /v1/chat. Stream tokens into the latest message bubble as they arrive. Render citation chips inline [1][2] that scroll to source on click. Show loading skeleton. Handle abort via AbortController. Mobile: collapsible sidebar, full-width on <768px. # Prompt 4: Source viewer Build the source viewer drawer: when user clicks a citation, open a drawer showing the source chunk + surrounding context + link to download original PDF at the right page. Highlight the cited text. Escape to close. Accessible (focus trap, ESC).

Phase 4 — Retrieval Quality (Evaluator Agent)

Don't ship without measuring retrieval

# Prompt: Dispatch an evaluator-agent to: 1. Generate 50 golden Q-A pairs from sample docs (using Claude) 2. Build packages/eval/golden.jsonl 3. Write packages/eval/run.py — runs each Q against retrieval, checks if answer's supporting chunks are in top_10 4. Metrics: Recall@10, MRR, nDCG@10 5. Output report table: baseline → after reranker → after BM25+vector hybrid 6. Fail the build if Recall@10 < 0.85 Commit the script + golden set + CI integration.

Phase 5 — Mobile Considerations (PWA)

Make it work on phones

# Prompt: Turn apps/web into a PWA: 1. Add manifest.json (name, icons, theme_color, display: standalone) 2. Service worker for: - Shell caching (fast cold start) - Offline fallback page - Background sync for failed uploads 3. iOS: add apple-touch-icons, viewport-fit=cover for notch 4. Android: trusted web activity setup guide in docs 5. Push notifications for long-running ingestion jobs (Web Push + VAPID) 6. IndexedDB cache for recent conversations Test: Lighthouse PWA score > 95.

Alt: React Native

For native iOS/Android, swap apps/web for apps/mobile using Expo SDK 52+. Reuse the same FastAPI backend, use react-native-sse for streaming, expo-document-picker for uploads.

Phase 6 — CSS & Tailwind Patterns

Design tokens + patterns

# Prompt: Set up Tailwind 4 design tokens for the chat UI: - Semantic tokens: --color-bg, --color-surface, --color-text, --color-accent - Message bubbles: user (accent bg, white text), assistant (surface bg, text) - Citation chips: pill with hover elevation, click-through underline - Code blocks in messages: monospace, syntax highlighting via shiki (SSR) - Streaming cursor: blinking underscore after last token - Dark mode via .dark class on html, all tokens switch Pattern library in apps/web/components/ui/. Document in Storybook.

Blueprint 2

Internal Tool — FastAPI + React Admin

Full blueprint for an internal admin tool. Auth-protected, CRUD over business data, tables + forms + charts + reports. The most common "build me an internal thing" pattern.

📦 Tech Stack

BackendPython FastAPI + SQLModel + asyncpg
FrontendVite + React 19 + TS + shadcn/ui + Tanstack Query + Table
DBPostgres 16, Alembic migrations
AuthJWT (access + refresh), bcrypt, RBAC
DeployDocker Compose → VPS (Hetzner/DigitalOcean)
CI/CDGitHub Actions → docker push → SSH deploy
Testingpytest + httpx + Playwright
ChartsRecharts for React

🎯 Core Features

Login + RBACAdmin, Manager, Viewer roles
User CRUDList + create + edit + deactivate
Business entitiesPaginated tables, server-side sort/filter
Audit logEvery mutation logged with actor + diff
ReportsDashboards with Recharts + CSV export
Bulk opsCSV import, bulk update, queued jobs
API tokensGenerate tokens for 3rd party integrations

Phase 1 — CLAUDE.md

The config for this project

# .claude/CLAUDE.md # Acme Internal Admin Tool ## Mission Internal admin dashboard for Acme's ops team. CRUD + reports + audit trail. Trusted network only — no public exposure. Used by ~20 employees daily. ## Stack - Backend: Python 3.12 + FastAPI 0.115 + SQLModel + asyncpg - Frontend: Vite + React 19 + TS strict + shadcn/ui - State: Tanstack Query (server) + Zustand (UI state) - Tables: Tanstack Table (client render, server sort/filter/page) - Forms: react-hook-form + zod - Auth: JWT access (15min) + refresh (7 day) + httpOnly cookies - Tests: pytest (backend) + vitest (FE unit) + Playwright (E2E) ## Project Layout ``` backend/ ├── app/ │ ├── api/v1/routes/ # feature routers │ ├── core/ # config, security, deps, middleware │ ├── models/ # SQLModel tables + DTOs │ ├── repositories/ # DB access │ ├── services/ # business logic │ ├── tasks/ # Celery jobs │ └── main.py ├── alembic/ └── tests/ (unit/ + integration/) frontend/ ├── src/ │ ├── features/<feature>/ # slice per feature │ ├── components/ui/ # shadcn + custom primitives │ ├── lib/ # api client, auth, utils │ ├── hooks/ │ ├── routes/ # Tanstack Router │ └── main.tsx └── tests/e2e/ ``` ## Conventions - **Vertical slices** — each feature has its own folder with routes+models+services+tests. - **Repository pattern** — services never touch SQLModel directly. - **Every mutation writes an AuditLog row** — actor, action, before, after. - **All endpoints require auth** — except /health, /docs (dev only). - **Pagination default** — max 100 per page, opaque cursor tokens. - **React features own their data** — no global store for server state, use Tanstack Query. - **Forms** — zod schema shared between FE and BE via codegen. ## Commands - Dev: `docker compose up -d` then `uv run fastapi dev` + `pnpm dev` - Test: `uv run pytest -xvs` + `pnpm test` + `pnpm e2e` - Lint: `uv run ruff check --fix && ruff format` + `pnpm lint --fix` - Migrate: `uv run alembic upgrade head` - New migration: `uv run alembic revision --autogenerate -m "msg"` - Build: `docker compose build` ## Never - Never skip writing an audit log row on mutations. - Never use `SELECT *` — explicit columns, always. - Never commit DB dump with real user data. - Never allow DELETE on users — use soft delete (deleted_at). - Never put business logic in routes — move to services. - Never use class-based views — functions only.

Phase 2 — Backend Build Sequence

Prompt chain for the API

# Prompt 1: Scaffold Scaffold backend/ per CLAUDE.md layout. Include: - main.py with FastAPI app + CORS + request id middleware - settings.py via pydantic-settings - docker-compose.yml (postgres + redis) - alembic configured - pytest + httpx + pytest-asyncio - GitHub Actions CI (lint + test + build docker) Just scaffolding. No business logic yet. # Prompt 2: Auth Implement auth: models (User, RefreshToken), routes (POST /auth/login, /refresh, /logout). JWT access 15min, refresh 7day rolling, httpOnly cookie for refresh. bcrypt for passwords. Rate limit login (5/min per IP). RBAC decorator: @require_role("admin"). Write tests. # Prompt 3: Users feature Implement users feature (vertical slice): - Router: GET /users (paginated), POST, PATCH, POST /:id/deactivate - Service: user_service (hash password, check email unique, write audit log) - Repository: user_repo - Tests: unit (service), integration (router with real Postgres via testcontainers) Include: pagination, filtering (q=search, role=X), sorting # Prompt 4: Audit log Implement audit log as a middleware + service: - AuditLog table: id, user_id, action, resource_type, resource_id, before_json, after_json, ip, ts - Service.log_mutation() called from all write services - GET /audit with filters (user, resource_type, date range, action) - Never log secret fields (passwords, tokens) — redact # Prompt 5: Bulk CSV import Implement POST /users/import — multipart CSV upload: - Validate CSV structure (zod-like via pydantic) - Preview mode: return first 10 rows + validation errors, no write - Apply mode: queue Celery job, return job_id - GET /jobs/:id — status (queued/running/done/failed) + error log - Tests: valid CSV, invalid CSV, partial failures

Phase 3 — Frontend Build Sequence

React + shadcn + Tanstack

# Prompt 1: Scaffold Scaffold frontend/ with Vite + React 19 + TS + Tailwind + shadcn/ui. Set up: Tanstack Router, Tanstack Query (with devtools), auth context, axios interceptor for JWT + refresh, theme (light/dark/system). Just scaffolding + login page + protected route stub. # Prompt 2: Login + auth flow Implement login page: email + password form (react-hook-form + zod), error states (wrong pw, rate limited, server down), loading states. On success: store access token in memory (NOT localStorage), refresh in httpOnly cookie. Silent refresh via axios interceptor on 401. Logout clears + redirects. Playwright E2E: login happy path + bad creds path. # Prompt 3: Data table primitive Build the DataTable component (shared): Tanstack Table + shadcn styling. Features: server-side sort/filter/pagination, row selection, bulk actions dropdown, column visibility toggle, density toggle, CSV export. API: <DataTable columns={} queryKey={} queryFn={} /> It should handle all the plumbing. Test with Storybook + vitest. # Prompt 4: Users feature page Build features/users/ — list page using DataTable, detail drawer (click row → slide-in with edit form), create dialog (button → modal form), row actions (deactivate with confirm, view audit log). Use Tanstack Query mutations with optimistic updates. Toasts for success/error. # Prompt 5: Dashboard Build features/dashboard/ — KPI cards (users active/new, actions last 7d), Recharts line chart for activity over time, pie chart for role distribution, recent audit log table. Date range picker affects all. Skeleton on load.

Phase 4 — C# Equivalent (ASP.NET Core)

Same blueprint, .NET stack

# If your team prefers .NET, swap backend with: Acme.Api/ # Minimal API endpoints per feature ├── Features/ │ ├── Users/ │ │ ├── Endpoints.cs # app.MapGroup("/users").MapGet(...) │ │ ├── Commands/ # MediatR: CreateUserCommand + Handler │ │ ├── Queries/ # GetUsersQuery + Handler │ │ └── Validators/ # FluentValidation │ ├── Auth/ │ └── AuditLog/ └── Program.cs Acme.Domain/ # Entities, value objects Acme.Infrastructure/ # EF Core DbContext, repos, external Acme.Contracts/ # DTOs shared with frontend (OpenAPI codegen) # Key mappings Python → C#: # SQLModel → EF Core + record types # Pydantic → records + FluentValidation # FastAPI routes → Minimal API endpoints # services/ → MediatR handlers # Depends() → built-in DI container # Celery → BackgroundService + Channels # pytest → xUnit + FluentAssertions + Testcontainers # Prompt to Claude: Translate my FastAPI backend to ASP.NET Core 9 minimal API with MediatR CQRS. Same vertical-slice layout. Preserve all endpoint contracts (same JSON shapes). Use EF Core with Npgsql. Tests with xUnit + Testcontainers for real Postgres.

Phase 5 — Testing Strategy

Multi-layer testing

# Prompt: Set up a layered test strategy: Backend tests: 1. Unit (pytest) — services + repos with mocked DB 2. Integration (pytest + testcontainers) — real Postgres, real HTTP via httpx 3. Contract tests — verify API matches OpenAPI spec Frontend tests: 1. Component (vitest + RTL) — each UI component in isolation 2. Integration (vitest + MSW) — feature flows with mocked API 3. E2E (Playwright) — critical paths only: login, create user, CSV import Coverage targets: - Backend: 85% services, 75% overall - Frontend: 70% components, 50% overall - E2E: critical paths (login, CRUD happy path, bulk ops) CI gates: all tests must pass + coverage must not drop.

Phase 6 — CI/CD with GitHub Actions

The deploy pipeline

# .github/workflows/ci.yml name: CI on: [pull_request, push] jobs: backend: runs-on: ubuntu-latest services: postgres: image: postgres:16 env: { POSTGRES_PASSWORD: test } steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v3 - run: uv sync - run: uv run ruff check && ruff format --check - run: uv run mypy app - run: uv run pytest --cov=app --cov-fail-under=75 frontend: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - run: pnpm install - run: pnpm lint - run: pnpm typecheck - run: pnpm test --coverage - run: pnpm build e2e: needs: [backend, frontend] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: docker compose up -d - run: pnpm playwright install - run: pnpm e2e deploy: needs: [e2e] if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: docker build -t registry/acme:${{ github.sha }} . - run: docker push registry/acme:${{ github.sha }} - name: Deploy via SSH run: ssh $DEPLOY_HOST "cd /app && docker pull $IMAGE && docker compose up -d"

Wisdom

Best Practices

BP 01 — Invest in CLAUDE.md Early

The #1 leverage point

Teams that spend 2-3 hours crafting a great CLAUDE.md (with real project conventions, explicit "never do" rules, and commands) report 3-5x better Claude Code output. Teams that skip it wrestle with hallucinated commands and wrong conventions forever.

Start from /init, heavily customise
Treat it like code — review, iterate, commit
Break it up with @imports when it exceeds ~150 lines
Include a "Never Do" section — Claude pays attention to negatives

BP 02 — Always Plan Complex Tasks

Plan mode > Jump-to-code

For anything more complex than a single-file change, force a plan first. Shift+Tab × 2 or "Plan (don't code)" at the start of the prompt. The planning step catches 80% of misunderstandings before you've spent tokens on wrong code.

BP 03 — One Concept Per Prompt

Don't overload the context

A prompt with "refactor X + add feature Y + fix bug Z + update docs" produces a mediocre version of everything. Split into 4 prompts. Each gets full attention. Chain them.

BP 04 — Verify Claims

"It's done" is a hypothesis, not a fact

Every claim of completion must be verified by running something: tests, builds, curl, manual check. "Run the tests and show me output" should appear at the end of most tasks.

BP 05 — Use Subagents for Research

Keep main context clean

Research tasks (explore codebase, look up library docs, analyse failure logs) should go to subagents. Their output comes back as a summary. Main session stays focused on the actual work.

BP 06 — Commit Early, Commit Often

Small commits = easy rollback

When Claude goes off the rails, a 200-line commit is painful to untangle. 20-line commits take seconds. Ask Claude to commit after each logical step — "commit this refactor, then move to the next task."

BP 07 — Custom Skills Over Inline Prompts

Encode repeat workflows

If you've typed the same instructions twice, make a skill. Future-you will thank you. Skills keep your workflows reproducible and shareable across the team.

BP 08 — Monitor Cost

Don't get surprised

Run /cost periodically. If a session is spending $5+ on routine tasks, something is wrong — usually too-large context or wrong model tier. Sonnet 4.6 is ~5x cheaper than Opus 4.7 for similar output quality on most code tasks.

BP 09 — Pin Model for Critical Skills

Don't leave it to chance

Skills that do security review, production deploys, or architectural decisions should pin model: claude-opus-4-7. Skills that do quick code edits or refactors can use Sonnet. Right tool for the job.

BP 10 — Keep Plans Persistent

Write plans to disk

Instead of holding plans in conversation memory, save them to docs/plans/<feature>.md. You can /clear the session and resume later by referencing the file. Plans survive session boundaries this way.

BP 11 — Hooks for Repeatable Safety

Encode your safety rules

Don't rely on remembering "don't let Claude touch production DB". Write a PreToolUse hook that blocks any command matching your danger patterns. One hook, zero ongoing discipline required.

BP 12 — Review Before Merging

Claude Code + human review

Claude-authored PRs still need human review. Period. Set up branch protection. Require approvals. Claude is fantastic at execution, but architecture decisions and product intent still need you.

For Contributors

Developer Guidelines

Dev 01 — Extending Claude Code

Three ways to add functionality

Skills — add a SKILL.md in .claude/skills/. Fastest, scoped to repo.
Plugins — bundle skills + agents + hooks + commands. Publish via marketplace.
MCP server — for external tool integration. Use the MCP SDK (TypeScript or Python).

Dev 02 — Writing a Good Skill

Best practices for skill authors

Specific description. Say EXACTLY when to invoke. Use trigger phrases: "Use when user says X, Y, or Z."
Explicit outcome format. Tell Claude the output shape you want.
Safety gates. For destructive ops: require confirmation, list what will change, allow abort.
Idempotent. Running it twice = same result as running once.
Error protocol. What to do when things fail — abort? retry? escalate?
Small surface. Use allowed-tools to limit what the skill can do.

Dev 03 — Building an MCP Server

Starter template (TypeScript)

import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server({ name: "my-mcp-server", version: "1.0.0" }); server.setRequestHandler("tools/list", async () => ({ tools: [{ name: "search_products", description: "Search product catalog by keyword", inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] } }] })); server.setRequestHandler("tools/call", async (req) => { if (req.params.name === "search_products") { const results = await searchDB(req.params.arguments.query); return { content: [{ type: "text", text: JSON.stringify(results) }] }; } }); await server.connect(new StdioServerTransport());

Dev 04 — Publishing a Plugin

The checklist

Create GitHub repo with .claude-plugin/plugin.json + skills/
Add thorough README with install instructions
Add screenshots/GIFs showing the plugin in action
Add example prompts that trigger each skill
Version with git tags (v1.0.0)
Submit to a marketplace (your own, or community ones like claude-plugins-official)
Publish a blog post / tweet with use cases
Monitor issues, respond within 48h initially

Dev 05 — Contributing to Claude Code Ecosystem

Where the community lives

Official docs: code.claude.com/docs
Platform docs: docs.claude.com
Claude Code repo: github.com/anthropics/claude-code
MCP servers: github.com/modelcontextprotocol
Essential plugins: superpowers (obra), everything-claude-code (affaan-m), plannotator (backnotprop)
Community: Discord, r/ClaudeAI subreddit, Hacker News discussion threads

Dev 06 — The Feedback Loop

When Claude Code fails, help Anthropic fix it

Inside any Claude Code session, run /bug to report issues. It auto-includes session metadata (model, version, OS, context). Be specific: "Claude tried to run rm -rf / after prompt X" is much more useful than "it's broken."

CLAUDECODEDEEP DIVE

✅ What Claude Code IS

❌ What Claude Code is NOT

Install Node.js 18 or later

Install the Claude Code CLI globally

Log in via browser or API key

Navigate to a project and launch Claude Code

Install the VS Code extension (or Cursor / JetBrains)

Auto-generate your project's CLAUDE.md

The file will look something like this

Create your user-level CLAUDE.md

Configure what Claude Code can and cannot do

Run the health check

Keep CLAUDE.md small by importing other files

Real-world CLAUDE.md for a Next.js 15 app

Real-world CLAUDE.md for a Python API

Real-world CLAUDE.md for an ASP.NET Core API

What to NEVER put in CLAUDE.md

CLAUDE.md vs AGENTS.md — which to use?

Every skill is a directory with a SKILL.md plus optional support files

All available frontmatter options

Full skill with safety gates

Auto-invoking review skill

Structured git commit skill

Where and how to define hooks

PreToolUse hook that blocks dangerous deletions

PostToolUse hook that lints files after Claude edits them

Stop hook that logs session cost + summary

How hooks return decisions

How MCP works

Use claude mcp add command

The essential toolkit

Manual config file format

Turn Claude Code into an autonomous background agent

MCP servers are arbitrary code — treat them accordingly

Two ways subagents launch

Write your own subagent

Dispatch multiple subagents in one message

Spec compliance + code quality as separate subagents

Subagents see ONLY what you send them

Don't let subagents spawn subagents unchecked

Three ways to activate

What Claude does in plan mode

Use --worktree flag to isolate tasks

File snapshots for rollback

The 3-state cycle

Install a plugin from a marketplace

Battle-tested plugins worth installing

The structure of a plugin repo

The plugin manifest

How to build a marketplace

Run Claude Code non-interactively

TypeScript/Node SDK

Programmatic agent calls

Inline subagent configuration

Load MCP inside an SDK call

Trigger Claude Code from webhooks / CI

Two options for auth

Auto-review on pull request

Auto-fix on CI failure

Claude responds when @claude-code is mentioned in issues/PRs

Critical safeguards

🛠 Install Commands

⚡ Core Slash Commands

⌨ Keyboard Shortcuts

📄 CLAUDE.md Patterns

🧠 SKILL.md Frontmatter

🪝 Hook Triggers

🔌 MCP Setup

🤖 Subagents

⛔ Rejected / Never Do This

🚦 Troubleshooting

Force high-effort reasoning for a single turn HIDDEN

Inline file references in prompts

Pin effort level for the whole session

Send a running task to the background

Skills you already have but may not know about

The YOLO flag DANGEROUS

Smart context compression

Safe to clear mid-project

CLAUDE
CODE
DEEP DIVE

Use `claude mcp add` command

Use `--worktree` flag to isolate tasks

After `/init`, replace with this