CLAUDE.md as an Org Operating System: Encode Topology, Priorities, Decisions

Most teams write a CLAUDE.md that lists their lint rules and a one-line project description. That's a config file. It misses the actual mechanism.

The file loads automatically at the start of every Claude Code session — concatenated into context before you type a word. That single property makes it the highest-leverage piece of persistent context in your entire workflow. Every conversation that doesn't start with the file ends up retyping the same context: who owns what, this quarter's priorities, the V1 API you already decided to deprecate. Each retype is coordination tax. It compounds across every engineer and every session.

Reframe it: CLAUDE.md is the operating system for how your team works with Claude. Not a README. Not a config file. A living document that encodes how the org thinks, decides, and communicates — loaded into every session by default.

One constraint, named upfront: the value of this system tracks the honesty of the maintenance. A CLAUDE.md full of priorities the team has quietly abandoned produces confidently misaligned advice — worse than no file at all. The weekly update ritual isn't optional. It's what keeps the rest from rotting.

Claude Code discovers CLAUDE.md files by walking up the directory tree from your working directory. If you launch from services/payments/, Claude reads services/payments/CLAUDE.md, services/CLAUDE.md, and the root CLAUDE.md — all concatenated into context, ordered from filesystem root down to your working directory. The most specific file appears last, giving project-level instructions the highest recency.

Subdirectory CLAUDE.md files load differently. A file in src/api/ doesn't load at session start — it loads on demand the first time Claude reads a file in that directory. That's the right behavior: API conventions are noise when you're working on the data pipeline.^[9]

Four scopes exist, each serving a different ownership layer:^[9]

The managed policy scope is underused. Organizations running Claude Code across a fleet of developer machines can deploy a centrally managed CLAUDE.md through MDM, Group Policy, or Ansible. It loads before any user or project file, and engineers can't exclude it via claudeMdExcludes. Use it for org-wide compliance requirements and behavioral standards — not build commands, which belong in the project file.^[9]

Token cost matters here. CLAUDE.md content enters the context window as a user message after the system prompt, consuming tokens on every session start. The official guidance: target under 200 lines per file. Longer files reduce adherence — not because Claude ignores them, but because the signal-to-noise ratio drops and important instructions get buried.^[9]

One gotcha that burns teams: imported files via @path/to/file load in full at launch alongside the base CLAUDE.md. Splitting a 300-line file into three @imports doesn't reduce token cost — it just improves human readability. To actually reduce startup context, use path-scoped rules instead.

The .claude/rules/ directory is separate from CLAUDE.md and solves a specific problem: instructions that apply to one part of the codebase but not others. You pay token cost for every rule that loads unconditionally. Path-scoped rules change the math.^[9]

A rules file with paths frontmatter only loads when Claude reads files matching the pattern. An API-design rule scoped to src/api/**/*.ts costs zero tokens when you're fixing a frontend bug:

Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md. That's the right scope for project-wide conventions: commit format, test runner commands, naming conventions. Rules with paths are the right scope for domain-specific constraints that would just be noise outside that domain.

Monorepos with multiple teams can use claudeMdExcludes in .claude/settings.local.json to skip CLAUDE.md files from other teams. This keeps each engineer's context clean without forcing a central debate about what goes in the root file.

Open a Claude session without organizational context and you start at zero. The model doesn't know your team lead is on parental leave, that your infra budget got cut last month, or that the board approved an enterprise pivot last Tuesday.

Those facts shape every recommendation. Without them, the answers are technically sound and organizationally tone-deaf. With them, you get a collaborator that understands the constraints, respects ownership boundaries, and stays inside what the team already committed to.

Practitioner reports converge on roughly 40-60% less time spent on session-setup prompts when persistent org context is loaded — though the spread is wide and depends on team size and workflow shape.^[2] The bigger gain shows up downstream: outputs need fewer correction cycles because the model isn't guessing at the org topology.

The official guidance from Anthropic's docs names when to add something to CLAUDE.md: when Claude makes the same mistake a second time, when a code review catches something Claude should have known about the codebase, or when you type the same correction into chat that you typed last session.^[9] Each of those is a coordination tax. The file is where you pay it once.

A useful organizational CLAUDE.md covers seven areas. Few teams need all seven on day one — start with two or three and expand as the gaps surface. The constraint is simple: capture context Claude can't infer from the code but that shapes every decision.

The most common failure is stuffing every fact into CLAUDE.md. A 300-line file dilutes signal with noise — the section the model actually needs gets buried. Working ceiling: roughly 100-150 lines in the root file, with @imports pulling in detailed sections for human organization (not token reduction) and path-scoped rules handling domain specifics. Calibrate against what your team actually consults.

