align-architecture

スキル：アーキテクチャの整合性確認

目的

コードの実装が、ADR、設計ドキュメント、またはアーキテクチャ仕様に記録されたアーキテクチャおよび設計上の決定と一致しているかを検証します。実装が記録された決定から逸脱している場合は、アーキテクチャ準拠レポートを生成します。

---

主な目標

ガバナンス目標：文書化されたアーキテクチャ／設計上の決定を現在の実装と比較し、準拠上のギャップとその影響、是正の提案を列挙した、実行可能なアーキテクチャ準拠レポートを生成します。

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

1. ✅ 設計の情報源を特定する：ADR、設計ドキュメント、またはアーキテクチャ仕様を見つけて解析する
2. ✅ 実装を比較する：記録された決定に照らしてコードを分析する
3. ✅ ギャップを分類する：準拠上の各ギャップを（境界違反、コンポーネントの欠落、パターンの相違などに）分類し、影響と根本原因を示す
4. ✅ レポートを保存する：アーキテクチャ準拠レポートを所定のパスに書き込む
5. ✅ 根拠を参照する：各ギャップについて、特定の設計情報源とコード上の位置を参照する。部分検証を行う場合は、対象範囲／対象外の範囲と確信度を明示する
6. ✅ 次の対応を提案する：設計が古い、または矛盾している場合は設計-解決方案を提案し、構造的なレビューが必要な場合は「アーキテクチャをレビュー」を提案する

受け入れテスト：チームメンバーがレポートを読んで、どのアーキテクチャ上の決定に違反しているか、コードのどこに問題があるか、次に何をすべきかをすぐに把握できますか？

---

対象範囲の境界

このスキルの担当範囲：

• 設計ドキュメントとコードの比較
• 準拠上のギャップの検出と分類
• 各ギャップの影響範囲と根本原因
• 是正と引き継ぎの提案

このスキルの担当範囲外：

• 設計の参照情報がないコード構造のレビュー（「review-architecture」を使用）
• 要件分析（「analyze-需求」を使用）
• 設計の作成や代替案の検討（「設計解決方案」を使用）
• 計画レイヤーの整合性確認（「align-planning」を使用）

引き継ぎのタイミング：レポート作成後、設計を変更する必要がある場合は「設計-解決方案」に引き継ぎ、設計との比較を伴わない構造的なコードレビューの場合は「審査-架構」に引き継ぎます。

---

使用例

• 実装後の確認：実装がADRまたは設計ドキュメントと一致しているか検証する
• マイルストーンまたはリリースゲート：アーキテクチャ上の決定がコードに反映されていることを確認する
• 乖離の調査：実装が文書化された設計から逸脱している場合に診断する
• オンボーディングレビュー：新しいコントリビューターが設計と実際の状態を把握できるよう支援する

---

オーケストレーションのガイダンス

シナリオ	推奨される順序
日常的なタスクの完了	align-planning（簡易）
マイルストーンまたはリリースゲート	align-planning（完全）→ 続いてalign-architecture
実装後の確認	对齐架构
計画とアーキテクチャの両方に問題がある	まず「对齐规划」を実行し、レポートで設計とコードの乖離が示された場合は → align-architecture

計画レイヤーの整合性が不明な場合は、「align-architecture」の前に「align-planning」を実行します。それ以外の場合は、設計とコードの検証のために「align-architecture」を単独で実行します。

---

動作

フェーズ 0：規範の解決（v1.3 で追加）

specs/artifact-contract.md §8 Runtime Norms Resolution Protocol の §8.2／§8.3／§8.5 に従って実装します。プロジェクト規範で architecture-compliance artifact_type の path_pattern が宣言されている場合は、プロジェクトの値を使用します。それ以外の場合は、スキルのデフォルト（docs/calibration/architecture-compliance.md）にフォールバックします。このスキルは固定パスのガバナンス成果物を生成するため、path_pattern による上書き機構のみを使用します。

エージェント実行時の契約

You are responsible for architecture compliance verification.

Compare documented architecture and design decisions (ADRs, design docs) against
the codebase and produce an Architecture Compliance Report when divergence exists.

インタラクションポリシー

• デフォルト：プロジェクト規範、または「docs/architecture/」、「docs/design-decisions/」、「docs/process-management/decisions/」にあるADR／設計パス。コード範囲はワークスペース内
• 選択オプション：デフォルト以外の場合は設計ドキュメントのパスを明示。範囲を限定する場合はコードのパスを明示
• 確認：設計ドキュメントの編集を提案する前、およびコード範囲が広い場合

フェーズ 0：設計情報源とコード範囲の解決

1、設計情報源のパスを解決します（プロジェクト規範、またはデフォルト：docs/architecture/、docs/design-decisions/、docs/process-management/decisions/） 2.コード範囲を解決します：

• 全体：リポジトリ全体（デフォルト）
• 増分：ユーザーが指定したパス、パッケージ、またはモジュール（大規模なコードベース向け。影響を受ける設計上の決定のみを検証します）

