architecture-review

テスト

レビューのロジックを検証するには、pytest plugins/pensive/tests/skills/test_architecture_review.py を実行します。

アーキテクチャレビューのワークフロー

ADR および設計原則に基づくアーキテクチャ評価です。

クイックスタート

/architecture-review

使用する場面

• 再実装の承認。
• 大規模なリファクタリングのレビュー。
• システム設計の変更。
• 新しいモジュール／サービスの導入。
• 依存関係の再構成。

使用しない場面

• アーキテクチャパラダイムの選定 — archetypes skills を使用
• API サーフェスのレビュー — api-review を使用
• アーキテクチャパラダイムの選定 — archetypes skills を使用
• API サーフェスのレビュー — api-review を使用

段階的な読み込み

レビューの対象範囲に応じてモジュールを読み込みます。

• modules/adr-audit.md（約400トークン）：ADR の検証とドキュメント。
• modules/coupling-analysis.md（約450トークン）：依存関係の分析と境界違反。
• modules/principle-checks.md（約500トークン）：コード品質、セキュリティ、パフォーマンス。
• modules/fpf-methodology.md（約800トークン）：FPF（機能的、実用的、基盤的）な多角的レビュー手法。
• modules/ceremony-audit.md（約600トークン）：決して乖離しないマッピング層を調べる手動の観点。パススルーマッパー、双子の型、先走って作成された DTO、実装が1つだけのインターフェースが対象です。IO 境界の反証サインも含みます。

包括的なレビューでは、すべてのモジュールを読み込みます。対象を絞ったレビューでは、関連するモジュールのみを読み込みます。

必須の進捗項目

1. arch-review:context-established：リポジトリ、ブランチ、動機。
2. arch-review:adr-audit：ADR の検証と新しい ADR の必要性。
3. arch-review:interaction-mapping：モジュールの結合分析。
4. arch-review:invariant-check：不変条件の競合検出と3つの選択肢の分析。
5. arch-review:principle-checks：LoD、セキュリティ、パフォーマンス。
6. arch-review:ceremony-audit：決して乖離しないマッピング層。
7. arch-review:risks-actions：推奨事項とフォローアップ。
8. arch-review:findings-verified

ワークフロー

ステップ1：コンテキストを確立する（arch-review:context-established）

リポジトリとブランチを確認します。

pwd
git status -sb

以下を記録します。

• レビューのきっかけとなった機能、バグ、エピック。
• 影響を受けるサブシステム。
• README／ドキュメントに記載されたアーキテクチャ上の意図。
• 設計上のトレードオフに関する前提。

ステップ2：ADR を監査する（arch-review:adr-audit）

読み込み：modules/adr-audit.md

• プロジェクト内の ADR を特定します。
• 必須セクションを検証します。
• ステータスの遷移を確認します。
• 不変性への準拠を確認します。
• 新しい ADR が必要かどうかを明示します。

ステップ3：相互作用をマッピングする（arch-review:interaction-mapping）

読み込み：modules/coupling-analysis.md

• モジュール間の相互作用を、変更前と変更後で図示します。
• コンポジションの境界を検証します。
• データの所有権が明確か確認します。
• 依存関係の流れの方向を検証します。
• 結合違反を特定します。

ステップ 3.5：不変条件の競合検出（arch-review:invariant-check）

原則を確認する前に、変更が既存の設計上の不変条件と競合していないかを特定します。これはアーキテクチャレビューで最も高度な判断が求められるステップです。モデルはほかのどの判断よりも、ここで誤ることがよくあります。

既存の不変条件を特定します：

1. ADR を調べ、「accepted」状態のままの記録済み決定を確認します
2. モジュールの境界を確認します（これまで越えていなかったレイヤー間でインポートが行われていますか？）
3. データフローの方向を確認します（データが新しい方向に流れるようになっていますか？）
4. API コントラクトを確認します（公開インターフェースの形が変わっていますか？）
5. 構造上のパターンを確認します（既存のパターンと並行して、新しいパターンが導入されていますか？）

# Detect boundary crossings in changed files
git diff --name-only | while read f; do
  head -20 "$f" 2>/dev/null | rg "^(import|from|use |require)" || true
done

競合が検出された場合：

解決策を推奨してはいけません。3 つの選択肢を提示し、人間の判断を仰いでください：

