architect-analyze

architect-analyze

このスキルの機能

ADR（アーキテクチャ決定記録）と AD（アーキテクチャ記述）の間で、読み取り専用のアーキテクチャ整合性分析を実行します。ファイルを変更せずに、不一致、品質上の問題、欠落を特定します。

主な分析の観点：

1. ADR の品質 — 完全性、明確さ、標準への準拠
2. ADR と AD の整合性 — 双方向のずれを検出
3. 内部整合性 — 成果物間の一貫性
4. 陳腐化の検出 — 古い参照やプレースホルダー
5. Mermaid 構文 — 図のブロックを対象とした決定的な妥当性チェックと、場所および推奨パッチの提示（Mermaid 検出パス）

このスキルは、アーキテクチャ成果物の整合性、完全性、品質を検証します。

使用するタイミング

• /architect-implement の後 — 生成された AD.md を検証するとき
• /architect-clarify の後 — ADR の改善内容を確認するとき
• 機能開発の前 — アーキテクチャが確固としていることを確認するとき
• アーキテクチャレビュー中 — アーキテクチャ文書の品質ゲートとして
• 定期的に — コードベースの進化に伴うずれを検出するとき

アーキテクチャ成果物が存在しない場合は使用しないでください。先に /architect-init または /architect-specify を使用してください。アーキテクチャの作成には使用しないでください。このスキルは分析専用です。

プロセス

ユーザー入力

空でない場合は、処理を進める前にユーザー入力を考慮します。

$ARGUMENTS

例：

• "system" — ルートレベルの AD.md と adr/ ディレクトリのみを対象にします
• "feature auth" — 特定の機能のアーキテクチャを対象にします
• "adrs" — ADR の品質と ADR 間の整合性を対象にします
• "views" — AD.md のビューの完全性と内部整合性を対象にします
• 空の入力 — すべてのアーキテクチャ成果物を完全に分析します

目標

読み取り専用のアーキテクチャ整合性分析を実行します。ファイルを変更せずに、不一致、品質上の問題、欠落を特定します。

運用上の制約

厳格な読み取り専用：ファイルを変更しないでください。構造化された分析レポートを出力してください。修正案を提示します（後続の編集コマンドを手動で実行する場合は、ユーザーが明示的に承認する必要があります）。

憲章の優先性：プロジェクト憲章（memory/constitution.md）は、この分析の範囲内で交渉の余地がありません。憲章との競合は自動的に CRITICAL と判定されます。

役割とコンテキスト

アーキテクチャ文書の品質を検証するアーキテクチャアナリストとして行動します。

• MADR 標準に照らして ADR の完全性を検証する
• ADR と AD.md の間のずれを検出する
• 成果物間の内部不整合を特定する
• 陳腐化と品質上の問題を指摘する

アーキテクチャ文書の階層：

文書	場所	目的
AD.md	プロジェクトルート	完全なアーキテクチャ記述（Rozanski & Woods）
adr/	{REPO_ROOT}/docs/adlc/memory/（旧 .adlc/memory/ をフォールバックとして使用）	システムレベルの ADR（個別ファイル）
constitution.md	{REPO_ROOT}/docs/adlc/memory/（旧 .adlc/memory/ をフォールバックとして使用）	ガバナンス原則と制約

概要

1. 分析コンテキストの初期化 — アーキテクチャ成果物を読み込む
2. 分析範囲の決定 — システム、機能、または全体
3. 検出パスの実行 — A から G
4. 重大度の割り当て — CRITICAL/HIGH/MEDIUM/LOW
5. レポートの生成 — 構造化された Markdown 分析
6. 次のアクションの提示 — 修正案

フェーズ 1：分析コンテキストの初期化

目的：分析対象となるすべてのアーキテクチャ成果物を読み込みます

