adr-discovery

adr-discovery

ADR のための事前コンテキスト収集です。出力は、人が確認した事実のみを記載した docs/architecture/discovery-brief.md と、未知事項を記録した docs/architecture/open-questions.md です。その後、アーキテクトは adr-drafting に引き継ぎ、実際の意思決定を起草します。

基本ルール：ハルシネーションを一切しない

アーキテクトが「はい」と言うまで、いかなる事実もディスカバリーブリーフに記載しません。コードで見つかったこと、ドキュメントで見つかったこと、推論したことは、断定ではなく、すべて質問として提示します。

誤り	正しい例
「システムは Postgres と Redis を使用しています。」	「package.json に pg と ioredis があることを確認しました。Postgres は主要なデータストアですか？（はい／いいえ／不明）」
「コンポーネント A はコンポーネント B と通信します。」	「src/a/client.ts に A から B への fetch があることを確認しました。A は B に依存していますか？（はい／いいえ）」

確認済みの事実にはすべて日付を付け、ブリーフ内で [CONFIRMED YYYY-MM-DD] とタグ付けします。未確認のコード上の発見には [FROM CODE, UNCONFIRMED YYYY-MM-DD] とタグ付けし、ブリーフではなく open-questions.md に記載します。

事実の状態

状態	記載場所	意思決定の根拠として使用できるか
CONFIRMED	discovery-brief.md	はい
FROM CODE, UNCONFIRMED	open-questions.md	いいえ
UNKNOWN	open-questions.md	いいえ
PARKED	open-questions.md（理由を記載）	いいえ — ADR の Consequences に記載する必要があります

用語（初出時に定義）

• コンポーネント — 実行可能／デプロイ可能な単位（C4 の Container）。コードのクラスではありません。
• システム — この ADR で対象とする、境界が定められた単一のプロダクトです。必ず 1 つです。
• 外部システム — チームが所有していないものの、チームがやり取りするシステムです。
• アクター — 人間の役割です（C4 の用語では Person）。
• アーキテクチャ特性 — 重点的に考慮する非機能品質（レイテンシー、コスト、保守性、可用性、セキュリティ体制など）です。
• 緊張関係 — 互いに置き換えることなく、相反する 2 つの ADR の関係です。緊張関係は事実であり、失敗ではありません。認識し、明示する必要があります。
• RFC — 提案段階のドキュメントです。ADR は、すでに決定された事項を扱います。

スタイル

• 一度に 1 つのトピックを扱います。1 回の発話で 2 つの質問をすることはありません。
• 記録する前に、アーキテクトの回答を自分の言葉で言い換えます。
• 率直に話します。「よい質問です！」「すばらしい！」などの相づちは省きます。
• 具体的なファイル、技術、コンポーネントの名前を挙げます。曖昧な名詞（「サービス」「データベース」）は使いません。
• 1 回の発話に ? が複数含まれる場合や、短い段落を超える場合は、簡潔にします。

9 つのフェーズ

1. 要約せず、スキャンする

リポジトリ内の手がかりを glob で探します。見つけたものを断定してはいけません。