Skills sit in the right layer for recurring procedures. Deployment checklist, incident response playbook, RFC template — procedural, not declarative. The token economics work in your favor: ~100 tokens of metadata loads at startup so Claude knows the skill exists; the full instructions enter context only when triggered.^[10] Skills cost effectively nothing until invoked.

MCP closes the live-data gap. CLAUDE.md can say 'we use Linear for project tracking' but can't show the current sprint board. An MCP server for Linear bridges that — real-time access without pasting ticket details into every conversation.^[7]

Skills use progressive disclosure: content loads in stages as needed, not all at once. Anthropic's official documentation names three distinct levels:^[10]

Level 1 — Metadata (~100 tokens, always loaded at startup): The YAML frontmatter name and description fields. Claude reads these at session start to know each skill exists and when to use it. You can install dozens of skills without meaningful context penalty.

Level 2 — Instructions (under 5K tokens, loaded when triggered): The SKILL.md body — workflows, best practices, example code. Claude reads this from the filesystem via bash when your request matches the skill description. Only then does this content enter the context window.

Level 3 — Resources (effectively unlimited, loaded as needed): Additional files bundled in the skill directory — companion markdown files, executable scripts, reference material. Scripts run via bash and only their output enters context; the script code itself never does. This is why a skill can bundle hundreds of lines of Python without any context penalty unless the script runs.

Static documentation rots. That's the failure mode every persistent context system inherits — the org moves on while the file sits unchanged. Untracked drift turns the OS into a confidently misaligned advisor.

The /update-context skill closes this loop. Once a week, you run it. The skill prompts Claude to scan recent changes across the codebase, the decision log, and team communications, then proposes specific amendments to your CLAUDE.md files. You review, approve or modify, and the org context stays current. Maintenance becomes a structured conversation instead of a chore that nobody owns.

Important: the skill proposes. It never auto-commits. Org context is too high-leverage for unsupervised edits — a wrong amendment misroutes every session that loads it.

Claude loads CLAUDE.md files hierarchically. Working in services/payments/ means the model sees both the root org context and the payments-specific context — but the subdirectory file loads on demand, not at session start, unless you're already working in that directory. Each team carries their own file without duplicating global information.

The leverage: the payments team documents Stripe-specific conventions, PCI compliance constraints, and migration timeline without polluting the file every other team sees. They still inherit org-wide priorities and the decision register from the root.

Here's the failure mode we hit early in multi-team deployments: every team writes context independently, without coordination. Within two months, three teams had contradictory escalation paths in their files, and two had different definitions of 'P1 incident.' The model then gives confidently inconsistent answers about which severity scale applies to which service.

The fix is a hard rule: the root CLAUDE.md owns all cross-team definitions. Sub-directory files reference root definitions — they don't redefine them. If a team needs to adjust the escalation definition for their domain, they open a PR against the root. That PR is the coordination mechanism. Without it, drift compounds silently.

Teams make dozens of consequential decisions each quarter. Six months later, nobody remembers why you chose Postgres over DynamoDB, or why billing stayed a monolith. The decision register captures the reasoning at the moment it was made, blocking two specific failure modes.

First: it stops Claude from suggesting approaches the team already considered and rejected. Without the register, the model builds a case for the migration you ruled out three weeks ago. With it, the model knows the decision was made, understands the rationale, and works inside the constraint instead of relitigating it.

Second: it absorbs organizational amnesia when people leave. The EM who championed the Postgres choice rolls to a different team. The reasoning survives in the register — the institutional memory is no longer locked in a specific person's head. This is the closest thing to externalizing your org's reasoning capacity.

Format matters. An undated entry with no participants loses context within weeks. The minimum viable entry: date, one-sentence decision, one-sentence rationale, named participants. Link to the full RFC or ADR where it exists. That link is the difference between a pointer and a copy — the copy drifts, the pointer stays current.

The shift from CLAUDE.md as style guide to CLAUDE.md as organizational OS isn't a technical lift. It's a reframing. You stop telling Claude about the code and start telling Claude about the organization.

Start small. Add team topology and the top three priorities this week. Add a decision register entry for the last consequential architectural choice your team made. Build the /update-context skill next week. Inside a month, every session starts with the weight of your team's context, decisions, and direction already loaded — and the coordination tax you used to pay every conversation stops compounding.

The weekly update ritual is not optional — that's the constraint. A CLAUDE.md that nobody updates is worse than no file at all, because it confidently misroutes instead of simply knowing nothing.