Docs Sync

---
name: docs-sync
description: Поддерживает документацию Astral Genesis в актуальном состоянии и подтягивает подробное описание механики по запросу — WHY-комментарии в коде, Obsidian-вики docs/astral-genesis/ и карта-указатель CLAUDE.md. Запускать после фичи/рефакторинга, менявшего поведение или связи систем, по просьбе «актуализировать документацию»/«проверить комментарии», перед закрытием карточки в docs/astral-genesis/Задачи/, а также когда нужно поднять подробности по конкретной системе или механике.
model: sonnet
effort: high
---

# Документация проекта: навигация и синхронизация

У скилла две работы:

1. **Подтянуть знание** — найти и прочитать подробное описание механики, когда
   работа её задевает (§«Навигация»).
2. **Свести документацию с кодом** — после того как код изменился
   (§«Сверка»).

## Главная конвенция

> **`CLAUDE.md` — карта, а не справочник.** В нём живёт короткая сводка
> инварианта и **ссылка** на подробное описание в `docs/astral-genesis/`.
> Подробности подтягиваются по ссылке в момент работы над областью, а не висят
> в контексте постоянно — вики для этого и ведётся.

Отсюда правило при добавлении знания:

- **Разрослось до нескольких строк — место в `docs/astral-genesis/`**, а в
  `CLAUDE.md` остаётся сводка «что это и чего нельзя» + ссылка.
- **Никогда не описывать одно и то же в обоих местах** — это не подстраховка, а
  гарантированный рассинхрон. Единственный источник правды — вики; `CLAUDE.md`
  цитирует из неё только инвариант.
- **Ссылки не должны идти по кругу.** Документ вики не отсылает за подробностями
  обратно в `CLAUDE.md` — если так вышло, содержимому нужен дом в вики.

## Навигация: где что описано

Полная карта — [references/doc-map.md](references/doc-map.md). Коротко:

| Нужно разобраться в… | Читать |
|---|---|
| модели ECS, «Правиле v9», ECS-паттернах | `how-to/GECS и правила движка.md` |
| генерации мира, слоях, дверях, переходах, сейве | `how-to/Цикл забега.md` |
| интерактивных объектах, луче, подсказках | `how-to/Взаимодействие.md` |
| захвате тела, характеристиках, распаде | `how-to/Захват тела.md` |
| граблях инструментов редактора, шаблонах сущностей | `how-to/Редакторские инструменты.md` |
| слоях физики, теме UI, префиксах, ребайнде | `Справка/Конвенции проекта.md` |
| CI, версиях, релизах | `how-to/Релизы и сборка.md` |
| что вообще уже реализовано | `Состояние проекта.md` |

Читать **до** правки подсистемы, а не после. Если нужного описания нет — это
пробел документации, а не повод восстанавливать логику из кода молча: завести
раздел там, где он должен быть по карте.

## Сверка: порядок

1. **Определить объём.** `git diff` / `git log` от последней ревизии либо явный
   список файлов от пользователя.
2. **Код-комментарии.** Для каждого затронутого `.gd` перечитать соседние
   комментарии. Правило комментария в проекте — **WHY, не WHAT**:
   - пересказ того, что и так видно из имени, — убрать;
   - скрытый инвариант, причина решения или обходной путь стали неочевидны, а
     комментария нет — добавить одну строку, не абзац;
   - комментарий ссылается на переименованный/удалённый метод или компонент —
     поправить.
3. **Вики.** По карте выше найти документ, описывающий затронутую область, и
   свести его с новым поведением. Частые цели: профильный how-to,
   `Состояние проекта.md` (раздел про затронутый поток или «что реализовано»),
   карточка в `Задачи/`.
4. **`CLAUDE.md`.** Трогать, **только** если изменился сам инвариант или
   конвенция — то есть сводка стала неверной. Если поменялись подробности, а
   инвариант тот же, `CLAUDE.md` не трогается вовсе. Проверить заодно, что
   ссылка ведёт туда, где описание действительно лежит, и что таблица
   «Документация — карта» знает про новый документ.
5. **Карточки задач.** Задача закрыта → перенести карточку из
   `Задачи/vX.Y.Z.md` в `Задачи/Завершено/`. Появилась незапланированная
   работа → завести карточку.
6. **Проверка целостности ссылок:**

   ```bash
   python .claude/skills/docs-sync/scripts/check_doc_references.py
   ```

   Ищет в `CLAUDE.md` и вики идентификаторы `C_*`/`S_*`/`E_*`/`O_*`/`RS_*`/`A_*`
   и пути файлов, которых нет в `src/`/`addons/` (кроме `addons/gecs` —
   апстрим-сабмодуль). Роадмап (`Задачи/`) пропускается по умолчанию: он
   намеренно описывает ещё не написанный код; `--include-roadmap` включает и
   его. Это **не автофикс** — регулярка ловит и случайные совпадения, список
   проверяется глазами.

   Отдельно проверить `[[wikilinks]]`: Obsidian не роняет ошибку на битой
   ссылке, поэтому после переименования файла надо руками найти ссылающихся
   (поиск по `[[старое имя`).
7. **Не описывать несуществующее.** Если фича откатана или недоделана, а вики
   называет её готовой — поправить сразу, а не оставлять расхождение до
   следующего прохода.

## Границы

- Не переписывать стиль и структуру документа без необходимости — только факты.
- Не документировать будущее в `Состояние проекта.md` — для этого `Задачи/`.
- Не трогать `История.md` (лор), если не попросили явно.
- Не раздувать `CLAUDE.md`: любое добавление туда — сводка и ссылка.