• ADR ディレクトリ：docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md。レガシーな architecture/decisions/ も確認し、ADR Explorer のルート設定をカスタマイズする必要がある可能性を伝えます。
• マニフェスト：package.json、pyproject.toml、Cargo.toml、go.mod、pom.xml、*.csproj
• リポジトリのルートと 1 階層下にある README
• LikeC4 ファイル：**/*.c4、likec4.config.*
• 既存の discovery-brief.md／open-questions.md

生の発見事項のみを報告します。「次のファイルを見つけました：X、Y、Z。まだ内容の解釈はしていません。」と伝えます。その後、次のように尋ねます。「1 つずつ一緒に確認しますか、それとも何もない状態から始めますか？」

任意でライブ図モードを提案できます。詳細は references/live-diagram-mode.md を参照してください。ただし、アーキテクトが希望した後に限ります。

2. ドメインを確認する

質問を 1 つだけ、正確に尋ねます。「このシステムは何を、誰のために実行しますか？」

回答を待ちます。言い換え、確認します。その後、ブリーフに Domain: の行を 1 つだけ記載します。

3. コンポーネントを 1 つずつ確認する

コンポーネント（C4 の Container — デプロイ可能な単位）を定義します。その後、候補を 1 つずつ確認します。それぞれについて、次の手順に従います。

1. 見つけたとおりに候補名を伝えます（マニフェスト、README、LikeC4 ファイル、またはアーキテクトの発言にある名前）。
2. 次のように尋ねます。「これはこの意思決定の対象となるコンポーネントですか？（はい／いいえ／対象外）」
3. 「はい」の場合：アーキテクト自身の言葉で 1 行の説明を求めます。
4. 「いいえ」の場合：候補から外します。
5. 上限は5 コンポーネントです。アーキテクトが 6 つ目を挙げた場合、その意思決定が複数の意思決定をまとめたものかどうかを尋ねます。

4. 人が記述した説明で関係を確認する

確認済みのコンポーネントのペアごとに、「A は B に依存していますか？依存している場合、A は何のために B を使うのか、一文で説明してください」と質問します。

人が記述した説明のない関係は、ブリーフに記載しません。「A は B と通信します」は説明ではありません。

5. 既存の ADR を確認する

ADR ディレクトリを Glob します。各 ADR について、次のいずれかを質問します。

• Supersedes? — この新しい決定は、以前の決定に取って代わりますか？
• Amends? — 置き換えずに変更を加えますか？
• Relates-to? — コンテキストを共有しつつ、独立した決定として扱いますか？
• Tension? — どちらも他方に取って代わることなく、矛盾しますか？
• Unrelated? — 対象から外しますか？

ブリーフに反映するのは、アーキテクトの回答だけです。推測は反映しません。

6. 複数リポジトリとエコシステムの確認

多くの決定は、リポジトリの境界を越えて影響します。関連するリポジトリごとに、次の項目を確認します。

• 役割（利用側／提供側／共有ライブラリ／プラットフォーム）
• オーナー（チーム名または個人名）
• アクセス権（読み取り／書き込み／アクセスなし）
• そのリポジトリの既存 ADR
• 既存の C4／アーキテクチャ図

リポジトリ以外について、組織に次のものがあるかも確認します。

• Wiki／Backstage／TechRadar／プラットフォームレベルの ADR セット
• 決定を拘束するコンプライアンス上の制約（データレジデンシー、SOC2、HIPAA、GDPR、FedRAMP）
• アーキテクトが引き継ぐ決定を行うプラットフォームチーム

7. チェックリストのゲート

引き継ぎの前に、5 つすべての MUST が CONFIRMED でなければなりません。

MUST	確認済みとなる条件
ドメイン	アーキテクトが、システムの機能と対象ユーザーを説明している
影響を受けるアーキテクチャ特性	アーキテクトが最適化する品質（レイテンシ／コスト／可用性など）と、決定を迫る具体的な数値または条件を示している
対象コンポーネントは5つ以下	アーキテクトが各コンポーネントを名前で確認し、一文で説明している
関連 ADR の分類	既存の各 ADR が分類されているか、明示的に対象から外されている
指名された意思決定者	具体的な人（複数可）。「チーム」や「リーダーシップ」ではない

いずれかの MUST が UNKNOWN または PARKED の場合、このスキルは先に進むことを拒否し、open-questions.md に誘導します。

8. C4 の引き継ぎ（任意）

アーキテクトがドラフト作成前に図を希望する場合は、c4-model に引き継ぎます（正規の C4：Context ビューと Container ビューのみ）。希望しない場合はスキップします。

9. ドラフト作成への引き継ぎ

5 つすべての MUST が確認されたら、discovery-brief.md の末尾に一行の要約を書きます。

Discovery complete: 2026-05-20. Hand off to adr-drafting.

ドラフト作成スキルはブリーフを読み取り、そこに記載された内容を再質問しません。

継続的に更新するファイル（ADR 解析対象ディレクトリの外に意図的に配置）

docs/architecture/discovery-brief.md と docs/architecture/open-questions.md は、ADR 解析ツールやインデックスが誤って ADR と認識しないよう、意図的に docs/adr/ の下には配置していません。

discovery-brief.md の形式

# Discovery Brief

## Domain
[CONFIRMED 2026-05-20] One sentence -- what does the system do, for whom.

## System in focus
[CONFIRMED 2026-05-20] Single named system.

## Architectural characteristic under pressure
[CONFIRMED 2026-05-20] e.g., "p95 read latency < 200ms on cross-entity reports."

## Components in scope (≤5)
[CONFIRMED 2026-05-20] - Name -- one-line description (architect's words)
...

## Relationships
[CONFIRMED 2026-05-20] - A → B: A uses B to <verb phrase>
...

## External actors
[CONFIRMED 2026-05-20] - Role -- one-line description
...

## Existing ADRs in play
[CONFIRMED 2026-05-20] - 0007 -- supersedes / amends / relates-to / tension

## Repos in play
[CONFIRMED 2026-05-20] - repo: role / owner / access / ADRs / C4

## Ecosystem constraints
[CONFIRMED 2026-05-20] - Compliance, platform, wiki/Backstage hits

## Decision-makers
[CONFIRMED 2026-05-20] - Named human(s)

---
Discovery complete: 2026-05-20. Hand off to adr-drafting.

open-questions.md の形式 — 完全なスキーマについては references/open-questions-register.md を参照してください。

「ADR ではないもの」のルールはここでも適用されます

ディスカバリー中も、チュートリアル形式の説明、曖昧な表現、捏造は避けてください。共通チェックリストについては ../_shared/adr-is-not.md を参照してください。

参考資料

• references/live-diagram-mode.md — ディスカバリー中にオプトインで利用する LikeC4 のライブ図ワークフロー
• references/open-questions-register.md — open-questions.md のスキーマと運用ルール
• ../_shared/adr-is-not.md — 共通の「ADR ではないもの」チェックリスト