Routing
Claude Code

Summary

This post defines the routing layer of a reusable Claude Code framework.

The framework is the shared process layer. It standardizes:

• a three-layer hierarchy: framework, personal, and repo
• a root contract that composes the three layers
• a typed documentation tree for routing, policy, playbooks, references, and decisions
• an authority order for resolving conflicts between layers
• a small agent-* command surface for extending the system

The appendix contains the complete file skeletons for the routing layer. Part 2 covers the change-rhythm layer. Part 3 covers review, verification, and deployment.

Problem

Without a clear structure, Claude Code guidance tends to collapse into one of two bad states:

• a single oversized CLAUDE.md that mixes routing, rules, rationale, and repo conventions
• an untyped pile of docs and commands with no clear boundary between shared process and repo-local behavior

An earlier draft of this RFC proposed a two-layer split (global framework vs repo) with the framework's files planted directly under ~/.claude/. That shape had two concrete flaws.

Flaw 1: the framework squats on Claude Code's own directory

Claude Code natively uses ~/.claude/ for its own state: CLAUDE.md as user memory, commands/, skills/, agents/, hooks/, settings.json, projects/, plans/, and keybindings.json. Planting framework-owned files at ~/.claude/CLAUDE.md and ~/.claude/docs/agents/ invites three kinds of breakage:

• a Claude Code release that starts using ~/.claude/docs/ (or any other top-level directory) silently collides with the framework
• a user who wants to install a second framework alongside has no safe path to do it
• a framework upgrade or reinstall can clobber the user's own CLAUDE.md content

Flaw 2: no user-level extension point

In a strict global-vs-repo model, a user who wants a preference that applies across all their repos has no place to put it. "Always prefer tabs over spaces in Go," or "no emoji in code comments," or "when writing commit messages, avoid marketing tone" are legitimate personal rules. With only two layers, the user must either edit the framework's own files (which breaks at enterprise scale where the framework is centrally managed) or copy the rule into every repo.

Both flaws share one root cause: the framework conflates user scope with framework scope. Namespacing the framework fixes both at once, because once ~/.claude/CLAUDE.md is no longer framework-owned, the user has somewhere to put personal preferences.

The framework also needs to avoid becoming a global dumping ground for frontend, backend, or infrastructure standards that only make sense inside a specific repo.

Goals

• Provide a reusable process layer that can be installed once per machine.
• Make the boundary between framework, personal, and repo layers explicit.
• Keep framework-owned files in a namespaced subdirectory so they never collide with Claude Code or with other frameworks.
• Give the user a first-class place to express cross-repo personal preferences.
• Keep docs typed so routing, policy, playbooks, references, and decisions each have a clear job.
• Support Claude Code Plan Mode without requiring writes during planning.
• Keep the global command surface small, namespaced, and process-oriented.
• Give repos a clean path to add local standards, workflows, and durable rationale.

Non-Goals

• Define universal frontend, backend, or infrastructure standards in the framework layer.
• Replace repo-local architecture docs with global abstractions.
• Provide a global command for every domain or team workflow.
• Turn the framework into a repo scaffolding engine for arbitrary project structure.
• Define the change lifecycle or review workflow here. Those are scoped to parts 2 and 3.

Proposed Design

1. Three-Layer Hierarchy

The system has three layers:

• Framework in ~/.claude/agent-governance/ owns shared process
• Personal in ~/.claude/CLAUDE.md and ~/.claude/personal/docs/agents/ owns one user's cross-repo preferences
• Repo inside the active repository owns local truth

The framework layer installs into its own namespaced subdirectory:

~/.claude/
├── CLAUDE.md                      # USER-owned. Imports framework + adds personal preferences.
├── commands/
│   └── agent-*.md                  # framework command shims. Claude Code's native commands dir.
├── personal/                      # optional: user's cross-repo docs tree
│   └── docs/agents/
│       ├── policy/
│       ├── playbooks/
│       ├── reference/
│       └── decisions/
└── agent-governance/              # framework-owned install
    ├── CLAUDE.md                  # framework root contract
    └── docs/agents/
        ├── router/
        ├── policy/
        ├── playbooks/
        ├── reference/
        └── decisions/

Two boundaries make this layout work:

