Managing Context at Organization Scale

I’ve written a lot of CLAUDE.md files. One for every project. Each one captures the stuff that doesn’t fit in code or docs: how the project is laid out, the conventions we follow, where things deploy, who to ask when something breaks.

For a single project, that’s enough. You write the file, you check it into the repo, and any new engineer (or AI assistant) has the context they need to be useful.

But scale that pattern up to fifty projects across ten teams in a two hundred person engineering org and it falls apart pretty quickly. The same security rules get copy-pasted into every file. Someone updates the policy in one place and the other forty-nine are now wrong. Project files get written when the project starts and never touched again. The AI helping you in one repo doesn’t know the conventions of the one next door.

The fix isn’t more files. It’s a defined hierarchy, and someone whose job it is to keep that hierarchy honest.

The Hierarchy

Almost all organizational context fits into one of three layers. The whole game is putting each piece of information in the layer where it belongs, and not letting it leak into the others.

The top layer is the stuff that applies to everyone. Security policies. Compliance requirements. The coding standards your whole org agreed on. There should be exactly one source of truth for this, and every project inherits it. When the policy changes, you change it once.

The middle layer is project-specific. The architecture of this particular service. Which database it talks to. How to run it locally. This is the layer your existing CLAUDE.md is probably already good at, and it’s the layer that should be smallest if you’ve done the top layer right.

The bottom layer is personal. The way you like to be talked to. The shortcuts you use. The framing that works for your brain. This is private to you and doesn’t belong in anyone else’s repo.

Claude Code already supports loading from all three: a system-wide file, a project file in the repo, a user file in your home directory. The mechanism is easy. The discipline is hard.

Where It Goes Wrong

The temptation is always to dump everything into the project file because that’s the one in front of you. It feels productive. You’re solving the immediate problem. But every time you copy a company-wide policy into a project file, you’ve just created another thing that will go stale, contradict itself, and need to be maintained in fifty places.

The first sign of trouble is usually duplication. The same paragraph about deployment standards starts showing up in multiple repos with slight variations. By the time you notice, you have three different versions of “the right way” and nobody knows which one is current.

The second sign is staleness. Nobody owns the enterprise layer, so it doesn’t get updated. People route around it by adding the real, current rules to their project files. The hierarchy is still there on paper but everyone’s ignoring it.

Both of these are management problems, not technical problems. The mechanism is doing what it’s supposed to. The org is failing to keep the layers clean.

Managing It

The thing that actually makes this work is treating the hierarchy as something that needs an owner. Someone has to be responsible for the enterprise layer the way a service has an on-call rotation. When the security policy changes, that person updates the enterprise file and the change propagates to every project automatically. When a project starts adding policies that should live higher up, that person pulls them up and removes the duplicate.

Without that owner, the hierarchy decays into the same mess of disconnected files you started with. With that owner, it stays useful for years.

The other piece is treating the files like code. Versioned. Reviewed via PR. Tagged when there are major changes. You wouldn’t let someone push directly to production. Don’t let them push directly to the enterprise context file either.

Start Small

If you’re sitting at an org trying to figure out where to begin, pick the rules you find yourself restating in every project README and move them into a single enterprise file. Assign one person to own it. Run that for a quarter. See what breaks, what gets ignored, what actually gets used.

The interesting part of this isn’t the architecture diagram. It’s the cultural shift toward treating organizational knowledge as something you maintain like code, with an owner and a process and the same level of care. The tools to support this already exist. The discipline to use them well is the part most orgs are still working out.