Documentation Writing

---
name: documentation-writing
description: |
  Единый вход для НАПИСАНИЯ и ПОДДЕРЖКИ любой документации проекта. Сначала определи ЖАНР дока,
  дальше работай строго по его гайду в references/: закон / справочник / инструкция / разбор / агент.
  Плюс обслуживание готовых доков: аудит, правка, сверка, статус.

  Use when: "напиши документацию", "написать стандарт", "написать инструкцию", "напиши разбор",
  "создай агента", "проверь документацию", "обнови документацию", "аудит документации",
  "write documentation", "check docs", "audit documentation", "update docs",
  "проверь базу знаний проекта"

  Для чтения доков или объяснения понятий — читай скилл project-knowledge напрямую.
---

# Документация: диспетчер жанров

**Зачем этот файл.** Развилка на пять жанров и базовые законы, общие для всех пяти. Любой док проекта принадлежит ОДНОМУ жанру. Жанр определяется одним признаком: что диктует структуру файла. Сначала определи жанр, потом пиши или правь строго по его гайду в `references/`. Свою структуру не выдумывай. Законы жанра лежат в его гайде.

## Базовые законы (любой жанр)

**Язык.** Документацию любого жанра пишем простыми словами, без жаргона и выдуманных образов. Канцелярит запрещён наравне с образами: пишем «сторож ловит», а не «осуществляется контроль»; «файл длиннее 500 строк», а не «в рамках соблюдения установленного лимита». Полное правило языка живёт в CLAUDE.md — сначала смотри глобальный `~/.claude/CLAUDE.md`, потом раздел про язык в CLAUDE.md проекта; второй раз правило нигде не переписываем. Раздела нет ни там ни там — скажи об этом владельцу и пиши по короткой формулировке выше, молча правило не пропускай. Исключение из запрета на образы одно: сам текст правила про образы и образ, приведённый как пример плохого.

**Счётное утверждение сверяется счётом на диске и пишется с адресом источника.** Число, путь, имя файла, номер строки. Не сверил — не пиши число. Пример адреса: `claude-server-kit/docs/04-manage-users.md:78`.

**Без заплаток.** Кривое старое правило переписываем целиком и начисто. Запрещено оставлять плохую формулировку и доклеивать сверху исключение или «но…» — убери старое и напиши правильно с нуля.

## Шаг 1. Определи жанр

- **Закон** → `references/ai-standard.md`. Структуру диктует список правил. Сюда: семь файлов `standards/*.md`, разделы `## Hard invariants` и `## Business rules` из `patterns.md`, редакционные стандарты вроде стандарта голоса.
- **Справочник** → `references/knowledge-base.md`. Структуру диктует устройство проекта. Сюда: все файлы `.claude/skills/project-knowledge/references/`. Устройство подсистемы забирает себе справочник целиком, даже когда подсистема чужая.
- **Инструкция** → `references/instruction.md`. Структуру диктует порядок шагов. Сюда: файлы `docs/` с настройкой внешних сервисов, раздел про запуск и выкатку в README. Разделы с пошаговой работой внутри справочника пишутся по этому же гайду: `## Откат` и `## Recovery procedures` в `deployment.md`, `## Canonical live pipelines` и `## Triage decision tree` в `testing-and-verification.md`; сами файлы остаются в справочнике.
- **Разбор** → `references/analysis.md`. Структуру диктует ход рассуждения на фактах. Сюда: рабочие книги и редакционные паки вроде `smm-training-pack/`, аудиты, отчёты и записи решений `docs/decisions/NNNN-название.md`.
- **Агент** → `references/agent.md`. Структуру диктует машина, которая файл читает: frontmatter решает, позовёт ли Claude исполнителя, и файл обязан нести контракт вывода. Опознаётся по месту: файл лежит в `.claude/agents/`.

**Граница справочника и разбора.** Готовое устройство любой подсистемы — справочник: стек, схема данных, интеграции, потоки, команды выкатки, даже когда подсистема чужая или её переносят на другое решение. Ход рассуждения на фактах, аудит и запись решения — разбор. Реальный случай: один проект держит `vexa-api.md`, `vexa-infrastructure.md` и `dashboard-migration.md` в базе знаний, и по прежним гайдам жанр этих файлов не определялся.

**Граница инструкции и справочника.** Инструкция несёт только то, что набирают руками по шагам. Адрес сервера, IP, домен, имена env-переменных живут в справочнике (`deployment.md`), инструкция ставит на них ссылку. Почему выбрано именно это решение — в `docs/decisions/NNNN-название.md`. Реальный случай: `docs/setup-domain.md` держит все три жанра в одном файле — строки 3-5 дают боевой домен и IP сервера (справочник), строки 5-7 объясняют, почему брошены два других способа выдать домен, `*.sslip.io` и `dns.army` (разбор), а ниже идут шесть шагов (инструкция).

