review-architecture

スキル：アーキテクチャレビュー

目的

提示されたコード範囲をarchitecture-qualityに照らして評価します。このスキルは実行と証拠収集を担当し、すべてのアーキテクチャ基準はルールが定めます。指摘事項リストを出力し、スコアや書き換えは行いません。

中核となる目標

該当するルール項目に違反したものすべてについて、位置が正確で対応可能なアーキテクチャ上の指摘事項を作成するとともに、該当しない項目と、プロジェクトパラメーターがないため評価できなかった項目を報告します。

成功には、次の条件が必要です。

1. 適用中のルールのバージョンと、該当するすべての項目 ID を明記します。
2. 判断を下す前に、プロジェクトの構成、保護対象の契約、プロファイル、有効な免除を特定します。
3. ルールで宣言されている場合は自動化された証拠を優先し、ツールが確認できる範囲を誇張しません。
4. すべての指摘事項で、違反したルール ID を 1 つ引用し、カテゴリ cognitive-architecture を使用します。
5. 該当するすべての項目について、合格、有効な免除、または証拠上の制約が明示されてから、指摘事項が 0 件であると報告します。

対象範囲の境界

このスキルはアーキテクチャのみをレビューします。差分とコードベースのどちらを対象とするかの選択、言語規約、セキュリティ、パフォーマンス、信頼性、オブザーバビリティ、テスト品質のレビュー、コードの変更、免除の承認は行いません。これらの懸念には、対応するアトミックスキルまたは orchestrate-code-review を使用してください。

使用例

• 変更、モジュール、リポジトリのアーキテクチャに焦点を当てたレビュー
• orchestrate-code-review 内のアーキテクチャ認知ステップ
• 宣言されたモジュール構成または保護対象の契約変更の検証
• 実装後の構成、配線、変更範囲のリスクのレビュー

動作

1. architecture-qualityを全文読み込み、そのバージョンを記録します。
2. 該当する場合は、最も近いプロジェクトの AGENTS.md、アーキテクチャ文書、.ai-cortex/config.yaml を読み込みます。rule-modelingに従って、適用中のプロファイル、パラメーター、免除を特定します。
3. 該当する項目で必要となる証拠のみを収集します。
   • リポジトリに組み込まれた依存関係チェックまたは契約チェックを優先します。
   • それ以外の場合は、ビルドメタデータ、インポートグラフ、エクスポートされたシグネチャ、本番環境の呼び出し箇所、提示された差分を使用します。
   • 判断を要する項目では、具体的な責務と依存関係の証拠を比較します。根拠の説明がない品質スコアは使用しません。
4. 該当する各項目を個別に評価します。プロジェクトパラメーターが欠けている場合、評価対象外となるのはその project:* 項目のみです。ベースライン項目には影響しません。
5. 違反した義務ごとに指摘事項を 1 件出力します。説明には、たとえば architecture-quality@<active-version>/ARC-003 のように、適用中のルールのバージョンを含めます。
6. 免除を適用するのは、すべての免除フィールドが有効で、ルール ID と適用範囲が該当する指摘事項に正確に一致する場合のみです。免除された項目は別途報告し、その存在を消去しません。
7. findings-list 仕様にある正確な passed、waived、not_applicable、evidence_limited フィールドを使用して、ルールの適用状況を返します。

入力と出力

入力は、すでに選定されたコード範囲（ファイル、ディレクトリ、または差分）です。任意のプロジェクトコンテキストには、変更規模や上流の技術設計を含められます。

出力は、findings-list形式の指摘事項（0 件以上）です。すべての指摘事項でカテゴリ cognitive-architecture を使用し、説明に違反したルール ID を記載します。適用状況のフッターはメタデータであり、指摘事項ではありません。

制約

