One rulebook for every agent: however well-written, if it sits on your machine it's useless to the team

You sit down and write a meticulous CLAUDE.md for your agent: naming conventions, error handling, the dangerous spots to avoid. Your agent swallows it and from then on works the way you want — clean, consistent.

The problem surfaces in the person next to you's pull request. Their code runs, but follows an entirely different set of conventions. Not because they're sloppy. Because their agent has never read a word of the file you wrote — that file sits on your machine, in your folder, within your agent's reach alone. You wrote rules for the whole house, but hung them in your private room.

01A rulebook reaches only the agents that can read it

This is easy to forget when you're used to working solo: a rulebook has no power beyond what reads it. It isn't an announcement broadcast to the team. It's a file — and a file is loaded only by the agents that can reach it.

When it's just you, that boundary is invisible, because you're the only agent-reader. Your file, your machine, your agent — a perfectly closed loop. Add a second person and that loop breaks without your noticing: now there are two rules files on two machines, and each agent reads only its owner's. Two rulebooks, neither knowing the other exists, both shaping one codebase. The result is identical to having no rules — only tangled in a way that's harder to trace.

So the turn is clean: a great rulebook in the wrong place loses to a mediocre one in the right shared place. Where the file sits matters as much as what's in it.

The difference isn't the words in the file. It's where the file sits: in a private folder (only your agent reads it) or in the committed shared place (every agent that pulls loads it).

02What belongs in the shared rulebook, and what stays private

Not everything in a personal rules file should be pushed to the shared one. Mix personal taste into team rules and others feel boxed in; let team rules blur into taste and they go soft. Separate these three as belonging to the shared rulebook:

The dividing line fits in one question: "if someone else's agent does this differently from me, does the shared thing break?" Yes → shared rules. No → keep it private. The shared rulebook should be thin and hold only what truly must be uniform.

03The shared rulebook is code, so treat it like code

Once the rulebook lives in the shared place and shapes what every agent does, it's no longer a personal note — it's part of the system, on par with code. And what's code has a code's lifecycle: it gets reviewed before it changes, has history you can trace, and changing it is a team decision rather than one person quietly editing.

This sounds heavy but is actually freeing: when the rulebook is reviewed like code, a new convention has to convince the team before it applies to every agent — so it's rarely reckless, and once settled, everyone knows why. The opposite — a personal rules file changed on a whim — is a quiet source of noise: your agent shifts behavior mid-stream while the other two have no idea.

This is also where the idea that CLAUDE.md is operating law, not a README grows a level — from rules for your agent into rules for the team's. And if you don't know what such a skeleton holds, there's a CLAUDE.md skeleton to start from — pull it in, cut the private parts, commit the shared ones. However well you write the rulebook, it's only worth as many agents as can actually read it — so the first job isn't writing it well, it's putting it in the one place every agent can see.