1. Scope: did it touch more than you asked?

The most common agent failure is not bad code - it is extra code. You asked for a validation fix and got a refactored helper, a renamed variable three files away, and an "improved" error message. Check the diff file list against the task. Anything outside the ask gets reverted or justified in the PR description. git diff --stat against the branch point is the fastest scope check there is.

2. Boundaries: did it reach across a line it should not cross?

Agents do not feel your architecture. They will happily import the database client into a UI component or call an internal service's private helper because it was the shortest path. Check every new import and every new call against your layering rules. This is the check that saves you six months later, and it is the one a skimmed diff never catches - the violation is one line that looks exactly like the legitimate lines around it.

3. Silent fallbacks and swallowed errors

Agents love making code that never fails visibly: catch blocks that log and continue, || defaultValue on things that should be required, retry loops that hide a broken dependency. Search the diff for catch, ||, ??, and try. For each one, ask: if this fires in production, will anyone know? If the answer is no, the fallback is a bug with extra steps.

4. Hallucinated APIs and config keys

The code calls client.getOrCreate() and the library has no such method - but it should have, which is why the agent wrote it and why your eye slides past it. Verify every unfamiliar method, option, and config key against the actual library version in your lockfile. Thirty seconds per call. This is the failure class with the highest embarrassment-per-line ratio.

5. Test theater

Agent-written tests often test the mock instead of the code: assertions on the stub's return value, happy-path-only coverage, or a test that passes whether the feature works or not. For each new test, apply the mutation check mentally - if you broke the implementation, would this test fail? If you cannot answer yes quickly, the test is decoration. Delete it or make it load-bearing.

6. Duplication of what already exists

Agents write new utilities instead of finding existing ones. Before accepting a new helper, search the repo for its job: rg "formatDate|format_date" style. Merging two near-identical helpers later costs more than catching the duplicate now.

7. Secrets, logging, and PII

Check new log lines for what they print - agents log entire request objects, including auth headers and user data. Check new config for keys committed in plaintext. One pass over the diff with this lens is cheap; cleaning a leaked token is not.

The short version

Scope, boundaries, silent fallbacks, hallucinated APIs, test theater, duplication, secrets. Seven checks, most answerable in under a minute each, aimed at how agents actually fail instead of how humans do. Paste the list into your PR template and the review stops depending on whoever is awake.

The Agentic Coding Kit ships this review checklist as a drop-in CLAUDE.md section plus pre-commit hooks that catch scope creep and boundary violations automatically. 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

What actually happens when the window fills

Every session has a fixed context window. Your messages, the agent's replies, every file it reads, and every tool result all share that space. When it approaches the limit, Claude Code compacts: earlier conversation gets replaced by a summary, and the session continues. Compaction is lossy by design. A summary keeps the gist of the task and drops most specifics - including the naming rule you stated once, forty minutes ago, in a paragraph about something else.

CLAUDE.md is the exception

CLAUDE.md is re-read at the start of every session and stays in context regardless of compaction. Facts placed there do not get summarized away. That makes it the right home for exactly the things you find yourself repeating: architecture boundaries, naming conventions, commands that must be run a specific way, files that must never be edited, the test command, the deploy command. If a fact would change what the agent does on any task in the repo, it belongs in CLAUDE.md, not in chat.

What to keep out of it

The failure mode in the other direction is a 900-line CLAUDE.md that buries the load-bearing rules under history and aspiration. Every line sits in every session's context, so each one pays rent or leaves. Keep it to current, durable, behavior-changing facts. Meeting notes, roadmap, and explanations of why a decision was made belong in docs the agent can read on demand - point to them with one line: See docs/architecture.md before touching the billing module.

A structure that holds up

# Project
One paragraph: what this is, who runs it, how.

# Commands
- test: npm test -- --run
- lint: npm run lint:fix
- dev: npm run dev (port 3100)