• Framework content lives under agent-governance/, not directly under ~/.claude/. Claude Code can add new top-level directories without conflict. A user can install a second framework alongside by giving it its own sibling directory. A framework upgrade or reinstall touches only ~/.claude/agent-governance/.
• Commands stay at ~/.claude/commands/. That is Claude Code's native location for user-installed commands, and moving them out would break how Claude Code loads them. The reserved agent-* prefix namespaces the framework's commands so they never shadow a user's own.

Each repo extends the upper layers with local docs and optional local commands:

repo/
├── CLAUDE.md
├── .claude/commands/
└── docs/agents/
    ├── router/
    ├── policy/
    ├── playbooks/
    ├── reference/
    └── decisions/

The framework layer explains how work should happen. The personal layer carries one user's cross-repo preferences. The repo layer explains how that codebase works.

2. Root Contract

Two files form the root contract, with a deliberate separation of ownership:

• ~/.claude/agent-governance/CLAUDE.md is the framework root contract. It defines the meaning of $CLAUDE_HOME, the authority order, the typed docs tree, and the command-surface rules. It is owned by the framework release and should be treated as read-only by users.
• ~/.claude/CLAUDE.md is the user's personal memory file. Claude Code loads it natively. The recommended shape is a thin composition: import the framework contract, then add personal preferences.

A minimal user ~/.claude/CLAUDE.md looks like this:

@agent-governance/CLAUDE.md

## Personal preferences

- Prefer tabs over spaces in Go.
- No emoji in code comments.
- When suggesting commit messages, avoid marketing tone.

The @ prefix is Claude Code's native import syntax for CLAUDE.md. The framework contract loads first and establishes the shared process layer; personal preferences follow and override framework defaults where they conflict, subject to the authority order below.

$CLAUDE_HOME is the framework install directory. By default that is ~/.claude/agent-governance/. Every reference to $CLAUDE_HOME/docs/agents/... in framework docs or repo docs resolves under that path.

3. Components

The framework uses a typed docs tree so each category has a single job. During a typical change, they are encountered in this order:

In short: router selects, policy constrains, playbooks sequence, references deepen, and decisions explain why.

