changelog

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

自動化モード：modes.automation（project.local.yaml → project.yaml → デフォルトの collaborative）を解決します。すべての AskUserQuestion 呼び出しと ファイルへの書き込みは、.claude/docs/automation-modes.md （collaborative は常に質問 · guided は大きな変更のみ · autonomous は記録して続行； automation_always_ask カテゴリでは常に確認）に従います。

変更履歴

最近の履歴

最近のコミット：

!git log --oneline -30 2>/dev/null || true

最近のタグ（新しい順）：

!git tag --list --sort=-v:refname 2>/dev/null | head -5

出所の確認 — 上記の履歴を信頼する前に

上記のコミットは、このゲームのものではない可能性があります。 このスキルの履歴ブロックは 本文の実行前に自動解決されるため、読み取りはすでに行われています。この確認で判断するのは、 出力が利用可能かどうかであり、取得するかどうかではありません。

1. 上に挿入されたコミットの件名を読みます。コミットがない場合 — ログが 空、または git が利用できない場合 — この確認はスキップしてください。分類する対象は なく、フェーズ 1 の履歴なしの分岐で停止するのが適切です。
2. 各コミットを分類します。ゲーム（ゲームの仕組み、コンテンツ、バランス、アート、音声、 UI、またはそれらのバグ）、フレームワーク／保守（スキル、フック、 エージェント、テスト計画、CI、またはフレームワーク独自のドキュメントに言及する件名）、または 不明に分類し、不明はフレームワークとして扱います。
3. 件数から判断します。
   • ゲームのコミットが 1 件以上 → それらのみを使って続行し、使用した件数と総件数を明記します。
   • ゲームのコミットが 0 件 → 下記のメッセージを使って停止します。

コミットごとにフィルタリングしてください。保守作業を含むリポジトリが間違ったリポジトリというわけではありません。 このフレームワークを使うプロジェクトでは、フック、CI、スキルに触れるコミットが蓄積されます。 ゲームのリポジトリはフレームワークのリポジトリでもあるため、それらを理由に停止すると、 実際のプロジェクトのほぼすべてで処理が止まってしまいます。問題なのは、それらのコミットがリリース用の説明文になることです。 それらを除外すれば、まさにその問題を防げます。

このルールは、意図的に /patch-notes と同一にしています。両者は異なる読者向けに 同じ履歴を読み取るため、どのプロジェクトの履歴なのかについて食い違ってはなりません。 変更する場合は、両方を一緒に変更してください。

本当の誤履歴の兆候は異なります。ゲームのコミットに記載された製品名が、 design/ とコードのルート（src/、Assets/、または Source/）には一度も出てこない場合です。 その場合は停止してください。

範囲内にこのゲームのコミットがない場合は、その旨を伝えて停止します。

「このリポジトリの git 履歴は [game] のものではないようです。最近の [N] 件のコミットのうち、ゲームのコミットは 0 件です。最近の コミットは、実際には [実際に記載されている内容] について述べています。これをもとに変更履歴は生成できません。 正しい履歴を指定するか、変更点の一覧を直接提示してください。」

判定：ブロック — ここで停止し、変更履歴を生成しないでください。

警告ではなく、ここで必ず停止する理由。 フレームワーク内部のコミットをプレイヤー向けの説明文にすると、 実際の変更のように見えてしまいます。たとえば、セッションフックのタイムアウトが、セーブシステムのないゲームで 「起動時に前回のセッションの進行状況が失われる問題を修正しました」 という説明になってしまいます。 その文章は自然で、もっともらしく、しかも完全な誤りです。読者には見分けがつきません。この確認だけがそれを防げます。

前置きが存在することを根拠にしないでください。 出力が挿入されているということは、コマンドが実行されたというだけで、 その件名がこのゲームに関するものだとは限りません。

---

両方のブロックは、このスキルの実行前に解決されます。同じコマンドを再実行するのではなく、 フェーズ 2 の出発点として使用してください。

---

Phase 1: 引数の解析

対象バージョンまたはスプリント番号の引数を読み取ります。バージョンが指定されている場合は、対応する git タグを使用します。スプリント番号が指定されている場合は、スプリントの日付範囲を使用します。

リポジトリが初期化されていることを確認します。git rev-parse --is-inside-work-tree を実行し、git が利用できることを確認します。git リポジトリでない場合は、ユーザーに伝えて適切に中止します。

読み取れる履歴がない場合 — git リポジトリでない、またはコミットがまだない場合：

"No git history found. A changelog is built from commits — commit the work first, or supply the change list directly."

判定：BLOCKED — ここで停止し、変更履歴を生成しません。

---

Phase 2: 変更データの収集

最後のタグまたはリリース以降の git ログを読み取ります。

git log --oneline [last-tag]..HEAD

タグがない場合は、範囲を明示して git log --oneline -n 100 を実行します。ログ全体へのフォールバックはしないでください。確立されたリポジトリでは、1 回のリリースを対象とする変更履歴に対して何千行ものログが出力され、最も古いコミットほど関連性が低いためです。100 件のコミットでは十分にさかのぼれない場合は、範囲を無闇に広げず、開始参照を指定するよう依頼してください。

該当期間の計画された作業と変更の背景を把握するため、production/sprints/ のスプリントレポートを読み取ります。

この期間中に実装された新機能については、design/gdd/ の完成済み設計ドキュメントを読み取ります。セクション単位で読み取ります。Grep ツールで必要な見出しを検索し（パターン ^#、コンテンツモード）、offset と limit を指定して該当範囲を Read します。