# Boundaries
- Never edit src/legacy/** - frozen, mirrors production.
- Database access only through src/db/client.ts.
- No new dependencies without asking.

# Conventions
- Files: kebab-case. React components: PascalCase.
- Errors: throw AppError, never raw Error.
- Commits: conventional commits, no scope.

Thirty to sixty lines like this outperforms a wall of prose. The agent follows lists of constraints far more reliably than paragraphs of advice.

Recovering a session that already drifted

When you notice drift mid-session, do not argue with the summary - it cannot give back what it dropped. State the rule once more, then move it into CLAUDE.md so it never needs restating: "Add to CLAUDE.md under Boundaries: never mock the payments service in tests." The agent can edit the file itself, and the rule is permanent from the next line onward. Run /clear between unrelated tasks so a stale summary from the last task does not leak into the next one.

The short version

Forgetting is compaction, and compaction is normal. Chat is scratch space; CLAUDE.md is project memory. Keep the file short, current, and limited to facts that change behavior, and the agent stops starting from zero.

The Agentic Coding Kit ships battle-tested CLAUDE.md and AGENTS.md templates - boundaries, commands, conventions - plus 30 more config files for Claude Code and Cursor. $19 one-time. Or draft yours free with the CLAUDE.md generator.

1. The settings file is not where you think it is

Hooks live in the hooks block of settings.json, and there are three of those files: ~/.claude/settings.json (global), .claude/settings.json (project, committed), and .claude/settings.local.json (project, personal). If you edited the project file but your session runs from a different directory - a worktree, a subdirectory outside the project root, a different clone - your hook is not loaded. Inspect from the exact directory where the hook should fire.

2. The event name is wrong

The hook events are exact strings: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, Notification, PreCompact, SessionStart. A hook registered under preToolUse or pre_tool_use never fires and never errors - the key is simply ignored. Copy the event name from the docs, not from memory.

3. The matcher does not match the tool name

For tool events, the matcher is a regex against the tool name: "Bash", "Edit|Write", ".*". The classic miss is matching "bash" (lowercase) or expecting the matcher to see the command content - it matches the tool name only, not the arguments. A hook meant to intercept git push needs Bash as the matcher and the git push check inside the hook script itself.

4. The JSON is broken

A trailing comma or an unquoted key makes the whole settings file unparseable - and the failure mode is that the file is skipped, not that you get an error dialog. Validate the file after every edit:

python3 -m json.tool .claude/settings.json > /dev/null && echo OK

If your editor shows the file as plain text instead of JSON, something in it is already invalid.

5. The script is not executable, or the path is wrong

A hook command that references ./scripts/check.sh resolves relative to the project root, not the settings file. And a script without the execute bit fails with a permission error you will never see unless you look at the logs. Test the exact command the hook runs, from the project root, in a plain shell: paste it, run it, check the exit code. If it fails there, it fails as a hook.

6. The hook runs but errors silently

Hook stdout for most events is discarded unless the hook exits with a specific code or writes the expected JSON to stdout. If your hook echoes a message and exits 0, you see nothing. For a blocking decision, exit code 2 surfaces stderr to the agent. While debugging, make the hook write to a file you control - echo "$HOOK_INPUT" >> /tmp/hook-debug.log - so you can prove whether it fired at all. That one line separates "never ran" from "ran and did nothing", which sends you to the right half of this list.

The short version

Check the file location, the event name casing, the matcher against the tool name only, JSON validity, the script path and execute bit, and finally whether it runs but swallows its own output. Add a debug log line first - it turns guessing into a two-minute check.

Want hooks that work out of the box? The Agentic Coding Kit ships tested hook configs - pre-commit checks, secret scanning, format-on-save - with the settings.json wiring already correct. 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

Who reads which file

Two details matter. First, .cursorrules is deprecated in favor of .cursor/rules/ - Cursor still reads the old file, but new projects should use the directory. Second, Claude Code can be pointed at AGENTS.md-style content through imports, which is the key to avoiding duplication.

They are the same document in spirit

Every one of these files answers the same five questions: how to build, how to test, what conventions to follow, what to never touch, and where the docs live. If you write that once well, the per-tool file is a packaging problem, not a writing problem.

The setup that covers everything

Write the content once in AGENTS.md at the repo root - it is the superset audience, readable by humans and by the widest range of agents. Then make the tool-specific files thin pointers.

CLAUDE.md becomes:

# Project rules

See @AGENTS.md for build, test, and conventions.

## Claude Code specifics
- Prefer `pnpm -r test` over per-package runs
- Permissions baseline lives in .claude/settings.json

The @AGENTS.md import pulls the shared file into context; the rest is only what is genuinely Claude-specific.

.cursor/rules/project.mdc becomes the same pointer in Cursor's format - a short rule file that says "follow AGENTS.md" plus any Cursor-only settings. Cursor does not have a file-import directive, so paste the critical ten lines rather than referencing the file path and hoping.

When they conflict, nobody wins

The classic failure: AGENTS.md says "use pnpm", an old .cursorrules says "use npm", and CLAUDE.md says nothing. Different agents now do different things in the same repo, and a developer running two tools gets inconsistent behavior they cannot explain. One source of truth, thin pointers, and deleting the stale file is the whole fix. Treat these files like CI config: reviewed in pull requests, one owner, no drift.

What about nested files?

AGENTS.md and CLAUDE.md both support nested per-directory files in monorepos; Cursor's rules directory approximates it with path-scoped globs frontmatter. The same layering rule applies everywhere: shared rules at the root, local rules next to the code.

The short version

Write your rules once in AGENTS.md. Make CLAUDE.md an import plus Claude-only extras. Replace .cursorrules with a .cursor/rules/ file that points at the same content. Delete anything that contradicts the source of truth.

Want the three-file setup pre-built? The Agentic Coding Kit ships an AGENTS.md baseline, a CLAUDE.md that imports it, and matching .cursor/rules/ files - 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

The layout that works

monorepo/
  CLAUDE.md                  # shared rules only
  packages/
    api/
      CLAUDE.md              # api-specific rules
      src/
    web/
      CLAUDE.md              # web-specific rules
      src/

Claude Code loads the root file on every session, and pulls in nested CLAUDE.md files when it works inside that directory tree. A session editing packages/api/src sees the root file plus packages/api/CLAUDE.md - not the web package's rules, not the other ten packages'. That scoping is the whole point: context follows the work.

What goes in the root file

Things that are true for every package, stated once:

• How to install, build, and test from the root (pnpm install, pnpm -r test)

• Repo-wide conventions: commit message format, branch naming, the lint config everything inherits

• Where the packages live and what each one is, in one line each

• Anything an agent must never do anywhere (no force-push, no committing secrets)

Keep it under 100 lines. If a rule only applies to one package, it does not belong here.

What goes in nested files

Package-local facts the agent needs only when working there: the package's test command if it differs, its framework quirks ("this package uses Vitest, not Jest"), generated-code directories to leave alone, and pointers to its README or docs. Five to twenty lines each is typical. When a nested file grows past that, the package probably needs its docs reorganized, not a bigger CLAUDE.md.

Use @imports for the long stuff

Reference material - API docs, architecture notes, runbooks - does not belong in any always-loaded file. Put it in a normal markdown file and mention it with an @path/to/doc.md import in the package file, or reference it in the task itself. The agent reads it when it needs it instead of paying for it on every prompt.

Per-package settings

The same layering applies to .claude/settings.json: a committed root file for shared permission allowlists, and nested settings where a package genuinely differs - the infra package that runs terraform plan needs different allowances than the docs package.

The failure modes to avoid

• Duplicated rules. If the same rule appears in root and three nested files, they will drift. Say it once at the highest level where it is true.

• Contradictions. "Always use npm" at the root and "use pnpm" in a package teaches the agent to guess. Nested files override, but contradictions still waste turns.

• A root file that documents everything. That is what wikis are for. CLAUDE.md is operating rules, not documentation.

The short version

Root CLAUDE.md for shared rules, nested CLAUDE.md files for package-local facts, @imports for reference material, nested settings for package-specific permissions. Context that follows the work stays small, cheap, and correct.

Want the monorepo layout pre-built? The Agentic Coding Kit ships root and nested CLAUDE.md templates, per-package settings baselines, and import patterns - 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

Where the settings live

Three files, checked in order, later ones win:

• ~/.claude/settings.json - your global defaults, every project

• .claude/settings.json - project settings, commit this one so the team shares it

• .claude/settings.local.json - project settings for just you, gitignore it

Put shared allowlists in the committed project file. Put your personal preferences (your editor, your scratch scripts) in the local one.

The allowlist syntax

Permissions are pattern rules in three lists: allow, deny, and ask. A rule names the tool and the argument pattern:

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(*)",
      "Edit(src/**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./.env*)"
    ]
  }
}

Order of evaluation: deny beats everything, then ask, then allow. A command matching nothing falls back to the default - which is the prompt you are trying to escape. :* means any arguments; a bare pattern means exactly that command.

What belongs on the allowlist

Read-only and reversible commands. A good test: could a new hire run this on day one without breaking anything? Test runners, linters, type checks, git inspection commands, build commands. Those are the prompts that interrupt you fifty times a day, and they are the safe ones.

File edits scoped to source directories (Edit(src/**)) are usually fine too - the changes are visible in git diff before you commit them. That is the review step that makes the permission unnecessary.

What never goes on the allowlist

• git push and anything that publishes. Keep it on ask. Publishing is the one step where a mistake leaves the building.

• Destructive filesystem commands. rm -rf belongs on deny, not allow. An agent that can delete freely will eventually delete the wrong thing confidently.

• Secrets files. Deny Read on .env, credential stores, and key material. Context that includes your secrets can end up in a prompt log or a generated file.

• Anything piped from the network. curl ... | bash should require a human every time.

The trap: allowlisting everything

The frustrated response to prompt fatigue is "allow": ["Bash(*)"]. That converts the tool from supervised to unsupervised. The prompts are annoying precisely because they catch the moments that matter - the unexpected DROP TABLE inside a migration helper, the force-push hidden in a "fix the branch" request. Allowlist the boring 90% so you actually read the prompts on the dangerous 10%.

Team-level settings

Commit .claude/settings.json with the repo and new contributors inherit a sane baseline: tests and linters pre-approved, pushes and deletes gated, secrets unreadable. It is the same philosophy as a committed .editorconfig - one less thing every person configures alone. Review changes to it in pull requests like you would CI config, because it controls what automation can do unsupervised.

The short version

Prompt fatigue comes from a default that trusts nothing. Fix it with a permissions block: allowlist read-only and reversible commands, keep publishing and deletion behind ask, deny secrets outright, and commit the project file so the team shares one baseline.

Want the settings file pre-built? The Agentic Coding Kit ships a tuned settings.json permissions baseline, CLAUDE.md templates, and hook configs - 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

Fix 1: Shrink CLAUDE.md

Every line of CLAUDE.md rides along on every single prompt. A 600-line file costs you on each message whether it is relevant or not. Keep it under 200 lines: rules only, no history, no API docs. Move reference material to separate files and import them when needed with @docs/file.md mentions in a task, not in the always-loaded file.

Fix 2: Add a .claudeignore

When Claude Code searches your repo, it searches everything it can see - including node_modules/, build output, and 40,000-line lockfiles. A .claudeignore file (same syntax as .gitignore) keeps searches fast and their results small:

node_modules/
dist/
build/
coverage/
*.lock
package-lock.json
*.min.js
public/assets/

Fix 3: Reference files directly

"Find the authentication code and fix the token refresh" triggers a search-and-read sweep across the repo. "@src/auth/token.ts - the refresh logic here loops on 401" skips it. The search is the expensive part, not the edit. Point at files you already know.

Fix 4: Smaller tasks, fresher sessions

A long session accumulates dead context: every file read, every dead end, every abandoned approach stays in the conversation and gets re-sent with each prompt. Symptoms: responses get slower and vaguer as the session ages. Run /clear between tasks. One task per session is not too fine-grained - it is the default that keeps each prompt cheap.

Fix 5: Audit MCP servers and hooks

Every connected MCP server injects its tool schemas into every prompt. Three servers you tried once and forgot about can cost more context than your CLAUDE.md. List what is connected, remove what you do not use weekly. The same goes for hooks that dump large outputs into context on every tool call - keep hook output to a line or two.

Fix 6: Measure before optimizing

Run /cost (or your client's usage view) before and after each change. The fix that matters depends on your repo: a monorepo with no ignore file is Fix 2; a year-old CLAUDE.md is Fix 1; a week-long session is Fix 4. Guess and you will optimize the wrong one.

The short version

Context is the currency. Spend it on the task, not on re-reading lockfiles and month-old conversations. A lean CLAUDE.md, a .claudeignore, direct file references, and short sessions cover most of the waste.

Want the lean setup pre-built? The Agentic Coding Kit ships a tight CLAUDE.md baseline, ready-made .claudeignore templates, and hook configs tuned to stay quiet - 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

Cause 1: You are still using .cursorrules

The single .cursorrules file at the repo root is the legacy format. Cursor has moved to the .cursor/rules/ directory of .mdc files, and the legacy file is on the deprecation path - some versions load it, some ignore it, and it never gets the scoping features. If your rules live in .cursorrules, migrate them first. The new format adds frontmatter that controls when the rule applies:

---
description: Next.js App Router conventions
globs: src/app/**/*
alwaysApply: false
---

