release-notes

リリースノートジェネレーター

次の内容から、ユーザー向けのリリースノートを生成します：$ARGUMENTS

リリースノートは機械ではなく、人に向けたものです。目的は、何が変わったのか、そしてそれがなぜ重要なのかを、対象読者が気にするレベルで伝えることです。コミットはコードの進化を記録し、リリースノートはユーザーにとっての意義を記録します。

ステップ 1：入力を解析する

ユーザーが何を提供したかを検出し、それに応じて変更内容の生データを収集します。

バージョン／タグの範囲（v1.2.0..v1.3.0 または 1.2..1.3 に一致するもの）：

git log --format='%H %s' $RANGE
git log --format='%B---COMMIT_BOUNDARY---' $RANGE
git diff --stat $RANGE

ブランチの比較（main..feature または origin/main..HEAD に一致するもの）：

git log --format='%H %s' $RANGE
git log --format='%B---COMMIT_BOUNDARY---' $RANGE
git diff --stat $RANGE

PR 番号（#42、#43 などに一致するもの）：

gh pr view <num> --json title,body,commits,labels

生テキスト：入力が上記のいずれのパターンにも一致しない場合、変更内容を直接記述したものとして扱います。git コマンドはスキップし、テキストをもとに作業します。また、ステップ 2 と 3 もスキップし、ステップ 4 に進みます。

引数がない場合：現在のブランチとベースを比較します：

CURRENT_BRANCH=$(git branch --show-current)
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback: try main, master, develop
git log --format='%H %s' $DEFAULT_BRANCH..$CURRENT_BRANCH
git log --format='%B---COMMIT_BOUNDARY---' $DEFAULT_BRANCH..$CURRENT_BRANCH
git diff --stat $DEFAULT_BRANCH..$CURRENT_BRANCH

ステップ 2：プラットフォームを検出する

このプロジェクトがどこでホストされ、課題がどこで管理されているかを特定します。コードと課題の管理場所は異なる場合があります。たとえば、コードは GitHub でホストし、課題は Jira で管理していることがあります。

コードホスト

git remote を解析してプラットフォームを検出します：

git remote get-url origin

• github.com → GitHub。gh CLI を使用
• gitlab.com（またはカスタム GitLab ドメイン）→ GitLab。glab CLI を使用
• それ以外 → git のみのモード（PR／課題の検索をスキップ）

課題トラッカー

ステップ 1 で収集したコミットメッセージをスキャンし、参照パターンを確認します。

• #123 形式の参照 → 課題はコードホスト（GitHub または GitLab）で管理されています
• PROJ-123 形式の参照（大文字、ハイフン、数字）→ Jira。利用可能な場合は Atlassian MCP ツール（mcp__claude_ai_Atlassian__getJiraIssue）を使用します
• 同じプロジェクトで両方のパターンが使われることもあります。両方を確認してください

プラットフォームのツールが利用できない場合や認証に失敗した場合は、適切に git のみのモードに切り替えます。処理を止めないでください。

ステップ 3：詳細を調査する — 参照先をたどる

これにより、コミットログの言い換えではなく、実用的なリリースノートになります。コミットから分かるのは、コードで_何が_変わったかです。PR から分かるのは、_なぜ_変更したかです。課題から分かるのは、_誰が_何を求め、どんな問題を抱えていたかです。どれも重要です。

参照を抽出する

ステップ 1 のすべてのコミットメッセージをスキャンし、次を探します。

• PR／MR 番号：#123（GitHub）、!123（GitLab）
• 課題番号：#456（GitHub／GitLab）、PROJ-789（Jira）
• PR または課題を指す URL

重複を除去します。複数のコミットが同じ PR を参照している場合があります。取得する PR と課題の一意なリストを作成します。

PR／MR を取得する

一意な PR 参照ごとに、次を行います。

GitHub：

gh pr view <num> --json title,body,closingIssuesReferences,labels,commits

GitLab：

glab mr view <num> --output json

PR の説明を注意深く読みます。ここでは開発者が次の内容を説明しています。

• 変更の動機
• ユーザーから見える影響
• 設計上の判断とトレードオフ
• スクリーンショットや変更前後の比較

関連する課題を取得する

PR が参照する各課題について（GitHub の closingIssuesReferences、または PR／コミットのテキストで言及されたもの）：

GitHub：

gh issue view <num> --json title,body,labels

GitLab：

glab issue view <num> --output json

Jira： 課題キー（例：PROJ-789）を指定して mcp__claude_ai_Atlassian__getJiraIssue を使用します。

課題本文には、本当の背景情報があります。ユーザーストーリー、再現手順付きのバグ報告、ユーザーが必要としているものやその理由を説明した機能リクエストなどです。ユーザーに伝わるリリースノートを書くうえで、非常に価値のある情報です。

