2. 基本設計・ADR | 工程別ドキュメント運用ガイド

主な読者: PMSE

経営層投資対効果とリスク低減の判断材料。全文読む必要はなく、KPIとBefore/Afterで十分。
この章 ADRで意思決定の説明責任

PM合意・スコープ・未決の管理。正本が1か所なら炎上の早期検知と説明責任が楽になる。
この章設計着手ゲートの入力

SE構造・IF・例外の設計品質。MD+Mermaid+OpenAPIでレビューとAI支援の精度が上がる。
この章 ADR + C4 が中心

PG実装の迷いが減る。AGENTS.md・型生成・PRテンプレで「聞き直し」工数が減る。
この章 IF・画面項目の参照先

ADR：「なぜ」を設計書から分離する

設計書に理由を混ぜると更新時に壊れます。ADR（Architecture Decision Record） に判断を残し、設計書は現状の仕様だけを書きます。

# ADR-003: 受注APIは同期RESTを採用

## コンテキスト
- モバイル連携は当面なし
- チームはOpenAPI運用に慣れている

## 決定
REST + OpenAPI 3.1。非同期は ADR-007 で再検討。

## 却下した案
- GraphQL: 学習コスト・キャッシュ複雑性
- イベントのみ: 参照系の実装コスト増

## 結果
FE/BEが同じ契約を参照。型生成で齟齬低減。

2.0b ADR を品質アンカーとして使う

AIに長く・多段に作業させると、過去に合意した設計意図・例外条件・命名規則・責務分離・非対象範囲を見落とす可能性がある。本ガイドでは、判断構造を参照点（アンカー）としてADRへ記録し、PR・CI・AIレビュー・handoff から継続参照する運用をPoC仮説として扱う。

設計上の着想: カリキュラム学習とDINOv3のGram Anchoringを運用設計へ比喩的に転用した仮説であり、ADR運用の有効性を原論文が実証したものではない。PoCでは、テストケース作成 → 失敗例収集 → ルール/スキル/ADR更新 → 再評価のループを検証する。

アンカーは「正解1行」ではない: 「この変数名を使え」ではなく、「要件Aと設計Bの依存関係」「この例外は業務制約Cとセット」「このレビュー観点は品質リスクRのため」といった構造・対応関係を固定する。正本: research/quality_anchor_ai_ops.md

AI運用の5層 — ルールだけでは長期作業の品質劣化を防げない
層	役割	例
ルール	常に守る制約	命名規則、禁止事項、マージ前レビュー必須
スキル	再利用可能な作業手順	要件ゲート、PRレビュー、チケットループ
アンカー	崩してはいけない判断構造・関係性	ADR の Quality Anchor、承認済み REQ、合格した設計判断
評価	アンカーが守られたか確認	CI、lint、eval、semantic-drift、人間レビュー
ログ	後から再評価する材料	PR説明、BTS判断履歴、Handoff、作業経過

ADR を品質アンカーとして使う — 追記セクション

従来の ADR（コンテキスト・決定・却下案）に加え、AI作業・CI/CD・レビューが参照する項目を載せる。

## Quality Anchor
このADRで固定する品質上の関係性・判断構造。

## Must Preserve
後続の実装・修正・AI作業で壊してはいけないこと。

## Drift Signals
このADRから逸脱している可能性がある兆候。

## CI/Review Checks
CI、Linter、テスト、AIレビュー、人間レビューで確認する観点。

## Related Skills / Rules
このADRを参照すべきAIスキル、ルール、handoff項目。

ADRを「設計判断の墓場」にしない。後続AI作業から参照する仮説を CI/CD×AI · Agent-native CI/CD とセットでPoC検証する。

既存要素との接続
要素	従来の役割	アンカー化の追加
ADR	判断理由の記録	Quality Anchor · Must Preserve · Drift Signals
handoff	作業再開地点	参照すべきアンカーADRを明記
rules / skills	制約・手順	作業前に関連ADRを読む手順を入れる
CI / PRテンプレ	機械チェック・変更説明	関連ADR · 逸脱有無 · 更新要否
semantic-drift	版間意味逸脱	Drift Signals の自動/半自動検知

Before / After

Before

Word設計書200頁・理由と仕様が混在
担当変更で「なぜこう？」が分からない
同じ議論を繰り返す

After

設計MD + ADRがリンクで接続
意思決定の履歴が残る
変更は新ADRで上書き（履歴保持）

Mermaid：C4コンテナ（サンプル）

```mermaid
C4Context
  Person(user, "担当者")
  System(order, "受注システム")
  System_Ext(erp, "基幹ERP")
  Rel(user, order, "受注・キャンセル")
  Rel(order, erp, "在庫連携")
```

画像ではなくテキストなので、差分レビューとAI修正が容易です。

この工程で使う AI（基本設計・ADR）

設計 — 推論と意思決定の記録
役割	ツール例	優れている点	典型用途
トレードオフ整理	Claude Code · Claude Opus 系	却下案・制約の列挙、長文コンテキスト	`adr/ADR-*.md` 草案
構造図	Cursor + Mermaid	テキスト差分で C4 / 状態遷移をレビュー可能	`design.md` · C4 コンテナ
UIたたき台	v0 · Figma AI（任意）	プロトから実装への短縮	画面ラフ → SCR 項目定義へ接続
不変コンテキスト	ASDLC 型 ADR	エージェントが「なぜ」を誤読しにくい	設計変更時の前提固定（ASDLC）

成果物サンプル一覧

実際のプロジェクトではファイル名・パスをテンプレに合わせてください。以下は掲載可能な具体イメージ（HTML/CSS埋め込み）です。

docs/adr/ADR-003-rest-api.md

ADR（意思決定記録）

ADR-003-rest-api.md

1# ADR-003: 受注APIは同期REST

2## コンテキスト

3- モバイル連携は当面なし

4## 決定

5REST + OpenAPI 3.1 を採用

6## 却下

7- GraphQL: 学習コスト

docs/design/c4-order.md

アーキテクチャ図（C4）

docs/design/screens/SCR-003.md

画面項目定義

画面項目定義 SCR-003（抜粋）
項目ID	ラベル	型	必須	備考
F-01	受注番号	text	○	読取専用
F-02	キャンセル理由	select	○	マスタ連携
F-03	在庫戻し確認	checkbox	○	REQ-042

docs/design/er-order.mmd

ER図（抜粋）

リンク	用途
要件	REQ-ID接続
API	IF設計
スターター ADR	意思決定記録