- Server Components by default; add "use client" only for interactivity.
- Data fetching in the page or layout, not in client components.
- Route handlers in route.ts, never pages/api.

Cause 2: No glob scoping, so rules compete

A rule file with no globs and alwaysApply: false is matched by description alone - Cursor decides from the description whether the rule is relevant to the current file. Vague description, rule skipped. Scope each rule to the paths it governs:

---
description: Database migration safety
globs: prisma/migrations/**/*, db/migrations/**/*
alwaysApply: true
---

- Never edit an existing migration. Create a new one.
- Destructive changes (DROP, column removal) need a comment explaining the rollback.

Cause 3: alwaysApply everywhere (or nowhere)

alwaysApply: true puts the rule in every prompt. Set it on ten files and you have recreated the 900-line CLAUDE.md problem - every rule diluted by every other rule. Reserve alwaysApply for the handful of project-wide rules (package manager, test command, forbidden paths). Everything else gets a glob.

Cause 4: Contradictory rule files

Two rules that disagree ("use default exports" in one, "named exports only" in another) do not average out - the model follows whichever loaded last or reads louder in context. Audit the whole .cursor/rules/ directory the way you would review a diff: one owner per decision, overlaps merged, losers deleted.

Cause 5: Prose instead of rules

Same failure as every agent config: "try to keep things tidy and consistent" is untestable. Working rules are one line, trigger plus action:

- Always run `pnpm test:unit` before declaring a task done.
- When you add a component, add a story in the same folder.
- Never import from @/legacy in new code.

Verify like you would any config

After changing rules, open a file the rule should govern and ask: "Which rules apply to this file?" Cursor will list them. A missing rule means a loading problem (Causes 1-3), not a behavior problem - fix the config before blaming the model.

Want the migration done for you? The Agentic Coding Kit ships ready-made .mdc rule packs for Next.js, Python, Go, and more - with glob scoping and alwaysApply already set correctly - plus CLAUDE.md templates and hook configs. 34 files, $19 one-time. A free Next.js .mdc example is on GitHub.

Cause 1: The file is not actually loaded

Claude Code reads CLAUDE.md from specific places: the project root (./CLAUDE.md), your user home (~/.claude/CLAUDE.md), and parent directories of where you launched it. A file named claude.md on a case-sensitive filesystem, sitting in docs/, or created after the session started will be silently ignored.

Check what is loaded with the /memory command inside Claude Code. It lists every memory file in play. If yours is not listed, nothing else in this post matters until you move it.

Cause 2: The file is too long

CLAUDE.md goes into the context of every single prompt. A 900-line file is not documentation; it is noise your actual instructions drown in. The model weights recent, short, clearly formatted text. Your rule about migrations is competing with 850 lines of architecture history.

Target under 200 lines. Move reference material out to separate files and pull it in only when needed with imports:

# CLAUDE.md
See @docs/api-conventions.md when editing anything under src/api/.

Cause 3: Your rules are prose, not rules

"We generally prefer to keep components reasonably small and consistent with the existing style" is a wish. The agent cannot test it, so it cannot follow it. Rules that work have a trigger and an action:

## Rules
- Run tests with `pnpm test:unit`, never `npm test`.
- When you add an API route, also add a zod schema in schemas/.
- Never edit files under generated/ - run `pnpm codegen` instead.
- Components stay under 150 lines. Extract helpers when you hit the limit.

One line per rule. Start with Always, Never, or When. If you cannot phrase it as a condition and an action, it does not belong in the file.

Cause 4: Contradictions across your config

If CLAUDE.md says "use tabs," .cursorrules says "use spaces," and your first prompt says "match existing style," the agent picks whichever instruction is loudest in context - usually not the one you meant. Audit every instruction file in the repo (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, AGENTS.md) and make them agree, or delete the losers.

Cause 5: You never verified, so drift went unnoticed

Memory is advisory. In a long session the model can literally forget mid-conversation. Two habits fix this:

• Start sessions with: "What rules from CLAUDE.md apply to this task?" A wrong answer means a loading problem (Cause 1), not a behavior problem.

• For rules that must never break - do not touch .env, never force-push, always run the linter - use a hook instead of memory. Hooks run as code, not as suggestions. A PreToolUse hook blocks the action no matter what the model decided:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *.env*) echo 'Blocked: .env files are read-only for agents' >&2; exit 2;; esac; exit 0"
      }]
    }]
  }
}

Full hook configs, including plan-gating and legacy-path protection, are in the hooks examples post.

The short version

Check /memory first. Then shorten the file, sharpen the rules into trigger-action lines, kill contradictions, and move the non-negotiables into hooks. A CLAUDE.md that fits on one screen, written in imperatives, with hooks behind it, is followed. A long one, written in prose, is decoration.

Want this pre-packaged? The Agentic Coding Kit ships a tight CLAUDE.md baseline, five stack-specific templates, hook configs, and review checklists - 34 files, $19 one-time. Or start free with the CLAUDE.md generator.

Here are five fixes, ordered from "do this today" to "belt and suspenders."

Why it happens

The agent is optimizing for "task looks complete," not "diff stays small." Anything that plausibly blocks the task - an outdated helper, a mismatched type, a TODO comment - looks like part of the job. Telling it "be careful" does nothing, because careful is not measurable. Scope is.

Fix 1: A scope rule in CLAUDE.md

Put an explicit boundary at the top of your CLAUDE.md, phrased as a rule with an action:

## Ground rules

- Stay in scope: touch only the files the task requires.
  If you believe a change outside the diff is needed, stop and ask first.
- Never modify: .env*, migrations/, generated/, package-lock.json.

This alone cuts the problem down noticeably. It is still advisory - the agent can forget it in a long session - which is why the next fixes exist.

Fix 2: Permission deny rules in settings.json

Claude Code supports permission rules that flat-out deny tool calls against path patterns. In .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Edit(.env*)",
      "Edit(migrations/**)",
      "Write(migrations/**)",
      "Edit(package-lock.json)"
    ]
  }
}

Denied calls fail no matter what the agent decides mid-task. This is the right place for files that should never change: environment files, lockfiles, generated code, migration history.

Fix 3: A PreToolUse hook for judgment calls