コンテキストマップを作成する

論理的な変更ごとに、次の最大 3 層のコンテキストが得られます。

• コミット — コードで何が変わったか
• PR の説明 — なぜ変更したか、どのように取り組んだか
• 課題本文 — 元のユーザーリクエスト、バグ報告、機能仕様
• ラベル — 分類の手がかり（bug、feature、breaking-change、security など）

すべての変更について、3 層すべてが得られるとは限りません。PR を参照しないコミットもあれば、課題にリンクしていない PR もあります。利用可能な情報を使ってください。コミットメッセージより一段深い情報だけでも、リリースノートの質は大きく向上します。

大規模リリースへの対応

コミット数の多いリリース（50 件以上）では、一意の PR に絞って情報を検索してください。ほとんどのコミットは、少数の PR に対応しています。個別に取得する PR が多すぎる場合は、次の順に優先してください。

1. breaking、security、feature ラベルが付いた PR
2. イシューをクローズする PR（ユーザー向けの背景情報があります）
3. 説明が最も長い PR（参考にできる情報が多くあります）

ステップ 4：プロジェクトを理解する

何かを書く前に、これらのノートを読む人について理解してください。リポジトリを手早く確認します。

1. プロジェクトの種類：package.json、Cargo.toml、pyproject.toml、go.mod、または README.md を確認して、ライブラリ、CLI ツール、ウェブアプリ、API、フレームワーク、プラグインのどれに該当するかを判断します
2. 対象読者：ライブラリ → 開発者／API 利用者。CLI → ターミナルの利用者。ウェブアプリ → エンドユーザー。API → インテグレーター
3. 既存の変更履歴：CHANGELOG.md、CHANGES.md、または HISTORY.md があるか確認します。存在する場合は、最新の項目を読み、慣例（見出しのスタイル、項目の形式、トーン）に合わせます

このコンテキストは、次のステップで行うすべての判断に影響します。ライブラリのノートでは API の変更を直接記載できますが、エンドユーザー向けアプリのノートでは実装ではなく、その結果を説明する必要があります。

ステップ 5：分析して取捨選択する

ここが中心となる作業です。コードの変更を、ユーザー向けの情報に変換します。コミットメッセージだけでなく、ステップ 3 で作成したコンテキストマップ全体を活用してください。

ノイズを除外する

ユーザーに影響しない変更は省きます。

• CI/CD 設定の変更（ユーザーが依存するリリース／デプロイ動作に影響する場合を除く）
• リンター／フォーマッターの設定、空白の修正
• 動作に変化のない内部リファクタリング
• 依存関係のバージョン更新（ユーザーに見えるバグやセキュリティ問題を修正する場合を除く）
• テストのみの変更

関連するコミットをまとめる

1 つの機能を実装する、または 1 つの問題を修正する複数のコミットは、1 つの項目にまとめます。次の点を確認してください。

• 同じ PR 番号またはイシュー番号を参照するコミット
• 関連するメッセージとともに、同じファイルを変更する連続したコミット
• 初回の実装に続く「fixup」または「address review」コミット

破壊的変更を特定する

次の兆候を確認してください。破壊的変更を埋もれさせてはいけません。

• コミット本文にある BREAKING CHANGE: または BREAKING:
• Conventional Commits でタイプの後に付く !（例：feat!:）
• 公開 API の削除、関数シグネチャの変更、設定オプションの名前変更
• ユーザーの対応が必要なデータベース移行
• デフォルトの動作の変更
• PR に付いた breaking、breaking-change などのラベル

コンテキスト全体を活用して表現を書き換える

ここで、詳しく調査した効果が表れます。コミットメッセージを言い換えるだけでなく、より豊富なコンテキストを活用してください。

• イシューにバグ報告がある場合：修正内容をユーザーの体験に基づいて表現します。「カスタム MOD を入れたサーバーに参加するとクラッシュするという報告がありました」→「MOD を導入したサーバーへの参加時にクラッシュする問題を修正」
• PR の説明にユーザーへの影響が書かれている場合：コミットタイトルよりも、その説明に沿った表現を優先します
• イシューに利用例を含む機能リクエストがある場合：実装内容ではなく、ユーザーができるようになることを説明します
• ラベルがカテゴリを示している場合：分類（バグ、機能、セキュリティなど）に活用します
• より詳しいコンテキストがない場合：従来どおり、コミットメッセージをユーザー向けに書き換えます

書き換えの例：

• コミット：「UserService.getProfile() の null ポインターを修正」／イシュー：「プロフィールをクリックするとアプリがクラッシュする」→「ユーザープロフィールの表示時にクラッシュする問題を修正」
• コミット：「商品クエリに Redis キャッシュを追加」／PR：「大規模な商品カタログでは検索に 3 秒以上かかっていた」→「商品検索を高速化 — 大規模なカタログでも結果をすぐに読み込めます」
• コミット：「lodash を 4.17.20 から 4.17.21 に更新」→ セキュリティ修正の場合は「lodash の依存関係にあるセキュリティ脆弱性を修正」、定期的な更新の場合は省略

