keep-a-changelog

Keep a Changelog

Keep a Changelog 1.1.0 に準拠した CHANGELOG.md ファイルを管理し、バージョンにはセマンティック バージョニングを使用します（完全なバージョン更新ルールは、関連する semver スキルに記載されています）。変更履歴は、人が変更点をひと目で把握できるようにするものです。そのため、項目は人向けに記述し（git log の出力をそのまま貼り付けるのではなく）、種類ごとにまとめ、新しい順に並べます。

基本原則

• 人向けに記述します。コミットや差分を、ユーザー向けの平易な文章に書き直し、生の git log を貼り付けないでください。
• リリースごとに項目を追加し、YYYY-MM-DD 形式の日付を付けて、新しい順に並べます。
• バージョンを付ける前の変更は、先頭の [Unreleased] セクションにまとめます。
• 変更を以下の6種類に分類します。項目のない種類の見出しは省略します。
• 前文には Keep a Changelog と Semantic Versioning の両方を記載します。

ファイルのひな形

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.2.0] - 2026-07-20

### Added

- User-facing description of a new feature.

### Fixed

- User-facing description of a bug fix.

[unreleased]: https://github.com/OWNER/REPO/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/OWNER/REPO/compare/v1.1.0...v1.2.0

末尾のリンクによって、各バージョン見出しが差分リンクになります。比較 URL はプロジェクトのリモートから作成してください。URL を推測するくらいなら、末尾のリンク部分を省略してください。

6つの種類

複数の種類に該当する場合は、次の順に記載します。Added（新機能）、Changed（既存の動作の変更）、Deprecated（引き続き存在するものの、削除予定）、Removed（今回のリリースで削除）、Fixed（バグ修正）、Security（脆弱性の修正。Fixed の項目と重複する場合も、分けて記載します）。箇条書きはそれぞれ1行にまとめ、実装の詳細ではなく、何が変わり、ユーザーにとってなぜ重要なのかを簡潔に記述します。

バージョンの決め方

影響が最も大きい変更に基づいてバージョンを更新します。詳しいロジックと判断手順は semver スキルに記載されています。

1.0.0 以上 — 公開 API は約束です。

リリースに含まれる変更…	更新
Removed に該当する変更、または互換性を損なう Changed の項目	MAJOR
Added または Deprecated の項目（互換性を損なう変更がない場合）	MINOR
Fixed／Security のみ	PATCH

0.y.z 未満 — まだ互換性を保証していないため、全体の段階が1つ下がります（npm の ^ 範囲の解決方法と同様です。semver を参照）。

リリースに含まれる変更…	更新
Removed に該当する変更、または互換性を損なう Changed の項目	MINOR（0.3.1 → 0.4.0）
互換性を損なわない項目のみ — Added／Changed／Deprecated／Fixed／Security	PATCH（0.3.1 → 0.3.2）

破壊的変更が1つでもあれば、リリース全体の更新レベルが決まります。更新を提案する際は、その判断理由を記載し、0.x バージョンには互換性の保証がないことを明示してください。API が安定し、本番環境で利用されるようになったら 1.0.0 をリリースします。

バージョンの参照元

更新を提案する前に、現在のバージョンを確認してください。決して推測してはいけません。

1. ファイルがある場合は package.json の version を参照します。次の更新バージョンの唯一の正しい参照元です。
2. それ以外の場合は、CHANGELOG.md の最新の ## [x.y.z] 見出しを参照します。
3. それもない場合は、ほかのプロジェクトマニフェスト（Cargo.toml、pyproject.toml など）を参照します。
4. いずれも存在しない場合は、推測せずに確認してください。

リリース時に package.json がある場合は、新しいバージョンに合わせて更新することを提案してください。ユーザーの確認を得るまでは変更しないでください。

このスキルで自動的に行わないこと

変更履歴を更新しても、公開の許可を得たことにはなりません。ユーザーから明示的に依頼されない限り、Git タグの作成、GitHub リリース（gh release create）の作成、リリースコミットのプッシュは絶対に行わないでください。プッシュ、マージ、変更履歴の用語で「リリースを切る」と依頼されても、それらが許可されたことにはなりません。

リリースの準備が整ったら、変更履歴（およびバージョンの提案）までで止め、次の作業を行うかユーザーに確認してください。

• package.json のバージョンを上げる
• コミットする
• タグを付ける
• プッシュする
• GitHub リリースを作成する

確認が取れた作業だけを行ってください。「変更履歴だけ更新して」と言われた場合は、それが作業のすべてです。

ワークフロー

変更を記録する： 変更を分類し、## [Unreleased] 内の該当する種類の下に1行の箇条書きを追加します（セクションまたは見出しがない場合は作成します）。バージョンと日付はまだ記入しません。

リリースを切る： package.json（またはバージョンの参照元に記載された代替元）から現在のバージョンを読み取り、上記の表に基づいてバージョンの更新幅を算出します。次に、## [Unreleased] の内容を新しい ## [x.y.z] - YYYY-MM-DD セクションに移し、その上に空の ## [Unreleased] を新たに置き、リンクフッターを更新します（[unreleased] → compare/vNEW...HEAD、[vNEW] を追加）。該当する場合は、package.json のバージョン更新も提案します。タグ付け、プッシュ、GitHub リリースの作成を行う前に止めて確認してください。詳しくはこのスキルで自動的に行わないことを参照してください。

コミットから作成する： ノイズ（マージ、フォーマットのみの変更、純粋なリファクタリング、ドキュメント／CI のみの変更――Conventional Commits における chore／style／ci／build／test の種類。conventional-commits スキルを参照）を除外し、残った各コミットをユーザー向けの箇条書きに書き換え、6種類に分類して、バージョンの更新幅を提案します。

取り消されたリリース： 公開後に取り下げられたリリースは、見出しにその旨を示し、削除せずに残します（インストールした人に知らせる必要があります）。

## [1.4.1] - 2026-07-18 [YANKED]

CHANGELOG.md の監査

次の点を確認します。日付が YYYY-MM-DD 形式であること、生のコミットや差分がそのまま貼り付けられていないこと、空の種類別見出しがないこと、バージョンが厳密に降順であること、前文に両方の規約が記載されていること、各バージョンの更新幅が変更内容に合っていること（例：機能の削除が PATCH のみとして扱われていないか）。具体的な修正点を簡潔に列挙し、レビューではなく修正を求められている場合は、その後に修正を適用します。