CLAUDE.md Playbook 2026: AI Governance Across Front-End and Back-End Repos

CLAUDE.md Playbook 2026: AI Governance Across Front-End and Back-End Repos

Author: CodeGateway Team Published: 2026-06-01 ｜ Last updated: 2026-06-01 Reading time: 13 minutes

TL;DR: CLAUDE.md is the file Claude Code reads at the start of every session — the persistent context that travels with your project. It is context, not enforced configuration: to actually block an action you use a hook or permissions.deny, not a sentence in CLAUDE.md. When your organization runs separate front-end and back-end repositories, the hard part isn't writing one good file — it's keeping shared standards in sync across repos that don't share a git root, so Claude can't simply walk up the tree to find them. This playbook covers the exact load order, a build-order view of the Claude Code "harness," copy-paste CLAUDE.md templates for a React front-end repo and a Go/FastAPI back-end repo, four concrete ways to share org-wide standards across separate repos, path-scoped .claude/rules/, the cross-repo API-contract problem, lightweight governance with managed-policy CLAUDE.md, the token-cost levers and ROI math a leader needs, and how to give a whole team one Claude Code endpoint through CodeGateway.

Table of contents

1. CLAUDE.md is context, not config

2. How CLAUDE.md loads — the exact order

3. The harness, in build order

4. Front-end + back-end repos: the practical playbook

5. Path-scoped rules with `.claude/rules/`

6. Sharing standards across separate repos

7. Keep every file lean

8. The cost angle: lean context, measurable ROI

9. Lightweight governance that scales

10. Maintain CLAUDE.md as models evolve

CLAUDE.md is context, not config

A lot of teams reach for CLAUDE.md expecting it to enforce rules. It doesn't. Per Anthropic's own docs, CLAUDE.md and auto memory "are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead."

That single distinction reshapes how you should govern AI coding across an org:

• Behavioral guidance → CLAUDE.md. Conventions, architecture, "always run the test suite before declaring done," "API handlers live in src/api/handlers/."

• Hard enforcement → settings. Blocking a command or path is permissions.deny in .claude/settings.json; isolating the agent is sandbox.enabled; pinning the model provider is env.

So CLAUDE.md is where you write down what you'd otherwise re-explain every session. The official rule of thumb is sharp: add to CLAUDE.md when Claude makes the same mistake twice, when a code review catches something Claude should have known, or when a new teammate would need the same context to be productive. If an entry is a multi-step procedure or only matters for one corner of the codebase, it belongs in a skill or a path-scoped rule — not in the file that loads on every single session.

How CLAUDE.md loads — the exact order

Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, then concatenating everything it finds — root first, your working directory last — so the most specific instructions are read last. There is no overriding; it all becomes context.

There are four scopes, loaded broadest to most specific:

Two mechanics matter in a multi-repo org:

• Closer wins, by position. Within a directory, CLAUDE.local.md is appended after CLAUDE.md; across the tree, deeper files come later, so they get the last word. Use this on purpose.

• Subdirectory files load on demand. Files above your working directory load in full at launch; files in subdirectories load only when Claude reads a file in that subtree. That's how a big repo keeps the token budget sane — irrelevant context never enters the window.

Start with /init. Claude analyzes the repo and generates a starting CLAUDE.md with build commands, test instructions, and conventions it discovers. Set CLAUDE_CODE_NEW_INIT=1 for an interactive flow that explores with a subagent and presents a reviewable proposal before writing anything. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting.

The harness, in build order

Anthropic's guidance for Claude Code at scale makes one point worth internalizing before you write a line of CLAUDE.md: the harness matters as much as the model. The harness is five extension points, and the order you build them in matters because each layer builds on the last.

Two more capabilities round it out: LSP integrations (symbol-level navigation, so Claude follows a function to its real definition instead of grepping a name and guessing) and subagents (an isolated context that explores a subsystem and returns only its findings, keeping the main thread focused).

CLAUDE.md comes first because it's the layer everything else assumes. But notice the most common mistake the docs call out for each layer: using CLAUDE.md for things that belong elsewhere. A multi-step workflow belongs in a skill. A "must always run before commit" rule belongs in a hook — it runs regardless of what Claude decides, which a CLAUDE.md sentence cannot guarantee. Keep CLAUDE.md for what genuinely applies to every session.

