code-review

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

コードレビュー

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います （collaborative は常に確認 · guided は重大な項目のみ · autonomous は記録して続行； automation_always_ask のカテゴリは常に確認します）。

入力不足 — レポートを作成する前に確認してください

このスキルが必要とする入力が存在しない場合、回答は「実行できません」です — 入力を補ったレポートではありません。 まず確認し、確認に失敗したら停止してください。

1. このスキルが読み取る入力（データファイル、過去のレポート、プロファイラー出力、 テスト結果、レジストリ、ソースコード）を列挙します。
2. それぞれについて、「存在すると仮定」するのではなく、FOUND または ABSENT を記録します。
3. あるセクションに必要な入力が1つでも ABSENT の場合、そのセクションは NOT ASSESSED — NO DATA です。推定したり、隣接する成果物から推論したりせず、 テンプレートを次に読む人が記入することになる必須セルを空欄のままにしないでください。
4. 必要な入力がすべて ABSENT の場合は、停止して NOT ASSESSED — NO DATA を判定全体として報告し、不足していた項目と それを生成するスキルを明記します。

NOT ASSESSED という判定は成功です。 データがないときに「データは何を示していますか？」と問われた場合の、正しく有用な回答です。これによって防ぐ具体的な失敗は、判定の列挙型に「実行できません」という状態がないレポートが生む誤った合格判定です。たとえば、アセットも基準もないプロジェクトのアセット監査で COMPLIANT と判定したり、プロファイラーデータがゼロで予算も一度も設定されていないのに、パフォーマンスプロファイルが「16.67ms の予算に対して >99% の余裕あり」と報告したりするケースです。

証拠がないことは、存在しない証拠にはなりません。 スキャン対象のファイルがないため一致が見つからなかったスキャンは、何も検証していません。どちらが起きたのかを明記してください。結果が緑色でも、読み手には判別できません。

---

Phase 1: 対象ファイルの読み込み

対象ファイルをすべて読みます。プロジェクトのコーディング規約については CLAUDE.md を読みます。

---

Phase 2: エンジンスペシャリストの特定

project.yaml の specialists ブロックを読みます。存在しない場合は、.claude/docs/technical-preferences.md の ## Engine Specialists セクションを参照します。次の項目を確認します。

• Primary スペシャリスト — engine.name から導出される <engine>-specialist（Godot→godot-specialist、Unity→unity-specialist、Unreal→unreal-specialist）。アーキテクチャとエンジン全般の懸念事項に使用します
• Language/Code Specialist — specialists.code — プロジェクトの主要言語のファイルをレビューするときに使用します
• Shader Specialist — specialists.shader — シェーダーファイルをレビューするときに使用します
• UI Specialist — specialists.ui — UI コードをレビューするときに使用します

値が null の場合は UNSET です。そのキーは存在しないものとして扱い、該当するスペシャリストをスキップしてください。エージェント名として起動してはいけません。 v1.0 の移行では、旧ファイルで指定されていないスペシャリストに null を書き込み、メンバーのうち1つでも設定されていればブロック全体を書き込みます。そのため、コードスペシャリストのみを設定したプロジェクトでは、shader: null と ui: null が含まれます。設定の読み込み処理はこれらを4文字の文字列 "null" として返します。これは空ではないため、設定済みとして扱われます。ここでは null、空、未指定は同じ状態です。