ステップ 6：リリースノートを書く

リリースノートは、リリースの経緯が伝わる短い散文にします。数段落でまとめてください。箇条書きや、カテゴリ分けされた変更履歴にはしません。コミットや PR の一覧はすでにあります。このスキルの目的は、それとは異なるものを作ることです。読者が 30 秒で読めて、何が変わり、なぜ重要なのかを理解できる、人間向けの要約です。

構成

関連する変更をテーマごとにまとめ、短い段落にします。自然な流れの例は次のとおりです。

1. 主な新機能から始める — 新しく追加された魅力的な機能です。バージョン番号を太字で示してから、主な追加機能と、それによってユーザーに何ができるようになるかを説明します。
2. インフラストラクチャやパフォーマンスの改善 — ユーザー体験に影響するバックエンドの変更（クエリの高速化、スケーラビリティの向上など）があれば、段落に含めます。
3. 小規模な改善や UX の変更 — ナビゲーションの改善、新しいビュー、使い勝手を向上させる機能などです。
4. バグ修正 — 信頼性の向上とバグ修正の取り組みをまとめた段落で締めくくります。すべての修正を個別に列挙する必要はありません。「信頼性に関する複数の問題」「いくつかの UI バグ」のようにテーマごとにまとめ、特に重要なものを具体的に挙げます。

リリースによっては、4 つすべての項目が必要とは限りません。小規模なパッチリリースなら、1 段落だけでもかまいません。メジャーリリースなら、5〜6 段落必要な場合もあります。内容に合わせて構成してください。

トーン

• 現在形で書き、くだけすぎず、会話調にします。製品を使っている人に、気の利くチームメイトがリリース内容を説明するようなトーンです
• 「あなた」を使って読者に直接呼びかけます（「ショップの出品情報をインポートできるようになりました」など）
• 対象読者が知っている技術用語は使ってかまいません。必要以上に簡単な表現にする必要はありませんが、内部向けの専門用語は避けてください
• 簡潔にまとめます。各段落は 2〜4 文にし、全体を 1 分以内で読める長さにします

破壊的変更

リリースに破壊的変更がある場合は、何よりも先に説明します。何が変わったのか、ユーザーが何をする必要があるのかを率直に伝えてください。ここでは、短い箇条書きが適切です。破壊的変更はひと目で分かり、見落とされないようにする必要があります。

例

適切なナラティブ形式のリリースノートは、次のようになります。

**v0.5.0** introduces Shop Actions, a new module component type that lets you
create automated actions triggered by shop purchases — opening up new
possibilities for your in-game economy. You can now also react to player
inventory changes through hook events, enabling modules for loot tracking,
item-based triggers, and more.

On the infrastructure side, events are now stored in ClickHouse, which means
faster queries and better scalability as your player count grows. If you're
migrating from CSMM, you can now import your shop listings directly.

This release also fixes several reliability issues — database connection pool
exhaustion that could occur around midnight, cronjob failures under high load,
and a handful of UI bugs including the version number incorrectly showing as
"0.0.0".

箇条書きも、カテゴリ見出しも、「追加／修正／変更」といった分類もありません。読者が読んで理解できる、明快な文章だけです。

避けること

• 箇条書きやカテゴリ分けされた変更履歴：変更履歴はすでにあります。少し形式を変えて作り直さないでください。このスキルの価値は、ナラティブ形式に変換することです
• コミットログの羅列：すべてのコミットをそのまま並べても、目的に反します
• 曖昧な要約：「さまざまなバグ修正と改善」では、読者に何も伝わりません
• 内部向けの変更：CI パイプラインの設定や依存関係の更新は、ユーザーには関係ありません
• 専門用語の不一致：エンドユーザーに「ミドルウェアのリファクタリング」と伝えるのではなく、何が速くなったのか、何が修正されたのかを伝えてください
• 目立たない場所に置かれた破壊的変更：既存の使い方に影響する変更は、最初に説明します

出力

リリースノートは会話内に直接提示します。ユーザーから明示的に求められない限り、ファイルには書き込まないでください。書き込みを求められた場合は、どこに書き込むか（CHANGELOG.md、RELEASE_NOTES.md など）を尋ねます。

GitHub のリリースやファイルに書き込む場合は、次の構成にします。

1. 冒頭にナラティブ形式の要約
2. 水平線（---）
3. その下に、すべての変更履歴を折りたたみやネタバレタグに隠さず表示します。そうしないと、読者が見落としてしまいます。