changelog-generator

changelog-generator skillの概要

changelog-generatorでできること

changelog-generator は、Conventional Commit の履歴をもとに、一貫性があり監査しやすいリリースノートを作成するためのエンジニアリング向けリリース管理 skill です。AI エージェントがコミット件名を解析し、セマンティックバージョンの更新幅を推定し、Keep a Changelog 形式のセクションを生成し、汎用プロンプトで曖昧な文章を作るのではなく、CI や hotfix ワークフローに接続できる形に整えることを支援します。

向いているユーザーとリリース場面

この changelog-generator skill は、実際の git 履歴から再現性のある CHANGELOG.md エントリを作成したいメンテナー、リリースエンジニア、DevOps チーム、テクニカルライターに向いています。リリースカット、PR のコミットチェック、セマンティックバージョン計画、monorepo のパッケージ単位リリース、トレーサビリティが重要な緊急 hotfix ノートに適しています。

特に、開発者向けのコミットメッセージからユーザー向けのリリースノートを作りつつ、コミット範囲、バージョン、破壊的変更、セキュリティ修正、移行メモといった根拠を残したい場合、Technical Writing 向けの changelog-generator として有用です。

通常のプロンプトとの違い

通常の「リリースノートを書いて」というプロンプトでは、構造が崩れたり、影響範囲を推測で補ってしまったりしがちです。この skill には、scripts/generate_changelog.py、scripts/commit_linter.py、scripts/version_bumper.py といった専用スクリプトに加え、changelog の書式、CI 連携、monorepo、hotfix 手順に関するガイドが含まれています。そのため、自動または半自動のリリースワークフローにより適しています。

導入前に確認すべき制約

この skill は、コミットが feat(auth): add OAuth2 integration や fix(api): resolve race condition のような Conventional Commits に近い形式で書かれていることを前提にしています。リポジトリで updates、misc fixes のような曖昧なメッセージを使っていたり、有用な件名なしで squash commit していたりする場合、追加の文脈を与えない限り出力品質は下がります。semver 以外のリリースポリシーを採用しているチームは、バージョン更新の推定結果を参考情報として扱うべきです。

changelog-generator skillの使い方

changelog-generatorのインストールとリポジトリ設定

Claude 形式のローカル skill として使う場合は、skill フォルダを自分の skill ディレクトリにコピーします。リポジトリの README には、次のような例が示されています。

cp -R engineering/changelog-generator ~/.claude/skills/changelog-generator

コピー元のパスは、実際に clone したリポジトリの場所に合わせて変更してください。本番運用でこの skill に依存する前に、次のファイルも確認しておくと安全です。

• SKILL.md: エージェント向けワークフロー
• README.md: クイックスタート用コマンド
• references/changelog-formatting-guide.md: 出力ルール
• references/ci-integration.md: CI 連携の例
• references/monorepo-strategy.md: パッケージを個別にリリースする場合の方針
• references/hotfix-procedures.md: 緊急リリースの分類手順

信頼できる出力に必要な入力

changelog-generator を効果的に使うには、明確なリリース範囲と十分なポリシー情報を渡します。役立つ入力の例は次のとおりです。

• v1.2.0..v1.3.0 のような前回タグと対象タグ
• skill に更新幅を計算させる場合の対象バージョンまたは現在バージョン
• エージェントが git にアクセスできない場合の git log --oneline から取得した生のコミット件名
• 破壊的変更に移行メモが必要かどうか
• payments や auth など、monorepo のパッケージスコープ
• 希望する出力形式: CHANGELOG.md 用の markdown、CI 用の JSON、リリース告知のドラフト

弱いプロンプト: “Generate a changelog.”

より良いプロンプト: “Use changelog-generator to create a Keep a Changelog entry for v1.4.0 from commits between v1.3.0 and HEAD. Group by Security, Added, Changed, Deprecated, Removed, Fixed. Flag breaking changes, infer the semver bump, and produce a concise markdown entry suitable for CHANGELOG.md.”

実用的なコマンド例

同梱ツールは直接実行することも、リリースワークフロー中にエージェントから参照させることもできます。

タグ範囲から markdown を生成します。

python3 scripts/generate_changelog.py \
  --from-tag v1.2.0 \
  --to-tag v1.3.0 \
  --next-version v1.3.0 \
  --format markdown

マージ前にコミット件名を lint します。

python3 scripts/commit_linter.py \
  --from-ref origin/main \
  --to-ref HEAD \
  --strict \
  --format text

