# Changelog Discipline

> Write and maintain a CHANGELOG that records every completed code change without becoming a commit dump. Use after any code change in a project that has a changelog, when setting one up, when preparing a release, or when the user asks why something was built this way. Keep mechanical entries brief; preserve reasons and rejected alternatives for non-obvious decisions. Do not use for commit messages, PR descriptions, or user-facing release notes.

- Skill: `hanumatori/changelog-discipline` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hanumatori/changelog-discipline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hanumatori/changelog-discipline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hanumatori (https://skillmd.com/u/hanumatori)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hanumatori/changelog-discipline

---


# changelog-discipline

CHANGELOG фиксирует **каждое законченное изменение кода**, но не пересказывает
каждый файл и коммит. Механическая правка получает короткую запись; решение —
контекст, которого нет в коде: почему сделали именно так, что было до этого и
что отвергли.

## Scope

- Применять после **каждого законченного изменения кода** в проекте, где ведётся
  changelog.
- Применять при настройке changelog в новом проекте.
- Применять при подготовке релиза.
- Не применять для сообщений коммитов, описаний PR и релиз-нот для
  пользователей — другие форматы, другие читатели.

## Core Principles

- **Пишется для того, кто вернётся через полгода.** Обычно это сам автор,
  забывший контекст.
- **Полнота не требует оценки важности.** Менялся код — появилась запись. Один
  пункт описывает цельное изменение, а не каждый файл или коммит.
- **Глубина зависит от решения.** Для механической правки достаточно назвать
  область и явно сказать, что поведение не изменилось. Для неочевидного решения
  нужны причина, прежнее состояние и отвергнутые варианты.
- **«Почему» дороже «что».** Что изменилось — видно в диффе. Почему выбрали
  этот вариант — не видно нигде.
- **Changelog не описывает текущее состояние.** Актуальное правило живёт в
  коде, конфигурации или контракте; changelog объясняет, почему оно изменилось,
  и указывает, где его искать.
- **Отвергнутая альтернатива ценнее описания принятой.** Она не даст через
  полгода переделать обратно и наступить на те же грабли.
- **Запись делается сразу, а не перед релизом.** Иначе полноту уже нельзя
  проверить по ходу работы, а причины решений успевают забыться.

## Формат

### Структура файла

```markdown
# Changelog

Все заметные изменения <проект>. Формат — Keep a Changelog.

---

## [Unreleased]

### Added
### Changed
### Fixed

---

## [0.1.3] — 2026-07-31

### <Заголовок релиза — одной фразой о сути>

- **Что:** …
- **Где:** …
- **Почему:** …
- **Было:** …

### Added
### Changed
### Fixed
```

### Резюме релиза — четыре поля

Самая ценная часть. Не пересказ пунктов ниже, а ответ на вопрос «что вообще
поменялось в продукте»:

| Поле | Что отвечает |
|---|---|
| **Что** | что теперь работает иначе, в терминах продукта, а не кода |
| **Где** | какие файлы и области затронуты — точка входа для того, кто полезет разбираться |
| **Почему** | какую боль это снимает; ради чего вообще делалось |
| **Было** | как вело себя до — иначе через полгода непонятно, что чинили |

Поле **Было** чаще всего пропускают, и зря: без него запись описывает мир,
которого читатель не помнит.

### Пункты внутри секций

Одна запись = одно законченное изменение, а не один файл или коммит. Внутри:

- **жирный заголовок** — суть одной фразой
- что поменялось и где
- для механической правки — явное «поведение не изменилось»
- для неочевидного решения — почему выбрали так, как было раньше и что отвергли

Пример:

> **ПКМ вместо всплывающего меню по ховеру.** Копирование ссылки из текста
> переехало в контекстное меню (`LinkContextMenu`). Сначала это было всплывающее
> по ховеру микро-меню, но до кнопки не успевал доехать курсор — контекстное
> меню совпадает с поведением родного текстового поля и не требует ни за чем
> успевать.

Здесь есть отвергнутый вариант и причина отказа. Через полгода это не даст
«улучшить» обратно.

## Workflow

1. **После каждого законченного изменения кода** — сразу дописать один пункт в
   `[Unreleased]`, в подходящую секцию (Added / Changed / Fixed).
2. **Выбрать глубину.** Механическую правку записать одной строкой с пометкой,
   что поведение не изменилось. Для изменения поведения или неочевидного решения
   добавить причину, прежнее состояние и отвергнутые варианты.
3. **Формулировать от продукта**, когда поведение изменилось: не «добавил
   параметр», а «теперь можно X».
4. **При релизе** — превратить `[Unreleased]` в версию с датой и написать резюме
   из четырёх полей.

## Проверка качества

Проверка полноты проста: если менялся код, в `[Unreleased]` появился пункт про
цельное изменение.

Для механической правки достаточно ответить:

- где менялось;
- подтверждено ли, что поведение осталось прежним.

Для изменения поведения или решения запись должна отвечать:

- что изменилось для пользователя;
- почему сделали так, а не иначе;
- где смотреть код;
- как было раньше.

Если по changelog приходится восстанавливать актуальные значения или правила —
они лежат не там; запись должна ссылаться на действующий источник.

## References

- `references/01-antipatterns.md` — как не надо, с разбором
- `references/02-examples.md` — примеры записей до и после