ADR 起案 draft Style Guide (詳細ルールと正典)

本文書は adr-draft.template.md の 書き方ルールの詳細・アンチパターン集・lint 仕様の正典。起案者がテンプレで足りない時に深掘り読みする。scripts/adr-draft-lint.mjs の検出ルールもここを SSoT として参照する。

1. 想定読者 (詳細)

1.1 persona

技術リテラシーのある経営者 (Technically Literate Executive)。半年後の自分・将来雇う取締役・出資検討者などを総称する。

1.2 知っている

• 一般的な技術用語: API / git / TypeScript / クラウド / LLM / RAG / agent / OAuth / cron
• 一般的な経営概念: ROI / KPI / 撤退条件 / 監査 / SoD / 機会損失 / TAM
• 業界相場: SaaS 月額レンジ・開発工数感覚

1.3 知らない

• 本プロジェクト固有のサービス名: /intake, /chat, drp, mas, ocr 等
• 本プロジェクト固有の役割名・経路名: 起案者・壁打ち相手・triage・pregate・spec-gen-pipeline
• ADR-NNNN の中身 (番号だけ出されても意味不明)
• プロジェクト固有の細部 (prompt caching の業者特有挙動 等)
• 業界専門フレーム: Y-Statement / MADR / Q42 9 タグ / Kruchten Type

1.4 読む目的

この起案が「何を」「なぜ」決定しようとしているのか、何が問題なのかを 5 分で 理解する。妥当性判断や承認はこの段階では行わない (後段の審査・承認プロセスで判定される)。

2. 3 層構造の詳細

2.1 Layer 1: 決定の骨子

これだけで「何をなぜ決めたか」が分かる最低限。経営者 persona は Layer 1 だけ読んで決定の輪郭を掴めるべき。

• 状況・問題: 今どういう状況で、何が痛くて動く必要があるのか
• 採用方針: 何を採用したのか (動詞 + 目的語 1 文)
• 採用理由: なぜそれが効くのか (問題への作用機序)

該当節: ## 何を解決するか / ## 採用したい方針 の Y-Statement Z + B 部分

2.2 Layer 2: 判断の質

決定が安易でない、ちゃんと比較された痕跡を残す層。

• 棄却した代替案と理由
• 採用の代償 (= 何を引き換えに受け入れるか)
• 判断軸 (= なぜこの軸で選んだか)

該当節: ## 採用したい方針 の Y-Statement A + C 部分 / ## 判断基準 / ## 検討した代替案

2.3 Layer 3: 運用への接続

決定が「言いっぱなし」でないことの担保。実装・運用フェーズで参照される。

• 影響: 何がどう変わるか
• コスト: いくらかかる / どれくらいの工数
• 撤退条件: いつ見直すか
• 観測手段: 守られているか確認する仕組み

該当節: ## 影響 / ## コスト試算 / ## 撤退条件 / ## Confirmation

2.4 Layer 0: 前提・文脈

本決定が依存する過去の決定や規約を指す。

該当節: ## 過去 ADR との関係

2.5 Light Mode 例外 (本流 2%)

ADR の Mode は ADR-0024 で導入された規模軸で、Light / Standard / Critical の 3 段。実績分布 (2026-06-25 / 163 本) は Standard 88% / Critical 11% / Light 2% (3 本) で、本流は Standard。template 本体のマスター表は Standard/Critical 基準で書いている。Light Mode で起案する場合のみ次の例外を適用する。

Light Mode の判定: frontmatter mode: Light または本文太字メタ **Mode**: Light を明示。

省略可な節 (Light のみ):

他 6 節 (何を解決するか / 採用したい方針 / 影響 / コスト試算 / 撤退条件 / 過去 ADR との関係) は Light でも必須。

Light Mode の量目安 (ADR-0024): 30-80 行。30 行未満なら ADR でなく README / コメントで十分の可能性。80 行を超えるなら Standard に昇格を検討。

Light に向く決定 (= 過去実績から): ライブラリ選定の小変更 / コーディング規約の追加 / 命名規約の調整。

Light に向かない決定: 不可逆な実装方針・監査要件影響・撤退コストが見えない選択。これらは Light の軽さで書くと後で不足が露呈する。

lint の挙動: scripts/adr-draft-lint.mjs は frontmatter または本文太字メタの mode: Light / **Mode**: Light を検出し、LIGHT_OPTIONAL = {判断基準, 検討した代替案} の 2 節を欠落しても error にしない。本表の Confirmation = N/A 許容 は lint では検査せず、PR レビューで確認する。

3. 1 文の書き方

3.1 文体の 3 階層

• A 具体: 動詞 + 観測可能な対象。誰が読んでも同じ画 (= what you can see) を描ける書き方。
  • ✓ 「Claude に別タブで質問している」
  • ✓ 「起案 1 本に 1-2 時間 余計にかかる」
  • ✓ 「triage 試行ボタンを毎回 2-5 秒待つ」
• B 中間: project 用語の 1 語。初出時はカッコで補足。
  • ✓ 「intake (起案フォーム UI・ADR-0164 で分離)」
  • ✓ 「triage (起案前簡易判定)」
• C 抽象 (本文では禁止): 名詞句の連鎖。動詞も観測可能対象も含まないので、読み手が脳内で名詞を動詞に戻しながら parse する必要が出る。
  • ✗ 「数値根拠探索コストが高い課題」
  • ✗ 「文脈分離コストが大きい状況」
  • ✗ 「心理的負担と探索コストが高い構造」