3. 設計ドキュメントがない場合は、必要最小限の入力を示すブロッキングレポートを出力し、「設計解決方案」または「ドキュメント整備」を提案します

フェーズ 0.5：根拠の準備状況の評価

比較の前に、設計による対象範囲を評価します：

• 十分：対象範囲内の関連するすべてのコンポーネント／モジュールに設計ドキュメントがある
• 不十分：設計ドキュメントが一部のみ。ADR があるコンポーネントとないコンポーネントが混在しているため、確信度を下げて部分検証を実施する
• なし：設計ドキュメントがない。レポートはブロックされ、設計ワークフローを提案する

ルール：

1. 準備状況が「不十分」の場合は、設計情報源がある決定のみを検証します。設計情報源が見つからないコードには「不明」のマークを付け、レポートに列挙します。
2. 準備状況が「不十分」の場合、高い確信度を示してはなりません。
3. 対象範囲、対象外の範囲、確信度を明確に報告します。

フェーズ 1：設計上の決定を抽出する

1. ADR、設計ドキュメント、アーキテクチャ仕様を解析します
2. 境界、コンポーネント、パターン、制約などの重要な決定を抽出します
3. 比較用の決定指標を作成します

フェーズ 2：実装を比較する

1. 記録された各決定に照らしてコードを分析します
2. 各決定を「準拠」 | 部分的 | 「違反」 | 不明として評価します
3. 根拠を記録します：ファイルパス、モジュール、またはコードスニペット
4. ギャップを分類します：
   • 境界違反：コードが文書化されたモジュール／レイヤーの境界を越えている
   • コンポーネントの欠落：記録されたコンポーネントまたはインターフェースが実装されていない
   • パターンの相違：実装で、ドキュメントとは異なるパターンが使用されている
   • 設計の陳腐化：設計ドキュメントが古く、実装が現在の意図を反映している可能性がある。recommended_actionを割り当てます：
     • update_设计：実装が正とされる。実装に合わせて設計を更新する必要がある（「設計-解決方案」を提案）
     • update_code：設計が正とされる。コードをリファクタリングして設計に合わせる必要がある
     • 「両方」：不明確で、関係者の判断が必要。「設計解決方案」を提案して調整する

フェーズ 3：レポートを生成する

1. 調査結果を要約し、影響範囲、根本原因、各ギャップの「推奨アクション」を含めます
2. 各ギャップについて、コード、設計、またはその両方のどれを更新すべきかを明記します（上記のギャップの種類を参照）
3. 設計を変更する必要がある場合は設計-解決方案への引き継ぎを提案し、構造的なレビューのみが必要な場合は「アーキテクチャをレビュー」を提案します
4. 部分検証を使用する場合は、根拠の準備状況と確信度を含めます

フェーズ 4：レポートを保存する

レポートを書き込む先：

• プロジェクト規範から解決したパス（docs/ARTIFACT_NORMS.md または .ai-cortex/artifact-norms.yaml）
• デフォルト：docs/calibration/architecture-compliance.md（スナップショットを明示的に要求された場合を除き、上書きします）
• または、ユーザーが指定したパス

レポートには、機械可読な準拠ブロック（YAML または JSON）を含める必要があります。

---

入力と出力

入力

• オプションのADR／設計ドキュメントのパス
• オプションのコード範囲（パスまたはモジュール）
• オプションのプロジェクトドキュメントのルートディレクトリ

出力

アーキテクチャ準拠レポートのテンプレート

# Architecture Compliance Report

**Date:** YYYY-MM-DD
**Design Sources:**
**Code Scope:**
**Status:** compliant | partial | violated
**Evidence Readiness:** strong | weak | missing (when partial verification used)
**Confidence:** high | medium | low

## Summary
- Total decisions checked:
- Compliant:
- Partial:
- Violated:

## Compliance Gaps

### Gap 1
- **Type:** boundary violation | missing component | divergent pattern | outdated design
- **Design Source:**
- **Code Location:**
- **Impact Scope:**
- **Root Cause:**
- **Recommended Action:** update_code | update_design | both
- **Remediation:**

## Covered / Uncovered Scope (when partial verification)
- Covered:
- Uncovered:
- Reason:

## Recommended Next Actions
1.
2.

## Machine-Readable Compliance

    evidence:
      readiness: "strong"  # strong | weak | missing
      confidence: "high"   # high | medium | low
    gaps:
      - type: "boundary violation"
        designSource: "docs/architecture/adr-001.md"
        codeLocation: "pkg/infra/db.go"
        impactScope: "Domain layer imports infrastructure"
        rootCause: "Repository interface not used; direct DB import"
        recommendedAction: "update_code"  # update_code | update_design | both
        remediation: "Implement repository pattern per ADR-001"

---

制限事項

厳格な境界

