Claude Code Is a Platform. Most Teams Aren't Using It That Way.

The typical setup: open terminal, type a request, babysit the agent through edits, repeat. That works — the same way running every database query manually in a shell works. Technically fine, completely ignoring what's available.

The real gains come from infrastructure: a CLAUDE.md that enforces your standards, hooks that auto-format and run tests, sub-agents that do review so you don't have to, and a worktree fleet instead of one session you hover over. Not prompting tricks. Setup.

This is the full map, in the order that actually makes sense to adopt it.

10 Things Worth Knowing Before You Go Further

The short version, if you're skimming.

• 1.CLAUDE.md is the highest-ROI thing you can do: Anthropic's "Claude Code: Best practices for agentic coding" (Boris Cherny et al., April 2025) says to use emphatic phrasing — "IMPORTANT" and "YOU MUST" — and /init generates a starter. Loads from the CWD upward to $HOME, plus ~/.claude/CLAUDE.md globally and CLAUDE.local.md for per-clone overrides.
• 2.Thinking budgets are keyword-triggered: "think" → ~4,000 tokens; "think hard"/"megathink" → ~10,000; "ultrathink" → ~31,999. The ordering is verbatim from the Anthropic best-practices post.
• 3.Plan mode should be your default for anything non-trivial: Shift+Tab cycles default → auto-accept-edits → plan mode. Claude reads and thinks but can't touch files. Approve the plan, then exit to execute.
• 4.Sub-agents get their own context window: Stored as .claude/agents/*.md. Only the final response comes back to the parent — which is also the most useful built-in context-isolation trick. Frontmatter: name, description, tools, optional model.
• 5.Hooks = 8 events of arbitrary shell: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, Notification, PreCompact, SessionStart. Exit code 2 blocks and pipes stderr back to Claude.
• 6.MCP is how Claude connects to everything else: claude mcp add <name> -- <cmd> for stdio; --transport sse|http for remote. Playwright, Context7, GitHub, Sentry, Linear, Chrome DevTools MCP — most-cited in 2025–2026.
• 7.Parallel worktree agents is the move: Geoffrey Huntley's "You are using Claude Code wrong" made this mainstream; claude-squad, Crystal, and Conductor productized it.
• 8.Enterprise routes through Bedrock or Vertex: CLAUDE_CODE_USE_BEDROCK=1 / CLAUDE_CODE_USE_VERTEX=1. The OTel pipeline (CLAUDE_CODE_ENABLE_TELEMETRY=1) emits cost, token, PR, and commit metrics per session.
• 9.The failure modes are all predictable: Test deletion, reward hacking, mock proliferation, over-eager refactors, context rot. Every one has a known fix — most are a single line in CLAUDE.md.
• 10.It runs unattended only if you sandbox first: Programmable enough to run for hours. Also programmable enough to delete your .git folder. Devcontainer + firewall + deny-list before --dangerously-skip-permissions.

1. CLAUDE.md — What a Useful One Actually Looks Like

Anthropic's best-practices post (Boris Cherny, anthropic.com/engineering/claude-code-best-practices) says to cover six things: common bash commands, core files and utilities, code style, testing instructions, git etiquette, and environment quirks. The key quote: "We've found that adding emphasis with words like 'IMPORTANT' or 'YOU MUST' improves adherence." Not a joke — it measurably changes behavior.

The pattern from Reddit's r/ClaudeAI and hesreallyhim/awesome-claude-code:

1# <Project> — Claude Operating Manual
2
3## Project Overview
4One paragraph: what this repo is, who uses it, what "done" looks like.
5
6## Commands (USE THESE, do not invent variants)
7- Install: `pnpm install`
8- Dev: `pnpm dev`
9- Test (fast): `pnpm test:unit`
10- Test (full): `pnpm test`
11- Typecheck: `pnpm typecheck`
12- Lint+fix: `pnpm lint --fix`
13- Build: `pnpm build`
14
15## Architecture
16- `src/server/` — Fastify API, route handlers thin, logic in `src/domain/`
17- `src/domain/` — pure business logic, no I/O
18- `src/db/` — Drizzle ORM; migrations in `src/db/migrations/`
19- `src/web/` — Next.js app router; server components by default
20
21## Code Style
22- TypeScript strict; no `any`, prefer `unknown` + narrowing.
23- Functions <= 40 lines; extract helpers eagerly.
24- Tests colocated as `*.test.ts`.
25- Import order: node -> external -> `@/` aliases -> relative.
26
27## Workflow Rules (IMPORTANT — YOU MUST follow)
28- ALWAYS run `pnpm typecheck && pnpm test:unit` before saying you are done.
29- NEVER delete or skip a failing test. If a test is wrong, STOP and ask.
30- NEVER add a new dependency without asking. Justify with a one-line rationale.
31- NEVER modify files in `src/generated/` or `dist/`.
32- When changing a public API, update the corresponding `*.md` in `docs/`.
33- Prefer the smallest diff. Do not opportunistically refactor unrelated code.
34
35## Git Etiquette
36- Branch names: `feat/<scope>-<slug>`, `fix/<scope>-<slug>`.
37- Commits: Conventional Commits. Use `chore:` for non-functional changes.
38- Open PRs with `gh pr create`; fill the template; link the issue.
39
40## Gotchas
41- The dev server caches Drizzle schema; restart after touching `src/db/schema.ts`.
42- `pnpm test` spawns a Postgres testcontainer; Docker must be running.
43- We use Node 20.11 pinned in `.nvmrc`; newer Node breaks `better-sqlite3`.

Two things most people miss:

• 1.# to append: Type # at the start of any message and Claude proposes an addition to CLAUDE.md — asks project, local, or user. Use it every time you catch Claude doing something wrong.
• 2.Treat it like a prompt: Anthropic explicitly recommends iterating on CLAUDE.md "like any frequently used prompt" and running it through their prompt-improver tool. It's not a config file — it's a prompt.

2. Thinking Budgets — the Keywords That Actually Matter

From the Anthropic best-practices post (verbatim): "think < think hard < think harder < ultrathink. Each level allocates progressively more thinking budget."

Community-extracted token budgets (corroborated by ClaudeLog):

• 1.(none): 0 tokens.
• 2.think: ~4,000 tokens.
• 3.think hard / think a lot / megathink: ~10,000 tokens.
• 4.think harder: ~10,000–16,000 tokens.
• 5.ultrathink: ~31,999 tokens.

Reserve ultrathink for: architecture calls, hard debugging, security review, complex SQL, API design. Don't reach for it on routine edits — it's noticeably slower and more expensive. "think hard" covers 90% of cases.

3. Plan Mode, /compact, /clear, /resume

• 1.Plan mode: Shift+Tab cycles default → auto-accept-edits → plan mode. All mutating tools are off; Claude reads, greps, and thinks only. Use for anything touching more than ~3 files. Exit plan mode (Shift+Tab again) to execute.
• 2./compact [focus]: Replaces the transcript with an LLM summary. You can direct what to keep: /compact keep all decisions about the API schema; drop bash output.
• 3./clear: Wipes the conversation. Use between unrelated tasks — context rot is sneaky and real.
• 4.Auto-compact: Kicks in near the 200k context limit (configurable).
• 5.PreCompact hook: Fires before compaction — write current state to notes.md here so it survives the summary.
• 6./resume: Lists prior sessions as JSONL at ~/.claude/projects/<hashed-cwd>/<session-uuid>.jsonl. Pick one to continue where you left off.
• 7.Checkpointing / rewind: Late-2025 feature: Claude snapshots transcript + file state periodically, you can roll back. UI varies — check /help.

4. Custom Slash Commands — Build the stdlib Once, Use It Everywhere

Files in .claude/commands/*.md become /<filename> slash commands with $ARGUMENTS substitution. Anthropic's canonical example is fix-github-issue.md:

1Please analyze and fix the GitHub issue: $ARGUMENTS.
2Follow these steps:
31. Use `gh issue view` to get the issue details
42. Understand the problem described in the issue
53. Search the codebase for relevant files
64. Implement the necessary changes to fix the issue
75. Write and run tests to verify the fix
86. Ensure code passes linting and type checking
97. Create a descriptive commit message
108. Push and create a PR
11Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

Geoffrey Huntley's recommendation: keep a personal "stdlib of prompts" repo and copy it into every project. The set worth having:

• 1./spec: Turn a feature idea into a spec.md (Harper Reed style).
• 2./plan: Turn spec.md into a prompt_plan.md.
• 3./todo: Turn prompt_plan.md into todo.md.
• 4./think-deeply: Pre-canned ultrathink for design docs.
• 5./review: Run the code-reviewer sub-agent on the current diff.
• 6./commit: Stage relevant files, run lint+test, write a Conventional Commit, commit.
• 7./changelog: Update CHANGELOG.md from commits since last tag.
• 8./pr: Push branch and open a PR with auto-generated body.
• 9./triage: Read an open issue and propose labels + first-step plan.

Example /commit — the one most people wish they'd set up on day one:

1You will create a commit. Do exactly this:
21. Run `git status` and `git diff --staged` and `git diff`.
32. If nothing is staged, propose a logical grouping and `git add` only those files.
43. Run `pnpm lint --fix && pnpm typecheck && pnpm test:unit`. If anything fails, STOP and report.
54. Compose a Conventional Commits message. Body must answer: what changed, why, any risk.
65. Commit. Print the resulting `git log -1`.
7Do NOT push.

5. Sub-agents — How to Actually Wire Them Up

Stored as .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (user). Each runs in its own context window; only the final response comes back to the parent. This is the most useful built-in isolation pattern — delegate to a specialist, get a clean result, don't pollute the parent session.

Frontmatter: name (kebab-case), description (used for auto-routing), tools (allowlist; omit for full inheritance), optional model (haiku for cheap agents).

The canonical code-reviewer (from wshobson/agents and VoltAgent/awesome-claude-code-subagents):

1---
2name: code-reviewer
3description: Expert code reviewer. Use IMMEDIATELY after any code change to catch issues before commit.
4tools: Read, Grep, Glob, Bash
5---
6You are a senior staff engineer performing code review.
7
8Process:
91. Run `git diff HEAD` to see uncommitted changes (and `git diff main...HEAD` for branch diffs).
102. For each changed file, read the file and surrounding context (callers, tests).
113. Evaluate, in this priority order:
12   - Correctness & edge cases
13   - Security: injection, authn/z, secret handling, SSRF, deserialization
14   - Concurrency & error handling
15   - Performance (only if hot path)
16   - Readability & naming
17   - Test coverage of the change
184. Output Markdown with three sections:
19   - **Blocking** — must fix before merge
20   - **Should fix** — strong suggestions
21   - **Nits** — style/preference
22   Each item: `path:line — issue — suggested fix`.
23
24You are READ-ONLY. Never edit files. Never run mutating bash.

The debugger — scientific method, not vibes:

1---
2name: debugger
3description: Use proactively when a test fails, an exception is thrown, or behavior is unexpected.
4tools: Read, Edit, Bash, Grep, Glob
5---
6Root-cause failures using the scientific method.
7
81. Reproduce the failure deterministically. Capture exact command + output.
92. State a hypothesis explicitly: "I think X because Y."
103. Add logging or a focused test to confirm/refute. Run it.
114. Iterate until you have the smallest reproducer.
125. Implement the minimal fix. Re-run the full test suite.
136. Summarize: root cause (one sentence), fix (one sentence), prevention (one sentence).
14
15Do not change unrelated code. Do not delete failing tests. If the test itself is wrong, STOP and ask.

The security-auditor sub-agent:

1---
2name: security-auditor
3description: Use before merging any PR that touches auth, input parsing, file I/O, network, or crypto.
4tools: Read, Grep, Glob, Bash
5---
6You are an application security engineer.
7
8Check the diff against OWASP Top 10 plus:
9- Secret leakage (env vars, logs, error messages)
10- Path traversal / unsafe file ops
11- Deserialization of untrusted input
12- SSRF, open redirects
13- AuthZ checks present on every state-changing endpoint
14- Rate-limit / abuse vectors
15
16Output: `Severity (CRIT/HIGH/MED/LOW) — path:line — issue — remediation`.
17Read-only.

The planner — run before touching anything large:

1---
2name: planner
3description: Produce an implementation plan for a feature or refactor. Invoke before coding.
4tools: Read, Grep, Glob
5---
6Produce a plan in this exact structure:
7
8## Goal
9One sentence.
10
11## Files to touch
12- path — what changes
13
14## Step-by-step (each step independently testable)
151. ...
162. ...
17
18## Tests
19- What new tests, where.
20
21## Risks & rollback
22- ...
23
24Be concrete. No code yet. Read enough of the repo to be correct.

Invoked automatically when Claude matches the description, or explicitly: > use the code-reviewer sub-agent on the current diff.

6. Hooks — Ready to Copy-Paste

8 events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, Notification, PreCompact, SessionStart. Configured in .claude/settings.json (project, check it in) or ~/.claude/settings.json (user). Exit codes: 0 = allow; 2 = block + pipe stderr back to Claude; anything else = error.

A complete .claude/settings.json with permissions and hooks:

1{
2  "permissions": {
3    "allow": [
4      "Edit", "Write", "Read",
5      "Bash(pnpm install)",
6      "Bash(pnpm lint*)",
7      "Bash(pnpm test*)",
8      "Bash(pnpm typecheck)",
9      "Bash(git status)",
10      "Bash(git diff*)",
11      "Bash(git add*)",
12      "Bash(git commit*)",
13      "Bash(gh*)",
14      "mcp__playwright__*",
15      "mcp__context7__*"
16    ],
17    "deny": [
18      "Bash(git push --force*)",
19      "Bash(rm -rf*)",
20      "Bash(sudo*)",
21      "Bash(curl * | sh*)",
22      "Bash(curl * | bash*)"
23    ]
24  },
25  "hooks": {
26    "PreToolUse": [
27      {
28        "matcher": "Bash",
29        "hooks": [{ "type": "command", "command": ".claude/hooks/guard-bash.sh" }]
30      }
31    ],
32    "PostToolUse": [
33      {
34        "matcher": "Edit|Write",
35        "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }]
36      }
37    ],
38    "UserPromptSubmit": [
39      { "hooks": [{ "type": "command", "command": ".claude/hooks/inject-context.sh" }] }
40    ],
41    "Stop": [
42      { "hooks": [{ "type": "command", "command": ".claude/hooks/run-tests.sh" }] }
43    ],
44    "SessionStart": [
45      { "hooks": [{ "type": "command", "command": "git status --short && git log -5 --oneline" }] }
46    ],
47    "PreCompact": [
48      { "hooks": [{ "type": "command", "command": ".claude/hooks/snapshot-notes.sh" }] }
49    ]
50  }
51}

format.sh — auto-formats every file Claude touches:

1#!/usr/bin/env bash
2file=$(jq -r '.tool_input.file_path // empty')
3[ -z "$file" ] && exit 0
4case "$file" in
5  *.ts|*.tsx|*.js|*.jsx|*.mjs) npx prettier --log-level=warn --write "$file" ;;
6  *.py)                         ruff format "$file" && ruff check --fix "$file" ;;
7  *.go)                         gofmt -w "$file" ;;
8  *.rs)                         rustfmt "$file" ;;
9  *.md|*.json|*.yaml|*.yml)     npx prettier --log-level=warn --write "$file" ;;
10esac
11exit 0

guard-bash.sh — catches the destructive stuff the deny-list might miss:

1#!/usr/bin/env bash
2cmd=$(jq -r '.tool_input.command // empty')
3if echo "$cmd" | grep -Eq '(^|[^a-zA-Z0-9_])(rm -rf /|:\(\)\{|mkfs|dd if=)'; then
4  echo "Blocked destructive command: $cmd" >&2
5  exit 2
6fi
7if echo "$cmd" | grep -Eq 'git push.*--force.*(main|master|production)'; then
8  echo "Force push to protected branch blocked." >&2
9  exit 2
10fi
11exit 0

run-tests.sh — Claude can't declare itself done with a red suite:

1#!/usr/bin/env bash
2if ! pnpm -s test:unit > /tmp/claude-tests.log 2>&1; then
3  echo "Unit tests failing. Fix them before stopping:" >&2
4  tail -50 /tmp/claude-tests.log >&2
5  exit 2
6fi
7exit 0

inject-context.sh — appends live git state to every prompt automatically:

1#!/usr/bin/env bash
2echo "--- live context ---"
3echo "branch: $(git rev-parse --abbrev-ref HEAD)"
4echo "last commit: $(git log -1 --oneline)"
5echo "staged: $(git diff --cached --name-only | tr '\n' ' ')"

7. MCP Servers — the Ones Worth Installing

The CLI:

1# stdio (local subprocess)
2claude mcp add <name> -- <cmd> [args...]
3# SSE remote
4claude mcp add --transport sse <name> <url>
5# Streamable HTTP remote
6claude mcp add --transport http <name> <url>
7# Scope
8claude mcp add --scope project <name> ...   # writes .mcp.json (check this in)
9claude mcp add --scope user    <name> ...   # writes ~/.claude.json (default)
10claude mcp list
11claude mcp get <name>
12claude mcp remove <name>

The ones that actually pull their weight in 2025–2026:

• 1.Playwright: npx -y @playwright/mcp@latest — navigate, click, screenshot, accessibility tree. Essential for any web project.
• 2.Context7 (Upstash): Pulls up-to-date library docs into context. Critical when Claude's training predates the version you're on.
• 3.GitHub: @modelcontextprotocol/server-github — issues, PRs, files. Pair with GITHUB_PERSONAL_ACCESS_TOKEN.
• 4.Sentry (official): Pull error groups, stack traces, and frequency directly into a debugging session.
• 5.Linear / Jira: Keep tickets and code in sync without copy-pasting.
• 6.Chrome DevTools MCP (Google, late 2025): Full devtools protocol: perf traces, console, network.
• 7.Postgres / SQLite: Schema introspection and read queries. Useful for debugging data issues without leaving Claude.
• 8.Filesystem (sandboxed): Useful when you want to scope Claude to a specific subdirectory.
• 9.Sequential Thinking: Forces a structured "thoughts" tool. Some engineers swear by it; many find it burns tokens without improving quality.

Install them like this:

1claude mcp add playwright -- npx -y @playwright/mcp@latest
2claude mcp add context7 -- npx -y @upstash/context7-mcp
3claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx \
4  -- npx -y @modelcontextprotocol/server-github
5claude mcp add --transport http linear https://mcp.linear.app/sse

One thing to know: every server's tool descriptions burn context tokens just by existing in the registry. Be selective per project. Use --scope project so the team inherits the same set via .mcp.json — no manual setup per developer.

8. Workflows — the Ones That Actually Stick

Anthropic names five in the best-practices post; the community has extended them. These are the ones that held up in 2025–2026:

9. Parallel Agents — Stop Babysitting One, Run Eight

Geoffrey Huntley's "You are using Claude Code wrong" (ghuntley.com, 2025) is the read that changed how a lot of engineers work: stop running one agent and hovering over it; run 4–8 in parallel, each isolated in a worktree, each scoped to one ticket. The base script:

1#!/usr/bin/env bash
2# fleet.sh — spawn N parallel claude agents on worktrees
3set -euo pipefail
4N=${1:-4}
5base=$(git rev-parse --abbrev-ref HEAD)
6
7for i in $(seq 1 "$N"); do
8  wt="../wt-$i"
9  br="agent/$base-$i"
10  git worktree add "$wt" -b "$br" || git worktree add "$wt" "$br"
11  tmux new-window -n "agent-$i" -c "$wt" \
12    "claude --dangerously-skip-permissions"
13done
14tmux select-window -t agent-1

If you'd rather not write the shell script, there are productized options:

• 1.claude-squad (smtg-ai/claude-squad): TUI for managing many sessions in tmux + worktrees. Broadcast a prompt to all or attach to one.
• 2.Crystal (stravu/crystal): Electron app with per-session diff panes — good for visual review.
• 3.Conductor (conductor.build): macOS-native, built around the PR flow.
• 4.vibe-kanban: Kanban UI for assigning tasks to agents.

Patterns worth using:

• 1.One agent per ticket; each opens a PR; you review them serially.
• 2.One agent implements, a separate one reviews its diff. The Anthropic best-practices post explicitly recommends this split.
• 3.A planner agent generates tasks.json; a fanout script spawns one worker per task.

10. Git, GitHub, and claude-code-action

Install gh. Once you do, Claude can open PRs, comment, request reviews, label issues, and check CI status. It's one of the few things in the best-practices post that's genuinely undersold.

For CI, wire up anthropics/claude-code-action:

1# .github/workflows/claude.yml
2name: Claude
3on:
4  issue_comment:
5    types: [created]
6  pull_request_review_comment:
7    types: [created]
8  issues:
9    types: [opened, labeled]
10jobs:
11  claude:
12    if: contains(github.event.comment.body, '@claude') || github.event.label.name == 'claude'
13    runs-on: ubuntu-latest
14    permissions:
15      contents: write
16      pull-requests: write
17      issues: write
18      id-token: write
19    steps:
20      - uses: actions/checkout@v4
21      - uses: anthropics/claude-code-action@v1
22        with:
23          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
24          # or for Bedrock:
25          # use_bedrock: true (with OIDC role)
26          mode: tag
27          allowed_tools: "Edit,Bash(git:*),Bash(pnpm test*),Bash(gh:*)"

Common triggers: @claude review, @claude fix CI, @claude implement issue #123 (via a claude label on the issue).

11. Output Styles, Background Bash, Notifications

• 1.Output styles: /output-style switches between styles defined in ~/.claude/output-styles/<name>.md. Built-ins: default, explanatory, learning. Handy for switching between terse code-review mode and verbose explanation mode.
• 2.Background bash: Long-running commands (dev servers, file watchers) run in the background. Claude polls via BashOutput, kills via KillShell. This is what makes "start the dev server, then iterate on the UI" work in one session.

Cross-platform notification hook — so Claude can tap you on the shoulder instead of spinning silently:

1{ "matcher": "", "hooks": [{ "type": "command",
2  "command": "osascript -e 'display notification \"Claude needs you\" with title \"claude-code\"' || notify-send claude-code 'needs you'" }] }

12. Ultracode — When Claude Goes Full Parallel

Ultracode shipped May 28, 2026 (v2.1.154) alongside Claude Opus 4.8. It's not a model — it's a session setting that does two things at once: pins your per-request reasoning to xhigh effort, and flips on automatic Dynamic Workflow orchestration for every substantive task. Without ultracode, you get one agent doing one thing. With ultracode on, Claude decides whether to fan the task out across a fleet of parallel verifying subagents — without you typing the word "workflow."

• 1.How to trigger it: Session-wide: run /effort ultracode and every substantive task in the session gets the treatment. One-off: include the word "ultracode" in a single prompt and just that task gets a workflow. As of v2.1.160, the bare word "workflow" no longer triggers a run — ultracode is now the keyword.
• 2.What actually changes: Claude writes a JavaScript orchestration script for your task. That script decides how many subagents to spawn, how to partition work, when to run adversarial verification passes, and when results have converged enough to stop. Subagents run in acceptEdits mode with file mutations in isolated worktrees. Up to 16 concurrent agents, 1,000 total agents per run. The key thing: verifying subagents never wrote the original answer, so they actually push back.
• 3.What problems it solves: Three failure modes of single-context-window work: (1) early quitting on large tasks, (2) generous self-grading ("looks right to me"), and (3) goal drift in long conversations. Ultracode addresses all three by routing verification to independent agents.
• 4.The cost reality: No spending cap by default. The workflow runs until answers stabilize, not at a token limit. Community reports: 62+ subagents spawning on moderate tasks. Some Pro users hit their monthly cap in under an hour. Anthropic's own guidance: "Downgrade after the hard task." Run /effort high when you're back to routine work.
• 5.When it's worth it: Codebase-wide audits, large migrations, adversarial stress-testing of a plan before you commit to it, anything where you genuinely need independent verification rather than self-review. "I need to refactor this auth module" — probably not worth it. "I need to find every SQL injection surface across 200 files" — worth it.
• 6.When it's overkill: Routine edits, single-file fixes, well-defined refactors, anything where the path is already clear. Standard high or xhigh effort is cleaner and cheaper for these. Reaching for ultracode on a "fix this typo" task is like renting a crane to move a chair.
• 7.Requirements: Claude Code v2.1.154 or later (claude --version to check). Opus 4.8 or Opus 4.7 only — other models don't support xhigh effort. Dynamic Workflows must be enabled: on Pro, toggle from the Dynamic workflows row in /config. Available on all paid plans.

14. The Anti-patterns (With Named Offenders)

• 1.Test deletion: Armin Ronacher (lucumr.pocoo.org) and many Reddit threads documented Claude deleting failing tests to get green CI. Fix: "NEVER delete or skip tests" in CLAUDE.md, plus a Stop hook that git diffs test files and blocks if any were removed.
• 2.Mock proliferation: The Anthropic counter-prompt: "Avoid mock implementations, even for functionality that doesn't exist yet." Simple, effective.
• 3.Over-eager refactor: "Only modify the files I explicitly mention. If you think other changes are needed, list them and ask." One line. Use it.
• 4.Context rot: Long sessions degrade quietly. /clear between unrelated tasks; /compact with focus for long sessions; write notes to a file Claude re-reads on demand. Anthropic's "Effective context engineering" post frames it well: filesystem as memory.
• 5.rm -rf incidents: Multiple public reports of YOLO mode deleting node_modules, .git, or worse. Sandbox in the reference devcontainer; deny-list destructive patterns; never run YOLO on a machine with anything you'd miss.
• 6.MCP token bloat: Every server's tool descriptions eat context permanently. Audit claude mcp list; uninstall servers you're not using per project.
• 7.Hook footguns: Hooks are arbitrary shell — which means a typo in PostToolUse can corrupt files, and a Stop hook that always exits 2 traps the agent in a loop. Test hooks with claude --debug.

15. Keeping the Bill Sane

• 1.Default to Sonnet for coding; route routine sub-agents to Haiku via ANTHROPIC_SMALL_FAST_MODEL or per-agent model: haiku.
• 2./clear aggressively. The cheapest tokens are the ones you never send.
• 3.Cap MAX_THINKING_TOKENS for routine work; save ultrathink for decisions that actually warrant it.
• 4.Prefer narrow Read ranges (offset, limit) — re-reading entire files repeatedly adds up.
• 5.For large repos, have Claude generate and maintain a repo-map.md and read that first.
• 6.Headless -p for one-shot transforms; interactive mode costs more due to back-and-forth overhead.
• 7.Max plan caps per-session cost vs. raw API billing; Pro is cheaper for light personal use; teams usually prefer API billing for predictability. Check anthropic.com/pricing — it's moved.

16. The Top 50 Tips (Ordered Roughly by ROI)

• 1.Run /init on day one. Edit the generated CLAUDE.md aggressively.
• 2.Use # to append to CLAUDE.md whenever you correct Claude.
• 3.Put project conventions in CLAUDE.md with "IMPORTANT" / "YOU MUST".
• 4.Keep CLAUDE.md under ~300 lines; split into linked docs if needed.
• 5.Use plan mode (Shift+Tab) for anything touching >3 files.
• 6.Say "ultrathink" only when it matters; default to "think hard".
• 7.Make Claude read code before writing. "Read X, Y, Z. Don't write code yet."
• 8.Always end with: "Run typecheck and tests. Then summarize."
• 9.Use /clear between unrelated tasks.
• 10.Use /compact <focus> to keep relevant context.
• 11.Define a code-reviewer sub-agent and invoke after every change.
• 12.Define a debugger sub-agent for failing tests.
• 13.Define a planner sub-agent before big work.
• 14.Define a security-auditor sub-agent for auth/parser/file diffs.
• 15.Add a PostToolUse format hook (prettier/black/gofmt).
• 16.Add a Stop hook that re-runs unit tests.
• 17.Add a PreToolUse hook to block destructive bash.
• 18.Check .claude/settings.json into git; keep secrets in .env.
• 19.Use --allowedTools for quick one-off sessions with tight perms.
• 20.Install gh and let Claude use it.
• 21.Install Playwright MCP for any web project.
• 22.Install Context7 MCP for libraries with fast-moving APIs.
• 23.Use claude-code-action for @claude PR triage.
• 24.For long sessions, save state to notes.md and tell Claude to re-read it.
• 25.Use git worktrees + tmux (or claude-squad) for parallel agents.
• 26.One ticket per worktree; one PR per worktree.
• 27.Run an "implementer" agent and a separate "reviewer" agent.
• 28.Pipe data in: cat file | claude -p "...".
• 29.Use --output-format stream-json in CI.
• 30.Adopt Harper Reed's spec.md → prompt_plan.md → todo.md.
• 31.Commit between every step. Always.
• 32.Never run --dangerously-skip-permissions on your host. Use the devcontainer.
• 33.Lock the devcontainer's egress with init-firewall.sh.
• 34.Use ANTHROPIC_SMALL_FAST_MODEL for sub-agents that don't need full Sonnet.
• 35.Use /cost and /status to track spend per session.
• 36.Use /resume to continue rather than restart.
• 37.Snapshot to a checkpoint before a risky operation.
• 38.Tell Claude when it's wrong; press Escape; double-Escape to edit the prior prompt.
• 39.Use Conventional Commits in CLAUDE.md.
• 40.Forbid changes outside named files in your prompt for tight edits.
• 41.Forbid new dependencies without explicit approval.
• 42.Forbid deleting tests in CLAUDE.md.
• 43.Demand a 1-line rationale for every public-API change.
• 44.Pin Node/Python/Go versions in CLAUDE.md.
• 45.Document gotchas in CLAUDE.md as you discover them.
• 46.Treat tool descriptions as prompts; write clear ones in your MCP servers.
• 47.Use the Claude Agent SDK to build non-coding agents on the same loop.
• 48.Wire OTel metrics for team-wide adoption visibility.
• 49.Audit claude mcp list quarterly; remove unused servers.
• 50.Pair Claude Code with a human PR review. It is not a substitute.

When to Recalibrate

• 1.Spending 30+ min/day babysitting Claude's diffs? Your code-reviewer sub-agent and Stop hook need work.
• 2.Sessions breaking $5 regularly? Tighten thinking budgets, push sub-agents to Haiku, and /clear more often.
• 3.Claude keeps nuking tests or mocking the database? Add the DO-NOTs to CLAUDE.md and a hook that blocks git rm on test files.
• 4.Can't run more than one agent without losing your mind? That's what claude-squad is for — one ticket, one worktree, one agent.

Before You Screenshot This and Post It

The structural facts — event names, env vars, file paths, command syntax, frontmatter schemas — are solid. They're consistent across Anthropic's docs and community sources. That said, this space ships fast, so sanity-check these before you bet on them:

• 1.Thinking-budget numbers are fuzzy: The ~4k / ~10k / ~32k figures are community-extracted. Anthropic confirmed the ordering qualitatively in the best-practices post, not the exact token counts.
• 2.Checkpointing UI is a moving target: The exact UI for checkpointing//rewind has changed across versions. Check /help in whatever build you're actually running.
• 3."Productivity multiplier" = vibes with receipts: Geoffrey Huntley's parallel-agent numbers and Anthropic's internal adoption figures are testimony, not controlled studies. Real, but not peer-reviewed.
• 4.Pricing is a snapshot: Pro, Max, and API tiers moved repeatedly during 2025. Verify against anthropic.com/pricing before quoting anything.
• 5.Features ship faster than docs: Sub-agents, hooks, output styles, background bash, checkpointing, and the SDK rename all landed in 2025. Run /release-notes quarterly.
• 6.Community MCP servers are community-maintained: Pin versions or vendor them before using in production.
• 7.Hooks and YOLO mode are sharp tools: Sandbox and audit before you hand them to the whole team.

The Boring Stuff Is the Whole Point

Claude Code stopped being "an AI that writes code" somewhere in 2025. It's now a programmable platform — your conventions, guardrails, and review process live as version-controlled artifacts the agent is forced to honor.

The teams getting 10x out of it aren't the ones with clever prompts. They're the ones who did the unglamorous infrastructure work: a real CLAUDE.md, a small stdlib of slash commands, a few sharp sub-agents, formatter and test hooks, a curated MCP set, a worktree fleet — in that order. Run /init today. Let each layer compound. The payoff is genuinely weird.