**Цена смешения.** Инструкцию выполняют по порядку на боевой машине, и промах вылезает через несколько шагов не там, где сделан. Соседние жанры читают с любого места, и на диске от них ничего не меняется.

**Файл держит куски разных жанров** — режь по разделам, как у `patterns.md`: блоки с правилами и чек-листами пиши по гайду закона, шаги — по гайду инструкции, остальное по гайду разбора. Жанр самого файла определяется по большей части.

Агент держится отдельным жанром, а не вливается в закон, по трём причинам. Поле `description` решает, запустят ли агента вообще, и такого промаха не ловит ни одно правило закона. У агента есть контракт вывода, у закона его нет. Мерки объёма у них разные, и держит их гайд жанра. Правила письма для самих правил внутри агента гайд агента не переписывает заново, а отсылает к гайду закона.

**Что вне карты.** Файлы скиллов (`SKILL.md` и их `references/`) правит скилл `skill-master`. Спеки фич — user-spec, tech-spec, bug-spec и файлы задач — правят свои скиллы планирования. Черновики постов в `content/posts/**` пишутся по стандарту копирайтинга, там образы разрешены осознанно. Пять жанров выше их не покрывают, и подгонять такие файлы под гайд отсюда не надо.

Жанр не определился — спроси владельца одним вопросом (А или Б), не угадывай.

## Шаг 2. Пиши или правь по гайду жанра

Открой гайд жанра и следуй ему целиком. Он держит структуру, глубину, правила письма и чек-лист перед сдачей для этого типа дока — второй раз их здесь не повторяем.

## Поддержка готовых доков

Всё ниже — обслуживание УЖЕ написанных доков (чаще всего справочника). Запускается ПОСЛЕ того, как определён жанр, и правит по гайду этого жанра.

**Аудит.** Триггер: «проверь / аудит документации». Прочитай все файлы жанра (для справочника — все `references/` + CLAUDE.md + README.md). Отметь нарушения гайда жанра, дубли между файлами, раздутые разделы, плейсхолдеры и разнобой терминов. Собери отчёт по файлам → спроси владельца, что чинить → примени → сверь.

**Правка.** Триггер: «обнови / поправь док». Найди файл (не ясно — спроси), прочитай, правь по гайду жанра. Проверь, не задел ли смежные файлы (стек, имена, версии) → обнови и их. Любую правку показывай владельцу в формате было→стало: приведи конкретный старый кусок текста и конкретный новый, а не пересказ изменения. Плохо: «усилю правило про ветки». Хорошо: «Было: „ветку называем по фиче“. Стало: „ветку называем `feature/<номер задачи>-<короткое имя>`“».

**Сверка.** Триггер: «проверь термины / расхождения». Собери по всем файлам жанра имена стека, версии, сервисы, БД, env. Найди разнобой («PostgreSQL» vs «Postgres») → спроси эталон у владельца → выровняй везде.

**Статус.** Триггер: «насколько заполнена документация». По каждому файлу жанра: есть? заполнен / частично / шаблон / нет? размер? → отчёт с рекомендациями.

## Корневые и новые файлы

CLAUDE.md — только факты о проекте и ссылки, своего гайда жанра у него нет. У README.md раздел про запуск и выкатку пишется по гайду инструкции (`references/instruction.md`), остальные разделы держим короткими и ссылаемся из них на справочник. При аудите проверяй это.

Заводишь новый файл — сделай шаги его жанра целиком:

- **Закон.** Текст в `standards/<имя>-standard.md`, символьная ссылка `ln -s ../../standards/<имя>-standard.md .claude/rules/<имя>-standard.md`, строка в списке законов CLAUDE.md и в дереве README.md. Без ссылки в `.claude/rules/` закон не грузится в контекст сессии и не работает вовсе. Закон, который грузится по типу файла в работе, несёт frontmatter с блоком `paths`.
- **Справочник.** Файл в `.claude/skills/project-knowledge/references/`, строка в `project-knowledge/SKILL.md` и, если они перечисляют доки, в CLAUDE.md и README.md.
- **Инструкция.** Файл в `docs/` (`standards/project-layout-standard.md` п.8).
- **Разбор: запись решения.** Файл `docs/decisions/NNNN-название.md` в день решения (`standards/architecture-standard.md` п.10).
- **Агент.** Файл в `.claude/agents/`, шапка проверяется живым вызовом (`references/agent.md`).