CI で機械可読な結果が必要な場合は JSON 出力を使い、人がレビューしたり CHANGELOG.md の先頭に追加したりする場合は markdown を使います。

より良いリリースノートを作るワークフロー

まずコミットを lint し、次にバージョン更新幅を推定し、その後 changelog エントリを生成して、最後にユーザーへの影響が伝わるよう編集します。最も重要な編集作業は、実装寄りのメッセージをユーザーに見える変更へ変換しつつ、重要な技術的リスクを隠さないことです。

たとえば、fix(db): resolve deadlock issues in concurrent transactions は “Changed transaction locking logic.” ではなく、“Fixed database deadlocks that could interrupt concurrent account updates,” のようなユーザー向けの説明にするべきです。

changelog-generator skillのFAQ

changelog-generatorは完全自動リリース専用ですか？

いいえ。この skill は、自動化されたワークフローでも、編集を前提としたワークフローでも有効です。CI でコミット形式を強制したりドラフトノートを生成したりしつつ、人間が文言を整え、移行の詳細を追加し、最終的なリリースエントリを承認できます。

初心者でもこのchangelog-generatorガイドを使えますか？

はい。リポジトリですでにタグが使われており、コミットがある程度構造化されていれば利用できます。初心者は assets/sample_git_log.txt から始め、スクリプトをローカルで実行し、出力を references/changelog-formatting-guide.md と比較するとよいでしょう。多くの場合、難しいのはツールそのものではなく、十分なスコープと意図を含むコミットメッセージを書く習慣を身につけることです。

このskillを使わないほうがよい場合は？

コミットが実態とずれている、過度に squash されている、または出荷された挙動と結びついていない場合は、これを主要な情報源にするのは避けてください。また、ポジショニング、スクリーンショット、顧客コメント、キャンペーンメッセージが必要なマーケティング向けローンチノートにも向きません。その場合は、この skill を事実ベースのリリース項目の棚卸しに使い、告知文は別途作成してください。

monorepoとスコープ付きコミットにはどう対応しますか？

monorepo のガイドでは、feat(payments): add Stripe webhook handler のようなスコープ付き Conventional Commits が推奨されています。これにより、パッケージ単位のフィルタリングやオーナーシップ管理が可能になります。スコープがパッケージ名やディレクトリ名と一致していない場合、パッケージ別 changelog が不完全になったりノイズが増えたりするため、自動化に依存する前にコミットスコープを揃えてください。

changelog-generator skillを改善する方法

生成前にchangelog-generatorの入力を改善する

changelog-generator の結果を最も早く改善する方法は、コミットの流れそのものを改善することです。明確な type、意味のある scope、ユーザーに関係する subject を使いましょう。

• Good: fix(security): patch SQL injection vulnerability in reports
• Good: feat(admin)!: redesign admin panel with role-based permissions
• Weak: fix stuff
• Weak: updates after review

破壊的変更では、コミット件名に ! を含め、コミット本文に移行に関する文脈がない場合はプロンプトで補足してください。

よくある失敗を防ぐ

よくある問題には、セキュリティ項目の漏れ、内部的な chore の過剰掲載、誤った semver 更新幅、プロダクトへの影響ではなくコード変更を説明してしまう changelog の箇条書きなどがあります。これを防ぐには、エージェントに次のように指示します。

• ユーザーに影響しない純粋な chore、style、test コミットは除外する
• security、deprecated、remove、破壊的変更のコミットを明示的に取り上げる
• “recommended version bump” と “release manager decision” を分ける
• 破壊的変更には移行メモを含める

初回出力の後に改善を重ねる

最初の changelog は、構造化されたドラフトとして扱います。次のようなフォローアップ質問を使うとよいでしょう。

• “Which bullets are not user-visible and should be removed?”
• “Which breaking changes need migration notes?”
• “Rewrite the Fixed section for customer-facing clarity.”
• “Return JSON with commit hash, category, scope, and final bullet for audit review.”

これにより、トレーサビリティを保ちながら読みやすさを高められます。

自社のリリースポリシーに合わせて拡張する

チームは、許可するコミット type、必須 scope、severity label、パッケージオーナー、changelog テンプレートなど、自社固有のリリースルールを追加することで skill を改善できます。CI から公開する場合は、実際の GitHub Actions または GitLab CI のジョブに合わせて references/ci-integration.md を拡張してください。hotfix が頻繁にある場合は、承認経路、ロールバックのトリガー、SLA の表現に合わせて references/hotfix-procedures.md をカスタマイズしてください。