graph TD
    entry["~/.claude/CLAUDE.md
user composition · imports framework + personal prefs"]:::routing

    subgraph framework ["$CLAUDE_HOME (framework)"]
      fcontract["CLAUDE.md
framework root contract"]:::routing
      subgraph router ["router/"]
        phases["phases.md"]:::api
        capmap["capability-map.md"]:::api
        composition["composition.md"]:::api
      end
      policy["policy/*
binding rules"]:::data
      playbooks["playbooks/*
ordered workflows"]:::data
      reference["reference/*
deep detail"]:::onDemand
      decisions["decisions/*
durable rationale"]:::onDemand
    end

    entry --> fcontract
    fcontract --> phases
    fcontract --> capmap
    fcontract --> composition

    phases --> policy
    capmap --> policy
    composition --> policy

    policy --> playbooks
    playbooks --> reference
    playbooks -.-> decisions

    classDef routing fill:#5C3E14,stroke:#E8A849,color:#fff,stroke-width:1.5px
    classDef api fill:#1B3D3A,stroke:#4ECDC4,color:#fff,stroke-width:1.5px
    classDef data fill:#2A3054,stroke:#7B93DB,color:#fff,stroke-width:1.5px
    classDef onDemand fill:#3A2054,stroke:#B07CD8,color:#fff,stroke-width:1.5px
        

This avoids the common failure mode where one document mixes routing, rules, examples, and rationale without clear boundaries.

4. Authority Order

Three layers plus direct instruction create a resolution order. When sources conflict, higher beats lower:

1. Direct user instructions for the current task
2. Repo ./CLAUDE.md and repo docs/agents/*
3. Personal ~/.claude/CLAUDE.md and ~/.claude/personal/docs/agents/*
4. Framework $CLAUDE_HOME/CLAUDE.md and $CLAUDE_HOME/docs/agents/*
5. Code and tests
6. External memory or prior-session context

The order is intentional. Personal preferences sit above framework defaults because a user's own rules should win over shared defaults. But personal preferences sit below the repo layer because a codebase's own conventions are more specific than any individual's personal style.

Within each layer, the typed categories resolve in their own order: repo-specific policy beats repo-specific playbook, personal policy beats personal playbook, framework policy beats framework playbook, and so on.

5. Composition Contract

Ownership is strict:

• Framework owns: ~/.claude/agent-governance/CLAUDE.md, ~/.claude/agent-governance/docs/agents/*, and the agent-* namespace within ~/.claude/commands/.
• User owns: ~/.claude/CLAUDE.md, ~/.claude/personal/docs/agents/*, and any non-agent-* commands under ~/.claude/commands/.
• Repo owns: ./CLAUDE.md, optional directory entrypoints, repo docs/agents/*, and repo .claude/commands/*.

Rules:

1. $CLAUDE_HOME always means ~/.claude/agent-governance/. It does not mean ~/.claude, and it does not mean the repo root.
2. Repo docs use repo-relative paths such as ./CLAUDE.md, docs/agents/..., and .claude/commands/....
3. Personal docs use ~/.claude/personal/docs/agents/....
4. The user's ~/.claude/CLAUDE.md begins with @agent-governance/CLAUDE.md (or equivalent import), then adds personal preferences.
5. Repos extend with their own capability map for repo-specific routing and workflow names.
6. Repo commands use distinct names, not agent-* shadowing.
7. Commands in every layer stay process-oriented.

Routing Capabilities

The routing layer has three capabilities of its own: adopting the framework in a new repo, growing a repo's local routing, and repairing routing friction. Everything else (change bundles, verify, review, deploy) is scoped to parts 2 and 3.

Adopt

/agent-adopt is first-time repo onboarding. It reads the framework composition contract and produces the repo's local entrypoint, capability map, and initial docs/agents/ tree. It does not invent the repo's standards; it sets up the shape into which repo-specific policy, playbooks, and reference docs are later added.

Add Capability

/agent-add-capability is the wizard for growing an already-adopted repo. It should:

• inspect the repo for ./CLAUDE.md, repo docs/agents/..., and .claude/commands/...
• determine whether the capability needs a policy, playbook, reference, workflow entry, command, or directory CLAUDE.md
• produce a concrete repo-local checklist with exact file paths and required updates
• redirect to /agent-adopt if the repo has not been integrated yet

The same wizard can grow the personal layer: invoked with --scope=personal, it writes under ~/.claude/personal/docs/agents/ instead of a repo-relative path.

Improve

/agent-improve is for root-cause routing repair. When the framework routes to the wrong doc, or a playbook is unclear, or a user hits the same friction twice, this command diagnoses the underlying issue and patches the canonical typed docs. It is not a general-purpose refactor tool. Its job is to fix routing, not to rewrite opinions.

Decision Records as a doc category

decisions/ is a routing category, but the discipline around writing Decision Records lives in part 2, because a Decision Record is the durable artifact that a change produces. From the routing perspective all you need to know is that every layer has a decisions/ directory and that a Decision Record is consulted on demand, not preloaded.

Usage

Framework commands live under ~/.claude/commands/ and use the reserved agent-* namespace. This post covers the routing subset: three commands for exploring, adopting, and extending.

graph LR
  ADOPT["/agent-adopt
first-time repo onboarding"]:::routing
  ADDCAP["/agent-add-capability
extend repo or personal
policy, playbook, reference"]:::routing
  IMPROVE["/agent-improve
root-cause routing repair"]:::routing

  ADOPT --> ADDCAP
  ADDCAP --> IMPROVE

  classDef routing fill:#5C3E14,stroke:#E8A849,color:#fff,stroke-width:1.5px
        

These commands are process-oriented. They load canonical docs and guide the workflow. They are not the place for hidden repo-specific standards or arbitrary scaffolding logic. More specific commands should be repo-local.

Change lifecycle commands (/agent-plan-change, /agent-open-change, /agent-implement-change, /agent-close-change, /agent-record-decision) are defined in part 2. The auto-triggered review command (/agent-review-change) is defined in part 3.

Extension

Because the framework lives in its own namespaced subdirectory, the same install pattern works at every scale: solo, team, or enterprise. ~/.claude is the user's surface. ~/.claude/agent-governance/ is the install surface. The difference between scales is only who authors the install and how it is distributed.

Personal install

A solo user can clone or download the framework into ~/.claude/agent-governance/ directly, then add a thin ~/.claude/CLAUDE.md that imports the framework contract and adds personal preferences. No version manager is required, but the directory-per-install pattern means they can keep multiple versions around during a migration.

Team or enterprise install

For larger deployments, the framework should be owned in a versioned internal source repository or package and installed onto developer machines via a version manager that maintains a current pointer:

~/.claude/
├── CLAUDE.md                              # user composition
├── commands/
│   └── agent-*.md                          # thin shims, resolve against current
└── agent-governance/
    ├── current                             # symlink to the active version
    ├── 1.4.0/
    └── 1.5.0/

In this model:

• ~/.claude/CLAUDE.md imports @agent-governance/current/CLAUDE.md so users get whatever version is installed
• ~/.claude/commands/agent-*.md are thin shims that resolve against current
• agent-governance/<version>/ contains each framework release
• repos continue to own repo-local architecture and workflow truth in checked-in docs

This structure gives the organization:

• controlled rollout of framework versions
• fast rollback by switching the current pointer
• a clear distinction between installed runtime files, personal preferences, and repo-owned truth
• a stable command surface that does not require every repo to vendor a copy

The enterprise rollout should use five layers:

1. enterprise policy memory for hard company-wide instructions
2. enterprise managed settings for enforced permissions and configuration
3. framework install at ~/.claude/agent-governance/ for the shared process runtime
4. personal at ~/.claude/CLAUDE.md and ~/.claude/personal/docs/agents/ for one user's cross-repo preferences
5. repo-local docs and commands for project-specific behavior

The framework should not rely on manual file copying at scale. Ship it through an internal installer or manager, for example:

company-claude install
company-claude update
company-claude doctor
company-claude adopt-repo

That tool installs the chosen framework version into ~/.claude/agent-governance/<version>/, updates the current pointer, verifies the effective runtime surface, and optionally bootstraps the minimal repo-local adoption files.

The framework may also integrate with MCP for dynamic company services such as service-catalog lookup or policy workflows, but MCP should not be the primary distribution mechanism for the core process docs. The base framework should still arrive through installed memory files and commands so it remains stable, inspectable, and versioned.

Example: Frontend Best Practices

If a repo wants frontend best practices, those rules belong in the repo layer, not in the framework.

A typical repo-local addition would look like this:

repo/
├── CLAUDE.md
├── .claude/commands/
│   └── frontend-change.md
└── docs/agents/
    ├── router/
    │   └── capability-map.md
    ├── policy/
    │   └── frontend.md
    ├── reference/
    │   └── frontend-best-practices.md
    └── decisions/
        └── DR-002-frontend-boundaries.md

In that design:

• policy/frontend.md contains binding frontend rules
• reference/frontend-best-practices.md contains deeper frontend guidance
• router/capability-map.md tells Claude when to load the frontend docs
• .claude/commands/frontend-change.md is optional ergonomics for repeated repo-local work
• DR-002-frontend-boundaries.md preserves the durable rationale behind lasting frontend boundaries

If the same user also wants a cross-repo rule such as "always scope new React state to the nearest route boundary," that belongs in the personal layer at ~/.claude/personal/docs/agents/policy/frontend.md, not in any repo and not in the framework. The personal rule applies everywhere unless a specific repo overrides it.

The framework owns the process for adding capabilities. The personal layer owns a user's cross-repo preferences. The repo owns the actual standards.

Tradeoffs

Benefits

• Shared process is centralized, reusable, and upgradeable in place.
• The framework namespace isolates it from Claude Code's own directory layout.
• Personal preferences have a first-class home without being baked into repos or into the framework.
• Repo-specific standards stay local to the repo.
• The typed docs tree makes routing decisions legible: each doc has one job.
• The command surface stays safe because the agent-* namespace does not claim generic repo-local names.
• Enterprise rollout can be versioned, audited, and rolled back by flipping a current pointer.

Costs

• The system introduces more files than a single monolithic CLAUDE.md.
• Authors need to understand the difference between routing, policy, playbooks, references, and decisions.
• Users need a ~/.claude/CLAUDE.md that does the composition, rather than relying on a single framework-owned file. That file is one line plus any personal preferences, but it is still a thing the user has to create.
• Organizations need a lightweight installer or manager instead of relying on manual setup.

These costs are acceptable because they buy a clearer separation of concerns, a safe install path that coexists with Claude Code's own evolution, and a first-class home for personal preferences that every engineer wants.

Recommendation

If your team uses Claude Code across multiple repositories and you want agents to follow a consistent, auditable process, adopt the routing layer described here:

• install the framework at ~/.claude/agent-governance/
• keep ~/.claude/CLAUDE.md as the user's composition file, importing the framework contract and adding personal preferences
• keep repo-local architecture and domain guidance in the repo
• use the typed documentation categories
• keep the global command surface small and namespaced

Parts 2 and 3 of this series cover the change lifecycle and the review/verify/deploy discipline that sit on top of this routing layer.