エンジンが設定されていない場合（project.yaml に engine.name がなく、technical-preferences.md が [TO BE CONFIGURED] またはファイルなしの状態）は、エンジンスペシャリストの手順をスキップします。この実行の出力に Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`) を記録してください。 スキップした確認について何も記載しなければ、確認に合格した場合と区別できません。エンジンに関するガイダンスを求めていないことを、読み手は判別できません。

---

フェーズ 3：ADR 準拠チェック

引数： /code-review [file(s)] では、最後の引数としてストーリーファイルのパスを任意で指定できます（例：/code-review Assets/Scripts/Combat/Attack.cs production/epics/combat/story-001.md）。ストーリーパスが指定されている場合は、そのファイルを読み込み、適用される ADR の参照を抽出します。

優先順位に従って、次の場所で ADR への参照を検索します。

1. ストーリーファイル（引数として指定されている場合）
2. 実装ファイル先頭のヘッダーコメント
3. これらのファイルを参照しているコミットメッセージ（git log --oneline -- [file]）

ADR-NNNN または docs/architecture/adr- のようなパターンを検索します（大文字・小文字は区別しません）。

ADR への参照が見つからない場合は、「ADR への参照が見つかりません — ADR 準拠チェックをスキップしました。完全な ADR 準拠レビューを行うには、ストーリーパスを指定してください：/code-review [files] [story-path]」と記載します。

参照された ADR ごとに、このチェックで必要なセクションだけを読み込みます。範囲を限定せずにファイル全体を読むことは避けてください。大規模な ADR は Read の 25k トークン上限を超えます。また、上限で読み込みが途切れた場合に残りを読むにはページ分割するしかなく、これは最もコストのかかる方法です。/dev-story および /create-stories と同じ方法を使います。

1. 見出しを一覧化します（低コスト — 行番号のみ）：Grep pattern="^## " path="[adr-file]" output_mode="content" -n
2. 行番号を使って Read(offset, limit) の範囲を設定し、次の見出しが始まる位置までに収まるようにして、## Decision と ## Consequences だけを範囲指定して読み込みます。見出し一覧が空の場合（テンプレートより前に作成された標準外の ADR）は、ファイル全体を一度だけ Read します。上限で読み込みが途切れた場合は、残りをページ分割して読むのではなく、決定内容や結果を直接 grep します。

参照された ADR のファイルが存在しない、または読み込めない場合、ADR 準拠は NOT ASSESSED — [ADR] could not be read とします。対象の ADR 名を記載してください。参照がまったくない場合は NO ADRS FOUND とします。これは別の結果です。

これら 2 つのセクションに基づき、逸脱を次のように分類します。

• アーキテクチャ違反（ブロッキング）：ADR で明示的に却下されているパターンを使用している
• ADR からの逸脱（警告）：禁止されたパターンは使用していないものの、選択されたアプローチから実質的に外れている
• 軽微な逸脱（情報）：全体的なアーキテクチャに影響しない、ADR のガイダンスからの小さな相違

---

フェーズ 4：標準への準拠

システムのカテゴリ（エンジン、ゲームプレイ、AI、ネットワーキング、UI、ツール）を特定し、次の項目を評価します。

• パブリックメソッドとクラスにドキュメントコメントがある
• メソッドごとの循環的複雑度が 10 未満である
• データ宣言を除き、40 行を超えるメソッドがない
• 依存関係が注入されている（ゲーム状態に静的シングルトンを使っていない）
• 設定値をデータファイルから読み込んでいる
• システムが具象クラスではなくインターフェースを公開している

---

フェーズ 5：アーキテクチャと SOLID

アーキテクチャ：

• 依存関係の方向が正しい（engine <- gameplay であり、その逆ではない）
• モジュール間に循環依存がない
• レイヤーが適切に分離されている（UI がゲーム状態を所有していない）
• システム間通信にイベント／シグナルを使用している
• コードベースで確立されたパターンと一貫している

SOLID：

• 単一責任の原則：各クラスには変更理由が 1 つだけある
• オープン・クローズドの原則：変更せずに拡張できる
• リスコフの置換原則：サブタイプを基本型と置き換えられる
• インターフェース分離の原則：肥大化したインターフェースがない
• 依存性逆転の原則：具象ではなく抽象に依存している

---

フェーズ 6：ゲーム固有の考慮事項

• フレームレートに依存しない（デルタタイムを使用している）
• ホットパス（更新ループ）でメモリ割り当てを行わない
• null／空の状態を適切に処理している
• 必要な箇所でスレッドセーフである
• リソースを適切に解放している（リークがない）

---

フェーズ 7：専門家レビュー（並列）

該当するすべての専門家を Agent 経由で同時に起動します。次の専門家の起動を始める前に、ひとつの結果を待ってはいけません。

報告する前に、専門家の指摘をすべて検証してください。確認せずに指摘を引き継いではいけません。 各指摘について、レポートに次の情報を記録してください。

• 該当するファイルと行。
• 根拠 — 引用したコード、または問題を引き起こす具体的な入力／状態。
• 確度 — VERIFIED（自分で確認した）または UNVERIFIED — specialist claim（確認できなかった）。

検証できなかった指摘は、未検証として報告するか、削除してください。自信に満ちた表現だけを根拠に、欠陥として扱ってはいけません。

これが必須である理由。 エージェントは導出には信頼できますが、既存コードの診断には信頼できません。短い関数についての誤った主張でも、ざっと目を通しただけなら説得力があるように見え、入力をひとつずつ列挙するとバグの主張が崩れることがあります。この手順がなければ、親レビューは指摘のロンダリング経路になります。推測が専門家の指摘として入り、レビュー済みの欠陥として出ていくのです。

エンジン専門家

エンジンが設定されている場合、各ファイルに該当する専門家を判断し、並列で起動します。

• 主要言語のファイル（.gd、.cs、.cpp）→ 言語／コード専門家
• シェーダーファイル（.gdshader、.hlsl、シェーダーグラフ）→ シェーダー専門家
• UI 画面／ウィジェットのコード → UI 専門家
• 横断的な内容、または判断が難しい内容 → 主任専門家

エンジンアーキテクチャ（シーン構造、ノード階層、ライフサイクルフック）に関わるファイルについても、主任専門家を起動します。

QA テスト容易性レビュー

ロジックおよび統合のストーリーでは、エンジン専門家と並行して Agent 経由で qa-tester も起動します。次の情報を渡してください。

• レビュー対象の実装ファイル
• ストーリーの ## QA Test Cases セクション（qa-lead が事前に作成したテスト仕様）
• ストーリーの ## Acceptance Criteria

qa-tester には、次の点を評価するよう依頼してください。

• すべてのテストフックとインターフェースが公開されているか（private/internal アクセスの背後に隠されていないか）。
• ストーリーの ## QA Test Cases セクションにある QA テストケースが、テスト可能なコードパスに対応しているか。
• 実装上、テストできない受け入れ基準がないか（例：値がハードコードされている、注入用のシームがない）。
• 既存の QA テストケースではカバーされない、新たなエッジケースが実装によって導入されていないか。
• テストすべきなのにテストされていない、観測可能な副作用がないか。

ビジュアル／操作感および UI のストーリーでは、qa-tester に、## QA Test Cases の手動検証手順が実装どおりに実行可能かをレビューしてもらいます。たとえば、「手動チェッカーが到達する必要のある状態に、実際に到達できるか」を確認します。

出力を作成する前に、すべての専門家の指摘を集めてください。

---

フェーズ 8：出力レビュー

## Code Review: [File/System Name]

### Engine Specialist Findings: [N/A — no engine configured / CLEAN / ISSUES FOUND]
[Findings from engine specialist(s), or "No engine configured." if skipped]

### Testability: [N/A — no story path given / N/A — Visual/Feel or Config story / TESTABLE / GAPS / BLOCKING]
[qa-tester findings: test hooks, coverage gaps, untestable paths, new edge cases]
[If BLOCKING: implementation must expose [X] before tests in ## QA Test Cases can run]

### ADR Compliance: [NOT ASSESSED / NO ADRS FOUND / COMPLIANT / DRIFT / VIOLATION]
[List each ADR checked, result, and any deviations with severity]

### Standards Compliance: [X/6 passing]
[List failures with line references; a missing doc comment names the method or class]

### Architecture: [NOT ASSESSED / CLEAN / MINOR ISSUES / VIOLATIONS FOUND]
[List specific architectural concerns]

### SOLID: [NOT ASSESSED / COMPLIANT / ISSUES FOUND]
[List specific violations]

### Game-Specific Concerns
[List game development specific issues]

### Positive Observations
[What is done well -- always include this section]

### Required Changes
[Must-fix items before approval — ARCHITECTURAL VIOLATIONs always appear here]

### Suggestions
[Nice-to-have improvements]

### Verdict: [NOT ASSESSED / APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]

次の優先順位で、最初に該当した判定を選びます。

• CHANGES REQUIRED — Required Changes に何か記載がある場合
• NOT ASSESSED — レビュー対象がない場合（上記のデータなしの経路）、エンジン専門家レビューが実行されなかった場合（エンジンが設定されていない、または専門家を起動できなかった）、またはレポートのいずれかのセクションが NOT ASSESSED と記載されている場合（参照先 ADR を読み取れなかった ADR Compliance、Architecture、SOLID）。該当するものを明記してください。既知の欠陥のほうが未実施のチェックより対処しやすいため、NOT ASSESSED は CHANGES REQUIRED より下位ですが、どちらの承認判定よりは上位です。エンジンチェックを省略したレビューでは、コードを承認していません。（NO ADRS FOUND は NOT ASSESSED ではありません。確認対象の ADR がないことは、承認を妨げません。）
• APPROVED WITH SUGGESTIONS — Suggestions のみの場合
• APPROVED — 必須の変更も提案もない場合

このスキルは読み取り専用です。ファイルは書き込みません。

---

フェーズ 9：次のステップ

AskUserQuestion を使用します：

• プロンプト：「コードレビューが完了しました — 判定：[NOT ASSESSED / APPROVED / APPROVED WITH SUGGESTIONS / CHANGES REQUIRED]。次にどのように進めますか？」（フェーズ 8 の判定を一字一句そのまま使用します）
• 選択肢（判定に応じて調整します）：
  • APPROVED の場合：
    • [A] /story-done を実行してストーリーを完了としてマークする
    • [B] ここで終了する
  • APPROVED WITH SUGGESTIONS の場合：
    • [A] 提案を適用してから /story-done を実行する
    • [B] 今すぐ /story-done を実行する — 提案は後で対応するものとして記録する
    • [C] ここで終了する
  • CHANGES REQUIRED の場合：
    • [A] 問題を修正して /code-review を再実行する
    • [B] 例外を記録したうえで、/story-done を実行する
    • [C] ここで終了する
  • NOT ASSESSED の場合：
    • [A] レビューを妨げた問題を解決する（コードの場所を教える、/setup-engine を実行する、または読み取れない ADR 参照を修正する）してから、/code-review を再実行する
    • [B] ここで終了する

ARCHITECTURAL VIOLATION が見つかった場合：

• 違反が既存の ADRに反している場合：docs/architecture/[adr-file].md に準拠するよう実装を修正します。設計が正当に変更された場合は、/architecture-decision を実行して既存の ADR を正式に改訂します。競合する ADR を新たに作成してはいけません。
• 違反したパターンに対応する ADR が存在しない場合：コードを修正する前に、/architecture-decision を実行して正しいアプローチを文書化します。