2026 — CLAUDE.md and plan mode

Why this matters

If the rest of the stack is the platform, CLAUDE.md is the contract. It’s the single piece of Claude Code that every team configures, and the 2026 community consensus — across firecrawl, buildfastwithai, the Anthropic engineering blog itself, and Forrest Chang’s 220,000-star configuration repo — is that CLAUDE.md is as important as .gitignore. Essential infrastructure, not optional documentation.

The other piece in this entry — plan mode and the spec-driven workflow that grew around it — is the most viral 2026 usage pattern. It’s the answer to “the agent went off the rails because I gave it a one-sentence brief.” Whatever your CLAUDE.md says, what the agent does next turn is set by the plan.

These two — the standing instructions (CLAUDE.md) and the turn-specific plan (plan mode) — are the foundations everything in the newer entries (managed agents, code review, hooks, skills) is built on. That’s why they’re at the bottom of this newest-first reference: you read up from here.

CLAUDE.md: the hierarchy

CLAUDE.md is loaded by Claude Code at session start and inserted into the system prompt. The 2026 hierarchy, in order of precedence (later overrides earlier):

File Scope What goes here
~/.claude/CLAUDE.md User-global Your name, role, communication preferences, tools you always use
<project>/CLAUDE.md Project Project-specific build commands, code style, architecture, what NOT to touch
<project>/CLAUDE.local.md Project, gitignored Personal-to-you, in-project overrides; not committed

Plus: --add-dir <path> extends what counts as “the project” — any CLAUDE.md inside the added directory is also loaded.

The leak revealed an implementation detail worth knowing: CLAUDE.md is loaded once per session, near the top of the system prompt. Editing it mid-session has no effect until you /init or restart. This is the difference between “Claude is ignoring my CLAUDE.md” (it isn’t — you edited it after the session started) and “Claude is misreading my CLAUDE.md” (the actually-rare case).

The Forrest Chang four-rule pattern (220K ⭐)

Forrest Chang’s CLAUDE.md repo, published 2026-01-27 and inspired by Andrej Karpathy’s “80% agent-driven coding” framing, accumulated 220,000+ combined GitHub stars across forks by mid-2026. It’s the most-copied single CLAUDE.md template in existence. The headline contribution: four rules that, in Chang’s framing, stop AI from breaking code.

Paraphrased shape (the actual rules vary by fork; the pattern is durable):

  1. Plan before code. No edits before the user agrees to a plan. If the user says “just do it,” ask once more in the form of a concrete plan, then proceed.
  2. One change, one place. Don’t refactor while fixing a bug. Don’t add features while refactoring. The scope is the brief, not what you noticed while reading.
  3. Verify before claiming. Don’t say “fixed” without running something that proves it. Tests, build, lint, manual check — whatever the project supports.
  4. Surface uncertainty. When you don’t know, say so. When you guess, say “I’m guessing.” The user is the decision-maker on ambiguity.

These four rules are notable because they’re not technology-specific. They survive switching languages, frameworks, even agents (the same rules work in Codex / Cursor / Gemini CLI). They’re a process guarantee, not a syntactic one — which is why they hold up.

Plan mode

Plan mode is invoked via /plan and is the implementation of rule 1 from the Chang pattern. The flow (per the Anthropic best-practices page and the DataCamp walkthrough cited below):

  1. User invokes /plan. Extended-thinking budget keywords (think, think hard, think harder, ultrathink) bias the model toward deeper deliberation but are model-side budget controls — they don’t on their own invoke plan mode; they’re commonly combined with /plan in community workflows.
  2. The harness dispatches a sub-agent specialised in research. The sub-agent reads the codebase, gathers context, and reports back to the main agent.
  3. The main agent produces a plan — in-context by default, or written out as plan.md on disk when used as part of the spec-driven workflow described below (where the plan is a first-class artefact reviewed alongside the spec).
  4. The user reviews the plan. Edits, accepts, rejects.
  5. Only on user acceptance does the main agent start executing. Tasks happen one at a time, with the human reviewing between each step.

The hierarchy of guarantees is important:

Spec-driven development

A pattern that emerged out of plan mode in early 2026 and got Hacker News thread #48231575

The full flow becomes:

  1. Spec — a spec.md describing what the change should do. Written by the user with light Claude assistance, NOT by Claude alone. The spec is the contract the rest of the flow honours.
  2. Plan — Claude reads the spec, dispatches a research sub-agent if needed, writes a plan.md describing how to implement what’s in the spec. Reviewed by user.
  3. Code — Claude writes code against the plan, one task at a time, with a human review between each pair of tasks.

The viral framing: spec → plan → code, with a human review between every pair of documents. Three documents, two reviews. The discipline is what stops scope creep.

Why this works in 2026 and didn’t really in 2025: the model’s ability to honour a multi-page spec without drifting got materially better in 2026 (specifically with Opus 4.x), and managed-agent dispatch (April 2026) made the research sub-agent step robust rather than experimental.

The extended-thinking budget keywords (not plan-mode triggers)

A common 2026 misconception: that phrases like think hard and ultrathink invoke plan mode. They don’t. These are extended-thinking budget keywords documented in Anthropic’s extended-thinking surface — they bias the model toward longer deliberation at higher token cost:

They’re model-side budget controls. Plan mode dispatch happens via /plan explicitly (or via plugins that wrap a plan-mode workflow around natural-language intent detection). Don’t rely on budget keywords as plan-mode triggers in scripted contexts where reliability matters; use /plan explicitly when you want the research-sub-agent dispatch + review pause.

The two surfaces combine well: /plan ... ultrathink invokes the plan-mode dispatch with the highest deliberation budget. That’s the 2026 community-favourite shape.

A minimum-viable 2026 CLAUDE.md

The 2026 community consensus shape, distilled:

# Project CLAUDE.md

## What this project is

One paragraph. Tech stack, what it does, who uses it.

## Commands

- `npm run dev` — start dev server
- `npm run test:run` — run tests once
- `npm run build` — production build

## Code style

- TypeScript strict. No `any`.
- Tests live in `test/`, not co-located.
- Prefer pure functions; isolate side effects in `services/`.

## Things to do

- Plan before coding. Show me the plan; wait for "ok."
- Verify before claiming. Run tests after edits.
- Surface uncertainty. If you're guessing, say so.

## Things NOT to do

- Don't touch `legacy/` — it's frozen and shipped to production.
- Don't run `--no-verify` on git operations.
- Don't add features while fixing a bug. Different PRs, different
  conversations.

## When you're stuck

If a build is failing and the cause isn't obvious in 5 minutes,
stop and ask. Don't keep changing things hoping it'll work.

That fits on one screen, covers the Chang four-rule essentials, and gives the agent concrete enough constraints that “go off the rails” becomes much harder.

Try this

  1. Read your installed Claude Code’s view of your CLAUDE.md. Inside a session, type /init to surface the current CLAUDE.md hierarchy and what’s loaded. Useful as a sanity check.
  2. Try plan mode on a small change. Pick a 30-minute task. Use /plan (or end your prompt with “think hard about this”). Watch the research sub-agent dispatch, watch the plan get written, edit the plan, accept, then watch the per-task review. Compare to the same task done without plan mode.
  3. Borrow Forrest Chang’s pattern, don’t fork it. Take the four-rule spirit, write your own version that’s specific to your project. The four rules generalise; which uncertainty surfaces matter to you, what “verify before claiming” looks like in your codebase — those are local. Copy the discipline; don’t copy the text.

Sources