CLAUDE.md Skeleton

On this page

.claude/CLAUDE.md is the project’s own context file: scaffolded ONCE by cargo xtask init (placeholder substitution), then OWNED by the project. Only its leading "How guidance is organized" preamble is template-synced (a managed-region — the cfg-claude-md-preamble manifest entry); everything else is project-owned and is NOT byte-synced or drift-gated. A written skeleton plus a migration thinning step are therefore the only levers that keep the file lean — this page is that skeleton.

The central rule: project context ONLY

CLAUDE.md is project context, nothing else. It must NOT contain:

  • Restated rules — the operating directives live in .claude/rules/* (synced digests, auto-loaded each session). Don’t paraphrase them here.

  • Full-prose standards — the canonical prose lives in docs/modules/standards/*. Link, don’t copy.

  • Work-stream status / TODO / next-steps / checklists — that belongs in GitLab work items (see the memory-hygiene and gitlab-issue-mr-standards rules), never in CLAUDE.md.

If a section is drifting toward any of these, cut it — the content already has a canonical home, and a duplicate here only rots. cargo xtask audit-claude-md is the advisory radar for this drift (duplicated-rule headers, size, guidance prose).

Canonical structure

In order:

Managed preamble (template-synced — do not hand-edit)

  • The leading HTML-comment provenance marker: states the file is scaffolded by init then project-owned, and that the marked preamble is managed-region-synced.

  • ## How guidance is organized — routes the reader to .claude/rules/, docs/modules/standards/, and docs/modules/ROOT/. Wrapped in claude-quickstart:managed markers; it re-syncs from the template, so edits to its interior are reverted by check-docs --fix.

Project-owned sections (you fill these in)

  • ## Tech Stack — the languages, frameworks, datastores, and key crates this project actually uses.

  • ## Build & Test — the handful of cargo xtask commands a contributor runs.

  • Conventions — project-specific conventions NOT already in the synced rules, with a # Project Overrides subsection recording dated, rationaled deviations from a non-security template default (security-baseline rules are NOT overridable).

  • ## Commit Signing — the project’s signing key/email setup.

  • ## Architecture — a brief orientation only; the detail lives in docs/modules/ROOT/ (architecture / services / security / local-dev).

  • ## Feature Status — a short status table of the project’s own features.

  • ## Visibility Exception (OPTIONAL) — only if the repo is private under a valid exception (see the security-baseline standard); omit it entirely otherwise.

The template’s own .claude/CLAUDE.md is the reference implementation of this skeleton.

Thinning an existing CLAUDE.md

When a CLAUDE.md has bloated, cut it back to the skeleton above. The migration runbook’s "Thin the CLAUDE.md" step drives this; the concrete checklist:

  1. Remove restated rule prose — anything paraphrasing a .claude/rules/* digest. Keep a pointer at most.

  2. Remove duplicated standards text — anything copied from docs/modules/standards/*. Link instead.

  3. Remove status / TODO / next-steps logs — move any live status to GitLab work items; delete stale logs (history lives in git).

  4. Keep only the managed preamble plus the project-owned section bodies above.

  5. Leave the claude-quickstart:managed preamble markers intact — they re-sync; do not hand-edit the interior.

After thinning, cargo xtask audit-claude-md should report no duplicated-rule headers and the file under the size soft-limit.

Edit this page · latest