Start with a rules file. Seriously.
One repository, one agent, one person, conventions that rarely change — a CLAUDE.md is the right tool and Coderbuds would be overkill. We use rules files ourselves. This page is about the specific point where they stop scaling, which is earlier than most teams expect: the second repo, or the second agent, or the fourth engineer.
Where a rules file starts to leak
1. It drifts, per repo
A file lives in one repository. Ship five services and you have five copies, and they diverge the first time someone fixes a convention in one and not the others. Nobody notices, because nothing compares them.
2. It duplicates, per vendor
CLAUDE.md for Claude Code, AGENTS.md for Codex, .cursor/rules for Cursor. Same intent, three files, three chances to be out of date. Your standard is now a function of which tool a developer happens to prefer.
3. It pays context rent on every session
A rules file loads in full whether or not it is relevant. Your migration conventions are in the window while the agent renames a CSS class. That is why rules files hit a ceiling at a few hundred lines: past that, the guidance competes with the actual task for attention, and the agent starts ignoring parts of it.
4. It never tells you which rules earned their place
This is the one people underrate. A file is unfalsifiable — you write "keep pull requests small", and you never learn whether the teams that followed it shipped faster. So rules accumulate and nothing is ever retired. Every line was someone's good idea once.
Side by side
| Rules file | Coderbuds | |
|---|---|---|
| Scope | One repository | Every repository the team ships to |
| Agent coverage | One file per vendor | Any agent that speaks MCP |
| Repo list & ownership | Hand-maintained, stale | Derived from live shipping data |
| Context cost | Loads in full, every session | An index; bodies fetched on demand |
| Size norms | A number someone guessed | Your team's own merged-PR median and p75 |
| Enforcement | Hope the agent read it | Pre-flight verdict before the PR opens |
| Did it help? | Unknowable | With-versus-without merge time |
| Retiring a bad rule | Nobody dares delete it | Adoption and outcome per rule |
Note the pattern: every row on the right is something that requires seeing both the prompt and the merge. That is the whole difference. A file only sees the prompt; a metrics dashboard only sees the merge.
You keep the file. It just gets shorter
This is not an either/or. Repo-specific facts belong in the repo. What moves out is everything that was duplicated, guessed, or going stale — the repo list, the size norms, the review expectations, the shared conventions. In practice a rules file shrinks to the parts that are genuinely local, plus a pointer:
## How we work
Call get-team-context-tool at session start for the org map and our conventions.
Before opening a PR, call assess-change-fit-tool with the diff numbers.
Fetch the matching get-playbook before writing a description, migration, or tests.
## Local to this repo
Run the worker with `php artisan horizon` — jobs will not process otherwise.
Five lines that never go stale, instead of three hundred that quietly do.
Try it against your own repo
Connect one repository and one agent. Your norms come from your own merged history, so the first verdict you get is about how your team ships — not our opinion of how it should.