For anything subtler than "never touch this," a hook can intercept every edit and apply your own logic. This one blocks edits to any file under src/legacy/ unless a plan file exists:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *src/legacy/*) test -f .claude/plan.md || { echo 'Blocked: src/legacy changes need .claude/plan.md' >&2; exit 2; };; esac; exit 0"
      }]
    }]
  }
}

Exit code 2 blocks the call and feeds the message back to the agent, so it learns the boundary instead of silently failing.

Fix 4: Require a plan before edits

Most scope creep happens when the agent starts editing before it has a plan. A one-line hook flips the order: no .claude/plan.md, no edits. The agent writes the plan, you glance at it, and the diff that follows matches the plan you approved.

Fix 5: A review checklist you actually run

Constraints reduce the problem; review catches what leaks through. Keep a short list in the repo and make "diff reviewed against it" part of done:

- [ ] Diff touches only files named in the task or plan
- [ ] No changes to .env, lockfiles, migrations, generated code
- [ ] Tests pass; new behavior has a failing-then-passing test

Putting it together

The reliable setup is layered: CLAUDE.md sets expectations, deny rules hard-block the untouchable files, a hook enforces process, and a checklist catches the rest. Each layer is a few lines of config. Together they turn "please stay in scope" into something structural.

This post first appeared on the Kitforge blog. Kitforge makes The Agentic Coding Kit - 34 drop-in templates (scope rules, deny lists, hook configs, review checklists) that make AI coding agents behave like senior teammates. The CLAUDE.md templates and hooks pack are free on GitHub.

1. Freeze the dependency tree

The single most common agent surprise: a new package appears in package.json because the agent "needed" it. It didn't. The rule is one line: never add a dependency without asking. This lives in your CLAUDE.md or rules file, and the serious version is a hook that blocks edits to lockfiles outright.

Every dependency is a supply-chain decision, a license decision, and a maintenance decision. An agent optimizing for "make the test pass" will happily import a 2019 package with three CVEs.

2. Scope the edit surface

Tell the agent where it's allowed to work. "Only touch files under src/features/checkout/" turns a possible repo-wide refactor into a reviewable diff. Claude Code's subdirectory CLAUDE.md files and Cursor's glob-scoped rules both exist for this - a rule placed in a folder only activates when the agent works there.

3. No tests, no "done"

Agents are optimists. Left alone, "done" means "the code is written." The fix is a definition of done with teeth: a task is finished when the tests pass and you've shown the output. Pair it with a PostToolUse hook that runs your fast test suite after every edit and the optimism problem mostly disappears.

4. Protect the files agents love to break

Every repo has them: .env, migrations, CI configs, the generated lockfile, the one legacy file held together by hope. List them by name. A PreToolUse hook can hard-block edits:

"matcher": "Edit|Write",
"command": "jq -r '.tool_input.file_path' | grep -qE '\\.env|migrations/|package-lock' && echo 'Blocked: protected file' >&2 && exit 2 || exit 0"

The agent routes around the block - that's the point. It asks you instead of apologizing later.

5. Keep the audit trail

When something breaks at 5 PM, "the agent did it" is not an answer. Two cheap habits: a hook that appends every bash command to a log file, and a rule that commits stay small and frequent so git log tells the story. Both take minutes to set up and pay off the first time you need them.

6. Humans own the irreversible steps

Force-pushes, schema migrations against production, deleting branches, publishing packages, deploying: these are the human's job. Write it down. Agents are excellent at preparing these steps - the migration file, the release notes, the deploy command - and should stop one step short of running them.

The pattern underneath

None of these are about making the agent smarter. They're about making the environment honest: fast feedback (tests), hard boundaries (hooks, scopes), and a paper trail (logs, small commits). A mediocre agent in an honest environment beats a brilliant agent in a chaotic one.

All six, pre-built: the Agentic Coding Kit ships these guardrails as drop-in CLAUDE.md sections and ready-made hooks, plus 28 more templates - $19 one-time. Or start free with the Kitforge generator.

Cross-posted from the Kitforge blog.

The short version

• CLAUDE.md is read by Claude Code (the terminal agent) at session start and stays in context the whole session. Best for long-horizon instructions: build commands, workflows, definition of done.

• .cursorrules (legacy) or .cursor/rules/*.mdc (modern) attach per-request in the Cursor editor. Best for inline-edit behavior: style, import rules, per-filetype conventions.

Both support nesting: Claude Code loads subdirectory CLAUDE.md files when it touches those files; Cursor rules use glob patterns to decide what attaches.

CLAUDE.md: the session constitution

Claude Code reads CLAUDE.md at session start and keeps it in context the whole time. That makes it the right place for things the agent must never forget:

• Build, test, and lint commands (so it stops guessing)

• Commit and PR conventions

• Hard prohibitions: don't touch .env, don't add dependencies, don't reformat untouched files

• Definition of done: "run the tests before you say finished"

Because sessions run long and edit many files, brevity matters: a 300-line CLAUDE.md gets skimmed like any long document. Keep the root file under ~100 lines and push detail into subdirectory files and slash commands.

.cursorrules: the pair-programmer's margin notes

Cursor's rules attach to individual requests. The modern .cursor/rules/*.mdc format lets each rule declare when it applies: always, when matching file globs are open, or only when invoked. That makes Cursor rules the right place for:

• Per-language style ("React components use named exports")

• Import and path conventions

• Framework-specific patterns that only matter when that framework's files are open

The legacy single .cursorrules file still works, but it applies to everything - the same skim problem as a long CLAUDE.md. New setups should use the rules directory.

Running both without going insane

Teams using both tools hit the same trap: two files drift apart, and each tool learns a different version of your conventions. Three rules prevent it:

1. One source of truth for the overlap. Put shared conventions in CLAUDE.md and make the Cursor rule a three-liner that says "read CLAUDE.md." Both tools can read files.

2. Tool-specific rules stay tool-specific. Cursor's inline-edit rules mention Cursor features; Claude Code's workflow rules mention slash commands and subagents.

3. Review rules changes like code changes. A sloppy rule costs you every session after you merge it.

What about AGENTS.md?

AGENTS.md is the emerging cross-tool standard (Codex, Amp, and others read it; Cursor and Claude Code can be pointed at it). If your team uses three or more tools, AGENTS.md as the shared file plus tiny tool-specific stubs is the cleanest 2026 setup. The content principles don't change - only the filename does.

Skip the blank page: the Agentic Coding Kit ships paired CLAUDE.md and .cursorrules templates that stay in sync by design, plus subdirectory scoping examples, subagent configs, and review checklists - 34 files, $19 one-time. Or build a free baseline with the Kitforge generator.

Cross-posted from the Kitforge blog.

Here are five hooks worth copying and what each one fixes.

How hooks work in 60 seconds

Hooks are defined per event. The two you'll use most:

• PreToolUse - runs before a tool call. Exit code 2 blocks the call and feeds your message back to the agent.

• PostToolUse - runs after a tool call. Perfect for formatters and tests.

Each hook gets a matcher (a regex against the tool name) and a shell command that receives JSON about the call on stdin.

1. Block edits to .env files

Fixes: the agent cheerfully pasting a live API key into a committed file.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | grep -q '\\.env' && echo 'Blocked: never edit .env files' >&2 && exit 2 || exit 0"
      }]
    }]
  }
}

Exit code 2 means "block this and tell the agent why." The agent adjusts immediately instead of you discovering the problem after commit.

2. Run the test suite after every code edit

Fixes: the agent declaring victory with broken tests.

"PostToolUse": [{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.file_path' | grep -qE '\\.(ts|js|py)$' && npm test --silent || exit 0"
  }]
}]

Scope it to your fast unit tests, or pair it with a Stop hook for the slow pass.

3. Auto-format on write

Fixes: style drift and lint noise in review.

"PostToolUse": [{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "command": "f=$(jq -r '.tool_input.file_path'); npx prettier --write \"$f\" >/dev/null 2>&1; exit 0"
  }]
}]

The agent never sees this happen. Your diffs stay clean.

4. Require a plan file before edits

Fixes: the agent spray-editing eight files when you wanted a two-line change.

"PreToolUse": [{
  "matcher": "Edit",
  "hooks": [{
    "type": "command",
    "command": "test -f .claude/plan.md || { echo 'Blocked: write .claude/plan.md first' >&2; exit 2; }"
  }]
}]

Brutal, but effective for big refactors. Delete the plan file when you want freeform mode back.

5. Log every bash command

Fixes: the "what did it actually do?" archaeology session.

"PreToolUse": [{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.command' >> .claude/bash-history.log; exit 0"
  }]
}]

Add .claude/*.log to .gitignore and you get a full audit trail for free.

The gotchas nobody mentions

• Hooks run with your permissions. A bad hook can break every tool call. Test the command standalone first.

• Keep them fast. A 10-second test suite on every edit makes the agent feel broken. Move slow checks to the Stop event.

• Only stderr + exit 2 reaches the agent. Write for that channel.

Want these without the config archaeology? The Agentic Coding Kit ships a ready-made hooks pack plus 29 other templates - $19 one-time, drop into any repo. Or generate a free CLAUDE.md baseline with the Kitforge generator.

Cross-posted from the Kitforge blog.

1. Community directories

Sites like cursor.directory collect rules by framework and language. Good for seeing conventions and stealing phrasing. The weakness: most entries are unreviewed, so popularity tracks "posted early" more than "works well." Treat them as inspiration, not gospel.

2. Awesome-lists on GitHub

Several awesome-cursorrules repos collect files per stack. Same caveat as directories, plus bit-rot: rules written for 2024 models often fight 2026 behavior. Check the last commit date before copying anything.

3. Generators

Rules generators ask about your stack and emit a tailored file. This beats copying a stranger's file because the output names YOUR tools, not theirs. The best use of a directory is as a checklist of topics to include; the best source of the actual text is a generator or your own hand.

The 60-second quality test

Before you adopt any rules file, scan it for four things:

Specificity. "Write clean code" is noise. "Use the existing cn() helper for conditional classes" is a rule.

Brevity. Over about 100 lines the model skims, like people do. Long files should move detail into scoped .cursor/rules files.

Negative rules. The highest-value lines are prohibitions: don't add dependencies, don't reformat untouched code, don't commit .env.

A definition of done. "Run the tests before declaring finished" saves more time than any style rule.

When to write your own

Always, eventually. Borrowed rules describe someone else's repo. Start from a template or generator output, then add a line every time the AI annoys you twice. After a month you have a rules file that fits like a glove - and it took five minutes at a time.

Start here: the free Kitforge generator builds a CLAUDE.md or .cursorrules for your stack in about a minute, with a shareable link for your team. For the deep bench - subagents, slash commands, review checklists, git hooks - the Agentic Coding Kit is 34 templates for $19, one-time.

Cross-posted from the Kitforge blog.

The template

# Project
[One sentence: what this repo is and who uses it.]
Stack: [Next.js 15 / FastAPI / Rails - name exact versions]
Package manager: [pnpm / uv / poetry - the agent will guess wrong]

# Hard rules
- Make the smallest change that satisfies the request. Do not
  refactor untouched code.
- Only use dependencies already in the project. Name any new one
  and stop before adding it.
- Never commit .env, credentials, or anything under /secrets.
- Match existing style: [quote style, naming, import order - point
  at a reference file]

# Architecture
- [Where things live: app/, src/, lib/, and what belongs in each]
- [The boundaries: what never imports from what]

# Testing
- Run tests with: [exact command]
- A task is not done until tests pass. Show the output.
- New behavior needs a test that fails without the change.

# When stuck
If two approaches fail, stop and describe the blocker in plain
language. Do not improvise a third approach.

Why each section earns its place

Project + stack. The agent hallucinates versions constantly. Naming "pnpm" alone prevents a class of lockfile corruption.

Hard rules. Prohibitions outperform suggestions. "Never commit .env" stops a leak; "be careful with secrets" does not. Every rule here should be a scar from a real incident - yours or someone else's.

Architecture. Without boundaries, the agent puts new code wherever the cursor was. Two lines of "what lives where" prevent the slow sprawl that makes a repo unreviewable.

Testing. The single most important line in any rules file is the requirement to show test output. Agents that must show evidence stop declaring victory over red suites.

When stuck. This is the safety valve. An agent with permission to stop asks good questions. An agent without it guesses, and guesses on load-bearing decisions are how databases get dropped.

.cursorrules vs .cursor/rules

Cursor is moving to a .cursor/rules/ directory where each file can carry a glob scope (e.g. Python rules that only load for *.py files). The template above works in both places. If you use the directory, split it: general.mdc for the hard rules, one file per stack section.

Want this tailored to your stack instead of templated? The free Kitforge generator asks five questions and emits a ready-to-paste file. For the full system - CLAUDE.md presets, subagents, slash commands, hooks, review checklists - the Agentic Coding Kit has all 34 files for $19 one-time.

Cross-posted from the Kitforge blog.

1. The general starter

Fixes: the AI rewriting half your file to change one line, and inventing libraries you do not use.

Make the smallest change that satisfies the request. Do not refactor
surrounding code unless asked.
Only use dependencies already in the project. If a new one seems
necessary, stop and name it first.
Match the existing code style: quote style, indentation, naming.
When the request is ambiguous, ask one question instead of guessing.

2. The Next.js / React ruleset

Fixes: client components creeping everywhere, and data fetching in the wrong layer.

This is a Next.js App Router project with TypeScript and Tailwind.
Default to server components. Add "use client" only when the component
uses state, effects, or browser APIs.
Fetch data in server components or route handlers, never in useEffect.
Use the existing cn() helper for conditional classes.
Forms use react-hook-form with zod schemas from /lib/validators.

3. The Python ruleset

Fixes: untyped function soup and print() debugging left in commits.

Python 3.12, type hints on all public functions, pydantic for data
shapes. No bare except. Use structlog, never print.
Tests go in tests/ and use pytest fixtures from conftest.py.
Functions over classes unless the class models a real entity.
Keep functions under 40 lines; extract helpers rather than nesting.

4. The API discipline ruleset

Fixes: breaking API contracts silently and inconsistent error shapes.

Never change a public endpoint's request or response shape without
updating openapi.yaml in the same change.
All errors return {"error": {"code", "message"}} with the right HTTP
status. No stack traces in responses.
Validate input at the boundary with zod; trust nothing downstream.
New endpoints need at least one integration test.

5. The git and commit ruleset

Fixes: the AI staging unrelated files and writing novels in commit messages.

When asked to commit: stage only files you changed for this task.
Commit messages are imperative, under 72 characters, no emoji.
Never commit .env files, credentials, or files under /secrets.
Never force-push or amend published commits unless explicitly told.

How to combine these

Start with the general starter, then add the stack-specific block that matches your project. Keep the whole file under about 100 lines - long rules files get skimmed by the model just like long READMEs get skimmed by people. Put the rules that hurt most when broken at the top.

One caveat: Cursor is phasing in .cursor/rules directory files with per-file glob scoping, which is the better long-term home for stack rules. The same text works in both places.

Want a tailored file instead of a template? The free Kitforge generator builds a CLAUDE.md or .cursorrules for your stack in about a minute. And the Agentic Coding Kit ships 34 ready-made rules, subagents, and workflows for $19 one-time.

Cross-posted from the Kitforge blog.

1. Write the rules down before you prompt

An empty CLAUDE.md means the agent infers conventions from whatever file happens to be open. Put your stack, style rules, and prohibitions in CLAUDE.md once, and every session starts aligned. Five minutes here saves an hour of review.

2. Scope every task to one diff

"Add auth" spirals. "Add a login endpoint that takes email and password and returns a session token" ships. If you cannot describe the change in one sentence, split it.

3. Make the agent run the tests

Never accept "the tests pass" as a claim. Require the command output in the reply. Agents that must show evidence stop declaring victory over red suites.

4. Review the diff, not the summary

Agent summaries are optimistic by construction. The diff is the truth. Build the habit: summary first for orientation, diff before approval.

5. Give it a way to stop

Tell the agent what to do when it is stuck: "if two approaches fail, stop and describe the blocker instead of trying a third." Without this, a stuck agent improvises, and improvisation is where the destructive commands come from.

6. Keep secrets out of reach

No .env in context, no credentials in prompts, and a pre-commit hook that blocks secret-looking strings. The agent cannot leak what it cannot read.

7. Use subagents for specialist jobs

A reviewer subagent with a strict checklist outperforms "now review your work" every time. Named specialists in .claude/agents/ get their own context and their own rules.

8. Turn repeated instructions into slash commands

If you typed it twice this week, make it a file in .claude/commands/. /review, /test, /changelog - one word instead of a paragraph, and the same quality bar every time.

9. Reset early, reset often

Long sessions decay. When the thread fills with dead ends, /clear and restart with a crisp task and the rules file. A fresh context with good instructions beats a long context with baggage.

All nine ship as ready-made files in the Agentic Coding Kit - CLAUDE.md presets, subagents, slash commands, hooks, and review checklists for Claude Code and Cursor, $19 one-time. Or start free: the Kitforge generator builds a tailored rules file for your stack in about a minute.

Cross-posted from the Kitforge blog.

Why bother: specialization keeps the main context clean and makes output more consistent. A reviewer subagent with a strict checklist produces the same shape of review every time, no matter what else happened in the session.

The file format

Each subagent is one Markdown file with frontmatter: a name, a description of when to use it, and the system prompt body. Drop it in .claude/agents/ and Claude Code picks it up automatically.

1. The diff reviewer

---
name: reviewer
description: Reviews a diff before it is called done. Use after any code change.
---
You are a strict code reviewer. Given a diff, check:
- Correctness: does the change do what the task asked, nothing more?
- Tests: is there a test that fails without this change?
- Style: does it follow the rules in CLAUDE.md?
- Risk: anything that touches auth, payments, or migrations gets flagged.
Report findings as a numbered list, most severe first. If clean, say so in one line.

2. The test writer

---
name: test-writer
description: Writes tests for a module. Use when new code lacks coverage.
---
Write tests for the specified module. Cover the happy path, one edge
case per branch, and one failure mode. Use the repo's existing test
framework and fixtures. Do not change the code under test. If a bug
surfaces while writing tests, report it instead of fixing it.

3. The security pass

---
name: security-pass
description: Audits a change for secrets, injection, and unsafe file ops.
---
Review the change for: hardcoded secrets or tokens, unsanitized input
reaching shell commands or SQL, file operations outside the project
root, and new network calls to unknown hosts. Report each finding with
the file and line. Never modify code in this pass.

4. The docs writer

---
name: docs-writer
description: Updates README and docs after a behavior change lands.
---
Given a merged change, update the README and any affected docs.
Match the existing tone. Add or fix examples so they reflect the new
behavior. Do not document unreleased flags or internal helpers.

How they work together

The main agent keeps the big picture. When it finishes an implementation, it hands the diff to reviewer. Reviewer findings go back to the implementer. Once clean, test-writer fills coverage gaps, security-pass audits anything touching input or files, and docs-writer tidies up. Each specialist sees only what it needs, so nobody's context window fills with the other five steps.

Two practical notes. Keep each subagent's scope narrow enough to describe in one sentence - broad subagents degrade into a second generalist. And restrict tools where you can: a reviewer that cannot edit files will never "fix" something while reviewing it.

These four definitions ship ready-made in the Agentic Coding Kit - 34 templates, rules and workflows for Claude Code and Cursor, $19 one-time. Or start free: the Kitforge generator builds a tailored CLAUDE.md or .cursorrules for your stack in about a minute.

Cross-posted from the Kitforge blog.

Claude Code and other agentic coding tools can spawn subagents: separate agent instances that get a slice of the work, their own context window, and a narrow job description. Used well, subagents are how you get parallel speed without the main agent losing the plot. Used badly, they are how you get five half-finished refactors that don't compile together.

After running subagent-heavy workflows on real codebases for months, here are the patterns that hold up.

Pattern 1: Scout agents for read-only exploration

The cheapest, safest subagent is one that can only read. Send it to answer a question like "where is authentication enforced in this repo?" or "what breaks if I change this interface?"

Why it works: the scout burns its own context on the boring traversal - opening 30 files, tracing imports - and returns a 10-line answer. Your main agent's context stays clean for the actual work.

Rules that keep scouts useful:

• Give it a question, not a task. "Map the billing flow" not "refactor billing."
• Cap the output. "Return the file paths, the key functions, and a 5-sentence summary."
• Forbid writes entirely. A scout that edits is no longer a scout.

Pattern 2: Worker agents with a definition of done

A worker subagent gets a concrete, verifiable task: "add input validation to these three endpoints, with tests that fail before and pass after." The key is that the task must be checkable without judgment.

If you can't write the done-condition in one sentence, the task isn't ready to delegate. Split it further or do it yourself.

The playbook version I use:

1. Scope: exact files or directories it may touch.
2. Done condition: the command that must pass (e.g. npm test -- billing).
3. Budget: stop and report after N minutes or M failed attempts, instead of spiraling.

That third one is the one everyone skips. An unbounded worker will confidently produce 800 lines of wrong. A bounded one reports "stuck, here's what I tried" and costs you two minutes.

Pattern 3: The reviewer is not the author

Never let the agent that wrote code be the agent that reviews it. Same context, same blind spots. A fresh reviewer subagent, given only the diff and the requirements, catches things the author agent sailed past - because it has no sunk cost in the approach.

This mirrors human teams for a reason. The kit's review checklist templates exist to give the reviewer agent the same bar every time: error handling, injection surface, migration safety, test quality.

What to never delegate

Some work should stay with the main agent (or with you):

• Deciding what to build. Subagents execute judgment; they shouldn't create it.
• Cross-cutting design. Anything that changes contracts between modules needs one coherent mind.
• Final review before merge. Delegated review is a filter, not a gate. The last pass belongs to whoever owns the outcome.
• Secrets and destructive ops. Permission guardrails should make this impossible, not just discouraged.

The coordination tax

Every subagent adds overhead: you write a brief, wait, and integrate the result. If the task takes less time than the brief, do it inline. My rule of thumb: delegate when the subtask needs more than ~10 minutes of focused work or a separate context window's worth of reading.

The win isn't parallelism for its own sake. It's keeping the main agent's attention on the decisions while the grunt work happens in quarantined contexts.

The full subagent playbooks - scout, worker, reviewer templates with done-conditions, budgets, and integration checklists - are in The Agentic Coding Kit, along with the CLAUDE.md template and permission guardrails that make delegation safe. One-time $19, lifetime updates.

I have reviewed a lot of these files, and the bad ones fail in predictable ways. They are either novels nobody would read, wish lists with no enforcement, or walls of style rules the model ignores because nothing says what matters most. Here is the structure that actually works, section by section.

1. Identity and mission (2-3 sentences, no more)

Open with what the project is and what the agent's job is. Not marketing copy - operational context.

This is a B2B invoicing API in TypeScript (Fastify + Postgres). You are the
primary maintainer. Prioritize correctness of money math over speed. When in
doubt, ask before changing anything under /billing.

That last line does real work. It tells the agent where the blast radius is.

2. Commands that must work

The agent will run things. Tell it exactly which commands are the source of truth so it does not invent npm run test:quick and hallucinate success.

- Install: `pnpm install`
- Test: `pnpm test` (must pass before every commit)
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`

Agents are surprisingly obedient here. If you give them the exact command, they run the exact command. If you do not, they guess, and guesses fail silently.

3. Hard rules, stated as rules

This is where most files go soft. "Try to avoid committing to main" is a suggestion. Write rules like a linter would:

- NEVER commit directly to main. Always create a feature branch.
- NEVER use `git push --force` on shared branches.
- NEVER commit files matching .env* or containing API keys.
- ALWAYS run `pnpm test` before committing. No exceptions.

The ALL-CAPS markers are not for style. Models weight emphatic, absolute language more heavily, and these are the rules you most want to survive a long context window.

4. Architecture map (the 60-second version)

Agents waste enormous effort exploring. Give them the map:

/src/routes - HTTP handlers, thin by design
/src/domain - business logic, no I/O allowed here
/src/db - migrations and queries
/tests - mirrors /src structure

Five lines saves dozens of exploratory tool calls per session.

5. How to verify work

This is the section almost everyone skips, and it is the one that changes behavior the most. Define what "done" means:

A task is done when: tests pass, typecheck is clean, the commit message
follows conventional commits, and you have re-read your own diff for
obvious mistakes.

Without this, agents declare victory after the code compiles. With it, they self-review.

6. What the agent is NOT allowed to do

Boundaries prevent the most expensive mistakes:

Do not: modify CI configuration, change database migrations that have
already been applied, add dependencies without asking, or touch anything
under /infra.

What to leave out

Three things do not belong in CLAUDE.md: your entire style guide (link it), exhaustive API docs (the agent can read code), and anything you would not enforce in review (every unenforced rule teaches the model that rules are optional).

The test of a good one

Read your CLAUDE.md and ask: if a talented contractor read only this file, could they work in this repo without asking me a single question for the first hour? If not, that gap is exactly what your agent is silently guessing about.

If you want this structure without writing it from scratch, I packaged a production-tested version into the Agentic Coding Kit - a CLAUDE.md template with these six sections, plus the git hooks that enforce the hard rules even when the model forgets them, review subagents, and slash commands. But the anatomy above is the real takeaway: identity, commands, hard rules, map, definition of done, boundaries. Everything else is decoration.