doc-diagnostic

doc-diagnostic

診断と規範を定めるスキルです。次の3つを担当します。

1. 代替案カタログ -- ユーザーの思いつきを ADR にすべきでない場合に、何を書くべきかを示します。完全なカタログ：references/alternatives-catalog.md。
2. ADR の規範 -- テンプレート、ステータスのライフサイクル、番号付け、必須フィールド、不変性のルールを定めます。（このファイルに記載。）
3. 監査手順 -- /doc-audit で使用する、フォルダー単位の KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR 分類です。完全な手順：references/audit-procedure.md。

ドキュメントのリクエストの振り分け、テンプレートの選択、ステータスの命名、または既存のドキュメント一式の監査に、このスキルを使用します。ドラフト作成／調査／批評の各スキルは、ここで定義する規範を参照します。独自に再定義することはありません。

4つの質問による診断（ドキュメントを勧める前に実施）

標準となる4つの質問によるチェックです。doc-expert エージェントと、このプラグイン内のほかのすべてのスキルは、このセクションを参照し、内容を繰り返しません。ドキュメントの作成に同意する前に、4つすべてを確認してください。答えが1つでも「いいえ」または「不明確」であれば、まだドキュメントを作成すべきではありません。

1. 目的 -- このドキュメントが、システムの存在をすでに知っている読者のどのような疑問に答えるのかを、1文で示します。
2. 対象読者 -- 具体的な状況にいる、具体的な読者を示します。「将来の保守担当者」は対象読者ではありません。「P1 のインシデントに対応中の、午前3時のオンコールエンジニア」は対象読者です。
3. オーナー -- 内容の正確性を保つ責任を負う、名前の明らかな人を示します。オーナーがいなければ、数か月で内容が現状から乖離します。
4. 更新のトリガー -- ドキュメントの再確認または置き換えを促す、具体的な出来事を示します。トリガーがなければ、いずれ化石となります。

4つすべてに答えられる場合は、doc-expert エージェントの本文にある「これは ADR か？」の診断に進みます。

アーキテクチャ上重要な要件（ASR）-- 標準定義

ADR は、単一のアーキテクチャ上の決定と、その根拠を記録します。アーキテクチャ上の決定とは、「ソフトウェアおよび／またはハードウェアシステムのアーキテクチャと品質に測定可能な影響を与える」、アーキテクチャ上重要な要件（ASR）に対応するものです。変更がアーキテクチャ上重要でない場合、ADR は適切な手段ではありません。代替案カタログを使って振り分けてください。

アーキテクチャの枠を超えて -- より広義の「決定記録」

この形式は、製品、ビジネス、ポリシー、セキュリティプログラム、プロセスに関する決定にも一般化できます。つまり、正当化された撤回困難な選択について、作成者の代を超えて根拠を残す価値のあるあらゆる場面で使えます。慣例として、docs/adr/ を docs/decisions/ に変更し、ASR の基準を「そもそもこの決定を記録する価値があるか？」に緩和します。テンプレート、ライフサイクル、番号付け、不変性、Relationships ミラーのルールは変更されません。総合的な資料：github.com/joelparkerhenderson/architecture-decision-record。references/adr-template-catalog.md も参照してください。

代替案カタログ（ADR を作成しない場合）

診断で「ADR ではない」と判断した場合は、references/alternatives-catalog.md を使って振り分けてください。これは、よくあるあらゆる思いつきに適切なドキュメント形式を割り当て、ADR が不適切な理由を説明し、Diátaxis の4分類（チュートリアル／ハウツー／リファレンス／解説）を示します。ADR は Diátaxis の解説ではありません。ユーザーが「ADR と RFC と設計ドキュメントとランブックとハウツーのどれか」を検討している場合や、「X はどこに記録すればよいか？」と尋ねた場合は、このカタログを読み込んでください。

ADR の規範

テンプレートの選択

判断を正確に記録できる、最も簡潔なテンプレートを選びます。

テンプレート	使用する場面	使用しない場面
Nygard / MADR light	判断がシンプルで、代替案が明らかであり、3〜5個の項目（Context、Decision、Consequences）で十分な場合。	複数の基準で3つ以上の代替案を比較する必要がある場合。
MADR (full)	複数の選択肢を並べて分析する必要がある場合、判断の基準が重要な場合、Confirmation/Validation フィールドが必要な場合、追跡可能性が重要な場合。	判断が些細で、完全版 MADR では内容が水増しされる場合。
Y-statement	1文で記述する場合：「X という状況で Y に直面し、W を達成するために Z を決定し、V を受け入れる。」 簡潔なログ項目やエグゼクティブサマリーに適しています。	判断に構造化された項目が必要な場合。
arc42 / Tyree-Akerman / Business case	プロジェクトですでに採用されている場合。	新たに始める場合。ほとんどのチームには過剰に複雑です。

プロジェクトごとに一度選択し、明示的に移行する場合を除き、1つのログ内でテンプレートを混在させないでください。

標準的なステータスのライフサイクル

  proposed  ----accepted---->  accepted  ----changed---->  superseded
                                      |
                                      +--no-longer-applies-->  deprecated

Explorer 互換のステータス値は、小文字の proposed、accepted、deprecated、superseded です。status に rfc、rejected、backfilled、説明文などを設定しないでください。

• proposed -- RFC として機能する ADR を含め、検討中です（rfc-deadline を追加し、status: rfc は作成しないでください）。
• accepted -- 有効です。
• superseded -- 後続の ADR に置き換えられています。新しい ADR の supersedes リストが関連付けを作成します。
• deprecated -- もはや適用されませんが、置き換える新たな決定がない場合、または「なぜ採用しなかったか」を残すために却下された提案です。説明は本文に記載し、status には記載しないでください。

不変性と置き換え

基本原則は、**「ADR の既存情報を変更しない」**ことです。修正するか、置き換えてください。

• Accepted になった後、本文は追記のみとします。誤字の修正、superseded by の注記、「Amendments」見出しの下への日付入り項目の追加は可能です。
• 判断を変更する場合は、新しい ADR を作成し、supersedes に古い ADR を指定します。古い ADR に読者向け注記 superseded by: NNNN を追加してもかまいませんが、それ以外は変更しないでください。関連付けは新しい ADR の supersedes リストで作成します。本文中の superseded-by の説明文では作成されません。
• 日付入りのインライン修正を含む「生きたドキュメント」を好むチームは、ログの README.md にその方針をあらかじめ明記してください。

番号付け、命名、所有者

• 番号付け：ゼロ埋めした単調増加の番号（0001、0002、...）を使います。再利用しないでください。番号が識別子です。
• ファイル名：ゼロ埋めした ID ＋現在形の命令句を、小文字のハイフン区切りで記述し、.md を付けます（0007-use-postgres-for-primary-store.md）。
• 所有者：deciders を YAML 配列として指定します（説明責任を担う担当者）。必要に応じて consulted／informed も指定します（MADR の RACI）。「チーム」は所有者ではありません。
• 日付：ISO 8601 を使用します。初稿の作成時ではなく、承認時に日付を記録します。
• レビューの頻度：ADR に具体的なきっかけを記載します（「QPS が 10k を超えたら再検討」など）。「毎年再検討」とはしないでください。

必須フィールド

すべての ADR に、以下を含めます。