1. セットアップスクリプトを実行：

   • リポジトリのルートから {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh を実行します（architect-clarify スキルが必要です：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。
   • JSON を解析して、ファイルパスと存在状況を取得します。

2. システムレベルの成果物を読み込み：

   • 存在する場合は AD.md（プロジェクトのルート）を読み込みます。
   • すべての場所から ADR を読み込みます（優先順位順）：
     1. {REPO_ROOT}/docs/adlc/memory/adr/adr.md（正規の場所 — 承認済み ADR。デュアルリードに基づき、レガシーの {REPO_ROOT}/.adlc/memory/adr/adr.md をフォールバックとして使用）
     2. {REPO_ROOT}/.adlc/drafts/adr/（作業用コピー — 提案済み／発見済み、個別ファイル形式）
   • {REPO_ROOT}/docs/adlc/memory/constitution.md（レガシーの {REPO_ROOT}/.adlc/memory/constitution.md をフォールバックとして使用）が存在する場合は読み込みます。

3. 機能レベルの成果物を読み込み（機能を分析する場合）：

   • specs/*/AD.md をスキャンして機能アーキテクチャを確認します。
   • specs/*/adr/ADR-*.md をスキャンして機能 ADR を確認します。

4. 成果物インベントリを作成：

   成果物	パス	状態
   システム AD	AD.md	存在／不在
   システム ADR（正規）	{REPO_ROOT}/docs/adlc/memory/adr/adr.md（レガシーの .adlc/memory/adr/adr.md をフォールバックとして使用）	存在／不在
   システム ADR（ドラフト）	{REPO_ROOT}/.adlc/drafts/adr/	存在／不在
   憲章	{REPO_ROOT}/docs/adlc/memory/constitution.md（レガシーの .adlc/memory/constitution.md をフォールバックとして使用）	存在／不在
   機能 AD	specs/*/AD.md	件数：N
   機能 ADR	specs/*/adr/	件数：N

フェーズ 2：分析範囲の決定

目的：ユーザー入力に基づいて分析対象を絞り込みます

ユーザー入力	範囲	分析対象の成果物
（空）	全体	すべてのシステム成果物
"system"	システムのみ	AD.md、システム ADR の各保存場所
"adrs"	ADR の品質	すべての ADR ファイル
"views"	AD の完全性	AD.md

フェーズ 3：検出パスの実行

重要度の高い指摘に焦点を当てます。指摘は合計 50 件までとし、超過分はまとめて概要に記載します。

パス A：ADR の品質分析

目的：各 ADR を MADR 標準に照らして検証します

品質の評価項目：

評価項目	確認事項	不足時の重大度
コンテキスト	問題が明確に記述され、制約が文書化されている	中
決定	実行可能で、検証可能な決定文である	高
肯定的な結果	メリットが文書化されている	中
否定的な結果	トレードオフが認識されている	高
リスク	特定され、緩和策がある	中
代替案	中立的なトレードオフを含む選択肢が少なくとも 2 つある	高
ステータス	有効なステータス（Proposed／Accepted／Deprecated／Superseded／Discovered）である	低
憲章との整合性	MUST 原則に準拠している	重大

ADR 品質チェックリスト：

各 ADR について、次の項目を確認します。

• 問題や機会を説明する明確なコンテキストがある
• 明示的で実行可能な決定文がある
• 肯定的および否定的な結果が文書化されている
• 中立的なトレードオフを含む一般的な代替案がある（「却下した理由」ではない）
• 緩和策とともにリスクが特定されている
• 有効なステータス値である
• 憲章の MUST 原則と矛盾しない

パス B：ADR 間の整合性

目的：ADR 間の矛盾や不整合を検出します

確認項目：

1. 決定の矛盾：

   • 相互に矛盾する ADR（例：一方が PostgreSQL を選択し、別の ADR が MongoDB を前提としている）
   • 技術スタックに一貫性がない

2. 依存関係の欠落：

   • 相互に参照すべき ADR が参照していない
   • 他の決定に関する暗黙の前提がある

3. 用語の揺れ：

   • 同じ概念が ADR ごとに異なる名称で呼ばれている
   • コンポーネント名に一貫性がない

4. 技術スタックの整合性：

   • フロントエンド、バックエンド、インフラストラクチャの選択が一致している
   • フレームワークの選択が相互に矛盾していない

パス C：ADR から AD へのドリフト（前方同期）

目的：AD.md に反映されていない ADR の決定を検出します

チェック項目：

ADR の要素	AD.md で期待される項目	ビュー／セクション
システムアーキテクチャのスタイル	コンテキストビュー	3.1
データベースの選択	情報ビュー	3.3
API のスタイル	機能ビュー	3.2
認証方式	セキュリティパースペクティブ	4.1
デプロイプラットフォーム	デプロイメントビュー	3.6
CI/CD の方式	開発ビュー	3.5
スケーリング戦略	パフォーマンスパースペクティブ	4.2
キャッシュ戦略	情報ビュー	3.3

検出ロジック：

各 ADR について：

1. ADR が主に影響するビューを特定します（上の対応表を使用）
2. AD.md を検索し、その決定が反映されているか確認します
3. 決定が記載されていない、または矛盾している場合にフラグを立てます

パス D：AD から ADR へのドリフト（後方同期）

目的：裏付けとなる ADR がない AD.md の要素を検出します

チェック項目：

1. ADR のないコンポーネント：

   • 決定の根拠が示されていない機能ビュー内の主要コンポーネント
   • ADR による正当化がないコンテキストビュー内の外部依存関係

2. 根拠のないパターン：

   • ADR を通じて説明されていないアーキテクチャパターン
   • 裏付けとなる決定がないままビューに記載されている技術の選択

3. インフラストラクチャの決定：

   • インフラストラクチャ ADR がないデプロイメントトポロジー
   • パフォーマンス ADR がないスケーリング方式

Pass E：AD の内部整合性

目的：各ビュー間で AD.md の一貫性を検証します

チェック項目：

1. ビュー間の一貫性：

   • すべてのビューで同じコンポーネントに同じ名前が付けられている
   • 情報ビューのデータエンティティが、機能ビューの参照と一致している
   • 配置ノードが機能コンポーネントと整合している

2. 図とテキストの整合性：

   • Mermaid 図が文章の説明と一致している
   • 図に含まれるコンポーネントがすべてテキストにも記載されている
   • テキストに記載されるコンポーネントがすべて図にも含まれている

3. ビューの完全性：

   • 必須セクションが含まれている（はじめに、ステークホルダー、ビュー、パースペクティブ）
   • 中核となるビューが含まれている（コンテキスト、機能、情報、開発、配置）
   • パースペクティブが扱われている（セキュリティ、パフォーマンス）

4. 図の構文検証（決定論的 — Mermaid の検出パス）：

   • Mermaid の構文が正しい（図に破損がない）

   • 図全体でスタイルに一貫性がある

   • 共通バリデーターを実行します。破損したブロックごとに、重大度、場所（ファイル＋行＋フェンスのインデックス）、推奨パッチを含む検出結果を 1 件出力します。

     sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh
     sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh --tsv <artifact>
     

     ルールセットはバリデーター自体に一度だけ記載されています。ここでルールを再導出せず、バリデーターを参照してください。終了コード：0 は問題なし、1 は HIGH（構文エラー）が存在、2 は MEDIUM（スタイル）の検出結果のみです。認識されない図の種類は MEDIUM であり、HIGH にはなりません。このルールセットによって誤った構文エラーが発生してはなりません。このパスは読み取り専用です（ライフサイクルの書き込み範囲）。修正は /architect-implement または人間が行います。

5. ビューファイルの一貫性（DAG 状態の検証）：

   • .adlc/architect/state.json が存在し、ビューが「completed」と報告されているか確認します
   • docs/adlc/architect/views/ ディレクトリが存在するか確認します（旧 .adlc/architect/views/ を代替として使用します）
   • state.json で「completed」となっている各ビューについて、対応するファイルがディスク上に存在することを確認します
   • 次の場合は重大度 HIGH としてフラグを立てます：
     • state.json がビューを「completed」と報告しているが、views/ ディレクトリが空である
     • ビューファイルは存在するが、20 行未満である（プレースホルダー／骨組みの内容）
     • ビューファイルを読み取れない（破損／権限不足）
   • レポート形式：

     DAG State Inconsistency Detected:
     - State reports: [N] views completed
     - Files on disk: [M] view files found
     - Missing files: [list of missing views]
     - Recommendation: Regenerate views or reset state.json
     

6. 技術中立性（機能ビュー）：

   • 機能ビュー（§3.2）をスキャンし、要素の説明や Mermaid 図に含まれる製品名／ベンダー名を確認します
   • アーキテクチャ上の役割（許容）：データベース、オブジェクトストレージ、キャッシュ、メッセージキュー、AI ゲートウェイ、ワークフローランタイム、アプリシェル、API ゲートウェイ、認証サービスなど
   • 製品名（MEDIUM としてフラグ）：PostgreSQL、Neon、Vercel、Next.js、Redis、MongoDB、AWS、Azure、S3 など
   • 重大度：MEDIUM — ブロック要因ではありませんが、抽象化への違反を示します
   • 注：ADR のトレーサビリティセクションで製品を参照するのは問題ありません。フラグの対象は要素の説明と図のラベルのみです

7. 機能ビューと開発ビューのマッピング：

   • 開発ビュー（§3.5）にテクノロジースタックマッピングの表（§3.5.2）が含まれていることを確認します
   • 機能ビューの要素表（§3.2.1）にあるすべての要素に、マッピング表内の対応するエントリが少なくとも 1 つあることを確認します
   • N:1 のマッピング（複数の機能要素 → 1 つのテクノロジー）は許容されます
   • 重大度：要素が不足している場合は MEDIUM、マッピング表がない場合は LOW
   • 相互確認：テクノロジーアーキテクチャ図（§3.5.3）の構造が、機能ビューの図（§3.2.2）と一致していることを確認します

パス F：陳腐化の検出

目的：古くなった参照やプレースホルダーを特定します

確認項目：

1. 非推奨の ADR が依然として参照されている：

   • AD.md がステータス「Deprecated」の ADR を参照している
   • 後継の決定が依然として実装されている

2. プレースホルダーの検出：

   • [TODO]、[TBD]、[PLACEHOLDER] マーカー
   • [SYSTEM_NAME]、[STAKEHOLDER_*] が未入力
   • ???、...、<placeholder> のパターン

3. 日付の不整合：

   • ADR の日付が AD の最終更新日より著しく古い
   • 機能アーキテクチャがシステムアーキテクチャと同期していない

4. 参照先のない参照：

   • ADR ID が記載されているが、その ADR が存在しない
   • コンポーネント名が参照されているが、定義されていない

パス G：機能とシステムの整合性（機能アーキテクチャが存在する場合）

目的：機能アーキテクチャがシステムの境界内に収まっていることを検証します

確認項目：

1. 機能 ADR の整合性：

   • 「Aligns with ADR-XXX」と記された機能 ADR が、有効なシステム ADR を参照している
   • 文書化された正当な理由のない VIOLATION フラグがない
   • 機能に関する決定がシステムの制約と整合している

2. 境界への準拠：

   • 機能コンポーネントがシステムの Functional View の構造に収まっている
   • 機能のデータエンティティがシステムの Information View と整合している
   • 機能がシステムのスコープ（Context View）を超えていない

3. 統合ポイント：

   • 機能とシステム間のインターフェースが文書化されている
   • 機能境界をまたぐデータフローに整合性がある

フェーズ 4：重大度の割り当て

重大度の基準：

重大度	基準	例
CRITICAL	憲章への違反、セキュリティ／データ整合性の欠陥、主要 ADR の欠落	ADR が MUST 原則に違反している、主要コンポーネントが文書化されていない
HIGH	実装に影響する ADR と AD の乖離、ADR 間の矛盾、代替案の欠落	ADR ではデータベースを選定しているが、AD では異なる DB が使われている、2 つの ADR が矛盾している
MEDIUM	結果の記載不備、陳腐化、用語の揺れ、任意のビューの欠落	ADR に否定的な結果が記載されていない、TODO のプレースホルダー
LOW	スタイルの改善、小さなドキュメントの不足、任意の詳細	書式の不統一、軽微な表現上の問題

フェーズ 5：分析レポートの生成

出力形式：

## Architecture Analysis Report

### Analysis Summary

| Attribute | Value |
|-----------|-------|
| **Mode** | [Full/System/Feature/ADRs/Views] |
| **Scope** | [Description of what was analyzed] |
| **Files Analyzed** | [List of files] |
| **Analysis Date** | [Current date] |

### Findings

| ID | Pass | Severity | Location | Summary | Recommendation |
|----|------|----------|----------|---------|----------------|
| A1 | ADR Quality | MEDIUM | ADR-003 | Missing negative consequences | Add trade-offs section |
| B1 | Inter-ADR | HIGH | ADR-002, ADR-005 | Conflicting database choices | Resolve PostgreSQL vs MongoDB conflict |
| C1 | ADR->AD Drift | HIGH | ADR-005 | Caching decision not in Information View | Update AD.md 3.3 |
| D1 | AD->ADR Drift | HIGH | AD.md:3.2 | Redis component has no ADR | Create ADR for cache choice |
| E1 | AD Consistency | MEDIUM | AD.md:3.2/3.6 | Component naming mismatch | Standardize "AuthService" naming |
| F1 | Staleness | LOW | AD.md:3.1 | [SYSTEM_NAME] placeholder | Fill in system name |
| G1 | Feature Align | HIGH | specs/auth/adr.md | VIOLATION flag unresolved | Document override justification |

### Coverage Metrics

| Metric | System | Feature: auth | Feature: payments |
|--------|--------|---------------|-------------------|
| ADR Count | 13 | 3 | 2 |
| AD Views Complete | 5/7 | 3/5 | 3/5 |
| ADR->AD Coverage | 85% | 100% | 67% |
| AD->ADR Coverage | 92% | 100% | 100% |
| Quality Score | 78% | 85% | 72% |

### Constitution Alignment

| Status | Count | Details |
|--------|-------|---------|
| Compliant | [N] | ADRs following MUST principles |
| Violations | [N] | ADRs violating MUST principles (CRITICAL) |
| Deviations | [N] | Justified SHOULD principle deviations |

### Issue Distribution

| Severity | Count |
|----------|-------|
| CRITICAL | [N] |
| HIGH | [N] |
| MEDIUM | [N] |
| LOW | [N] |

### Next Actions

Based on findings, recommended actions:

**If CRITICAL issues exist:**
- **Immediate**: Resolve constitution violations before proceeding
- Command: `/architect-clarify` to address ADR compliance

**If HIGH ADR quality issues:**
- **Refine**: Address missing alternatives and consequences
- Command: `/architect-clarify` to improve ADR quality

**If ADR->AD drift detected:**
- **Sync AD**: Update AD.md to reflect ADR decisions
- Command: `/architect-implement` to regenerate views

**If AD->ADR drift detected:**
- **Document**: Create missing ADRs for undocumented decisions
- Command: `/architect-specify` or `/architect-init` to add ADRs

**If feature alignment issues:**
- **Align**: Resolve feature-system boundary violations
- Command: Run `/architect-specify` or `/architect-init` to create missing ADRs

フェーズ 6：修正案の提示

レポートを提示した後、次のように尋ねます：

「上位 [N] 件の問題に対する具体的な修正手順を提案しましょうか？各指摘事項について詳しいガイダンスを提示できますが、変更を自動的に行うことはありません。」

主なルール

分析の完全性

• ファイルを変更しないでください — 読み取り専用の分析です
• 存在しない内容を捏造しないでください — 欠落は正確に報告します
• 憲章への違反を優先してください — これらは常に CRITICAL です
• 証拠に基づいて指摘してください — 該当する場所と内容を明記します

整合性の基準

• すべてを相互参照してください — 双方向に検証します（ADR と AD）
• すべてのレベルを確認してください — システムアーキテクチャと機能アーキテクチャの整合性が必要です
• 用語を検証してください — 同じ概念には同じ名称を使用します
• 図を検証してください — Mermaid の構文が有効であることを確認します

レポートの基準

• 指摘事項は 50 件までにしてください — 超過分は要約にまとめます
• 場所を記載してください — 必ずファイル名と行番号、またはセクションを明記します
• 実行可能な推奨事項を提示してください — 各指摘事項に修正案を示します
• カバレッジ指標を算出してください — 完全性を定量化します

次のステップ

問題が見つかった場合：

• /architect-clarify を実行して ADR を改善します（品質の問題、結果／代替案の欠落、憲章への違反）。
• ADR と AD の乖離が検出された場合は、/architect-implement を実行して AD.md を再生成します。

ADR の欠落や機能境界の問題については、状況に応じて /architect-specify または /architect-init を使用します。

検証

このスキルの具体的な出力：

• アーキテクチャ分析レポート（構造化された Markdown 形式）。以下を含みます。
  • 分析概要（モード、対象範囲、分析したファイル、分析日）
  • ID、合否、重大度、場所、概要、推奨事項を含む指摘事項の表
  • カバレッジ指標（ADR 数、AD のビューの完成度、ADR→AD のカバレッジ、AD→ADR のカバレッジ、品質スコア）
  • 憲章との整合性の概要（準拠、違反、逸脱）
  • 重大度別の問題の分布（CRITICAL、HIGH、MEDIUM、LOW）
  • 指摘事項の種類に応じた次のアクション
• Mermaid 構文の検証を、AD と図を含むすべての成果物に対して実行します（共有リンター、Mermaid 検出パス）。壊れたブロックはすべて、重大度、場所、推奨パッチとともに報告されます。
• ファイルは変更されません — 分析は完全に読み取り専用です。
• レポートの提示後、ユーザーの承認を得たうえで修正のガイダンスを提供します。