Grow a shared CLAUDE.md from every PR mistake
Check one CLAUDE.md into git, add a rule whenever Claude repeats a mistake, tag @claude on review to capture learnings, start in Plan mode, and give Claude a way to verify its own work.
Tools used
- Claude CodeLoads CLAUDE.md every session and can update it from review
- GitHubClaude Code GitHub Action used when you tag @claude on a PR
Step navigator
A checked-in CLAUDE.md that shrinks repeated mistakes, plus a habit of planning before edits and verifying before you merge.
Teams or solo developers using Claude Code who keep re-explaining the same project rules.
Before you start
Boris Cherny, creator of Claude Code, posted his personal setup on 3 January 2026. InfoQ summarised it, and Claude Code's memory docs now spell out when to add to CLAUDE.md. This guide sticks to that loop: one shared file, updated from real mistakes, with Plan mode and a verification step. Parallel sessions and PostToolUse formatting hooks are already covered in other StepGleam guides, so they are left out here rather than repeated.
Step-by-step instructions
Put one shared CLAUDE.md in the repo and check it into git
Boris: "Share a single CLAUDE.md for the repo. Check it into git, and have the whole team contribute multiple times a week." The Claude Code docs put the same file at ./CLAUDE.md or ./.claude/CLAUDE.md for team-shared instructions. Run /init if you need a starting draft from the codebase, then refine it with rules Claude would not discover on its own. Confirm it loaded with /context.
Why this works
One file means one place to update when Claude gets something wrong.
Add a rule when Claude makes the same mistake again
Boris: "Anytime Claude does something incorrectly, add it to the CLAUDE.md so Claude knows not to do it next time." The docs list the same triggers: Claude makes the same mistake a second time, a code review catches something Claude should have known, or you typed the same correction last session. Keep entries concrete ("Use 2-space indentation", "Run npm test before committing") and under about 200 lines per file.
Add a short, concrete rule to CLAUDE.md that would have prevented the mistake we just hit. Do not rewrite the whole file.
During review, tag @claude on the PR to capture the learning
Boris tags @claude on coworkers' PRs "to add something to the CLAUDE.md as part of the PR" using the Claude Code GitHub Action (/install-github-action). He calls it their version of compounding engineering: each review leaves the next session smarter. InfoQ repeats the same practice from his thread.
Start the session in Plan mode, then switch to auto-accept edits
Boris: "If my goal is to write a Pull Request, I will use Plan mode, and go back and forth with Claude until I like its plan. From there, I switch into auto-accept edits mode and Claude can usually 1-shot it." Enter Plan mode with Shift+Tab twice. He calls a good plan "really important."
Why this works
Planning first keeps CLAUDE.md rules from being ignored mid-refactor.
Turn repeated prompts into slash commands under .claude/commands/
Boris puts daily inner-loop workflows in .claude/commands/ so he does not re-prompt them. His example: /commit-push-pr, used "dozens of times every day", with inline bash that pre-computes git status so the command runs quickly. Commands are checked into git and shared with the team.
Pre-allow safe commands with /permissions instead of skipping all permissions
Boris almost never uses --dangerously-skip-permissions. He uses /permissions to pre-allow bash commands that are safe in his environment (build and test scripts), checked into .claude/settings.json and shared with the team. He reserves the skip-permissions flag for long-running tasks inside a sandbox.
Give Claude a verification loop before you treat the change as done
Boris's most important tip: "give Claude a way to verify its work" with a bash command, a test suite, or a browser/simulator check. He says that feedback loop can improve the final result by a factor of two to three. His concrete example: Claude tests every change he lands to claude.ai/code with the Claude Chrome extension, iterating until the UI works.
Before you finish, run the verification steps for this change (tests, and a browser check if the UI moved) and fix anything that fails.
Why this works
Without a feedback loop, CLAUDE.md rules alone will not catch a broken change.
End of guide · Reviewed Oct 28, 2026
Pro tips2
- Keep the file short; Anthropic's own CLAUDE.md for Claude Code is about 2.5k tokens in Boris's telling.
- Use CLAUDE.local.md (gitignored) for personal sandbox URLs and test data.
Common mistakes2
- Maintaining the same paragraph in CLAUDE.md, AGENTS.md and Cursor rules by hand until they drift.
- Dumping multi-step procedures into CLAUDE.md; the docs say those belong in a skill or a path-scoped rule.
FAQ2
Where should the file live?
What if we already have AGENTS.md?
Related field guides.
CodingReduce attack surface with Claude before you chase individual CVEs
Have Claude inventory what code is reachable by default, before authentication, and under conflicting config options, then gate or feature-flag what you do not need, and prove the change with the project tests.
CodingShip AI-written code you can still explain: own the design, make the agent show its assumptions
Decide the abstractions yourself, pin them in a sketch or diagram, have the agent describe every change and flag what it assumed, then ask it to explain the diff before you commit.
CodingKeep a Claude Code session running on a remote box and steer it from your phone
Run Claude Code inside tmux on a server, use mosh for flaky links, connect Remote Control so you can steer and approve from your phone, and keep your SSH keys out of the agent's reach.