architect-clarify

architect-clarify

このスキルでできること

既存のADRで仕様が不明確な箇所を特定し、的を絞った確認質問を通じて精緻化します。ADRが完全で一貫性があり、アーキテクチャ生成に対応できる状態であることを確認します。

ADRの品質を保証するアーキテクチャレビュアーとして、次のことを行います。

• MADR 標準に照らして、ADRの完全性を検証する
• 結果または代替案の不足を特定する
• ADR間、または憲章との矛盾を検出する
• 的を絞った確認を通じて、決定内容を精緻化する

使用するタイミング

次の場合にこのスキルを使用します。

• /architect-init の後：アーキテクチャ生成の前に、初期ADRを精緻化する
• ADRレビュー：主要なマイルストーンの前にADRを検証する
• 新しいチームメンバー：初めて見る人にもADRが理解できることを確認する
• 矛盾の解消：特定された不整合を解消する

次の場合、このスキルは使用しないでください。

• ADRが存在しない場合：まず /architect-init を使用してADRを作成します
• ブラウンフィールドプロジェクトの場合：/architect-init を使用して、コードからADRをリバースエンジニアリングします

プロセス

ユーザー入力

$ARGUMENTS

空でない場合は、先に進む前にユーザー入力を必ず考慮してください。

ユーザー入力の例：

• "データアーキテクチャの決定に注目してください。データベースの選択を再検討しています"
• "コンプライアンスレビューに向けて、セキュリティに関するADRを詳しくする必要があります"
• "ADR-003 の結果が不完全に思えます"
• 入力が空の場合：すべてのADRの完全性をレビューします

目標

既存のADRで仕様が不明確な箇所を特定し、的を絞った確認質問を通じて精緻化します。ADRが完全で一貫性があり、アーキテクチャ生成に対応できる状態であることを確認します。

ADR品質チェックリスト

各ADRには、次の項目を含める必要があります。

• 問題または機会を説明する明確なコンテキスト
• 明示的な決定事項
• 肯定的な結果と否定的な結果
• 文書化された一般的な代替案（「却下した理由」ではなく、中立的なトレードオフ）
• 軽減策とともに特定されたリスク
• 正確なステータス（Proposed/Accepted/Deprecated/Superseded/Discovered）
• 他のADRとの矛盾がない
• 憲章の原則との整合性
• リバースエンジニアリングされたADRにおいて、却下理由を捏造していない

概要

1. 現在の状態を読み込む：{REPO_ROOT}/.adlc/drafts/adr/（個別ファイル形式）および {REPO_ROOT}/docs/adlc/memory/constitution.md（従来の {REPO_ROOT}/.adlc/memory/constitution.md をフォールバックとして使用。両方を読み込み）からADRを解析します

重要 — パスの解決：

