Commit Message

---
name: commit-message
description: Пишет коммит-сообщение, реально прочитав и осмыслив diff — не подставляя его в шаблон. Формат (subject/body, ветки) уже зафиксирован в CLAUDE.md → Git conventions; этот скилл — про содержание. Использовать, когда пользователь просит закоммитить, написать сообщение коммита, или перед тем как предложить `git commit`.
model: sonnet
effort: high
---

# Коммит-сообщения: читать diff, а не подставлять в шаблон

Формат уже задан в `CLAUDE.md` → «Git conventions»: `Область: что сделано» в
subject, без Conventional Commits, тело о ПОЧЕМУ не о ЧТО, без списка файлов.
Здесь эти три строки не повторяются — здесь то, что в CLAUDE.md сознательно не
уместилось: как получить содержание тела, а не только его форму.

## Суть: diff — это симптом или решение, а не список строк

Плохой процесс: пробежать `git diff` построчно, пересказать «добавлено X,
удалено Y», подставить пересказ в шаблон. Так получается сообщение, которое
технически по форме верно и ничего не объясняет — ровно то, что этот скилл
должен предотвратить.

Настоящие коммиты проекта (полные примеры —
[references/style-examples.md](references/style-examples.md)) устроены иначе:

- **Багфикс — сначала диагноз, потом лечение.** Не «поправлена позиция при
  вселении», а: в чём разные точки отсчёта у тела и у игрока, почему игрок
  проваливался, почему лечение — «взять офсет из коллайдера», а не константа.
- **Фича — сначала чего не хватало по существу**, потом раскладка решения и
  явно названные отвергнутые варианты («иначе выбор сводится к…», «дублировать
  ещё и здесь — два источника правды»).
- **Правки задним числом ссылаются на предыдущий коммит по хэшу**, если diff
  его откатывает или уточняет — не «раньше было неправильно», а
  `git log -p -- <файл>` / `git blame`, чтобы найти, какой коммит уточняется, и
  назвать его.
- **Никогда не перечисляет изменённые файлы** — это уже есть в самом diff.
- **Числа и проценты — только когда они реально посчитаны** (тест прогнан,
  профайлер запущен), не для солидности.
- **Масштаб тела соразмерен масштабу diff**: одна правка — два абзаца, даже
  маленькая (см. форму «HUD: карта в панель» в примерах); диагностика на CI —
  список из нескольких независимых причин, потому что их правда несколько.

## Порядок работы

1. **Что вообще коммитим.** `git status` (никогда `-uall`) и `git diff`.
   Если что-то уже в индексе — читать `git diff --cached`, это и есть
   предмет коммита; если нет — прочитать `git diff` по рабочему дереву и
   решить вместе с пользователем, что стоит в этот коммит, а что нет (не
   `git add -A` — конкретные пути, см. общий протокол коммитов).
2. **Прочитать diff по намерению, не по строкам.** Если контекста в диффе не
   хватает, чтобы понять, что именно изменилось в поведении — дочитать файл
   целиком (`Read`), не гадать по трём строкам контекста. Хунк в компоненте +
   хунк в системе + хунк в сцене часто — одно намерение, а не три отдельных.
3. **Смотреть, что удалено и что было ДО, не только что стало.** Диагноз бага
   виден в разнице между старым и новым условием/веткой; дизайн-решение — в
   том, какая структура заменена (лист характеристик → компоненты, множитель →
   абсолютное число). Комментарии в диффе, особенно WHY-комментарии по
   правилу проекта, часто уже содержат готовую причину — не придумывать её
   заново, если она написана прямо в патче.
4. **Сгруппировать хунки по потокам замысла**, не по файлам и не по папкам.
   Одна причина, тронувшая пять файлов, — один поток, один абзац. Две
   несвязанные причины в одном файле — два потока, два абзаца.
5. **Свериться со словарём проекта.** Если правка касается именованного
   инварианта («Правило v9», модель распада, двери↔граф) — назвать его так,
   как он назван в `docs/astral-genesis/` (через карту `docs-sync`), а не
   изобретать синонимы для того же самого. Область в subject — тоже по
   возможности из уже использованного словаря
   ([references/style-examples.md](references/style-examples.md), раздел
   «Словарь Область»), а не новое имя для той же подсистемы.
6. **Составить subject**: `Область: что сделано`, без точки в конце,
   по-русски. Две явно связанные области — через «и» («Риг тел и геометрия
   комнат»). Действительно несвязанная россыпь (заметки, план, разбор
   бэклога) — общая область вроде «Планирование», раз в истории так уже
   делали; но см. следующий пункт.
7. **Составить тело**: абзац на поток, в порядке значимости, форма — по
   образцам выше. Bullets — только когда внутри потока правда несколько
   отдельных решений (не как замена абзацу).
8. Упомянуть headless-проверку одной строкой в конце, **только если она
   реально прогонялась в этой сессии** (см. навык `gameplay-testing`) —
   придуманная строка «проверено» хуже отсутствующей.
9. Показать черновик пользователю. Сам `git add`/`git commit` — по общему
   протоколу (конкретные файлы, heredoc, `Co-Authored-By`, коммитить только
   когда попросили).

## Когда НЕ сводить в один коммит

Если diff — это две причины, которые не связаны и не бьют по одной и той же
цели (не «фикс + рефакторинг вокруг него», а буквально два разных дела,
случайно оказавшихся в одном рабочем дереве) — сказать об этом прямо и
предложить разбить на отдельные коммиты (`git add` по конкретным файлам под
каждый), прежде чем писать сообщение на всё сразу. Легитимный грабж-бэг вроде
«Планирование: баг вселения, экран итогов, коридоры, звук, настройки, арт» в
истории проекта тоже есть — это нормально, когда коммит и есть заметки/план по
нескольким темам сразу, а не код с двумя случайно сбившимися в одно рабочее
дерево задачами.