Front-end + back-end repos: the practical playbook

Here's the situation most teams are actually in: a React/Next.js front-end repo and a Go or FastAPI back-end repo, each with its own git root, each cloned side by side. The official large-codebase guidance is written around monorepos, and one assumption quietly breaks when you split into separate repos:

Claude automatically walks up the directory tree and loads every CLAUDE.md it finds.

Across two separate git roots, there is nothing to walk up into. frontend/CLAUDE.md and backend/CLAUDE.md never see each other. So the playbook splits into two problems: (a) make each repo excellent on its own, and (b) share what must be shared (covered in §6).

Each repo gets a focused root CLAUDE.md

A good CLAUDE.md describes intent and constraints, not commands Claude can already discover. Keep it under 200 lines. Here's a front-end repo:

# Front-end web app

Next.js 15 (App Router), TypeScript, Tailwind, TanStack Query, Vitest.
Talks to the `payments-api` back-end (separate repo) over REST.

## Conventions
- Components: PascalCase under `components/`. Hooks: `useFoo` under `hooks/`.
- Server state via TanStack Query only — never duplicate it into a client store.
- Validate every boundary (forms, API responses, env) with Zod.
- API calls go through `lib/api/` clients; never call `fetch` from a component.

## Test discipline
- Before declaring done: `pnpm typecheck && pnpm test --run`.
- UI with logic needs a Vitest test, not just a snapshot.

## Don't
- Don't add a second state-management library; TanStack Query + Zustand only.
- Don't touch `src/generated/` — it is regenerated from the API's OpenAPI spec.

And the back-end repo:

# payments-api

FastAPI + SQLAlchemy 2.0 (async), Postgres, Python 3.12. Serves the web app.

## Architecture
- Routes in `app/api/v1/` stay thin: parse, call a service, return.
- Business logic in `app/services/`, DB models in `app/db/models.py`.
- Every public endpoint declares a Pydantic `response_model`.

## Test discipline
- Run `uv run pytest -q` before declaring a task done.
- New endpoints need at least one TestClient integration test.
- Never call a live model provider in tests — mock it.

## Don't
- Don't edit the DB by hand; every schema change is an Alembic migration.
- Don't change a `response_model` without flagging the front-end contract impact.

Notice both files name the other repo and the contract between them. That cross-reference is the seed of the real multi-repo problem.

Scope test and lint commands to where they apply

A monorepo lesson that transfers directly: running the whole suite when Claude touched one service "causes timeouts and wastes context on irrelevant output." In separate repos this is automatic — but inside each repo, if you have a web/ and a mobile/ package, put the per-package commands in per-directory CLAUDE.md files so Claude runs only what's relevant.

Working across both repos at once

When a front-end change needs the back-end's API context, you don't have to copy anything. Point Claude at the sibling repo and pull in its CLAUDE.md:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../payments-api

--add-dir grants access to the sibling directory; the env var tells Claude to also load that repo's CLAUDE.md, .claude/rules/*.md, and .claude/CLAUDE.md. Now a front-end session understands the API's conventions without you maintaining a duplicated copy of them.

Path-scoped rules with .claude/rules/

Once a CLAUDE.md starts growing, move situational guidance into .claude/rules/. Each file covers one topic, and a paths: frontmatter field scopes it so it only loads when Claude touches matching files — keeping it out of context the rest of the time.

---
paths:
  - "src/api/**/*.ts"
---

# Front-end API-client rules

- Every client method validates the response with the matching Zod schema.
- Surface errors with the shared `ApiError` type; never throw raw fetch errors.
- Regenerate clients from the API's OpenAPI spec; don't hand-edit `src/generated/`.

your-repo/
├── .claude/
│   ├── CLAUDE.md            # lean: pointers + critical gotchas
│   └── rules/
│       ├── code-style.md    # loads every session (no paths)
│       ├── api-client.md    # loads only for src/api/**
│       └── testing.md       # testing conventions

Rules without a paths field load every session at the same priority as .claude/CLAUDE.md. Rules with paths trigger only when Claude reads a matching file. Glob patterns work the way you'd expect — src/**/*.{ts,tsx}, tests/**/*.test.ts, brace expansion included.