選択肢	適切な場合	不適切な場合
不変条件を維持する（機能を却下する）	不変条件によって多くのことが簡素化され、機能の重要性が低い場合	機能が本当に必要で、不変条件が古くなっている場合
上に重ねる（洗練されていない形で追加する）	機能が必要で、不変条件にも引き続き価値があり、不完全さを許容できる場合	重ねることで、積み重なる保守上の罠が生じる場合
不変条件を改訂する（設計を変更する）	新たな知見によって、元の判断の根拠が無効になった場合	十分に理解していない決定を「整理」しようとしている場合

出力形式：

### Invariant Conflicts

[I1] **[Invariant name]** — [what decision it represents]
- **Location**: file.py:42
- **Anchor**: `verbatim source text at line 42`
- **Conflict**: [what change clashes]
- **Options**: Preserve / Layer / Revise
- **Recommendation**: ESCALATE TO HUMAN
- **Risk if wrong**: [what compounds]

重要な理由： 不適切な不変条件の判断は積み重なります。誤った判断が数回続くと、コードベースは修復不可能になります。これはコンテキストの問題ではなく、判断の問題です。エージェントは問題を提示すべきであり、解決すべきではありません。

ステップ 4：原則のチェック（arch-review:principle-checks）

読み込み：modules/principle-checks.md

• デメテルの法則。
• アンチスロップパターン。
• セキュリティ（入力検証、最小権限）。
• パフォーマンス（N+1 クエリ、キャッシュ）。

ステップ 4.5：儀式的な構造の監査（arch-review:ceremony-audit）

読み込み：modules/ceremony-audit.md

結合分析（ステップ 3）では、境界が漏れている箇所を見つけます。このステップでは、その反対の問題、つまりコストがかかる一方で、何も分離していない境界を見つけます。

• フィールドがすべて 1:1 のコピーである、受け渡しだけのマッパー。
• レイヤー間で構造が同一の対応する型。
• 形を固定する外部コントラクトがない、先回りして作られた DTO。
• 実装が 1 つだけで、テスト用の代替実装もないインターフェース。

各指摘では、その構造が現在どのような必要性に応えているのかを明示してください。現在の必要性を示せない場合、その構造自体が指摘対象です。

IO 境界にあるマッパーを問題として指摘してはいけません。 受け渡しだけに見えても、将来の内部フィールドが外部に漏れるのを防ぐため、重要な役割を果たしています。モジュール内の反対の兆候を参照してください。

ステップ 5：リスクとアクション（arch-review:risks-actions）

imbue:diff-analysis/modules/risk-assessment-framework を使用して要約します：

• 現在のアーキテクチャと提案されたアーキテクチャ。
• ビジネスへの影響。
• 技術的負債への影響。

担当者と日付を添えて、フォローアップ項目を列挙します。

推奨事項を提示します：

• 承認：アーキテクチャに問題はありません。
• 条件付き承認：軽微な問題への対応が必要です。
• 却下：再設計が必要となる根本的な問題があります。

アーキテクチャ原則チェックリスト

結合度

• 依存関係が定義された境界に従っている。
• 循環依存がない。
• 拡張ポイントが適切に使用されている。
• 抽象化から内部の詳細が漏れていない。

凝集度

• 関連する機能がまとめられている。
• 各モジュールが単一の責務を持っている。
• モジュールの目的が明確である。

レイヤー構造

• 各レイヤーの責務が明確である。
• 依存関係が下位に向かっている。
• レイヤーを迂回していない。

不変条件

• 既存の設計上の不変条件が特定されている。
• 変更と不変条件の競合が明示されている。
• 3 つの選択肢（維持／上に重ねる／改訂）の分析が提示されている。
• 不変条件の変更について、人間の判断を仰いでいる。
• 差分で不変条件が暗黙に改訂されていない。

進化

• 変更を元に戻せる。
• 移行経路が明確である。
• 決定が ADR に記録されている。

調査結果の根拠を検証する（arch-review:findings-verified）

調査結果を.review/findings.jsonに書き込み、引用検証ツールを実行し （Skill(imbue:review-core)のステップ5）、検証ツールが却下した項目を削除するか、 UNVERIFIEDのラベルを付けます。

完了条件

• コンテキストが確立され、ADR監査が完了し、インタラクションのマッピングが行われ、 不変条件の競合が明らかになり、原則のチェックが実施され、リスクとアクションが 文書化されていること。
• 報告するすべての調査結果に、citation_verifier.py（終了コード0）で確認済みの Locationと逐語的なAnchorが含まれていること。確認できていない調査結果は 削除するか、UNVERIFIEDのラベルを付けていること。