• ドキュメントがない場合は、設計上の決定をでっち上げてはなりません。レポートをブロックし、設計ワークフローを提案します
• 根拠の準備状況が「不十分」の場合、高い確信度を示してはなりません（部分検証）
• 設計情報源が不完全または不明確な場合、準拠していると主張してはなりません
• ユーザーの明示的な承認なしに、設計ドキュメントをひそかに変更してはなりません
• 設計の参照情報なしに、構造的なコードレビュー（つまり「アーキテクチャをレビュー」）を実施してはなりません

スキルの境界（重複の回避）

次の作業は行わないでください（他のスキルで対応できます）：

• コード構造のみのレビュー → 審查架构
• 設計の作成や代替案の検討 → 設計解決方案
• 計画レイヤーのトレースバック → align-planning

作業を停止して引き継ぐ場合：

• 設計ドキュメントが存在しない → 「設計解決方案」または「ドキュメント整備」を提案
• 設計が矛盾している、または古い → 「設計解決方案」に引き継ぐ
• 設計との比較を伴わない構造的なコードレビューが必要 → 「アーキテクチャをレビュー」に引き継ぐ

---

セルフチェック

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

• 設計情報源を特定し、解析した
• コードを記録された決定と比較した（または準備状況が不十分な場合は部分検証を実施した）
• 各ギャップに影響範囲、根本原因、および種類が設計の陳腐化の場合は「推奨アクション」が含まれている
• レポートを所定のパスに保存した
• 各ギャップの根拠を参照している（部分検証を使用する場合は、対象範囲／対象外の範囲と確信度を含む）
• 該当する場合、引き継ぎの提案を含めた

受け入れテスト

チームメンバーは、追加の説明なしで上位1～3件のコンプライアンス上の差異に対応できますか？

いいえの場合：証拠を補強し、是正措置を明確にします。

はいの場合：レポートを完成させ、引き継ぎまたは是正を行います。

---

例（サンプル）

例 1：境界違反

コンテキスト：ADR-001 では、ドメインがインフラストラクチャをインポートしてはならないと定めています。コードでは、ドメインパッケージがデータベースドライバーをインポートしています。

出力：

• 種類：境界違反
• 設計の出典：docs/process-management/decisions/20240101-adr-001-layered-architecture.md
• コードの場所：pkg/domain/order.go（pkg/infra/dbをインポート）
• 影響：ドメインとインフラストラクチャが結合されており、クリーンアーキテクチャに違反しています
• 修正：ドメインでリポジトリーインターフェースを定義し、インフラストラクチャで実装して、コンストラクターインジェクションを使用します

例 2：設計ドキュメントなし

背景：プロジェクトに ADR または設計ドキュメントがありません。

出力：

• ステータス：ブロック中
• メッセージ：アーキテクチャまたは設計ドキュメントが見つかりませんでした。「ソリューションを設計」を実行して設計ドキュメントを作成するか、「bootstrap-docs」を実行して構成を整えてください。
• 信頼度：該当なし

例 3：部分的な検証（準備状況が不十分）

コンテキスト：pkg/auth にのみ ADR があり、pkg/orders と pkg/inventory には設計ドキュメントがありません。

出力：

• 証拠の準備状況：不十分
• 信頼度：中程度
• 対象範囲：pkg/auth（ADR-002 に基づいて検証）
• 未確認の範囲：pkg/orders、pkg/inventory（設計の出典がないため、不明としてマーク）
• レポートには引き続き「pkg/auth」の調査結果を含めます。コンプライアンスが必要な場合は、未対象のパッケージについて設計ドキュメントを作成することを推奨します

例 4：古くなった設計と推奨アクション

コンテキスト：ADR-003 では同期 API を指定していますが、実装では非同期のイベント駆動型プロセスを使用しており、関係者もそれを希望しています。

出力：

• 種類：古くなった設計
• 推奨アクション：設計を更新
• 修正：ADR-003 を更新して非同期のイベント駆動型アプローチを記録します。実装が正と見なされます。設計ドキュメントの変更を「ソリューションを設計」に引き継ぎます。

---

付録：出力コントラクト（Appendix: Output Contract）

このスキルは Architecture Compliance Report を生成します。人が読める説明文に加え、機械可読の部分は以下の表の構造を満たす必要があります：

要素	形式	必須フィールド	パスパターン
レポート本体	Markdown	front-matter（artifact_type/created_by/created_at/lifecycle）；本文のセクション：概要 / 設計の出典 / 対象範囲 / 差異の一覧 / 引き継ぎの推奨事項	docs/calibration/architecture-compliance.md（デフォルト；スナップショットが必要な場合は -snapshot のコピーを別途作成）
差異項目	リスト項目	type（boundary_violation / outdated_design / undocumented / partial_validation）/ design_source / code_location / impact / fix（または recommended_action）	レポート本文の「差異の一覧」セクション
証拠の準備状況	スカラー	readiness（strong / moderate / weak）/ confidence / covered_scope / uncovered_scope	レポート本文の「対象範囲」セクション
機械可読ブロック	YAML fenced yaml compliance_gaps:	gaps[] の各項目に id/type/design_source/code_location/severity/fix_kind を含める	レポート本文の末尾。plan-next/auto-iterate が利用