1. タイトル — NNNN. Decision (imperative verb phrase)。
2. YAML フロントマター — 必須。 最低限 title、status、date、deciders を含む --- ブロックです。関係性がある場合は supersedes／amends／relates-to を追加します。任意項目：tags、review-by、expires、confidence: high|medium|low、confidence-score、rfc-deadline（status: proposed が RFC として機能する場合）。gray-matter パーサーが読み取るのはフロントマターのみです。これがないと、そのノードは孤立します。
3. 本文の関係性ミラー — フロントマターに関係性がある場合は必須。 MADR 4.0.0 の ## More Information → ### Relationships に、リンク接頭辞の語彙（Supersedes、Superseded by、Amends、Amended by、Related to）を使います。本文をスキャンするパーサーが読み取るのはこのセクションのみです。2 つの箇所の内容を一致させる必要があります。
4. コンテキスト — アーキテクチャ上重要な制約や要因です。3 年後に読む人でも、なぜ今決める必要があったのかが分かるようにします。
5. 決定 — 現在形で、単独で意味が通じる選択です。
6. 決定の推進要因（MADR）、またはコンテキストに暗黙的に含めます（Nygard）。
7. 検討した代替案 — 同じ抽象度で現実的な案を挙げ、それぞれについて「採用しない理由」を 1 段落で説明します。実質的な代替案ではないものは省きます。
8. 結果 — 良い点：…のため、悪い点：…のために加え、後続作業も記載します。
9. 確認／検証（MADR full）— 準拠をどのように徹底するかを記載します。
10. 再評価の契機 — 新しい ADR でこの ADR を置き換えるべき具体的な条件です。

保存場所と見つけやすさ

• ADR は、適用対象のコードとともに、ソースリポジトリ内でソース管理下に置きます。
• 見つけやすい保存場所：docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md。いずれか 1 つを選び、ログの README.md に記載します。
• README.md に、すべての ADR とそのステータス、1 行の要約を記載したインデックスを用意します。インデックスはナビゲーション用であり、グラフではありません。インデックスハブのリンクはエッジのシグナルではありません。
• デフォルトでは MADR 4.0.0 ＋ フロントマター ＋ 本文の Relationships ミラーを使用します。 フロントマターの supersedes／amends／relates-to は gray-matter パーサーに使われ、本文の ### Relationships は本文をスキャンするパーサーに使われます。どちらか一方だけでは半分しか描画されません。プロジェクトですでに Nygard、Y-statement、arc42、Tyree-Akerman を使っている場合は、それに従います。MADR：adr.github.io/madr/、ソース：github.com/adr/madr。
• ### Relationships の外にある Related ADRs: のような本文行や、### Notes 内の Related docs: は、便宜上のナビゲーションであり、エッジではありません。
• フロントマターのリスト内での ID 形式： 4 桁のゼロ埋め文字列（"0008"）。エクスプローラーパーサーは /(\d+)/ で数字を抽出してゼロ埋めするため、8、"08"、"0008"、"ADR-0008" は同じものとして解決されます。ただし、ゼロ埋め文字列なら一貫した表示とソートが可能です。
• 可能であれば、コードから相互リンクします（// See docs/adr/0007-use-postgres-for-primary-store.md）。
• 関係性リンクを維持するためのガバナンスルールを明記します。Accepted ADR が不変の場合は、メタデータのみの関係性リスト編集と本文の Relationships への追加を許可するか、明示的な例外を必須にします。
• オフラインでの正準チェック：plugins/doc-master/scripts/validate_adrs.py。ファイルごとのチェック項目と CLI フラグの全一覧は plugins/doc-master/scripts/README.md を参照してください。/doc-audit 中または CI ゲートとして使用し、4 つの質問によるチェックの代わりにはしないでください。

正準ミラーの例

---
title: "Use Postgres for primary store"
status: accepted
date: 2026-05-20
deciders: [Jane Doe]
supersedes: ["0004"]
relates-to:
  - id: "0011"
    reason: "shares the tenancy model decided in 0011"
---

# 0017. Use Postgres for primary store

## More Information

### Relationships

- Supersedes [ADR-0004](0004-use-dynamodb-for-primary-store.md) -- replaced because Q3 reporting needs sub-200ms joins.
- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model decided in 0011.

