changelog-maintenance

変更履歴の管理

成果物がリリース履歴またはリリース済みの変更に関する告知であり、広範なドキュメントやローンチキャンペーン一式ではない場合に、このスキルを使用します。

changelog-maintenance は、ドキュメントクラスターの中核として、以下を扱います。

• CHANGELOG.md の更新
• GitHub ／ GitLab ／ドキュメントサイトのリリースノート
• リリース済みの変更に伴う移行および非推奨化の更新
• 顧客向けの「変更点」概要
• 簡潔なゲームのパッチノートや小規模アップデートの投稿

モードや対象範囲を決める前に、以下の補足ドキュメントを確認してください。

• references/modes-and-boundaries.md
• references/output-packets-and-channel-handoffs.md
• references/release-note-quality-checklist.md
• references/automation-and-source-of-truth.md

このスキルを使用する場合

• リリース済みの作業に基づいて、リポジトリに永続的な変更履歴の項目を追加する、または Unreleased を更新する必要がある
• 開発者、顧客、社内関係者、プレイヤー向けに、対象読者に適したリリースノートが必要である
• 破壊的変更、非推奨化、互換性の変更に伴い、リリース履歴から参照できる移行情報が必要である
• リリース自動化で作成されたノートに、正確な分類、わかりやすい表現、適切な参照先の案内を加える必要がある
• ゲームのアップデートについて、マーケティング文、デプロイ手順書、ヘルプドキュメント一式に寄せず、簡潔なパッチノートが必要である
• 隣接するドキュメントをすべて一から書くのではなく、リリース文書作成に必要な最小限の一式を決めることが本来の作業である

このスキルを使用しない場合

• 主な作業が社内仕様書、手順書、ADR、ロールアウト計画、詳細な移行手順である → technical-writing
• 主な作業が公開 API ／ SDK ／ webhook ／開発者ポータルのコンテンツである → api-documentation
• 主な作業がエンドユーザー向けのオンボーディング、チュートリアル、スクリーンショット、FAQ、ヘルプセンターの手順である → technical-writing
• 主な作業がデプロイの実行、環境への昇格、ロールバックの仕組み、リリースのオーケストレーションである → deployment-automation
• 主な作業がローンチ文、機能の訴求、キャンペーンの段取り、GTM メッセージである → marketing-automation
• リリース済みであると裏付ける確かな証拠がまだない → ロードマップや TODO リストからリリースノートをでっち上げず、まず証拠を集めてください

手順

ステップ 1：主要なリリース文書作成モードを 1 つ分類する

下書きを始める前に、依頼の内容を整理してください。

changelog_mode:
  primary_mode: changelog | release-notes | migration-update | game-patch-notes
  audience: developers | end-users | mixed | players | internal-stakeholders | unknown
  release_scope: patch | minor | major | rolling | unknown
  source_of_truth: release-pr | tagged-release | prs | issues | commits | docs | mixed | unknown
  publishing_surface: changelog-file | github-release | docs-site | in-app-updates | steam-news | mixed | unknown
  automation_context: manual | release-drafter | changesets | release-please | autogenerated-release-notes | mixed | unknown
  output_shape: single-entry | summary-plus-links | migration-brief | patch-note-brief | sync-packet | unknown

実行ごとにモードを 1 つ使用してください。

• changelog → CHANGELOG.md に記録する、リポジトリの永続的な変更履歴
• release-notes → 何が変わり、それがなぜ重要なのかを伝える、対象読者向けの概要
• migration-update → 変更された動作、必要な対応、期限、互換性に関する注意事項
• game-patch-notes → プレイヤー向けの簡潔なアップデート概要

ステップ 2：対象読者、根拠、参照先を確認する

執筆前に、以下に回答してください。

1. 最初に読むのは誰ですか？
2. 読んだ後、どのような対応を取ってもらうべきですか？
3. 見出しごとの主張を裏付ける、リリース済みの証拠は何ですか？
4. 残りの情報を記載する、より詳細な成果物はどれですか？

参照先のクイック選択表：

依頼が次のような内容なら…	使用するスキル
「アーキテクチャ ／ ロールアウト ／ 手順書 ／社内移行計画を作成する」	technical-writing
「API リファレンス、SDK ドキュメント、認証トラブルシューティング、ポータルページを公開する」	api-documentation
「変更されたワークフローのヘルプドキュメント、チュートリアル、スクリーンショット、FAQ を作成する」	technical-writing
「デプロイ ／ ロールバック ／ リリース実行を計画する」	deployment-automation
「ローンチ文 ／ 告知 ／キャンペーンメッセージを作成する」	marketing-automation
「リリース向けの場に、リリース済みの変更を正確に要約する」	changelog-maintenance

ステップ 3：信頼できる最小限の根拠を集める

記憶だけを頼りにリリース履歴を書かないでください。まず、信頼できる最小限の資料を集めます。

• 存在する場合は、マージ済みのリリース PR、タグ、リリース項目
• リリースに含まれるマージ済みの PR／課題／コミット
• 関連する移行ドキュメント、アップグレードの注意事項、ヘルプドキュメント
• 互換性を破る変更、削除、非推奨化、期限、ロールアウトに関する注意事項
• 公開先の制約（CHANGELOG.md、GitHub Release、顧客向け更新ハブ、Steam のパッチノート投稿）
• 自動化の状況（該当する場合）

根拠が不完全な場合は、前提と不足している証拠を明示してください。

ステップ 4：有用な最小限の成果物パケットを選ぶ

references/output-packets-and-channel-handoffs.md を参照してください。

標準的な形式：

