system-evolution-review

システムレビュー

実装が計画にどの程度従ったかをメタレベルで分析し、プロセスの改善点を特定します。

目的

システムレビューはコードレビューではありません。 コード内のバグではなく、プロセス上の問題を探します。

あなたの役割：

• 計画への準拠状況と逸脱のパターンを分析する
• どの逸脱が正当で、どれが問題だったかを特定する
• 今後の問題を防ぐプロセスの改善点を明らかにする
• AI-Layer のアセット（CLAUDE.md、計画テンプレート、スキル）の更新を提案する

考え方：

• 適切な逸脱は計画の限界を明らかにします → 計画を改善する
• 不適切な逸脱は要件の不明確さを明らかにします → コミュニケーションを改善する
• 繰り返し発生する問題は自動化の不足を明らかにします → スキルを作成する

コンテキストと入力

次の4つの主要な成果物を分析します。

計画スキル： 計画プロセスと計画作成の指針となる指示を把握するため、これを読みます。 .claude/skills/piv-plan-implementation/SKILL.md

生成された計画： エージェントが実行するはずだった内容を把握するため、これを読みます。 計画ファイル：$plan

実行スキル： 実行プロセスと実装の指針となる指示を把握するため、これを読みます。 .claude/skills/piv-implement/SKILL.md

実行レポート： エージェントが実際に行ったこととその理由を把握するため、これを読みます。 実行レポート：$report

分析ワークフロー

ステップ1：計画されたアプローチを把握する

生成された計画（$plan）を読み、次の内容を抽出します。

• どのような機能が計画されていましたか？
• どのようなアーキテクチャが指定されていましたか？
• どのような検証手順が定義されていましたか？
• どのようなパターンが参照されていましたか？

ステップ2：実際の実装を把握する

実行レポート（$report）を読み、次の内容を抽出します。

• 何が実装されましたか？
• 計画から何が逸脱しましたか？
• どのような課題に直面しましたか？
• 何が、なぜ省略されましたか？

ステップ3：それぞれの逸脱を分類する

実行レポートで特定された逸脱ごとに、次のように分類します。

適切な逸脱 ✅（正当な理由あり）：

• 計画で想定されていたものがコードベースに存在しなかった
• 実装中に、より適切なパターンが見つかった
• パフォーマンスの最適化が必要だった
• セキュリティ上の問題が見つかり、異なるアプローチが必要だった

不適切な逸脱 ❌（問題あり）：

• 計画の明示的な制約を無視した
• 既存のパターンに従わず、新しいアーキテクチャを作成した
• 技術的負債を生む近道を選んだ
• 要件を誤解した

ステップ4：根本原因を追跡する

それぞれの問題のある逸脱について、根本原因を特定します。

• 計画のどこが、なぜ不明確でしたか？
• コンテキストのどこが、なぜ不足していましたか？
• 検証のどこが、なぜ不足していましたか？
• 手作業のどの工程が、なぜ繰り返されていましたか？

ステップ5：プロセス改善案を作成する

逸脱のパターンに基づき、次の改善案を提案します。

• CLAUDE.md の更新： 文書化すべき共通のパターンやアンチパターン
• 計画スキルの更新： 明確化が必要な指示、または不足している手順
• 新しいスキル： 自動化すべき手作業のプロセス
• 検証項目の追加： 問題を早期に検出するチェック

出力形式

分析結果を .claude/system-reviews/[feature-name]-review.md に保存します。

レポート構成：

メタ情報

• レビュー対象の計画：[$plan のパス]
• 実行レポート：[$report のパス]
• 日付：[現在の日付]

全体の準拠スコア：__/10

採点基準：

• 10：完全に準拠しており、すべての逸脱に正当な理由がある
• 7～9：正当な理由のある軽微な逸脱
• 4～6：正当な逸脱と問題のある逸脱が混在
• 1～3：重大な問題のある逸脱

逸脱分析

実行レポートに記載された逸脱ごとに：

divergence: [what changed]
planned: [what plan specified]
actual: [what was implemented]
reason: [agent's stated reason from report]
classification: good ✅ | bad ❌
justified: yes/no
root_cause: [unclear plan | missing context | etc]

パターンへの準拠

文書化されたパターンへの準拠状況を評価します。

• コードベースのアーキテクチャに従った
• 文書化されたパターン（CLAUDE.md の記載）を使用した
• テストパターンを正しく適用した
• 検証要件を満たした

システム改善アクション

分析に基づいて、具体的なアクションを提案します。

CLAUDE.md を更新する：

• 実装中に見つかった[パターン X]を記録する
• [Y]に関するアンチパターンの警告を追加する
• [技術的制約 Z]を明確にする

Plan Skill（$plan）を更新する：

• [不足しているステップ]の指示を追加する
• [曖昧な指示]を明確にする
• [X]の検証要件を追加する

新しいスキルを作成する：

• 3 回以上繰り返された[手動プロセス]向けの新しいスキルを作成する

Execute Skill を更新する：

• 実行チェックリストに[検証ステップ]を追加する

主な学び

うまくいったこと：

• [スムーズに進んだ具体的な内容]

改善が必要なこと：

• [特定された具体的なプロセス上の不足]

次回の実装に向けて：

• [試してみる具体的な改善策]

重要

• 具体的にする：「計画が不明確だった」ではなく、「計画に使用する認証パターンが指定されていなかった」と述べてください
• **パターンに注目する：**一度限りの問題は実行可能なアクションにつながりません。繰り返し発生する問題を探してください。
• **アクションにつなげる：**すべての所見に、具体的なアセットの更新案を含めてください
• **改善を提案する：**分析するだけでなく、CLAUDE.md やスキルに追加する文章も実際に提案してください