agent-changelog

エージェント変更履歴

コーディングエージェントのコンテキスト構築に役立つよう、重要な決定、アーキテクチャの変更、プロジェクトの変遷を時系列で記録します。

出力

プロジェクトのルートに AGENT_CHANGELOG.md を作成します。このファイルはエージェントが以下を行う際に役立ちます。

• 重要な決定とその根拠を理解する
• 非推奨となったパターンやアプローチを特定し、避ける
• 過去から現在、そして今後の方向性までの変遷を把握する
• 現状と矛盾する古いドキュメントを検出する

ワークフロー

1. 情報源を収集する

以下の情報源から並行して情報を収集します。

Git 履歴：

git log --oneline --since="6 months ago" | head -100
git log --all --oneline --grep="BREAKING" --grep="deprecate" --grep="remove" --grep="migrate" -i
git tag -l --sort=-creatordate | head -20

ドキュメント：

• .claude/plans/ - 実装計画と決定事項
• CLAUDE.md - プロジェクトの指示
• README.md - プロジェクトの概要
• docs/ または同様のドキュメントディレクトリ
• CHANGELOG.md が存在する場合（従来型の変更履歴）

コード内の兆候：

• @deprecated 注釈
• 日付のある TODO、FIXME、HACK コメント
• マイグレーションファイル、アップグレードスクリプト

2. 重要なイベントを特定する

エージェントが理解しておくべき重要なイベントを抽出します。

必ず含める項目：

• アーキテクチャ上の決定（新しいパターン、廃止されたパターン）
• 破壊的変更とマイグレーション
• 非推奨となった機能やアプローチ
• 主要な依存関係の変更
• ディレクトリ構造の変更
• API の変更（内部または外部）

重要な場合に含める項目：

• エージェントの作業方法を変える新機能
• 誤った前提を明らかにするバグ修正
• 推奨するアプローチに影響するパフォーマンスの変更

含めない項目：

• 軽微なバグ修正
• 外観上の変更
• 定期的な依存関係の更新
• 個別の機能追加（アーキテクチャに関わる場合を除く）

3. 矛盾を相互参照する

重要なイベントごとに、既存のドキュメントに矛盾がないか確認します。

Event: "Migrated from Redux to Zustand" (commit abc123, 2024-03)

Check: Does any documentation still reference Redux patterns?
- README.md mentions Redux? → Flag as STALE
- CLAUDE.md suggests Redux approach? → Flag as STALE
- Old tutorials in docs/? → Flag as STALE

矛盾は「検出された古い情報」セクションに記録します。

4. 変更履歴を作成する

出力ファイルを次の構成にします。

# Agent Changelog

> This file helps coding agents understand project evolution, key decisions,
> and deprecated patterns. Updated: [DATE]

## Current State Summary

[2-3 sentences on where the project is NOW - the authoritative current architecture]

## Stale Information Detected

[List any documentation that contradicts current reality - agents should ignore these until fixed]

| Location | States | Reality | Since |
|----------|--------|---------|-------|
| docs/auth.md | "Uses JWT tokens" | Migrated to sessions | 2024-06 |

## Timeline

### [YEAR-MONTH] - [Brief Title]

**What changed:** [Factual description]

**Why:** [Decision rationale if known from plans/commits]

**Agent impact:** [How this affects how agents should work in the codebase]

**Deprecated:** [What approaches/patterns should agents avoid]

---

[Repeat for each significant event, reverse chronological]

## Deprecated Patterns

[Consolidated list of things agents should NOT do, with what to do instead]

| Don't | Do Instead | Deprecated Since |
|-------|------------|------------------|
| Use `OldService` | Use `NewService` | 2024-08 |

## Trajectory

[Brief note on where the project appears to be heading based on recent changes and plans]

5. 検証して更新する

作成後：

• 既存の AGENT_CHANGELOG.md がある場合は読み込み、重複を避けて統合する
• Git 履歴と照合して日付を検証する
• 「検出された古い情報」セクションに実行可能な対応が記載されていることを確認する

積極的に実行するタイミング

以下の場合は、このスキルの実行を提案します。

• 大規模なリファクタリングやマイグレーションが完了した直後
• .claude/plans/ の計画が最近実行された
• 複数のアーキテクチャ上の決定が短期間に行われた
• ドキュメントがコードの現状と矛盾しているように見える
• 長い中断期間の後にコードベースで作業を始める
• 不慣れなコードベースで作業を始める

ガイドライン

• 完全性より正確性を優先します。不正確な履歴は、不完全な履歴よりも問題です
• 根拠がわかる場合は記載します（コミットメッセージ、計画ドキュメントなど）
• 変更点だけでなく、エージェントが避けるべきことを具体的に示します
• 簡潔にまとめます。ストーリーではなく、参照資料として作成します
• エージェントが情報の関連性を判断できるよう、すべての日付を記載します