• アーキテクチャチェックリストを言い換えたり、ローカルで拡張したりしないでください。基準が不足している場合は、Rule の変更を提案してください。
• 名前付きのアーキテクチャスタイルを前提にしたり、モジュール構成を作り上げたりしないでください。
• 依存関係ツールがないことを、依存関係に関する項目に合格した証拠として扱わないでください。
• レビュー中に免除を承認、拡大、作成しないでください。
• 修正作業は行わないでください。修正を依頼された場合は、ブロッキングとなる指摘事項を orchestrate-repair-loop に引き継いでください。
• テストがないことをアーキテクチャ上の指摘事項として報告しないでください。この Skill が判断するのは、本番コードにおける構成と契約が適切かどうかです。問題を検出できるものがあるかどうかは review-testing が判断します。

セルフチェック

• 正規のアーキテクチャ Rule を読み込み、そのバージョンを記録した。
• プロジェクトの証拠から、有効なプロファイル、パラメーター、免除を特定した。
• 適用可能なすべての Rule ID について、合格、指摘事項、有効な免除、または明示的な証拠上の制限を記録した。
• 各指摘事項に、正確な場所、カテゴリ cognitive-architecture、有効な重大度、引用した Rule ID を記載した。
• この Skill でアーキテクチャ基準を作り出したり、重複させたりしていない。
• カバレッジのフッターで、合格、免除、該当なし、証拠上の制限を区別した。

例

例 1：宣言された依存関係への違反

入力：プロジェクトでは domain に外部モジュールへの依存関係がないと宣言されていますが、domain/order.ts がデータベースアダプターをインポートしています。

想定される結果：インポート箇所に対し、ARC-002 を引用した重大度 major の cognitive-architecture 指摘事項を出します。また、ARC-003 とその他の該当するベースライン項目も評価します。これらも違反していると決めつけてはいけません。

例 2：有効なレガシー循環の免除

入力：循環が ARC-003 に該当し、期限切れではない免除が、承認済みの凍結管理を伴って正確なレガシーディレクトリを対象としています。

想定される結果：ARC-003 を免除 ID の一覧に記載し、凍結された循環に新しいノードやエッジが加わっていないことを検証します。補償管理に違反があった場合は、指摘事項を出します。

例 3：プロジェクトのトポロジーがない

入力：小規模なライブラリに .ai-cortex/config.yaml がありません。

想定される結果：パラメーターの要件に応じて、ARC-002 と ARC-009 を評価不能または該当なしとします。そのうえで、ベースラインの凝集度、循環、境界の漏出、結合、投機的な拡張を通常どおり評価します。

例 4：アナライザーが解決できないシンボル

入力：未使用シンボルアナライザーが jobs.QuarterlyCloseTask を未到達と報告しています。このクラスは設定に保持された名前からインスタンス化されており、レビュー対象の変更では削除されます。

想定される結果：ARC-010 を引用した軽微な指摘事項を出します。削除の根拠となっているツールは、設定に記述された名前による構築やリフレクションによる構築を検出できません。そのため、このクラスが呼び出されていないことの証拠にはなりません。この項目には、四半期決算処理で実行される頻度の低いパスも含め、1 回の完全な業務サイクルにわたるランタイムシグナルが必要です。変更でそのようなシンボルを残し、どちらの場合もランタイムシグナルがない場合は、ARC-010 を evidence_limited として報告します。アナライザーの実行結果がクリーンでも、アナライザーが解決できない対象について合格とはなりません。

例 5：担当者も削除時期もない非推奨マーカー

入力：api.v1.SearchRequest の @deprecated アノテーションには置き換え先が記載されていますが、担当者も、削除するリリースまたは日付も記録されていません。

想定される結果：マーカー全般ではなく、欠けている 2 つのフィールドを明示したうえで、ARC-011 を引用した軽微な指摘事項を出します。プロジェクトが所有していない依存関係上のマーカーは該当しません。すでに過ぎた削除時期が記録されている場合は、削除が行われておらず、更新の記録もないときに限り、指摘事項となります。