This is the single highest-leverage move for keeping a large front-end repo legible: the root CLAUDE.md stays a one-screen orientation, and the detailed rules surface exactly when they're relevant.

Sharing standards across separate repos

This is the part the monorepo guides skip, and it's the heart of governing AI coding across split front-end/back-end repos. There are four mechanisms, from lightest to most managed:

1. User-level rules (`~/.claude/rules/`). Personal conventions that apply to every project on your machine — loaded before project rules, so project rules still win. Good for individual preferences, not team standards.

2. Symlink a shared rules directory into each repo. Maintain one source of truth and link it in. .claude/rules/ resolves symlinks normally:

# one shared standards repo, linked into both front-end and back-end
ln -s ~/org-standards/security.md      frontend/.claude/rules/security.md
ln -s ~/org-standards/security.md      backend/.claude/rules/security.md
ln -s ~/org-standards/api-contract.md  frontend/.claude/rules/api-contract.md
ln -s ~/org-standards/api-contract.md  backend/.claude/rules/api-contract.md

Edit ~/org-standards/security.md once and every linked repo picks it up. Keep org-standards as its own git repo (or a submodule) so the standards are themselves versioned and reviewed.

3. Import from home with `@`. A committed CLAUDE.md can pull in a personal or shared file with @path syntax (max depth four hops):

# Individual + shared preferences
- @~/.claude/org-standards/security.md

4. Managed policy (the org-wide lever). Deploy one CLAUDE.md to the managed-policy location via MDM, Group Policy, or Ansible — or put the content directly in managed-settings.json:

{ "claudeMd": "Never push directly to main.\nAll AI-generated code goes through the same PR review as human code." }

A managed-policy CLAUDE.md applies to every session on the machine, in every repo, and cannot be excluded by individual settings. That's exactly what you want for the rules that must hold everywhere — security, compliance, "AI code is reviewed like human code" — regardless of which of your ten repos a developer happens to be in.

The cross-repo contract. Front-end and back-end share an API contract: shared types, request/response schemas, error codes. When they drift, Claude confidently writes a front-end call against a shape the back-end no longer returns. Pick one home for the contract — most teams generate the front-end client from the back-end's OpenAPI spec — and put a short api-contract.md rule in both repos (symlinked from one source) describing where the contract lives and the rule that it is generated, never hand-written. That one shared rule prevents a whole class of confident-but-wrong cross-repo edits.

Keep every file lean

CLAUDE.md is loaded into context in full, every session, regardless of length — so length is a direct tax on every conversation, and longer files measurably reduce adherence (important rules get lost in the noise). The official target: under 200 lines per file.

Practical discipline:

• The root file is pointers and critical gotchas only. A one-line description of each top-level folder plus the three things Claude keeps getting wrong. Everything else drifts into noise.

• If Claude already does something correctly without the instruction, delete the instruction.

• Multi-step procedure → skill. Path-specific detail → .claude/rules/ with paths. Must-run-every-time → hook.

• Block-level HTML comments are stripped before the content reaches Claude, so you can leave notes for human maintainers without spending tokens.

A related mechanism: auto memory. Separate from CLAUDE.md, Claude can keep its own notes (build quirks, debugging insights, preferences it discovers) in a per-repo memory directory; the first ~200 lines of its MEMORY.md index load each session. CLAUDE.md is what you write to guide behavior; auto memory is what Claude writes to remember. Run /memory to browse, edit, or disable it.

The cost angle: lean context, measurable ROI

For a leader, the question under all of this is money: AI coding burns tokens, and tokens are a line item. The reassuring part is that almost every practice in this playbook is also a cost lever — and the few that raise spend tend to pay for themselves in engineer time.

Where the tokens go — and what cuts them. CLAUDE.md loads in full, on every session, for every developer. That makes a bloated root file the single most controllable recurring cost in the whole setup. Each mechanism in this guide keeps tokens out of the main context:

A back-of-envelope illustration: trimming a root CLAUDE.md from ~600 lines to ~180 saves on the order of a few thousand input tokens per session. For a 20-developer team running ~40 sessions a day, that recurs ~800 times daily — fixed waste paid whether or not those lines ever helped, and exactly the kind of number that compounds into a real monthly bill.

