docs — правило для Claude Code: что делает и как установить
Правило docs регламентирует структуру документации, шаблонов и спецификаций агентов. Следит за версионированием, ссылками по якорям и манифестом публикации.
Apache-2.0 ★ 121 обновлён 2026-10-29
.claude/rules/docs.mdЧто делает docs
Правило задаёт жёсткие границы для файлов в docs/, templates/, CLAUDE.md, .claude/agents/ и чейнджлогов. Оно запрещает встраивать текст документации напрямую в CLAUDE.md, требуя импорта через директиву @path. Документы разделены на три слоя: системный базовый слой 0, контекстный слой 1 по путям и архивный слой 2. Устаревший текст не исправляется постскриптумами, а переносится в docs/archive/ без удаления истории.
При добавлении любых отслеживаемых файлов в репозиторий с scripts/publish-manifest.json правило обязывает классифицировать их статусом ship или exclude. Запрещено менять замороженные версии в CHANGELOG.md, уже опубликованные в публичном зеркале. Ссылки между живыми документами должны вестись строго по именованным якорям, а не по номерам строк. Номера строк быстро устаревают.
Без классификации нового файла в манифесте хук .claude/hooks/pre-commit полностью заблокирует коммит. Для спецификаций агентов обязательна проверка скриптом scripts/test-agent-spec-sync.js: имена моделей указываются только семействами, без номеров версий.
Какие задачи решает
- упорядочить хранение системной документации и шаблонов по слоям
- предотвратить коммит файлов без классификации в
scripts/publish-manifest.json - защитить опубликованные секции
CHANGELOG.mdот случайных правок - сохранить точность перекрёстных ссылок с помощью именованных якорей
Примеры запросов агенту
- Обнови
docs/core/ORCHESTRATION_RULES.mdи проверь перекрёстные ссылки наdocs/AGENT_SPEC.md - Зарегистрируй новый файл в
scripts/publish-manifest.jsonсо статусом exclude - Перенеси устаревший раздел
CLAUDE.mdвdocs/archive/по правилам архивации
Как установить docs
Вручную: положить файлы
.claude/rules/docs.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/docs.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/docs.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/docs.mdВручную: положить файлы
.clinerules/docs.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о docs
Как установить docs в Claude Code?
Сохраните файл правила по пути .claude/rules/docs.md в корне вашего проекта.
Что делает правило docs?
Оно предписывает разделять документацию на слои загрузки, использовать импорты через @path вместо прямого копирования в CLAUDE.md и архивировать устаревшие фрагменты в docs/archive/. Также оно контролирует регистрацию файлов в манифесте сборки и запрещает править уже выпущенные версии в чейнджлоге.
Что произойдёт, если добавить новый файл без записи в publish-manifest.json?
Хук .claude/hooks/pre-commit заблокирует коммит, если в репозитории есть scripts/publish-manifest.json, а новый отслеживаемый файл не помечен как ship или exclude.
Исходный текст
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