• セットアップスクリプトが REPO_ROOT を出力します。これを使用して正しいパスを特定してください
• REPO_ROOT は、現在のディレクトリから上位へ検索して .adlc ディレクトリを見つけます
• .adlc/drafts/adr.md のような相対パスは絶対に使用しないでください。常に {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md を使用します
• セットアップスクリプトは、adr/ ディレクトリから個別のADRファイルを読み込みます
• サブプロジェクトのディレクトリなど、サブディレクトリから実行する場合は、.adlc が親ディレクトリに存在することがあります

2. ADRを分析する：各ADRを品質チェックリストに照らして確認します
3. 不足箇所を特定する：確認が必要な領域を列挙します
4. 対話的に精緻化する：不足を埋めるための的を絞った質問をします
5. ADRを更新する：精緻化したADRをファイルに書き戻します

実行手順

フェーズ 1：コンテキストの読み込み

目的：現在のADRの状態を把握します

1. 前提条件スクリプトを実行する：

   • リポジトリのルートから scripts/bash/setup-architect.sh を実行します
   • JSONを解析して、メモリファイルへのパスを取得します
   • ファイルが存在しない場合は、適切にエラーを処理します

2. ADRファイルを読み込む：

   • ADR一覧として {REPO_ROOT}/.adlc/drafts/adr/adr.md を読み込みます
   • 個別のADRを {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md から読み込みます
   • ADRの総数を数え、ステータスの内訳を特定します

3. 憲章を読み込む：

   • {REPO_ROOT}/docs/adlc/memory/constitution.md（従来の {REPO_ROOT}/.adlc/memory/constitution.md をフォールバックとして使用）が存在する場合は読み込みます
   • 整合性確認のために原則を抽出します
   • ガバナンス上の制約を確認します

4. ユーザーの関心事項：

   • ユーザーが特定のADRまたは領域を指定した場合は、対象を絞ります
   • それ以外の場合は、すべてのADRをレビューします

Step 0: 軽量ドラフト形式の検出

レビュー対象のドラフトが軽量ドラフトテンプレートを使用しているか確認します（フロントマターに type、evidence、source、revisit-when フィールドがあり、本文に正式なテンプレートの全セクションではなく ## Rejected Alternatives／## Reason セクションがある場合）。

軽量形式の場合：

1. ドラフトに記録されたフィールド（Context、Decision、Rejected Alternatives、Reason）を読み取ります
2. 正式な完全版テンプレートに変換します：
   • ADR：Decision Drivers、Considered Options、Pros/Cons、Constitution Alignment、Related ADRs を含む完全版 MADR 形式
   • PDR：Market Forces、Consequences、Alternatives Considered、Links を含む完全版 PDR 形式
   • ChDR：Issue Links、Commits、Consequences、Evidence を含む完全版 ChDR 形式
   • CDR：Context Type、Target Module、Descriptor、Evidence を含む完全版 CDR 形式
   • EVAL：Error Analysis、Pass/Fail Examples、Implementation Notes を含む完全版評価形式
3. セッションのコンテキストから情報を補足します（軽量ドラフトで省略されている可能性のある詳細を追加します）
4. 補足したドラフトをレビュー用に提示します

すでに完全版の形式であれば、通常のレビューに進みます。

Phase 2: ADR 分析

目的：各 ADR の品質上の不足を特定します

確認する品質の観点

1. コンテキストの網羅性：

   • 問題が明確に記述されていますか？
   • 要因／判断基準が記録されていますか？
   • 決定の範囲は明確ですか？

2. 決定の明確さ：

   • 決定は実行可能ですか？
   • 実装への影響は明確ですか？
   • この決定を検証／テストできますか？

3. 結果の網羅性：

   • プラスの成果が記録されていますか？
   • マイナスのトレードオフが認識されていますか？
   • リスクとその緩和策が特定されていますか？

4. 代替案の記録：

   • 少なくとも 2 つの代替案が記載されていますか？
   • 各案を却下した理由は明確ですか？
   • 妥当な選択肢が検討されていますか？

5. ADR 間の一貫性：

   • 決定が他の ADR と矛盾していませんか？
   • ADR 間の依存関係が記録されていますか？
   • 用語は一貫していますか？

6. 憲章との整合性：

   • 決定は MUST 原則に準拠していますか？
   • SHOULD 原則に対応していますか？
   • 違反がある場合、明示的に正当化されていますか？

Phase 2.5: リスクと不足の分析（横断的）

目的：すべてのビューにわたって記録されていない運用上の不足、技術的負債、SPOF、セキュリティ上の懸念を特定します

分析の観点：

観点	確認するビュー	確認事項
運用上の不足	運用（3.7）、デプロイ（3.6）	監視の欠如、オンコール体制の未定義、ランブックの不備、ロールバックの不明確さ
技術的負債	開発（3.5）、情報（3.3）	非推奨の依存関係、テストの不在、レガシーコード、スキーマの負債
単一障害点	デプロイ（3.6）、並行処理（3.4）	DB インスタンスが 1 つのみ、冗長性の欠如、クリティカルパスのボトルネック
セキュリティ上の懸念	すべてのビュー	暗号化されていないデータ、認証の不在、露出したシークレット、監査証跡の欠如

不足の特定プロセス：

1. 各ビューを確認：ビューの有無を確認し、重要なセクションの欠落を特定して、[TODO]／[TBD] の箇所にフラグを付けます
2. ビュー間の分析：「高可用性」と記載されているのに単一インスタンスが示されている、といった矛盾を見つけます
3. リスクの重大度：CRITICAL（停止／侵害／損失）、HIGH（運用負荷）、MEDIUM（負債）、LOW（ドキュメント）

不足 ID の形式：セクションベース（例：3.6.1 = デプロイビュー、不足 #1）

フェーズ 2.6：憲章との相互参照

目的：ADR に重複や準拠上の問題がないか、憲章と照合します

分析：

1. 重複チェック：ADR が憲章の原則を再掲していませんか？すでに決定事項として定められていませんか？
2. 準拠チェック：決定が MUST の原則に違反していませんか？正当な理由なく SHOULD を無視していませんか？
3. 例外の分類：意図的な逸脱ですか？十分に正当化されていますか？

憲章との相互参照テーブル：

問題の種類	ADR	憲章の原則	必要な対応
重複	ADR-002	§DataStorage で PostgreSQL を義務付け	削除するか、参照に変更
違反	ADR-003	§Security で JWT を必須とする	例外の正当化を追加するか、変更
不明確	ADR-004	キャッシュについて記載なし	関係を明確化

フェーズ 3：ギャップの特定

目的：明確化が必要な項目に優先順位を付けます

ギャップレポートを作成します：

## ADR Clarification Report

### Summary
- Total ADRs: [N]
- Complete: [N]
- Needs Clarification: [N]

### Gaps by ADR

| ADR | Title | Gap Type | Severity | Priority |
|-----|-------|----------|----------|----------|
| ADR-001 | [Title] | Missing alternatives | HIGH | 1 |
| ADR-002 | [Title] | Incomplete consequences | MEDIUM | 2 |

### Cross-ADR Issues

| Issue | ADRs Affected | Description |
|-------|---------------|-------------|
| [Conflict] | ADR-001, ADR-003 | [Description of conflict] |

ギャップの優先順位付け

• CRITICAL：憲章への違反、決定事項の記述がない
• HIGH：代替案の記載がない、影響の記載がない
• MEDIUM：リスクが不完全、背景が不明確
• LOW：軽微な表現の改善、任意の詳細

フェーズ 4：対話型の改善

目的：対象を絞った質問でギャップを埋めます

質問形式

明確化が必要な各ギャップについて：

## Clarification [N]: [ADR-XXX] - [Gap Type]

**Current State**: 
[Quote current ADR content]

**Gap Identified**: 
[Explain what's missing or unclear]

**Question**:
[Specific question to address the gap]

**Suggested Options** (if applicable):

| Option | Description |
|--------|-------------|
| A | [Option A] |
| B | [Option B] |
| C | [Custom response] |

Reply with your choice or provide additional context.

憲章との相互参照に関する質問

憲章に関する問題が検出された場合：

重複の場合：

## Clarification [N]: Constitution Duplication Detected

**Question**: How should this duplicate ADR be handled?

**ADR**: ADR-XXX - [Title]
**Constitution Principle**: §[Section] - [Principle Name]
**Issue**: This ADR documents a decision already mandated by constitution

**Options**:
| Option | Action | Result |
|--------|--------|--------|
| A | Remove ADR | Decision covered by constitution only |
| B | Convert to Reference | Keep ADR as "See Constitution §X" |
| C | Add Context | Keep ADR with "Aligns with Constitution §X" |
| D | Extend | Keep ADR as "Extends Constitution §X" |

Reply with your choice (A/B/C/D).

違反の場合（オプション A が第一候補 — 憲章を改訂）：

## Clarification [N]: Constitution Violation Detected ⭐

**Question**: How should this constitutional violation be resolved?

**ADR**: ADR-XXX - [Title]
**Decision**: [What the ADR decides]
**Constitution Principle**: §[Section] - [Principle]
**Conflict**: [How they conflict]

**The constitution should evolve with the project's needs.**

**⭐ RECOMMENDED: A. Amend Constitution**
Update constitution §[Section] to accommodate this decision. This establishes a new principle for future decisions.

**Alternative Options**:
B. Override in ADR - Document justification for deviation
C. Revise ADR - Change decision to comply with constitution
D. Remove ADR - Delete and follow existing constitution

**Consider Amendment If**:
- [ ] This decision will be used again in the future
- [ ] Team's approach has evolved since constitution was written
- [ ] Existing principle is too restrictive for current needs

**Amendment Text**: [If choosing A, provide the specific constitutional amendment]

Reply with: "A [amendment text]" or "B/C/D [reasoning]"

明確化のルール

• 一度に 1 件の明確化を提示します
• 深刻度の高いものを優先し、CRITICAL／HIGH のギャップから対応します
• 憲章違反の場合は、オプション A（改訂）を第一候補とします
• 1 セッションあたり最大 5 件の明確化に制限します（アーキテクチャが存在する場合は 10 件に増加）
• 重要度の低い明確化は、ユーザーがスキップできるようにします
• 回答のたびに変更内容を要約します
• ユーザーは「done」と入力して、明確化を途中で終了できます

フェーズ 5：ADR の更新

目的：改善した ADR をファイルに書き戻します

1. 明確化内容の適用：

   • 新しい内容で ADR のセクションを更新します
   • 構成と書式を維持します
   • 「Last Updated」のタイムスタンプを更新します

2. 競合の解決：

   • ADR 間の競合が見つかった場合は、解決策を提案します
   • どちらの ADR を優先するかという判断を記録します
   • 関連する ADR 間に相互参照を追加します

3. インデックスの更新：

   • タイトルが変更された場合は、ADR インデックステーブルを更新します
   • 該当する場合はステータスを更新します

4. ファイルの書き込み：

   • 個別の {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md ファイルにアトミックに書き込みます
   • 変更されていない ADR はそのまま保持します
   • セットアップスクリプトが、更新後に adr.md と adr.md インデックスを自動的に再生成します

フェーズ 5.5：ADR の承認 ⭐

目的：アーキテクチャ生成の前に、ADR の承認についてユーザーの確認を得ます

implement はステータスが「Accepted」の ADR のみを処理するため、このステップは重要です。ステータスが「Discovered」または「Proposed」の ADR はスキップされます。

承認リクエスト

## ADR Approval ⭐

**Total ADRs**: [N]
**Status Distribution**:
- Accepted: [N]
- Proposed: [N]
- Discovered: [N]

**⚠️ Important**: Only "Accepted" ADRs will be processed by `/architect-implement`

### Options

| Option | Action |
|--------|--------|
| A | Accept All - Change Proposed/Discovered → Accepted |
| B | Review Specific - Select individual ADRs to accept |
| C | Defer - Keep current status, decide later |

**Note**: You can also run `/architect-clarify` again later to approve additional ADRs.

Reply with A, B, or C (or "done" to skip).

一括承認（オプション A）

ユーザーがオプション A を選択した場合：

## Confirm Bulk Approval

Change [N] ADRs from Proposed/Discovered → Accepted?

| ADR | Current Status | New Status |
|-----|----------------|-------------|
| ADR-001 | Proposed | Accepted |
| ADR-002 | Discovered | Accepted |

Reply with "yes" to confirm or "no" to cancel.

個別承認（オプション B）

ユーザーがオプション B を選択した場合、ADR を 1 件ずつ提示します：

## ADR Approval: ADR-XXX

**Title**: [Title]
**Current Status**: [Proposed/Discovered]
**Context**: [Brief summary]

**Options**:
| Option | Action |
|--------|--------|
| A | Accept - Change to "Accepted" |
| B | Keep - Keep current status |
| C | Skip - Move to next ADR |

Reply with A, B, or C for ADR-XXX.

承認後

承認後（またはユーザーが C を選択して保留した場合）：

## ADRs Approved

**Status Changes Applied**:
- ADR-001: Proposed → Accepted
- ADR-002: Discovered → Accepted
- ADR-007: Kept as Proposed

**Ready for Implementation**:
- Accepted ADRs: [N]
- Pending Approval: [N]

Run `/architect-implement` to generate AD.md from accepted ADRs.

承認後の状態更新

承認後、ワークフロー状態ファイルを必ず書き込んでください。ディレクトリが存在しない場合は作成してから、{REPO_ROOT}/.adlc/architect/state.json に書き込みます：

mkdir -p {REPO_ROOT}/.adlc/architect

以下の JSON コンテンツをファイルに書き込みます（[N] を承認済み ADR の実際の件数に置き換え、タイムスタンプには現在の時刻を指定します）：

{
  "workflow": {
    "clarify_completed": true,
    "clarify_completed_at": "2024-01-20T10:30:00Z",
    "adrs_approved_count": [N],
    "implement_started": false,
    "implement_started_at": null
  }
}

重要：/architect-implement を実行するには、このワークフロー状態ファイルが必須です。 implement コマンドは、事前検証時にこの状態を確認します。このステップを省略すると、implement コマンドは検証エラーで停止します。

主なルール

非破壊的な改善

• ユーザーの明示的な承認なしに、既存の ADR を削除しないでください
• 文言を更新する際は、元の意図を維持してください
• 結果と代替案は置き換えずに追加してください
• 更新したタイムスタンプで変更を明記してください

焦点を絞った確認

• 一度に1つ質問してください
• 質問は具体的で回答可能なものにしてください
• 可能であれば選択肢を提案してください
• ユーザーの時間を尊重し、確認事項は5つまでにしてください

憲章の権限

• 憲章への違反には必ずフラグを立ててください
• 明示的な正当化がない限り、ADR で MUST 原則を覆すことはできません
• 対立が体系的なものである場合は、憲章の更新を提案してください

量より質

• 実装に影響する重要な不足点に焦点を当ててください
• ユーザーから求められない限り、見た目だけの改善は省略してください
• 重大な不足点が残っている場合は、軽微な問題は後回しにしてください

完了レポート

確認が終了した後（すべての不足点に対処した場合、またはユーザーが「done」と伝えた場合）：

## ADR Clarification Complete

**Changes Made**:
- ADR-001: Updated consequences section
- ADR-002: Added Common Alternatives (neutral trade-offs)
- ADR-003: Resolved conflict with ADR-001
- Constitution: Amended §DataStorage to allow NoSQL for document flexibility

**Risks & Gaps Status**:
- Critical gaps identified: [N] → [N resolved]
- High priority gaps: [N] → [N resolved]
- Cross-view inconsistencies: [N] → [N resolved]
- Integration with AD sections: [N updates]

**Remaining Gaps** (deferred):
- 3.6.2: Minor operational documentation (LOW)

**Cross-ADR Consistency**: ✅ Verified

**Constitution Alignment**:
- Duplicates resolved: [N]
- Violations addressed: [N]
- Constitution amended: [N] (if applicable)
- References added: [N]

**Recommended Next Steps**:
1. Review updated ADRs in `{REPO_ROOT}/.adlc/drafts/adr/adr.md`
2. Run `/architect-implement` to generate AD.md
3. Or run `/architect-specify` to create new ADRs for additional decisions

ワークフローのステータス

⚠️ 必須：ADR を承認するには、/architect-implement の前に /architect-clarify を必ず実行してください。

ステータスのワークフロー：

• init → 「Discovered」（ブラウンフィールド）
• specify → 「Proposed」（グリーンフィールド）
• clarify → 承認を求める → 「Accepted」 ⭐
• implement → 「Accepted」のみを読み込み、「Discovered」／「Proposed」はスキップします

注：「Validated」のような中間ステータスを作り出さないでください。ユーザーが承認すると、ADR は「Discovered」／「Proposed」から直接「Accepted」に移行します。

コンテキスト

$ARGUMENTS

次のステップ

clarify の完了後、/architect-implement を実行して、アーキテクチャ記述（AD.md）を生成してください。

アーキテクチャの生成に含まれるのは、ステータスがAcceptedの ADR のみです。必要に応じて、このスキルを再実行し、先に追加の ADR を承認してください。

検証

このスキルの具体的な成果物：

• 明確化した内容で更新された {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md の ADR ファイル
• 更新された {REPO_ROOT}/.adlc/drafts/adr/adr.md の ADR インデックス
• 修正が承認された場合は、更新された憲章
• clarify_completed: true を含む {REPO_ROOT}/.adlc/architect/state.json に記録されたワークフローの状態
• 少なくとも1つの ADR ステータスがAcceptedに変更されていること、または明示的な保留が記録されていること
• ADR 間の競合が解決または文書化されていること
• 重大度が Critical／High の不足点への対応状況を示すギャップレポート