docs — Claude Code rule: what it does, how to install
docs enforces structural discipline for documentation, agent specifications, and templates. Controls layer imports, manifest logging, and anchor citations.
Apache-2.0 ★ 121 updated 2026-10-29
.claude/rules/docs.mdWhat docs does
This rule governs markdown files across docs/, templates/, CLAUDE.md, .claude/agents/, and project rules. It establishes docs as the source of truth, prohibiting direct inlining of operating text into CLAUDE.md and requiring @path imports. Content is categorized into three layers: always-loaded layer 0, scoped on-demand layer 1, and archived history in layer 2. Old sections are never deleted. Displaced text moves directly to docs/archive/.
The rule strictly controls project hygiene and public releases. Any newly tracked file in a repository with scripts/publish-manifest.json must be classified as ship or exclude. Tagged changelog entries are immutable. Citations across docs must rely on named anchor targets instead of bare line numbers.
Failing to log a new file in scripts/publish-manifest.json causes .claude/hooks/pre-commit to reject the commit. In agent definitions, model strings must use family names rather than specific version tokens to pass scripts/test-agent-spec-sync.js.
What it helps with
- organize repo architecture documentation across distinct loading layers
- stop commits containing unclassified files missing from
publish-manifest.json - prevent edits to tagged changelog sections on the public mirror
- maintain valid cross-references using semantic anchor targets
Example prompts for the agent
- Update
docs/core/ORCHESTRATION_RULES.mdand verify references todocs/AGENT_SPEC.md - Classify the new script as exclude in
scripts/publish-manifest.json - Move displaced
CLAUDE.mdsections intodocs/archive/with proper naming
How to install docs
Manually: put the files in place
.claude/rules/docs.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/docs.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/docs.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/docs.mdManually: put the files in place
.clinerules/docs.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about docs
How to install docs in Claude Code?
Save the rule file to .claude/rules/docs.md in the root of your project.
What does the docs rule do?
It enforces documentation standards, separating files into three loading tiers and prohibiting direct inlining into CLAUDE.md. It also validates agent spec naming, preserves changelog history, and tracks new files in the release manifest.
Why does pre-commit block unclassified files?
The .claude/hooks/pre-commit hook enforces that every newly tracked git file is registered in scripts/publish-manifest.json as either ship or exclude.
Source text
docs.md · Apache-2.0
--- paths: - "docs/**/*.md" - "templates/**/*.md" - "CLAUDE.md" - "CHANGELOG.md" - ".claude/agents/**/*.md" - ".claude/rules/**/*.md" --- # Docs and Templates Rules - Docs are the source of truth for the operating model. Do not inline their content into CLAUDE.md — use `@path` imports instead. - When updating a doc that is referenced from another doc (e.g. `docs/core/ORCHESTRATION_RULES.md` → `docs/AGENT_SPEC.md`), check that cross-references remain accurate. - Templates in `templates/` are canonical starting points for new projects. Keep them minimal — do not add project-specific content. - Role definitions live in `docs/core/ROLES.md`. The Main Agent is the orchestrator; do not introduce new top-level roles without a lightweight decision record. - **Publish-manifest registration** — if the repo contains `scripts/publish-manifest.json`, every new git-tracked file must be classified there in the same task: ship for framework content, exclude with a one-line reason for internal material. Roles whose scope excludes `scripts/` must instead emit `MANIFEST_REGISTRATION_NEEDED: <path> -> <ship|exclude> (<reason>)` in their final report so the Main Agent registers it. Developers editing the manifest run `node scripts/check-publish-manifest.js` and quote its output in evidence. See DR-002 (`docs/core/DECISIONS.md`). When the new file's path is known at spawn, the Main Agent pre-registers its entry in the working tree before spawning the docs role, so no token is needed — see the "Pre-spawn registration for docs roles" procedure in CLAUDE.md's "Publish-manifest registration" convention and DR-017 (`docs/core/DECISIONS.md`). A trailing-slash `exclude` entry (e.g. the `docs/archive/` prefix) classifies every file beneath it, so such files need no per-file registration. **Brief authors: never forbid a developer's self-registration line and never route a developer through the token above — the token is for scope-forbidden roles only.** `.claude/hooks/pre-commit`'s blocking backstop makes developer self-registration mandatory: a worktree with an unclassified new file cannot commit at all, token or no token. See DR-007 (`docs/core/DECISIONS.md`) for the incident and the parallel-conflict merge protocol for colliding developer registrations. - **Frozen changelog sections** — never add to or edit a `CHANGELOG.md` section whose version is already tagged on the public mirror; see `docs/PUBLIC_RELEASE_STRATEGY.md` §5 "Frozen-section rule" for the rule and the mirror-tag verification command to run first. - **Agent spec invariants** — an edit to `.claude/agents/*.md` or `docs/AGENT_SPEC.md` that breaks one of the pinned invariants fails `scripts/test-agent-spec-sync.js` on every filtered run, so check these before you commit: model names are family names only, never a versioned token, in both the specs and AGENT_SPEC.md's "Model selection"; the Fable-only roles' "Model self-report" sections must match AGENT_SPEC.md's literal grammar verbatim; and every report-only role (its `deny-tools:` denies both Edit and Write) keeps a "Budget awareness" section whose backticked `maxTurns: N` equals its own frontmatter `maxTurns`. Frontmatter `model:`/`maxTurns:` must also agree with AGENT_SPEC.md's per-role tables. Lines inside a spec's protected block are not yours to rewrite. - **Shipped secret-string discipline (docs)** — doc prose in a ship-classified file trips the publish secret-scanner exactly as code does, however innocent it reads: describe private repo names, absolute home-directory paths, credential shapes and non-reserved email domains in words, never as a literal. The full rule, the remedy and the gate command are in the "Shipped secret-string discipline" clause of `.claude/rules/scripts.md`. - **Anchor-first citations** — in living normative docs, a `file:line` citation must lead with a named anchor (a job name, config key, function name, or verbatim fragment) and treat any line number as secondary — insertions above the cited line silently move the number onto a different referent, not onto nothing, so a bare number decays into a wrong claim rather than a broken one. Citations **between living markdown docs** (e.g. `docs/core/GATE_LEDGER.md` → `docs/PUBLIC_RELEASE_STRATEGY.md`) use section headings or item names and **never** bare line numbers, for the same reason. **Exempt, and must never be retro-edited to "freshen" a citation**: `EXECUTION_LOG.md`; dated decision records in `docs/core/DECISIONS.md` — e.g. its `mavp-operator-agent.js:394-399` citation for `semverCompare` and its `mavp-install.js:1026-1041` citation for `detectBehindUpstreamGuard` are dated evidence of what was true when the decision was recorded, not current-state pointers, and must stay exactly as written even after the cited lines move; dated audits and RCAs under `docs/audits/` and `docs/rca/`; frozen `CHANGELOG.md` sections; and `BACKLOG.md`/`TASK_STATUS.md` task blocks. - **Layers and archive-not-delete** — docs are layered by *load mechanism*, not by importance. **Layer 0** is loaded at every start: `CLAUDE.md`, its `@` imports, and `.claude/rules/` files without `paths:` frontmatter. **Layer 1** is loaded on demand: path-scoped rules (this file is one — it carries `paths:` frontmatter, so it is layer 1), module `context_docs`, and skills. **Layer 2** is history, never auto-loaded: `BACKLOG.md`, `TASK_STATUS.md`, `EXECUTION_LOG.md`, `PROCESS_STATE.*`, git, and `docs/archive/`. Do not `@`-import layer 1 or 2 material into layer 0. - **Replace, not amend** — in layers 0-1, a statement that has become false is *replaced* in place, not corrected by a dated amendment appended below it. A "do not do X because Y" warning stays, undated, for as long as X stays tempting. An in-place extension or correction of a statement — words added, a word that became false swapped — is a replacement, not a displacement: nothing is archived, and git is its record. - **Archive, not delete** — displaced text moves verbatim to `docs/archive/<DOC_NAME>/<YYYY-MM-DD>-<slug>.md`, where `<DOC_NAME>` is the source path without `.md`, a leading `docs/` dropped, each `/` written as `__` (`docs/core/ORCHESTRATION_RULES.md` → `core__ORCHESTRATION_RULES`; `CLAUDE.md` → `CLAUDE`). Displaced text is a block that leaves layers 0-1 with no amended descendant: a section, a whole file, or a single top-level list item (one `CLAUDE.md` convention bullet is one). That block is the unit of a move; one archive file per move. `--check-archive` judges this per line: a removed line that an added line in a perimeter doc keeps at least 80% of (words in order, or all but one word) is amended in place, and so is a removed keyed line (a list item opening with a bold lead, or a table row keyed on its first cell) whose key occurs exactly once in the same file at the parent and exactly once at the child with the child line newly added — same document only, so a rewrite in another file, or under a repeated key, is not amended, and a keyed body cut to a bare lead still passes (git is its record; the archive duty for a displaced convention-bullet body is unchanged); any other removed line must reappear verbatim in a perimeter doc or in a `docs/archive/` file the same commit touches (that archive copy may be blockquoted: the check ignores leading `>` markers on the archive side, nested too, while the text after them must still be verbatim and a source line that is itself a blockquote keeps its marker); framework-managed files (the ones `--update` rewrites) are outside the perimeter in adopter repositories. Keep all heading levels and numbering as they were. Start the file with a provenance header: source path, last commit before the move, task, path of the topic's current state, and the words "verbatim — never edited". Leave a stub heading in the source with two pointers: current state and archive. Files under `docs/archive/` are classified by the manifest's `docs/archive/` prefix entry, so an archive file needs no per-file registration and no `MANIFEST_REGISTRATION_NEEDED` token. - **Validator perimeter** — `checkDocsRefs` (`scripts/mavp-validator.js`, `DOCS_REF_PATTERN`) resolves only `docs/[A-Z_]+.md` citations in `TASK_STATUS.md` Evidence/Notes. `docs/archive/` and `docs/waves/` are outside that perimeter by design; do not widen the pattern to cover them.
© yahor-punko · Apache-2.0 · yahor-punko/mavericks-os