• single-entry → 変更履歴の項目を 1 つ、またはリリースノートのブロックを 1 つ
• summary-plus-links → 簡潔なリリース概要と移行／ヘルプ／API のリンク
• migration-brief → 変更内容、影響を受ける人、必要な対応、期限、関連リンク
• patch-note-brief → 簡潔な新コンテンツ／調整／修正／既知の問題のパケット
• sync-packet → リリースノートの草案と、内容を揃える必要がある下流のドキュメントまたはチャネルの一覧

リリースパケット 1 つと短い同期リストで足りる場合、広範なハンドブックを作成しないでください。

ステップ 5：モード固有の執筆ルールを適用する

• 変更履歴：コミットの詳細な掘り起こしより、重要な変更をまとめたカテゴリ分けを優先します。リポジトリで比較リンクやバージョン／日付の表記を使っている場合は、それらを残します。
• リリースノート：社内のチケット番号ではなく、影響を先に伝えます。平易で、ざっと読める表現にします。
• 移行に関する更新：必要な対応、影響を受ける読者、期限、互換性リスクを前面に出します。
• ゲームのパッチノート：簡潔でプレイヤー向けの内容にします。ロールアウトの仕組みやキャンペーン文言を紛れ込ませないでください。

ステップ 6：記録、コミュニケーション、プロモーションを分ける

次の境界を厳守してください。

• 変更履歴／リリースノートでは、リリース内容を要約します
• 手順が概要に収まらない場合、移行の詳細はリンク先の移行ドキュメントに記載します
• チュートリアル／FAQ は technical-writing に記載します
• API と統合の詳細は api-documentation に記載します
• ロールアウト／ロールバックの仕組みは deployment-automation に記載します
• キャンペーン風の表現は marketing-automation に記載します

ステップ 7：判断力を手放さずに自動化を活用する

自動化は草案の材料として使い、最終的な編集には使わないでください。

• Release Drafter／自動生成されたリリースノート → PR の分類と箇条書きのたたき台に適しています
• Changesets → パッケージ／バージョンの意図やモノレポのリリース集約に適しています
• release-please／semantic-release 系のフロー → リリース PR、バージョン更新、コミットベースの要約に適しています

次の点は、引き続き手作業で判断してください。

• 主な対象読者
• 何を重要な変更とみなすか
• どの変更に移行リンクが必要か
• 別のヘルプ／API／社内向けドキュメントに分けるべき内容

ステップ 8：公開前に信頼性を確認する

references/release-note-quality-checklist.md を参照してください。

次を確認します。

1. すべての記述が、リリース済みまたはマージ済みの証拠と一致している。
2. 選択した形式が対象読者とチャネルに合っている。
3. 互換性を破る変更、削除、期限が見落とされないよう明示されている。
4. 関連先への案内が明確で、ノートを膨らませていない。
5. 内容の正確さを保てる範囲で、パケットが可能な限り小さい。

ステップ 9：概要または完成した成果物を返す

本格的な執筆に入る前の、推奨される概要の形式：

# Release Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Evidence used
- Source of truth:
- Supporting docs / links:
- Assumptions / missing proof:

## Planned artifact packet
1. main release artifact
2. downstream sync / linked-doc follow-up

## Writing notes
- Breaking changes / deadlines:
- Route-outs kept out of scope:
- Channel-specific constraints:

ユーザーが完成した成果物をすでに求めている場合は、選択したパケットを対応する構成で直接作成してください。

例

例 1：移行リンク付きの変更履歴

入力

マージ済みの PR 一覧をもとに、v2.4.0 の CHANGELOG.md を更新し、Basic Auth の非推奨化が明確に伝わるようにしてください。

望ましい出力の方向性

• モード：changelog
• 出力形式：summary-plus-links
• Added、Changed、Deprecated、Fixed などのカテゴリでまとめる
• 認証の手順全体を埋め込む代わりに、移行リンクまたはプレースホルダーを記載する

例 2：顧客向けリリース概要

入力

リリース済みの製品アップデートを、顧客が実際に読みたくなるリリースノートにまとめてください。

望ましい出力の方向性

• mode: release-notes
• output shape: single-entry または summary-plus-links
• 新機能、改善点、修正点 など、メリットを前面に出した見出し
• チュートリアルやヘルプの更新は technical-writing に振り分ける

例 3：簡潔なゲームのパッチノート

入力

最新のゲームアップデートのパッチノートを、簡潔に作成してください。

望ましい出力の方向性

• mode: game-patch-notes
• output shape: patch-note-brief
• 新コンテンツ、調整、修正、既知の問題を簡潔なセクションにまとめる
• リリースイベントの盛り上げやキャンペーンの展開は marketing-automation に振り分ける

ベストプラクティス

1. 雰囲気ではなく、リリース済みの内容を根拠に始めます。
2. 主な対象読者と主なモードをそれぞれ 1 つ選びます。
3. 使用するチャネルに合う、最小限の情報セットにします。
4. リリース概要、移行の詳細、ヘルプドキュメント、API ドキュメント、ロールアウトの仕組み、リリース告知を分けます。
5. 自動化で下書きの材料を集めても、判断まで委ねないでください。
6. 破壊的変更や期限は早い段階で明示します。
7. パッチノートは、単に名前を変えた変更履歴ではなく、プレイヤー向けの制約を伴う実際のワークフローとして扱います。

参考資料

• Keep a Changelog
• Semantic Versioning 2.0.0
• Release Drafter
• Changesets
• release-please
• GitHub Docs：自動生成されるリリースノート
• Steamworks：イベントタイプ — 小規模アップデート／パッチノート
• Steamworks：ゲームのアップデート — ベストプラクティス