Ephasme/コード品質スキャン

コード品質スキャン は何をしますか？

オーケストレーターとしてシニアコードレビューチームを指揮します。あなた自身がすべてのファイルを読むわけではありません — 作業範囲を設定し、専門レビューア(品質観点ごとに1名)に作業を割り振り、その後、より低コストなチェッカーが各所見を検証・ランク付けし、その結果を1つの証拠ベースのレポートにまとめます。

レビューを分割することで、各レビューアは1つのレンズに集中できます（6つの懸念事項に浅く触れるのではなく、深く掘り下げます）。また、レンズを並列実行し、発見にのみ高価なモデルを使用します。具体的なクレームの検証と優先順位のスコアリングは、小さく高速なモデルの範囲内で十分に行えるため、そこで処理されます。

並列性は最適化であり、要件ではありません。 このエージェントがサブエージェントをディスパッチできる場合は、各レビューアと各チェッカーにそれぞれ独自のサブエージェントを与えてください。これにより、分離が実際に機能し、実行が高速になります。できない場合は、同じリストを自分で処理してください — 一度に1つのカテゴリずつ、各カテゴリの所見を次のカテゴリを開始する前にファイルに書き込み、その後、収集した所見に対して個別の検証パスを実行します。カテゴリを決して省略せず、発見パスとチェックパスを1回の読み取りに統合しないでください。チェックは、引用されたコードを独立した視点で確認するために存在します。

使用するタイミング

• コードレビューまたは品質監査
• 技術負債の評価またはリファクタリングの準備
• コードベースの健全性を理解するためのオンボーディングレビュー
• リリース前のコードスメル検出

オプション

これらは呼び出しから読み取ります（例: --find-model <ミッドティア> --check-model <低コスト> --depth thorough src/）。存在しない場合はデフォルト値を使用し、解決された値をレポートの先頭に記載します。

オプション	デフォルト	意味
--find-model	ミッドティア: 利用可能な最大のものではない、強力な汎用モデル	観点別レビューア（発見フェーズ）用のモデル
--check-model	最安値: 利用可能な最小・最速のモデル	検証とランク付けパス（チェックフェーズ）用のモデル
--depth	thorough	quick = 上位の所見のみ（各レビューアは最大8つの最も強い所見を返す）、1回のチェッカーバッチ; thorough = 完全なカタログ、所見ごとの検証
--focus	すべてのカテゴリ	検出カテゴリリストの名前またはスタックパックテーブルのレンズID（swift-concurrency、react-coreなど）のカンマ区切りのサブセット（大文字小文字を区別せず一致） — 指定されたレビューアのみが実行されます。何にも一致しない名前は、スキャンが空であることを示すのではなく、報告すべきエラーです。
--stack	自動検出	スタックパックを強制（--stack swift-ios、--stack react、カンマ区切り）または無効化（--stack none）
ターゲットパス	リポジトリルート	位置引数: スキャンするディレクトリ/ファイル
--exclude	ベンダー、生成ファイル、ビルド出力、ロックファイル	スキップするパス

モデル値は、このエージェントが公開するモデルセレクターにそのまま渡されます — エイリアスまたは完全なモデルIDのいずれか、セレクターが受け入れる形式です。セレクターがない場合は、両方のフラグを無視し、レポートの設定行にその旨を記載します。フェーズは引き続き実行されますが、1つのモデル上で行われます。オーケストレーター自体は常にセッションモデル上で実行されます。

ティアの名前よりも重要なのは、その役割です。構造的問題の発見には推論が必要ですが、引用されたコードに対する具体的なクレームのチェックには必要ありません。両方を同じ大きなモデルに送信すると、実行コストの大部分が作業の安価な半分に浪費されます。

アーキテクチャ

orchestrator (このセッション)
  │  1. スコープ設定 + 共有コンテキストブリーフの作成
  ├──► 発見フェーズ (並列, モデル = --find-model) ───────────────┐
  │      レビューア: アーキテクチャの一貫性                          │
  │      レビューア: 設計原則の遵守                                  │  スコープ内の各
  │      レビューア: デッドコードと未使用アーティファクト              │  カテゴリに1つの
  │      レビューア: 適切な複雑性                                    │  サブエージェント
  │      レビューア: コードの明確性                                  │
  │      レビューア: 状態管理                                        │
  │      レビューア: パックが一致した場合、スタックレンズごとに1つ    │
  │  2. 生の所見を収集、安定したIDを割り当て                     ◄───┘
  ├──► チェックフェーズ (並列, モデル = --check-model) ─────────────┐
  │      チェッカー: 引用されたコードを再読み取り、確認/反論、        │  すべての所見を
  │                   対抗シグナルを適用、優先順位をスコアリング       │  検証＋ランク付け
  │  3. 確認された所見を保持、優先度でソート                     ◄───┘
  └──► 4. レポートを合成

ワークフロー

1. スコープ設定。 ターゲットパスを解決。設定ファイルとディレクトリ構造から、言語、フレームワーク、レイヤリング、プロジェクト規約を特定。除外パターンを適用。これらを一度だけ取得し、短いコンテキストブリーフ（言語、フレームワーク、ターゲットパス、除外パターン、注目すべきレイヤリング）として記録 — この同じブリーフをすべての発見サブエージェントに渡し、各サブエージェントが再度導出する必要がないようにします。

   スタックパックテーブルに対してスタックを検出。パックの検出シグナルがリポジトリ内のどこかだけでなく、ターゲットパスに該当する場合に適用されます。どのパックが一致したか、およびそのルールが依存するツールチェーン情報をブリーフに記録します。これは、ターゲットごとに異なる場合（言語バージョンとモード、デフォルトの分離、最小OS、UIフレームワーク）に行います。ルールはターゲットごとに適用され、リポジトリは多くの場合、アプリターゲットと拡張機能、パッケージを異なる設定で混合します。パックが一致しない場合 → 汎用カテゴリのみ。設定行にその旨を記載します。

2. 発見フェーズ — スコープ内のカテゴリごとに1つのレビューアサブエージェントを、すべて1つの並列バッチでディスパッチ。各サブエージェントには model = --find-model を使用。カテゴリは6つの汎用カテゴリと、一致した各パックのすべてのレンズです。各サブエージェントに与えるもの: コンテキストブリーフ、その単一のカテゴリの名前、参照するファイルとセクション（汎用カテゴリ: references/generic.md の該当セクション; スタックレンズ: パックファイル全体）、および以下の発見出力契約。次のセクションのプロンプトテンプレートを使用します。広く浅くレビューするレビューアは目的を損なう — 各レビューアは正確に1つのレンズのみを担当します。

   一致したスタック上の汎用レビューアも、パックのイディオムを適用します。SwiftUIの「神オブジェクト」は、20のメソッドを持つクラスではなく、画面全体のビューモデルです。どのパックが一致したかをレビューアに伝えます。レビューアはそれを読んでもかまいませんが、自分のカテゴリのみを報告します。

   重複。 1つの欠陥、1つの所見: レンズは同じコードをしばしば見ます — 共有可変状態は「Swift並行性」と「状態管理」の両方に該当します。Effectによって useState にコピーされたサーバーデータは、react-core と react-architecture の両方に該当します。スタックレンズのルールが構造に名前を付けている場合、スタックレンズは汎用カテゴリよりも優先されます。2つのスタックレンズ間では、根本原因に関するルールを持つレンズが優先されます（キャッシュ、それをコピーするEffectではありません）。収集時に、位置が重複し、パターンが同じメカニズムを指定している所見をマージし、所有者のものを保持し、残りをその下にリストします。

3. 収集。 すべてのレビューアのJSON出力を収集し、連結し、各所見に安定した id（例: arch-1、complexity-3）を割り当てます。完全な重複（同じ位置 + パターン）を削除し、上記のルールに従って重複をマージします。

4. チェックフェーズ — すべての所見を検証およびランク付け。model = --check-model を使用。以下のチェックプロンプトテンプレートを使用して、チェッカーサブエージェントを並列にディスパッチします。各チェッカーは、引用されたコードを独立して再読み取りし、所見が本物かどうかを判断し、対抗シグナルを適用し、重大度を調整し、0〜100の優先度スコアを割り当てます。thorough 深度では、真に独立した検証のために各所見（または小さなバッチ）に独自のチェッカーを与えます。quick 深度では、カテゴリ内のすべての所見を1つのチェッカーにバッチ処理します。refuted（反論）の所見は破棄します（「検討されたがフラグ付けされなかった」として表示）。confirmed（確認）の所見を保持し、uncertain（不確か）にフラグを付けます。

5. レポート。 残った所見を priority_score の降順（同点の場合は重大度）でソートします。以下のレポート構造を出力します。解決された設定（ターゲット、深度、フォーカス、find-model、check-model）を先頭に配置し、実行を再現可能にします。

発見サブエージェント — プロンプトテンプレート

プレースホルダーを埋め、model = --find-model でカテゴリごとに1つディスパッチします。

あなたは、1つの品質観点: {CATEGORY_NAME} についてコードを監査するシニアコードレビューアです。他のすべての観点は無視してください — それらは他のレビューアがカバーします。

コンテキストブリーフ: {言語、フレームワーク、ターゲットパス、除外パターン、レイヤリングに関するメモ}

この観点の検出シグナル、しきい値、リファクタリングレシピについては、{{CATEGORY_NAME} の {references/generic.md の絶対パス} のセクション | {パックファイルの絶対パス} 全体} を読んでください。それらを使用してください — 記憶に頼らないでください。各パックルールの Since は、そのルールが必要とするバージョンを示しています。プロジェクトのバージョンが古い場合、ルールの修正はそのバージョンに存在しない可能性があります。そのバージョンに問題自体が存在する場合は欠陥を報告し、そのバージョンで機能するリファクタリングを提示し、新しい修正はアップグレードパスとしてのみ言及してください。ルールの対象がそのバージョンに存在しない場合（API、ルーター、コンパイラ）、ルールを完全に削除してください。ターゲットパスのみをスキャンしてください。

具体的な証拠（ファイルパス、シンボル、メトリクス/カウント、または特定の構造）を持つすべての問題について、所見を出力します。証拠を指し示せない場合は、出力しないでください — 根拠のないフラグはレビューアの時間を無駄にします。プロジェクトの既存の規約を尊重してください。リファクタリングの方向性は、非破壊的で動作を維持するものでなければなりません。

のみ JSON配列を返してください（散文は不要）。各要素は次のフィールドを持つ: { "category", "pattern", "location", "evidence", "impact", "refactor_direction", "severity" }。ここで severity ∈ high|medium|low は私が指定したルーブリックに従います。何も見つからない場合は [] を返します。

チェックサブエージェント — プロンプトテンプレート

収集された所見を埋め、model = --check-model でディスパッチします。

あなたは、敵対的な検証者でありトリアージ担当者です。以下の各候補所見について、引用されたコードを独立して再読み取り、それが本当の欠陥であるかどうかを判断してください — 所見自身の主張を信頼しないでください。

所見: {JSON配列の所見。各所見には id が含まれます}

各所見について以下を判断してください:

• verdict: confirmed（証拠が成り立ち、本当の欠陥である）、refuted（証拠が成り立たない、引用されたコードが異なる、または対抗シグナルが適用される）、または uncertain（引用された場所からは判断できない）。証拠が不十分で実証できない場合は、デフォルトで refuted にします。
• confidence: 0.0〜1.0。
• adjusted_severity: high|medium|low（レビューアの重大度を上書きしても構いません）。
• priority_score: 0〜100 — 重大度 × 影響範囲 × 修正レバレッジ でランク付け: 放置した場合の悪影響の大きさ、影響を受けるファイル/コンシューマ/パスの数、および非破壊的な修正が努力単位あたりにもたらす改善の大きさ。1つのデッドファイルに閉じ込められた高重大度の問題は何もランク付けしません。ホットパスに波及する中程度の問題は、孤立した高重大度よりも優先されます。
• rationale: 1〜2文。コードで見たものを引用してください。

所見を refuted に押し上げるべき対抗シグナル: 3つ以上の独立したコンシューマによる実証された再利用; コンプライアンス/規制上の義務; 積極的に使用されている拡張ポイント; 意図的なAHA重複（間違った抽象化よりも安価）; スタックレンズの所見の場合、ルール自身の対抗シグナル、プロジェクトのバージョンに存在しない対象、または代替手段なしでプロジェクトが実行しているバージョンよりも新しいバージョンを必要とするリファクタリング。

のみ JSON配列を返してください。各要素: { "id", "verdict", "confidence", "adjusted_severity", "priority_score", "rationale" }。

検出カテゴリ

デフォルトの優先順位順にリストされています。各カテゴリは、健全なコードがどのようなものかを説明しています。逸脱があれば所見となります。各発見サブエージェントに正確に1つ渡します。

1. アーキテクチャの一貫性 — 各モジュールは明確な境界と単一の目的を持ちます。依存関係は一方向に流れます。1つの機能の変更は、その境界内に留まります。
2. 設計原則の遵守 — コードはSOLID、DRY、YAGNI、KISSに従います。抽象化は、実証された現在のニーズのためにのみ存在します。各クラスには変更する理由が1つあります。
3. デッドコードと未使用アーティファクト — エクスポートされたすべてのシンボル、ファイル、ブランチ、パラメータは、現在のコードパスによって到達可能であり、実行されます。
4. 適切な複雑性 — 関数は低い分岐（CC ≤ 15）、浅いネスト（≤ 3レベル）、少ないパラメータ（≤ 4）を持ちます。間接層は再利用によって正当化されます。
5. コードの明確性 — 名前は意図を明らかにします。定数はマジック値を置き換えます。制御フローは直線的に読み取れます。用語はコードベース全体で一貫しています。
6. 状態管理 — 依存関係は明示的に渡されます。可変スコープは可能な限り狭くなります。副作用はシグネチャで可視化されます。

各発見サブエージェントは、references/generic.md の該当セクションのみを読み、特定のシグナル、しきい値、リファクタリングレシピを参照します — そのファイルにはカテゴリごとの詳細が含まれており、レビューアが記憶に頼らないようにします。

スタックパック

パックは、1つのスタック用のレンズを追加します。そのスタックに固有のルール、またはそのスタックで特定の形式をとるルールであり、それぞれに検出シグナル、適用開始バージョン、重大度、リファクタリング、対抗シグナル、ソースが含まれます。パックのレンズは、汎用カテゴリの後に優先順位順に実行されます。

パック	検出条件	レンズ（各レビューア1つ）
swift-ios	*.swift ソースに加え、*.xcodeproj、project.yml（XcodeGen）、Tuist/、または .iOS プラットフォームを含む Package.swift がある場合	swift-concurrency — 並行性とデータ競合の安全性、references/swift-concurrency.md; swift-language — 言語とAPI設計、references/swift-language.md; swiftui — 状態とレンダリング、import SwiftUI が出現する場合のみ、references/swiftui.md; ios-platform — プラットフォームの正確性とApp Storeリスク、references/ios-platform.md
react	ターゲットパスを管理する package.json の dependencies に react があり、*.jsx/*.tsx ソースがある場合	react-core — コンポーネント、フックとレンダリング、references/react-core.md; react-architecture — データ、状態とフレームワーク、references/react-architecture.md