mcpField
C
changelog-discipline

changelog-discipline

github.com/hanumatoriDevelopment51192 installsUpdated 1d ago
Repository

About changelog-discipline

A skill for maintaining a project changelog after code changes, during setup, and at release time. It emphasizes recording the reason behind decisions, prior behavior, and rejected alternatives so future maintainers can recover context rather than just file-level changes.

Key features

  1. 01Add an entry after each completed code change
  2. 02Separate concise mechanical notes from decision context
  3. 03Record why, prior behavior, and rejected options
  4. 04Organize entries under Unreleased sections
  5. 05Prepare release summaries with four fields

Use cases

  1. 01Update Unreleased after a completed change
  2. 02Document why a behavior or design choice changed
  3. 03Set up a changelog for a new project
  4. 04Turn Unreleased notes into a release summary

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/hanumatori/nodumbmode --skill changelog-discipline

After installing, type/changelog-disciplinein Claude Code to confirm it loaded.

Bundled filesreferences/01-antipatterns.mdreferences/02-examples.md

Details

From the project README

changelog-discipline

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

Scope

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

Core Principles

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

Формат

Структура файла
# 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 — примеры записей до и после

Comments

Markdown supported