3.1.1 各節で許容される階層

3.2 1 文 1 メッセージ

複数主張を読点で詰めない (docs.md の DRP ドキュメント文章方針に準拠)。

• ✗ 「起案前ゲートで数値必須化されたため起案前に現実的なコストレンジを当てる必要があり、これを別タブで Claude に聞いている。」(3 つの主張が詰まっている)
• ✓ 「起案前ゲートで数値必須化された。」「コストレンジを当てるには業界相場を引く必要がある。」「これを別タブで Claude に毎回聞いている。」(3 文に分割)

3.3 カッコ補足を本文で繰り返さない

「X (= ...)」のような補足は別の 1 文に分けるか、初出時 gloss でのみ許容。本文中に何度も繰り返すと文が長くなって読みにくくなる。

• ✗ 「intake (起案フォーム UI) で triage (起案前簡易判定) を試行すると ADR-0164 (intake サイト分離) で分離した /chat (審査専用 UI) に影響しない」(カッコ 4 つで本文が読めない)
• ✓ 「起案フォーム (= /intake、ADR-0164 で 6 月分離) で起案前簡易判定を試行しても、審査専用 UI には影響しない。」(初出 gloss は 1 回。以降は素の語で書く)

3.4 接続詞「で」「と」で名詞を連ねない

A で B と C が高い課題 のような名詞句連鎖を作る接続を禁止。1 文 1 メッセージ違反 + Tier C 違反になりやすい。

• ✗ 「壁打ち相手不在で心理的負担と数値根拠探索コストが高い課題」
• ✓ 「壁打ち相手がいないので 1 本に 1-2 時間 余計にかかる課題」(動詞で名詞を分解)

3.5 規模感の数値を入れる

Y-Statement の Y 課題、影響の負の影響、撤退条件 では特に重要。経営者 persona が問題の大きさを掴むには数値が不可欠。

• ✗ 「LLM 呼び出し料金の増分」
• ✓ 「LLM 呼び出し料金月 $38-$1,125 の増分」(規模感が掴める)

4. 用語の選択

4.1 用語タイプ別の扱い

4.2 初出 gloss の書き方

• 短く: 1 句 (1-15 字程度)
• 観測可能 or 役割: 「起案フォーム UI」「審査専用 UI」「起案前簡易判定」のように何の機能/役割か
• ADR 番号付き場合のフォーマット: 用語 (gloss・ADR-NNNN で 月日 採用/分離/変更)

例:

• ✓ /intake (起案フォーム UI・ADR-0164 で 2026-06 分離)
• ✓ triage (起案前簡易判定)
• ✓ 壁打ち相手 (起案中の対話相手)
• ✗ /intake (これは ADR-0164 で導入された起案者専用の Web UI で...) (gloss が長すぎる)

4.3 ADR-NNNN 併記の書き方

ADR 番号だけで本文中に出すと persona は意味を取れない。初出時はタイトル併記 (同節内の 2 回目以降は番号のみで OK)。

• ✗ 「ADR-0164 の影響で /intake は審査機能が削られた」
• ✓ 「ADR-0164 (intake サイト分離) の影響で /intake は審査機能が削られた」

5. アンチパターン集 (✗ → ✓ 対比)

5.1 Tier C 名詞句連鎖

5.2 gloss 漏れ

5.3 ADR-NNNN 番号孤立

5.4 カッコ補足の多用

5.5 1 文への多論点詰め込み

5.6 ファイルパスを Layer 1 に混入

5.7 規模感の数値欠落

6. CI lint 仕様

scripts/adr-draft-lint.mjs が検出するルール。本節がルール定義の SSoT (lint 実装はこの定義を満たす)。

6.1 既存 3 ルール

6.2 新規 2 ルール (本ガイドで導入)

新規 2 ルールは warning で開始。1 ヶ月運用して false positive 率 < 10% なら error に昇格。Tier C 名詞句連鎖の自動検出は false positive 警戒で本 PR では見送り (将来 RQ 化)。

6.3 用語リスト (adr-draft-gloss-on-first-use の対象)

優先度高 (= 確実に gloss 必須):

• /intake → 起案フォーム UI
• /chat → 審査専用 UI
• /drafts → draft 投入 API
• triage → 起案前簡易判定
• pregate → 起案前ゲート
• 壁打ち相手 → 起案中の対話相手
• spec-gen-pipeline → ADR 本文生成パイプライン
• draftSoFar → 起案フォーム現状
• verdict → 審査結果

将来追加候補 (= false positive を見てから判断):

• 起案者 / 起案中 / 起案 (見出しとしては OK・通常文中の初出 gloss は要検討)

7. 参照

• adr-draft.template.md — drafter-facing なテンプレ本体
• scripts/adr-draft-lint.mjs — 本ガイドの CI 強制実装
• .claude/rules/adr-draft.md — path-scoped rule (本ガイドと template への参照)
• ADR-0097 — 起案テンプレ canonical 形式 / 9 節 1:1 マッピング
• ADR-0091 — 起案前ゲート 3 ルール
• ADR-0088 — コスト試算必須化
• ADR-0053 — 判断基準 MCDA 構造
• ADR-0036 — Confirmation セクション
• ADR-0105 — 用語 Tier・原語温存 (本ガイドの Tier B 由来)
• .claude/rules/docs.md — DRP ドキュメント文章方針 (1 文 1 メッセージ / カッコ補足禁止 由来)