mcpField
C
changelog-discipline

changelog-discipline

github.com/hanumatori开发51192 次安装1 天前更新
代码仓库

关于 changelog-discipline

用于在代码变更后、项目初始化及发布时维护项目变更日志的技能。它强调记录决策原因、此前行为和未采用的方案，帮助后续维护者恢复背景，而非只罗列文件改动。

主要功能

  1. 01每项已完成代码变更后添加记录
  2. 02区分机械修改与决策背景
  3. 03记录原因、原有行为和被舍弃方案
  4. 04在 Unreleased 下组织条目
  5. 05用四个字段编写发布摘要

适用场景

  1. 01完成代码变更后更新 Unreleased
  2. 02说明行为或设计选择改变的原因
  3. 03为新项目设置变更日志
  4. 04将 Unreleased 条目整理为发布摘要

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/changelog-discipline确认已加载。

附带文件references/01-antipatterns.mdreferences/02-examples.md

README 原文English

来自项目 README

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 — примеры записей до и после

评论

支持 Markdown