# 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.

- **Category:** [Coding](https://stepgleam.com/categories/coding)
- **Difficulty:** Beginner
- **Time:** ~25 minutes
- **Tools:** Claude Code, GitHub
- **Reliability score:** 86/100
- **Steps:** 7
- **Last updated:** 2026-10-28
- **Published:** 2026-10-28

## Tools used

- [Claude Code](https://code.claude.com/docs/en/memory) — Loads CLAUDE.md every session and can update it from review
- [GitHub](https://github.com/apps/claude) — Claude Code GitHub Action used when you tag @claude on a PR

## What you'll get

A checked-in CLAUDE.md that shrinks repeated mistakes, plus a habit of planning before edits and verifying before you merge.

## Who this is for

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.

## Steps

### Step 1: Put one shared CLAUDE.md in the repo and check it into git

**Tool:** Claude Code

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.

[Open step 1](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-1)

### Step 2: Add a rule when Claude makes the same mistake again

**Tool:** Claude Code

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.

**Prompt:**

```
Add a short, concrete rule to CLAUDE.md that would have prevented the mistake we just hit. Do not rewrite the whole file.
```

[Open step 2](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-2)

### Step 3: During review, tag @claude on the PR to capture the learning

**Tool:** GitHub

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.

[Open step 3](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-3)

### Step 4: Start the session in Plan mode, then switch to auto-accept edits

**Tool:** Claude Code

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.

[Open step 4](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-4)

### Step 5: Turn repeated prompts into slash commands under .claude/commands/

**Tool:** Claude Code

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.

[Open step 5](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-5)

### Step 6: Pre-allow safe commands with /permissions instead of skipping all permissions

**Tool:** Claude Code

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.

[Open step 6](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-6)

### Step 7: Give Claude a verification loop before you treat the change as done

**Tool:** Claude Code

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.

**Why this works:** Without a feedback loop, CLAUDE.md rules alone will not catch a broken change.

**Prompt:**

```
Before you finish, run the verification steps for this change (tests, and a browser check if the UI moved) and fix anything that fails.
```

[Open step 7](https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake#step-7)

## Pro tips

- 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 mistakes

- 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.

## FAQ

### Where should the file live?

Project instructions go in ./CLAUDE.md or ./.claude/CLAUDE.md and are shared via git. Personal preferences for one project go in CLAUDE.local.md, which you gitignore.

### What if we already have AGENTS.md?

Claude Code can read AGENTS.md when there is no CLAUDE.md, or you can import it with @AGENTS.md from a thin CLAUDE.md. The docs cover the combinations.

---

Canonical guide: https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake
Read this guide as Markdown: https://stepgleam.com/guides/grow-a-shared-claude-md-from-every-pr-mistake.md