---

Phase 3: 変更の分類

すべての変更を、次のいずれかのカテゴリに分類します。

• 新機能：まったく新しいゲームプレイシステム、モード、コンテンツ
• 改善：既存機能の強化、UX の改善、パフォーマンスの向上
• バグ修正：正常に動作していなかった挙動の修正
• バランス調整：ゲームプレイの数値、難易度、経済要素の調整
• 技術的負債／リファクタリング：プレイヤーから見える部分に変更を加えない、ゲームコードのリファクタリングや整理。修正、機能、調整には触れず、リファクタリング、整理、クリーンアップのみを記載したコミットが該当します。内部向けの変更履歴にのみ記載し、プレイヤー向けの変更履歴には記載しません
• 既知の問題：チームが把握しているものの、まだ解決していない問題
• その他：上記のカテゴリに当てはまらない変更、またはメッセージが曖昧すぎて確実に分類できないコミット

各コミットについて、メッセージにタスク ID またはストーリー参照（例：[STORY-123]、TR-、#NNN など）が含まれているかを確認します。タスク参照がないコミット数を数え、その数を Phase 4 のメトリクスセクションに タスク参照のないコミット：[N] として記載します。

---

Phase 4: 内部向け変更履歴の生成

# Internal Changelog: [Version]
Date: [Date]
Sprint(s): [Sprint numbers covered]
Commits: [Count] ([first-hash]..[last-hash])

## New Features
- [Feature Name] -- [Technical description, affected systems]
  - Commits: [hash1], [hash2]
  - Owner: [who implemented it]
  - Design doc: [link if applicable]

## Improvements
- [Improvement] -- [What changed technically and why]
  - Commits: [hashes]
  - Owner: [who]

## Bug Fixes
- [BUG-ID] [Description of bug and root cause]
  - Fix: [What was changed]
  - Commits: [hashes]
  - Owner: [who]

## Balance Changes
- [What was tuned] -- [Old value -> New value] -- [Design intent]
  - Owner: [who]

## Technical Debt / Refactoring
- [What was cleaned up and why]
  - Commits: [hashes]

## Miscellaneous
- [Change that didn't fit other categories, or vague commit message]
  - Commits: [hashes]

## Known Issues
- [Issue description] -- [Severity] -- [ETA for fix if known]

## Metrics
- Total commits: [N]
- Files changed: [N]
- Lines added: [N]
- Lines removed: [N]
- Commits without task reference: [N]

---

Phase 5: プレイヤー向け変更履歴の生成

# What is New in [Version]

## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do
  and why it is exciting. Focus on the experience, not the implementation.]

## Improvements
- **[What improved]**: [How this makes the game better for the player.
  Be specific but avoid jargon.]

## Bug Fixes
- Fixed an issue where [describe what the player experienced, not what was
  wrong in the code]
- Fixed [player-visible symptom]

## Balance Changes
- [What changed in player-understandable terms and the design intent.
  Example: "Healing potions now restore 50 HP (up from 30) -- we felt
  players needed more recovery options in late-game encounters."]

## Known Issues
- We are aware of [issue description in player terms] and are working on a
  fix. [Workaround if one exists.]

---
Thank you for playing! Your feedback helps us make the game better.
Report issues at [link].

---

Phase 6: 出力

両方の変更履歴をユーザーに出力します。内部向け変更履歴は、主に作業用のドキュメントです。プレイヤー向け変更履歴は、レビュー後にコミュニティへ投稿できる状態にします。

---

Phase 7: ファイルへの書き込みを提案

変更履歴を提示した後、ユーザーに次のように尋ねます。

"May I write this changelog to docs/CHANGELOG.md? [A] Yes, append this entry (recommended if the file already exists) [B] Yes, overwrite the file entirely [C] No — I'll copy it manually"

• 尋ねる前に docs/CHANGELOG.md が存在するか確認します。存在する場合は、[A] 追記を推奨します。
• ユーザーが [A] を選択した場合：新しい内部向け変更履歴エントリを既存ファイルの先頭に追記します（新しいエントリが先頭）。
• ユーザーが [B] を選択した場合：新しい変更履歴でファイル全体を上書きします。
• ユーザーが [C] を選択した場合：書き込みを行わず、ここで停止します。

書き込みに成功した場合：判定：CHANGELOG WRITTEN — 変更履歴を docs/CHANGELOG.md に保存しました。 ユーザーが辞退した場合：判定：COMPLETE — 変更履歴を生成しました。

---

Phase 7: 次のステップ

• /patch-notes [version] を使用して、一般公開向けのスタイルを整えたバージョンを生成し、保存します。
• 変更履歴を外部に公開する前に、/release-checklist を使用します。

ガイドライン

• プレイヤー向けの変更履歴には、内部コードの参照、ファイルパス、開発者名を記載しないでください
• 個々のコミットを列挙するのではなく、関連する変更をまとめてください
• コミットメッセージが不明瞭な場合は、関連ファイルやスプリントのデータを確認して背景を把握してください
• バランス調整については、数値だけでなく、調整の設計意図も必ず記載してください
• 既知の問題については正直に伝えてください。プレイヤーは透明性を高く評価します
• Git の履歴が煩雑な場合（マージコミット、リバート、修正用コミットなど）は、すべてのコミットをそのまま列挙するのではなく、内容を整理して説明してください