2 つの箇所の内容を一致させる必要があります。### Notes 内にある余分な Related ADRs: 行、インデックスハブの項目、superseded-by の本文注記は、便宜上のナビゲーションであり、エッジではありません。

意思決定ログに関連するリポジトリレベルの要点

意思決定ログは、README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT（opensource.guide の4ファイル標準）に加え、GitHub の拡張プロファイル（SECURITY、SUPPORT、CODEOWNERS、FUNDING、CITATION、.github/ テンプレート）という、より広範なコミュニティヘルス関連ファイル群の一部です。doc-master はこれらを自動作成しません。引き続き、4つの質問による診断を適用してください。標準一式は repo-health スキルにあります。ユーザーがコミュニティヘルス関連ファイルを設定するとき、リポジトリのブートストラップ用ドキュメントを監査するとき、またはライセンス／行動規範／貢献ガイドを選ぶときに読み込んでください。

ADR の失敗パターン

11の標準的な失敗パターン（乖離、ADR と PRD の重複、複数の意思決定の一括化、時期尚早な ADR、テンプレートの頻繁な変更、合意のない AI による意思決定など）と、その兆候および対処法：references/failure-modes.md。監査時と adr-critique で読み込んでください。

フォルダーレベルの監査手順（/doc-audit で使用）

references/audit-procedure.md にある8段階の手順に従ってください。棚卸し → ADR 標準チェック → 4つの質問によるチェック → 乖離 → 重複 → 誤分類 → バックフィル候補の検出（リリース済み変更の証拠に対する ASR テスト） → KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR を含む番号付きアクションリスト。

BACKFILL-ADR は候補であり、ドラフトではありません。監査で候補を提示し、アーキテクトが adr-backfill を読み込むかどうかを決定します。証拠は独立した2か所に記載されている必要があります。reconstruction-confidence: low の場合は open-questions.md に誘導します。手順ファイルには、厳守すべき制約（Accepted ADR の本文を編集しない、一括で番号を振り直さない、Owners を自動生成しない、承認なしに削除しない）と承認後のフローが定められています。

水増しを防ぐルール

推奨するドキュメントはすべて、4つの診断質問（目的、対象読者、責任者、更新のきっかけ）に答えられる必要があります。いずれかに答えられない場合、そのドキュメントはまだ作成すべきではありません。これは ADR、RFC、ハウツー、リファレンス、解説、チュートリアル、ランブック、README、CONTRIBUTING のすべてに当てはまります。ドキュメントには利点だけでなくコストもあります。適切な数は、システムを理解し、運用し、判断できる状態に保つために必要な最小限の数です。

参考資料

• references/alternatives-catalog.md -- Diátaxis / RFC / ランブックの使い分け
• references/failure-modes.md -- 対処法を含む11の ADR 失敗パターン
• references/audit-procedure.md -- 厳守すべき制約を含むフォルダーレベルの監査手順
• references/changelog-canon.md -- Keep a Changelog 1.1 + SemVer 2.0.0
• references/runbook-canon.md -- ページャー対応が必要なインシデント向けのランブック構成（ハウツーではありません）
• references/postmortem-canon.md -- 責任追及をしないポストモーテム（PagerDuty + Google SRE）
• references/open-questions-canon.md -- 独立した未解決事項の登録簿
• references/agentic-docs-canon.md -- AI エージェントのコンテキスト向け AGENTS.md 規約
• references/adr-template-catalog.md -- テンプレート一覧（Nygard / MADR short / MADR long / Y-statement / Tyree-Akerman / arc42 §9）
• ../_shared/adr-is-not.md -- 標準の「ADR ではないもの」チェックリスト
• adr-discovery、adr-drafting、adr-critique スキル
• c4-model スキル -- 標準 C4 LikeC4 図
• repo-health スキル -- コミュニティヘルス関連ファイル（README / LICENSE / CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / SUPPORT / テンプレート / REUSE-SPDX）