CAPHTECH Architecture Reviewer
3種類の分析を並行実行し、矛盾検出と優先順位付けまで一貫して行う。
核心: 単体分析で終わらせない。3視点の分析 → 矛盾検出 → 優先順位付けを必ず通す。
ワークフロー
1. 3種類の分析（並行）→ 2. 矛盾検出（4類型）→ 3. 優先順位付け → 4. 出力
前提条件
Full Mode（デフォルト）
必須:
system-map/invariants.yaml- 不変条件component-dossiers/*.yaml- コンポーネントカード
推奨:
system-map/dependencies.yaml- 依存グラフsystem-map/boundaries.yaml- 境界定義- 既存ADR（アーキテクチャ決定記録）
- プロジェクト特性の定義（品質優先順位）
Lightweight Mode
system-map が存在しない場合、scripts/collect_artifacts.py でプロジェクトをスキャンし、D2/D3/D5 の検証のみを実行する。
python3 scripts/collect_artifacts.py <project_root> -o /tmp/dcc-manifest.json
Phase 1: 3種類の分析
┌─────────────────────────────────────────────────────────┐
│ 必ず3つとも実行する（単体だけで終わらせない） │
├─────────────────────────────────────────────────────────┤
│ (1) コンポーネント内レビュー ─ ノード（局所の健全性） │
│ (2) インタラクションレビュー ─ エッジ（依存の整合性） │
│ (3) クロスカッティングレビュー ─ 縦串（横断的品質） │
└─────────────────────────────────────────────────────────┘
分析1: コンポーネント内レビュー（ノード）
各コンポーネントの局所的な健全性を検証する。不変条件（invariants.yaml）に照らして評価すること。
| 観点 | チェック内容 |
|---|---|
| 責務 | 過多（God Object）/ 不足（Anemic）はないか |
| 境界 | 境界を逸脱した処理をしていないか |
| データ所有 | owned_data以外を直接書き込んでいないか |
| 例外設計 | 例外の握りつぶし、過剰なcatch-allはないか |
| テスト可能性 | 依存注入、モック可能性は確保されているか |
| テスト網羅性(D2) | 各不変条件・状態遷移・境界条件にテストがあるか |
| 障害モード網羅性(D5) | 各障害モードに処理コードとリカバリ戦略があるか |
指摘は component_findings として出力する。category は responsibility/boundary/data_ownership/exception/testability のいずれか。
分析2: インタラクションレビュー（エッジ）
依存グラフの「辺」ごとに検証する。全体性の本丸。
| 観点 | チェック内容 |
|---|---|
| 契約整合 | スキーマ、バージョン、後方互換性 |
| エラー伝播 | リトライ連鎖、サーキットブレーカ、タイムアウト整合 |
| 冪等性 | リトライ時の副作用、重複処理 |
| 順序性 | イベント順序の前提、順序逆転時の挙動 |
| 整合モデル | 結果整合/強整合の前提が一致しているか |
| セキュリティ | 認証・認可・秘密情報の境界超え |
| スキーマ実装一致(D3) | データスキーマとコードの型・フィールド・制約が一致しているか |
エラー伝播の連鎖分析: A -> B -> C の場合、タイムアウトの大小関係、リトライ連鎖の指数的爆発を確認する。
指摘は interaction_findings として出力する。category は contract/error_propagation/idempotency/ordering/consistency/security のいずれか。
分析3: クロスカッティングレビュー（縦串）
システム横断的な品質を検証する。
| 縦串 | チェック内容 |
|---|---|
| セキュリティ | 脅威モデルとの整合、境界の一貫性 |
| 信頼性 | SLO/SLI定義、障害分離、リカバリ戦略 |
| 観測性 | ログ・メトリクス・トレースが責務境界と一致 |
| 変更容易性 | モジュール結合度、影響範囲、ADR整合 |
指摘は crosscutting_findings として出力する。aspect は security/reliability/observability/changeability のいずれか。
各指摘のYAML例は references/finding-examples.yaml を参照。指摘を書くときのテンプレートとして使用する。
Phase 2: 矛盾検出（4類型）
分析結果の指摘間、および指摘と不変条件/ADR間の矛盾を検出する。改善案の列挙より矛盾の発見に注力する。
4類型の概要
| 類型 | conflict_type | 内容 |
|---|---|---|
| 改善案間の矛盾 | improvement_tradeoff | 改善案Aは品質Xを改善するが品質Yを損なう |
| 前提破壊 | assumption_violation | コンポーネントiの改善が依存先jの前提を破壊 |
| 不変条件違反 | invariant_violation | 推奨アクションが不変条件と食い違う |
| ADR矛盾 | adr_inconsistency | 推奨がADRと矛盾、またはADRが欠落 |
検出手順
- 全 findings の recommendation を品質属性でタグ付け
- 同じ品質属性に対して逆方向の recommendation がないか走査
- 各 recommendation が invariants.yaml の条件に違反しないか確認
- 各 recommendation が既存ADRと矛盾しないか確認
- 重要な決定にADRがなければ
missing_adrsとして記録
各類型の詳細説明とYAML例は references/conflict-types.md を参照。矛盾を特定する際のパターンマッチに使用する。
Phase 3: 優先順位付け
スコアリング
Priority = Severity x Likelihood x Detectability_inv x Quality_Weight
| 要素 | 説明 | スケール |
|---|---|---|
| Severity | 発生時の影響度 | critical=4, high=3, medium=2, low=1 |
| Likelihood | 発生確率 | high=3, medium=2, low=1 |
| Detectability_inv | 検出困難なほど高い | easy=1, medium=2, hard=3 |
| Quality_Weight | プロジェクト品質優先順位 | 1位=5, 2位=4, 3位=3, 4位=2, 5位=1 |
優先順位カテゴリ
| カテゴリ | スコア | 対応 |
|---|---|---|
| P0 - Blocker | 36+ | 即時対応（リリース不可） |
| P1 - Critical | 24-35 | 今スプリント内 |
| P2 - High | 12-23 | 次スプリント |
| P3 - Medium | 6-11 | バックログ |
| P4 - Low | 1-5 | 技術的負債 |
プロジェクト特性が未定義の場合、Quality_Weight は全て 3（中央値）として計算する。
スコアリングの詳細計算例とプロジェクト特性の定義例は references/priority-scoring.md を参照。スコア算出に迷った時に使用する。
出力形式
architecture-review/{timestamp}/review.yaml に統合出力する。
id: architecture-review
reviewed_at: "2024-01-21T10:00:00+09:00"
mode: full # full | lightweight
reviewed_scope:
components: 15
interactions: 23
invariants_checked: 24
summary:
total_findings: 12
by_category:
component: 4
interaction: 5
crosscutting: 3
by_severity:
critical: 2
high: 4
medium: 5
low: 1
verification_summary:
verdict: NEEDS_ATTENTION # PASS | PASS_WITH_WARNINGS | NEEDS_ATTENTION | FAIL
by_verdict: { pass: 18, warn: 4, fail: 2 }
dimensions_checked: [D2_test_coverage, D3_schema_match, D5_failure_modes]
# Phase 1 の結果
component_findings: [...] # finding-examples.yaml 参照
interaction_findings: [...] # finding-examples.yaml 参照
crosscutting_findings: [...] # finding-examples.yaml 参照
# Phase 2 の結果
conflicts:
total: 8
by_type:
improvement_tradeoff: 3
assumption_violation: 2
invariant_violation: 2
adr_inconsistency: 1
items:
- id: CONF-001
type: improvement_tradeoff
findings: [COMP-001, EDGE-003]
description: 抽象化 vs 直接通信のトレードオフ
resolution:
decision: performance優先（EDGE-003採用）
rationale: プロジェクト特性でperformance > changeability
deferred_action: COMP-001は技術的負債として記録
# Phase 3 の結果
prioritized_actions:
- priority: P0
items:
- finding_id: EDGE-001
score: 180
action: payment-serviceタイムアウト整合
deferred_items:
- finding_id: COMP-001
reason: 優先度が低い（changeability）
revisit: リリース後のスプリント1
missing_adrs:
- topic: サービス間タイムアウト戦略
related_findings: [EDGE-001, EDGE-003]
recommendation: ADR作成を推奨
注意事項
- 3種類すべてを実行: 単体分析だけで終わらせると全体性を見落とす
- 矛盾検出が本丸: 改善案の列挙より、矛盾の発見と解決に注力
- 不変条件に拘束: 評価基準は invariants.yaml から導出
- プロジェクト特性を必ず適用: 同じ問題でも優先順位が変わる
- 推測禁止: 根拠がない指摘はしない。evidence を必ず記載
- severity は客観的に: 影響範囲と発生確率で判定
- ADR欠落の検出: 重要な決定にADRがなければ指摘
参照
- references/finding-examples.yaml - 3種類の分析指摘のYAML例。指摘を書くときのテンプレートとして使用
- references/conflict-types.md - 矛盾の4類型の詳細説明とYAML例。矛盾を特定する際に使用
- references/priority-scoring.md - スコアリング詳細とプロジェクト特性の定義例。スコア算出時に使用
- references/crosscutting-checklist.md - クロスカッティング分析の詳細チェックリスト。縦串分析時に使用
- references/verification-dimensions.md - D2/D3/D5 検証次元の詳細。設計整合性チェック時に使用
- references/report-verdicts.md - PASS/WARN/FAIL 判定基準。verdict 付与時に使用
scripts/collect_artifacts.py- Lightweight Mode 用アーティファクト収集スクリプト