К основному содержанию
правило CX Codex

docs — правило для Claude Code: что делает и как установить

Правило docs регламентирует структуру документации, шаблонов и спецификаций агентов. Следит за версионированием, ссылками по якорям и манифестом публикации.

Apache-2.0 ★ 121 обновлён 2026-10-29

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/rules/docs.md
Открыть на GitHub

Что делает 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 и 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

Похожие правила IDE

Все правила IDE по теме «Тексты и документация» →
docs-updater giuseppe-trisciuoglio Скилл docs-updater для Claude Code анализирует изменения Git и обновляет документацию проекта. Запускается при подготовке релиза, синхронизации README или перед pull request. CX Codex +1 3 700установок docs-sync-audit официальный github Скилл docs-sync-audit сверяет документацию с кодом и конфигурацией в режиме чтения. Пригодится после изменений в API, CLI, настройках или пользовательском сценарии. CX Codex +1 68установок docs-sync ChrisWiles Команда docs-sync сравнивает свежие изменения кода с документацией и выявляет несоответствия. Помогает найти устаревшие примеры, неправильные сигнатуры API и несовпадения в типах параметров. CX Codex +1 ★ 6 091звёзд репо skillshare-update-docs runkids Скилл skillshare-update-docs синхронизирует документацию проекта skillshare с кодом на Go и сверяет флаги CLI с исходниками. Пригодится после добавления новых команд или опций. CX Codex +1 ★ 3 269звёзд репо update-docs rerun-build Скилл update-docs для Claude Code сверяет документацию Rerun с изменениями в коде. Запускается перед завершением работы или созданием PR, если затронуты указанные части проекта, а также по просьбе обновить документацию. CX Codex +1 ★ 1 120звёзд репо oma-docs First Fluke Сверяет ссылки в документации, обновляет тексты под изменения в коде и находит рассинхрон в переводах. Работает через CLI oma docs или ручной парсинг ссылок. CX Codex +1 ★ 1 472звёзд репо

Из того же набора16

Весь набор →
ui-designer Субагент ui-designer для Claude Code читает Figma-файлы, извлекает токены, создаёт Code Connect-маппинги и экспортирует ассеты. Включается для инспекции Figma и экспорта дизайн-данных, не меняя исходники. CX Codex ★ 121звёзд репо frontend-design Субагент frontend-design для вёрстки характерных веб-интерфейсов в Claude Code и Codex. Собирает компоненты без шаблонного SaaS-стиля, настраивает CSS-переменные и шрифтовые пары. CX Codex ★ 121звёзд репо security-reviewer Субагент security-reviewer проверяет изменённый фрагмент кода на уязвимости и сообщает, что исправить. Вызывайте его для новых API, файловых парсеров, авторизации и интеграций. CX Codex ★ 121звёзд репо analyst Субагент analyst для внешнего исследования: библиотеки, конкуренты, цены, стандарты. Возвращает структурированный бриф для решения, а не просто ссылки. CX Codex ★ 121звёзд репо exa-researcher Субагент exa-researcher для Claude Code ищет через Exa внешние сведения, новости и примеры кода и передаёт находки главному агенту. Исследует материалы за пределами кодовой базы. CX Codex ★ 121звёзд репо qa Субагент, который проверяет готовые срезы (slices) против acceptance criteria. Запускается, когда разработчик отмечает срез как dev_done или ready_for_qa, и помогает найти баги до code review. CX Codex ★ 121звёзд репо architect Субагент architect для Claude Code декомпозирует задачи, анализирует кодовую базу и формирует критерии приёмки перед началом кодинга. CX Codex ★ 121звёзд репо session-start Скилл session-start подгружает текущее состояние Mavericks в начале сессии или после потери контекста: инициативу, этап, активные задачи и следующий шаг. CX Codex +1 ★ 121звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой