review-codebase

スキル：コードベースのレビュー

目的

指定されたパス（単一ファイル／ディレクトリ／リポジトリ）の現在の状態を対象に、スコープのみのアトミックレビューを実施します。Git の変更のみをレビューする review-diff と対をなすこのスキルは、orchestrate-code-review のスコープステップ候補の 1 つです。このスキルではスナップショットを確認し、review-diff では変更を確認します。

ここでは扱いません：セキュリティ／パフォーマンス／アーキテクチャなどの認知的な観点（これらは認知ステップ用のアトミックスキル review-security／review-performance／review-architecture が担当します）、および言語固有・フレームワーク固有の分析（これらは言語／フレームワークの各ステップが担当します）。

---

主な目的

主な目標：指定されたパスにおける構造上の問題（境界、パターン、依存関係、技術的負債、インターフェース）を特定する、スコープのみの指摘事項リストを作成します。

成功基準（すべて満たす必要があります）：

1. ✅ スコープを確定する：ユーザーが指定したパスまたはディレクトリを使用します。より限定された範囲が指定されていない場合は、リポジトリのルートを使用します。
2. ✅ 5 つの観点を網羅する：モジュール境界、パターンの一貫性、モジュール間の依存関係、技術的負債、インターフェースの安定性について指摘事項を提示します。
3. ✅ 位置を正確に示す：すべての指摘事項に file:line 形式の参照を付けます。
4. ✅ 形式に準拠する：すべての指摘事項が Findings Spec §5.1 に準拠し、カテゴリが scope であること。
5. ✅ 大規模なスコープに対応する：リポジトリ全体が対象の場合は、レイヤー（モジュール／ディレクトリ）ごとに提示するか、ユーザーと相談して優先対象を絞ります。
6. ✅ 範囲を逸脱しない：セキュリティ／パフォーマンス／アーキテクチャ／言語／フレームワークに関する認知的な指摘事項は提示しません（該当するアトミックスキルを示してフラグを立てます）。

---

スコープの境界

このスキルが担当すること：

• 指定されたパスの現在の状態に対する構造的なレビュー
• 5 つの観点にわたる指摘事項：モジュール境界、パターンの一貫性、モジュール間の依存関係と結合、技術的負債と保守性、インターフェースの安定性

このスキルが担当しないこと：

• Git の変更のみのレビュー（review-diff を使用）
• オーケストレーションによるレビュー全体（orchestrate-code-review を使用）
• 言語固有／フレームワーク固有の規約（review-<lang>／review-<framework> を使用）
• セキュリティ／パフォーマンス／アーキテクチャの認知的な観点（review-security／review-performance／review-architecture を使用）

引き継ぎ地点：指摘事項を作成した後、それらは集約のため orchestrate-code-review のスコープステップに渡すか、次に何を行うか（リファクタリング／より詳細なレビュー）を決めるためにユーザーに渡します。

---

ユースケース

• 新規モジュールのレビュー：src/auth/ が指定された場合、現在の構造と依存関係を確認します。
• レガシーパスの監査：パスが指定された場合、技術的負債と境界の問題を確認します。
• サンプルレビュー：同僚が指定したファイルまたはディレクトリを、差分なしでレビューします。
• orchestrate-code-review のスコープステップとして使用：review-diff とこのスキルのどちらか一方を使用し、両方は使用しません。

---

動作

スコープの確定

• 入力によってスコープを定義します：ユーザーが指定した単一ファイル／ディレクトリ／リポジトリのルート／複数のパス
• 差分には依存しません：現在のファイル内容を分析します。ユーザーが提示する差分はコンテキストとしてのみ扱い、必須ではありません。

スコープのデフォルト

項目	デフォルト	ユーザーが変更する方法
パス	リポジトリのルート	次から選択：[リポジトリのルート]／[現在のファイルのディレクトリ]／[トップレベルディレクトリの一覧から選択]
大規模スコープへの対応	レイヤー（モジュール／ディレクトリ）ごとに提示	優先対象を選択（トップレベルディレクトリの一覧から）

指定されたパスは確認を求めずに使用します。リポジトリ全体をレビューする場合は、ユーザーが対象を絞らない限りレイヤーごとに作業します。確認するのは、要求されたスコープを特定できない場合のみです。

5 つの観点

対象コード（ユーザーが選択したレイヤー／サブセット）について、以下の観点で指摘事項を出力します。

1. モジュール境界：モジュール／サービスの境界が明確か、責務が単一か、依存の方向が適切か
2. パターンの一貫性：パターンが適切に使われ、リポジトリ内の既存スタイルと一致しているか
3. モジュール間の依存関係と結合度：依存関係、循環依存、結合度
4. 技術的負債と保守性：重複、複雑さ、テスト容易性、ドキュメントやコメントの現状、呼び出し元が見当たらないコード、残存している非推奨マーカー
5. インターフェースの安定性：モジュールの外部向けインターフェースがどれだけ明確で安定しているか

すべての指摘事項に file:line 形式の参照を付けてください。

対象外の指摘事項のフラグ付け

分析中に具体的なセキュリティ／パフォーマンス／アーキテクチャ／言語／フレームワークの問題が見つかった場合は、分析を進めずにフラグを付け、該当する個別スキルを案内してください。例：

SQL インジェクションの潜在的なリスクを検出しました（ユーザー入力がエスケープされずに連結されています）。review-security の実行を提案します。

このスキルが最初に遭遇することが多く、コードを読むだけでは判断できないため、特に指摘しておく価値のある技術的負債の観察事項が 2 つあります。呼び出し元が見当たらないシンボルは、リフレクションによって呼び出されていたり、設定に名前が記載されていたりする可能性があるため、必要かどうかの判断には、ビジネスサイクル全体にわたる実行時のシグナルが必要です。非推奨マーカーについては、所有者、削除時期、置き換え先を併記するかどうかを責任者が判断します。場所を示して判断を委ねてください。

jobs/settlement.py:18 で定義されているクラスには、対象範囲内に呼び出し箇所が見当たりません。また、config/jobs.yaml ではハンドラーが文字列で指定されています。review-architecture の実行を提案します。このスキルでは、必要な証拠を用いて ARC-010 に基づき判断します。

api/v1/search.py:7 の非推奨マーカーには、所有者も削除時期も記録されていません。ARC-011 に基づき判断する review-architecture の実行を提案します。

---

入力と出力

入力

• パス：1 つ以上のファイル／ディレクトリのパス
• 任意：重点項目のヒント（例：「モジュール境界に重点を置く」）

出力

• 指摘事項リスト：Findings Spec §5.1 に準拠し、カテゴリは scope とします。
• 大規模スコープの概要：レイヤー別に整理する場合は、各レイヤーの指摘事項数と重大度の内訳を出力します。

---

制約

厳守すべき境界

• 「差分のみ」を対象とする前提を置かないでください。デフォルトでは、このスキルは指定された対象範囲の現在の状態全体をレビューします。
• 認知的側面の指摘事項（セキュリティ／パフォーマンス／アーキテクチャ）は出力しないでください。
• 言語／フレームワーク固有の指摘事項は出力しないでください。
• file:line 形式の参照がない指摘事項は出力しないでください。
• 曖昧な表現（種類も方向性も示さない「問題かもしれない」など）は使わず、削除してください。

スキルの境界

ここでは行いません（以下は他の個別スキルの担当です）。

• Git の変更内容のレビュー → review-diff
• 全観点にわたるオーケストレーション → orchestrate-code-review
• 言語の規約 → review-<lang>
• フレームワークの規約 → review-<framework>
• セキュリティ／パフォーマンス／アーキテクチャ → review-security / review-performance / review-architecture

---

セルフチェック

• レビュー対象範囲が、依頼内容または文書化されたデフォルトから確定されている
• 大規模な対象範囲はレイヤー別に出力されているか、優先するサブセットが確定されている
• 5 つの観点すべて（モジュール境界／パターン／依存関係／技術的負債／インターフェース）を網羅している
• すべての指摘事項に file:line 形式の参照が付いている
• 認知的側面／言語／フレームワークの指摘事項は出力していない（該当する個別スキルを案内する形でフラグを付けるのみ）
• 出力が Findings Spec §5.1 に準拠している

---

例

例1：単一ディレクトリ

• 入力：src/auth/
• 出力：5つの観点にわたる指摘事項をファイルごとにまとめ、それぞれに auth.go:42 の形式の参照を付けます。弱い暗号アルゴリズムについては指摘のみ行い、review-security を参照します。

例2：単一ファイル

• 入力：pkg/validator/validator.go
• 出力：モジュールの責務／インターフェースの明確さ／テストカバレッジ／上位モジュールへの依存関係などに関する指摘事項

例3：リポジトリ全体（大規模な範囲）

• 入力：リポジトリのルート
• 動作：まずレイヤー（トップレベルディレクトリ）ごとの指摘事項の概要表を出力し、次に、より詳しく調査する優先対象をユーザーに選んでもらいます。
• 出力：レイヤーごとの概要と、優先対象に関する詳細な指摘事項