The ROI of spending deliberately. Not every token should be cut. The expensive token is the one spent navigating blind and then redoing the work. A read-only subagent that maps a subsystem before the main agent edits costs tokens — and prevents a wrong-context change plus the review round that would have caught it. Anthropic's own observation is blunt: teams that invest in codebase setup see better results. The math that matters to a leader isn't tokens in isolation; it's tokens against engineer time. An agent session costs cents; an engineer-hour costs orders of magnitude more; a bad merge costs more still. If good context turns a three-iteration task into one, the spend paid for itself many times over.

So the governance goal is not "minimize tokens." It is maximize useful work per token: cut the waste (bloated context, blind navigation, full-suite test runs on a one-line change) and invest where it compounds (a sharp CLAUDE.md, LSP, exploration subagents).

Make the cost visible. You can't optimize what you can't see. The most common runaway-cost session traces back to something concrete — a 900-line CLAUDE.md, a missing .ignore that lets Claude read node_modules, a whole monorepo loaded when one service was in play. Per-developer and per-repo usage visibility is what turns "our AI bill is high" into "this repo's root file is the problem." That visibility is itself a governance lever — and one more reason to route the team through a single endpoint (see One endpoint for the whole team).

Lightweight governance that scales

You don't need an enterprise program to govern AI coding well — you need a few decisions made on purpose. The patterns Anthropic observed in successful rollouts compress to this:

• Assign a DRI. One person with ownership over the Claude Code configuration: settings, permissions policy, the plugin set, and CLAUDE.md conventions — and the responsibility to keep them current. Without someone centralizing what works, good setups stay tribal and adoption plateaus. Larger orgs formalize this as an agent manager (a hybrid PM/engineer role).

• Separate enforcement from guidance. Block tools, commands, and paths with managed permissions.deny; reserve managed-policy CLAUDE.md for behavioral and compliance guidance. Settings are enforced by the client no matter what; CLAUDE.md shapes behavior but is not a hard wall.

• Route AI code through the same review as human code. This is a CLAUDE.md/process rule, not a tool setting — state it in the managed policy so it holds across every repo.

• Start narrow, expand on confidence. A defined set of approved skills and plugins, required review, limited initial access — then widen. The smoothest rollouts brought engineering, security, and governance together early to define requirements jointly.

For split front-end/back-end repos specifically, distribute the approved setup as a plugin (skills + hooks + MCP bundled) through a managed marketplace, so a new engineer installing it on day one has the same context and guardrails as everyone else — in both repos.

Maintain CLAUDE.md as models evolve

A CLAUDE.md is not write-once. Instructions written for today's model can work against a future one: a rule that tells Claude to break every refactor into single-file changes may have helped an older model stay on track but would stop a newer one from making the coordinated cross-file edits it now handles well.

Treat configuration as something that decays:

• Review CLAUDE.md, nested files, and .claude/rules/ every three to six months, and again whenever performance feels like it plateaued after a major model release.

• Review CLAUDE.md edits like documentation changes — in pull requests.

• Add a Stop hook that receives the session transcript and proposes CLAUDE.md updates while the gap it exposed is fresh. This is the highest-value use of hooks: not just preventing mistakes, but making the setup self-improving.

• Delete rules and hooks that compensated for limitations a newer model no longer has — they're pure overhead once the limitation is gone.

CLAUDE.md vs AGENTS.md vs .cursor/rules

If your team runs more than one coding agent, you'll meet three filenames for the same idea. Each agent reads only its own file, but the content discipline transfers cleanly.

Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already uses AGENTS.md for another agent, don't duplicate — import it:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

A symlink works too (ln -s AGENTS.md CLAUDE.md), though on Windows that needs Administrator or Developer Mode, so the @AGENTS.md import is the portable choice. Running /init in a repo that already has an AGENTS.md reads it and folds the relevant parts into the generated CLAUDE.md. One source of truth; no diverging copies to rot.

(For the Codex CLI side of this story, see our AGENTS.md Hierarchy Playbook.)

Verify what Claude actually loaded

A few months in, almost every team has at least one CLAUDE.md whose rules aren't loading — a path quirk, a file in the wrong place, a conflict resolved arbitrarily. Verify, don't assume:

• Run /memory to list every CLAUDE.md, CLAUDE.local.md, and rules file loaded in the current session. If a file isn't listed, Claude can't see it.

