正しいテンプレートの選び方

このガイドが解く問題: これから doc を書こうとして、PRD・ADR・モジュール詳細設計・Use Case のどれにすべきか決められない。WORKFLOW.md §1 には決定木があるが、それは AI エージェント向けに最適化されたものなので、人間は決定木の背後にあるメンタルモデルを欲しい。

これは 人間向け のテンプレート選択ガイドです。AI 向けの版は ../../template/docs/WORKFLOW.md §1 を参照。

テンプレートを決める 3 つの質問

ほとんどのテンプレート選択は次の 3 質問のどれかに帰着します:

何を、なぜ 作るのか? → PRD または Use Case
どう作るのか? → モジュール詳細設計 または Architecture Overview
なぜこの技術選択 を代替案より優先したのか? → ADR

このどれにも当てはまらないなら、おそらく durable な doc は不要です ―― report/・impl-plan/・postmortem/（揮発性）を使ってください。

完全な選択フロー

単一のアーキテクチャ決定とその代替案を記録しているか?
   YES → Template 5（ADR — MADR v3.0）。arc42/09-decisions/ の下に 1 ファイル

ユーザーが何を求めていて、なぜ作るのかを記述しているか?
   YES → Template 2（PRD）。arc42/03-context-and-scope/prds/ 配下

特定アクターが特定シナリオでどう使うかを記述しているか?
   YES → Template 4（Use Case）。arc42/03-context-and-scope/use-cases/ 配下

一つのモジュール / サービスがどう実装されるかを仕様化しているか?
   YES → Template 3（モジュール詳細設計）。detailed-design/ 配下

システム全体や crosscutting concern を記述しているか?
   YES → Template 1（Architecture Overview）。arc42 §1, §3, §4, §5, §8

UX リサーチ成果物（ペルソナ・ジャーニーマップ・サービスブループリント）か?
   YES → それぞれ Template 6 / 7 / 8

日付付きの作業材料（plan・sprint タスクリスト・postmortem・report）か?
   YES → テンプレート不要 ―― 対応する Layer B ディレクトリの Markdown ファイル
         ファイル名は YYYY-MM-DD_<kebab-title>.md

それ以外?
   → Template 0（Default）。最も近いディレクトリに置く

それでも迷うなら、下の よくある混同 セクションをどうぞ。

よくある混同 #1: 「これは PRD なのか Use Case なのか?」

観点	PRD（Template 2）	Use Case（Template 4）
焦点	どの問題を、誰のために解くのか?	アクター X はどう目標 Y を達成するのか?
寿命	機能リリースまで生き、その後も「なぜ」の正本として残る	シナリオが有効である限り生きる
粒度	1 機能 or プロダクト領域	1 シナリオ。1 機能に複数 use case
著者	PM / プロダクトリード	インタラクションを設計する人なら誰でも
典型的な長さ	1〜3 ページ	0.5〜1 ページ
例	「ユーザーがインストールを試せるよう `greet` コマンドを追加」	「初回ユーザーが `my-app greet` を実行する」

経験則: システムを通じたユーザージャーニー について書いているなら Use Case。 この機能を作るべきかどうか について書いているなら PRD。

両方を同じ機能について書いてよい（多くの場合書くべき）。

よくある混同 #2: 「これは ADR か、モジュール詳細設計の一部か?」

観点	ADR（Template 5）	Module DD（Template 3）
焦点	なぜこのオプションを選んだか?	実装は何か?
寿命	`Accepted` になったら immutable。新 ADR で supersede する	living document ―― コードと同期し続ける
粒度	1 決定、1 ファイル	1 モジュール / サービス / サブシステム
代替案	必須 ―― 何を却下したか・なぜか	不要
典型的な長さ	1 ページ	1〜10 ページ

経験則: そのセクションを doc から削除したとき、実装は依然として記述可能だが選択が説明されない ―― それは ADR。選択は説明されるが実装が不透明 ―― それは Module DD の一部。

実装が 2〜5 件の ADR を Module DD から参照するのは普通です。

よくある混同 #3: 「これは ADR か、コード中のコメントか?」

ADR は「後で誰かが蒸し返す可能性のある決定」のため。コードコメントは「将来の読者が現在のコードを理解するのに必要な文脈」のため。

ADR を書くのは:

他の誰かが本気で検討しそうな、名前のある代替案がある
コードからは明らかでないトレードオフがある
半年後に「なぜ Y ではなく X なのか?」と聞かれそう
決定が 2 つ以上のモジュールに影響する

ADR を書かないのは:

変数名・フォーマッティング・lint 規約（lint ルールが ADR）
「ライブラリ X を使う」で、現実的な代替案がない
1 行のワークアラウンド（// HACK: コメントが正しい）

Alternatives セクションを持たない「ADR」を書きそうになったら、それは ADR ではありません。

よくある混同 #4: 「これは Architecture Overview か Module Detailed Design か?」

Architecture Overview（Template 1）	Module DD（Template 3）
複数モジュールにまたがる	1 モジュール
`arc42/` 配下	`detailed-design/` 配下
新参とアーキテクトが読む	実装者とレビュアが読む
稀にしか更新しない（システム形状変化時）	そのモジュールへのコード変更ごとに更新
図: 高レイヤー C4（Context / Container）	図: 低レイヤー（Component / sequence）

経験則: コードベースに不慣れな人が システム を理解するために読むなら overview。 特定の一部 を理解するために読むなら Module DD。

よくある混同 #5: 「これは durable か volatile か?」

最も鋭いテスト: この doc はシステムを「あるがまま」記述するのか、「ある時点で何をしたか」を記録するのか?

システムをあるがまま → durable。arc42/・detailed-design/・design-guide/・api-contract/・user-manual/ 配下。front-matter 必須。ライフサイクル Draft → Review → Done
ある時点で何をしたか → volatile。impl-plans/・task-list/・postmortems/・reports/・cost-estimates/ 配下。ファイル名に YYYY-MM-DD プレフィックス。append-only ―― 閉じた揮発性 doc は編集せず、新しい日付付きを書く

両方の性質を 部分的に 持つ doc を書きそうになったら（例: 永続的な設計決定で終わる impl plan）、分割しましょう: 日付付きプランを impl-plans/ に、durable な部分を ADR や Module DD 更新として持ち上げる。

どうしても決められないとき

エスケープハッチが 2 つ:

Template 0（Default） は「本当に分からない」用に設計されています。それを使い、最も合理的なディレクトリに置き、次のレビュアに再分類を手伝ってもらう
Claude / チームメイトに聞く。doc の目的を 1 文で引用して「どの pentaglyph テンプレート?」と聞く。ほぼ即答で返ってきます

やってはいけないこと: 新しいテンプレートやディレクトリを発明する。pentaglyph はその失敗モードを防ぐために設計されています。

完全なテンプレートリスト

このリポジトリに今あるテンプレートの正本リストは reference/template-index.md を参照。本ガイド執筆時点の番号付け・命名の不一致もそこにフラグしてあります。