adr-critique

adr-critique

レガシー、外部、既存の ADR を行ごとに監査します。共通の「ADR ではない」ルールへの違反、理由付けの不足、関連する ADR との不整合、LikeC4 モデルとの乖離を明らかにします。変更するのはアーキテクトが承認した行のみです。

このスキルを使用する場面

• adr-drafting より前に作成された ADR（レガシーコーパス）
• 他のチームから取り込んだ ADR
• 汎用 LLM ツールで、反論を受けずに生成された ADR
• コーパス全体の定期的な品質確認

このスキルを使用しない場面

• adr-drafting（フェーズ 6）で既にセルフレビューした ADR — フィルターを通過しています。
• 一から書き直したい ADR — 代わりに adr-drafting を使用し、元の ADR に取って代わるものを作成してください。

スタイルルール

• 問題のある行を一字一句そのまま引用します。 ADR の記述を言い換えてはいけません。アーキテクトが批判されている正確なテキストを確認できるようにします。
• 違反している具体的なルールを明示します。 ../_shared/adr-is-not.md の該当セクションを参照してください（例：「ルール 5 — 一般的なベストプラクティスの引用」）。
• 書き換えは元の文章より短くします。 書き換えのほうが長い場合、それは批評ではなく改稿です。adr-drafting に回してください。
• メッセージごとに指摘は 1 つです。 違反をまとめて列挙してはいけません。行ごとにアーキテクトの承認を求めてください。
• 肯定的な評価はしません。 「ADR 全体は素晴らしく、細かな指摘が少しあるだけです」や「堅実な決定です」といった表現は禁止です。監査では問題を見つけるか、見つからないかのどちらかです。

用語

• コンポーネント — C4 コンテナー（デプロイ可能な単位）であり、コードのクラスではありません。
• アーキテクチャ特性 — 最適化の対象となる非機能品質（レイテンシー、コスト、保守性など）です。
• 矛盾 — どちらかが他方に取って代わることなく、2 つの ADR が衝突している状態です。明示的に認める必要があります。
• 理由付けの不足 — Decision セクションの正当化が、ビジネス上の懸念をアーキテクチャ特性に結び付けず、「ベストプラクティス」や「業界標準」に頼っている状態です。
• 乖離 — ADR と LikeC4 モデルで、存在するコンポーネントやその関係について食い違いがある状態です。

6 つのフェーズ

フェーズ 1 — 読む

対象の ADR を読み込みます。次に、supersedes、amends、relates-to リンクをたどって関連する ADR をすべて検索し、それぞれを読みます。監査にはグラフのコンテキストが必要です。

ADR が LikeC4 ファイルを参照している場合は、**/*.c4 を検索し、参照されているモデルを読みます。

フェーズ 2 — 行ごとの指摘

ADR を先頭から末尾まで確認します。ルールに違反する行ごとに、次のテンプレートを使って指摘を1 つ出します。

Original: <verbatim line from ADR>
Violates: <rule number and name from adr-is-not.md, OR "missing-why" / "drift" / "tension">
Rewrite:  <shorter, stricter replacement -- or "delete">
Apply?    (yes / no / adjust)

アーキテクトの返答を待ちます。返答があった後にのみ、次の指摘に進みます。

アーキテクトが adjust を選んだ場合は、その書き換えを受け入れます（ただし、元の文章より短いという制約は引き続き適用されます）。

フェーズ 3 — 理由付けの不足を確認する

Decision セクションに注目します。有効な理由付けは、ビジネス上の懸念をアーキテクチャ特性に結び付けます。無効な理由付けには、次のようなものがあります。

• 「これは業界標準です。」
• 「これはマイクロサービスのベストプラクティスです。」
• 「ほとんどのチームがこのようにしています。」
• 「これが推奨されるアプローチです。」

無効な行ごとに、Violates: missing-why として指摘します。書き換えでは、不足しているつながりを補う（「コンプライアンス上、EU 内にデータを保管する必要があるため、この DB はリージョンごとのレプリカを提供します」）か、その行を削除します。

理由付けの不足を確認するための詳しい質問については、references/audit-checklist.md を参照してください。

フェーズ 4 — 整合性チェック

ADR とそのグラフ上の隣接関係を確認し、次の点を探します。

• 矛盾 — 2 つの ADR が、どちらももう一方を置き換えることなく、互換性のない決定を主張しています。両方を指摘し、どちらが優先されるかを確認します。
• 関係の欠落（フロントマター） — 後発の決定が 0004 を置き換えると主張しているのに、フロントマターに supersedes: ["0004"] がない場合、related／amended リンクが有効な YAML リストではない場合、または関係を示す唯一の証拠が Related ADRs: [ADR-0004](0004-foo.md) のような本文中の行や、決定ログの README.md インデックスにある場合です。gray-matter 形式のパーサーはフロントマターのみを読み取るため、本文だけのリンクやインデックスのリンクは、そのパーサー群のグラフエッジにはなりません。フロントマターの supersedes／amends／relates-to への移動が必要な、本文だけに記載された関係をすべて指摘します。ID は 4 桁のゼロ埋め文字列にします。
• フロントマターと本文のミラー不一致 — doc-master では、2 つの情報源が一致している必要があります。次の各項目を指摘します。
  • フロントマターに supersedes、amends、relates-to が設定されているのに、本文に ## More Information セクションと、その関係を doc-master のリンク接頭辞（Supersedes、Superseded by、Amends、Amended by、Related to）を使って反映する ### Relationships サブセクションがない場合です。これらの ADR は、本文をスキャンするパーサー（ADR Manager など）から認識されません。
  • 本文に ADR 間のリンクを列挙する ### Relationships セクションがあるのに、対応するフロントマターの関係キーが空、または存在しない場合です。これらの ADR は、gray-matter 形式のパーサー（ADR Explorer など）から認識されません。
  • 2 つの情報源で関係の集合が一致しない場合（例：フロントマターが supersedes: ["0004"] なのに、本文が Supersedes [ADR-0005] となっている場合）です。不一致を指摘し、どちらが正しいかを確認します。
• 重複する権威ある主張 — 2 つの ADR が同じコンポーネント／決定について権限を主張しています。一方が譲る必要があります。

整合性チェック項目については、references/audit-checklist.md を参照してください。

フェーズ 5 — LikeC4 との乖離チェック

**/*.c4 と、存在する場合は likec4.config.* を Glob で検索します。ADR で言及されているコンポーネント名を LikeC4 モデルと比較します。

• ADR が、C4 モデルに存在しないコンポーネントに言及している → 乖離として提示し、どちらを正とするか確認します。
• C4 モデルに、ADR と矛盾するコンポーネントがある → 乖離として提示します。

どちらも自動更新してはいけません。どちらを情報源とするかは、アーキテクトが決定します。

フェーズ 6 — 承認済みの変更を適用

すべての指摘事項が解決したら、アーキテクトが承認した編集を1 回の編集パスで適用します。

• 承認された行だけを変更します。
• ファイルに監査マーカー、[reviewed] スタンプ、コメントを追加してはいけません。
• フロントマターと構造化されたセクションを保持します。
• ADR が accepted の場合、本文を編集してはいけません。代わりに、それを置き換える新しい ADR を作成します。監査で置き換えを推奨することはできますが、黙って実行してはいけません。

出力の規律

• 一括編集は禁止です。 行ごとの承認を徹底することで、監査の有用性を保ちます。
• Accepted ADR の本文は編集してはいけません。 Accepted ADR で許可される編集は、誤字の修正、グラフとの互換性を保つヘッダーの修正、プロジェクトのガバナンスで明示的に許可されたメタデータのみの関係リンクの修正、ヘッダーへの人が読める superseded by 注記の追加、または明示的な見出しの下で末尾に日付入りの「Amendments」注記を追加することです。それ以外はすべて新しい ADR とします。
• 判断せず、提示します。 矛盾、乖離、理由の欠落を指摘し、解決方法はアーキテクトが決定します。
• 最後に報告します。 変更の適用後、1 行の要約を出力します。「NNNN-title.md を監査しました。 件の指摘、 件を適用。 件の未解決項目：<一覧>。」

参考資料

• references/audit-checklist.md — フェーズ 3〜5 で使用する、セクションごとの確認項目一式
• ../_shared/adr-is-not.md — 指摘の Violates: フィールドで参照する、正式なルール一式
• adr-drafting スキル — 新規作成する ADR 用。監査対象ではありません
• c4-model スキル — フェーズ 5 で見つかった LikeC4 との乖離を解決する際に使用します