• For deeper debugging, the InstructionsLoaded hook logs exactly which instruction files loaded, when, and why — invaluable for path-scoped rules and lazy-loaded subdirectory files.

• After /compact, the project-root CLAUDE.md is re-read from disk and re-injected; nested subdirectory files are not re-injected until Claude next reads a file in that subtree. If an instruction "disappeared" after compaction, it was either conversation-only or lives in a nested file that hasn't reloaded.

When instructions conflict, Claude may pick one arbitrarily — so the maintenance pass above isn't optional hygiene, it's how you keep the whole hierarchy trustworthy.

Five common mistakes

1. Treating CLAUDE.md as enforcement. It's context. Anything that must happen — block a path, run before commit — is a hook or a permissions.deny rule.

2. One giant root CLAUDE.md. Over ~200 lines, adherence drops. Push detail into path-scoped rules and skills; keep the root a one-screen orientation.

3. Writing commands instead of intent. "Run pnpm test" rots when you rename the script. "Run the test suite before declaring done" survives.

4. Assuming separate repos share context. They don't — no common git root to walk up. Share standards explicitly via symlinked rules, @ imports, or managed policy.

5. Never reviewing. Configuration decays as models improve. Schedule a review every 3–6 months and after major model releases; delete what newer models made unnecessary.

One endpoint for the whole team via CodeGateway

Governance has a billing dimension too. Once a dozen developers across two repos are each running Claude Code, you want one place to see usage and one bill — not a dozen personal cards and no visibility. Point Claude Code at CodeGateway as an Anthropic-compatible endpoint:

export ANTHROPIC_BASE_URL=https://api.codegateway.dev
export ANTHROPIC_API_KEY=cg-...   # from your CodeGateway dashboard
claude

Your CLAUDE.md, rules, hooks, skills, and subagents behave identically — CodeGateway sits at the API layer, so the harness above is untouched. What you gain is at the team level: each developer signs in with their own key, the gateway aggregates billing, and you get one usage dashboard across the whole team without standing up your own proxy. It's also the clean way to set a single custom endpoint when your developers sit behind a corporate network that requires routing API traffic through an approved gateway.

Pricing follows the same per-token model as going direct, plus a transparent tier markup that drops as team usage grows — see pricing and the tier markup explained.

FAQ

Q: Does Claude re-read CLAUDE.md when I edit it mid-session? The project-root CLAUDE.md is re-read after /compact, but for a clean pickup of edits, start a new session. Nested subdirectory files reload the next time Claude reads a file in that subtree.

Q: How do I share standards across separate front-end and back-end repos? Four ways, lightest first: user-level ~/.claude/rules/, a symlinked shared rules directory, @-importing a file from home, or a managed-policy CLAUDE.md deployed via MDM. Managed policy is the only one that can't be turned off per-developer.

Q: CLAUDE.md or `.claude/rules/` or a skill? CLAUDE.md for what every session needs (build commands, architecture). .claude/rules/ with paths: for guidance that only matters in part of the tree. A skill for a multi-step workflow Claude needs only sometimes.

Q: My CLAUDE.md is too long — what do I do? Trim to under 200 lines. Move path-specific content into .claude/rules/ (it loads only for matching files). Note that @ imports help organization but not context size — imported files still load in full at launch.

Q: How do I stop other teams' CLAUDE.md files from loading in a big repo? Use claudeMdExcludes (glob patterns against absolute paths) in .claude/settings.local.json. Managed-policy files are the exception — they can never be excluded.

Q: Is CLAUDE.md enough for compliance requirements? No. CLAUDE.md guides behavior but isn't enforced. Pair behavioral guidance in a managed CLAUDE.md with hard controls in managed settings (permissions.deny, sandbox.enabled) and a review process that treats AI-generated code exactly like human-generated code.

Related resources

• AGENTS.md Hierarchy Playbook 2026 — the Codex CLI counterpart to this guide

• OpenAI Codex CLI Complete Reference 2026

• Claude Code vs Cursor vs Copilot

• Error troubleshooting (401 / 429 / 500)

• Tier markup explained · Pricing

Official references

• How Claude remembers your project (CLAUDE.md & memory)

• How Claude Code works in large codebases

• Using CLAUDE.md files

• Set up Claude Code in a monorepo or large codebase