Cross-Repo Consistency

Organizations with multiple repositories face a consistency problem. Each repo develops its own CLAUDE.md independently. Over months, conventions drift. One repo requires semicolons, another bans them. One repo uses barrel exports, another forbids them. The rules are not wrong individually — they are wrong collectively, because an engineer moving between repos encounters contradictory instructions and the AI produces inconsistent code.

The solution is a template hierarchy. Create a shared CLAUDE.md template at the organization level — the rules that apply to every repository regardless of language, framework, or purpose. Security constraints, commit message conventions, PR review requirements, documentation standards. This template lives in a dedicated repository (e.g., org-claude-rules) and is versioned.

Each project-level CLAUDE.md then inherits from the organizational template and adds project-specific overrides. The structure looks like this: the organizational template provides the first 50 lines — identity, security rules, universal conventions. The project-specific section provides the next 100-200 lines — architecture, build commands, tech-stack-specific rules, gotchas. The override mechanism is explicit: if a project needs to deviate from an organizational rule, it states the deviation and the reason.

Synchronization happens through automation. A GitHub Action or CI check compares each project's CLAUDE.md against the organizational template on every PR. If the template has been updated and the project has not pulled the changes, the check warns. If a project overrides a rule without an explicit reason, the check fails. This is not about control — it is about visibility. You want to know when projects deviate, not prevent it.

1. 1. Create the Organizational Template Define rules that apply universally: security constraints, commit conventions, PR requirements, documentation standards. Version this in a dedicated repository. Keep it under 60 lines — this is the shared foundation, not the complete rulebook.
2. 2. Define the Override Protocol Establish how projects deviate from the template. Require an explicit comment: "OVERRIDE: [org rule] — Reason: [why this project is different]." This creates an audit trail and forces conscious deviation rather than accidental drift.
3. 3. Automate Synchronization A CI check on every PR compares the project's CLAUDE.md against the current organizational template. Warn on template updates not yet pulled. Fail on overrides without explicit reasons. This keeps the template alive instead of letting it become a forgotten artifact.