DESIGN.mdテンプレート実例：仕様書の章立てと書き込み例

DESIGN.mdとは、リポジトリのルートなどに置く、その時点でのアプリの仕様をまとめたMarkdownファイルです。要件定義書が「何のために作るか」という全体像を扱うのに対し、DESIGN.mdは「具体的にどんな画面・機能を、どう動かすか」という詳細を扱います。要件定義書の書き方で決めた目的とスコープを、実装可能な粒度まで落とし込む役割です。

ファイル名やMarkdownという形式にこだわる必要はありませんが、リポジトリに常駐する1つの文書として置いておくと、AIコーディングエージェントに新しい作業を頼むたびに「このファイルを読んでから進めて」と伝えるだけで前提を共有できるという利点があります。実装前に設計をドキュメント化する考え方は、Googleのエンジニアリング組織でも設計ドキュメント（デザインドック）文化として広く実践されています（参考：「Design Docs at Google」）。

個人開発規模のDESIGN.mdは、次の章立てで十分機能します。

• 概要：このアプリが何をするものか、1段落で説明
• 画面一覧：存在する画面と、それぞれの役割
• 主要機能の詳細：画面ごとの入力項目・表示内容・操作
• データの形：扱うデータの項目と型（例：タスクは「タイトル・期限・完了フラグ」を持つ）
• やらないこと：スコープ外として明記する機能
• 受け入れ基準：何をもって完成とみなすかの判定リスト

コピーして使えるDESIGN.mdの雛形

次の雛形をコピーして、角括弧の部分を自分のアプリに合わせて埋めてください。決まっていない項目は「未定」と書き、実装前に確認する点として残します。

# [アプリ名]の設計メモ

最終更新：[YYYY-MM-DD]

## 概要
- 使う人：[誰が使うか]
- 解決したいこと：[どんな場面で、何に困っているか]
- 今回作るもの：[最初の版でできることを1〜2文で]

## 画面一覧
- [画面名]：[この画面の役割と、主な表示内容]

## 主要機能の詳細
- 入力：[利用者が入力する項目、必須・任意の区別]
- 操作：[ボタンなどを押したときの動き]
- 表示：[処理後に何が、どの順番で表示されるか]
- 例外：[入力が空のとき、失敗したときの動き]
- 保存：[何を、どこに、いつ保存するか]

## データの形
- [項目名]：[文字列・数値・真偽値などの型と用途]
- [項目名]：[型と用途]
- データがないとき：[空の一覧など、初期状態の見せ方]

## やらないこと
- [今回の版には含めない機能]
- [後から検討する機能]

## 受け入れ基準
- [ ] [具体的な操作]をすると、[期待する結果]になる
- [ ] [空欄やエラーなどの条件]で、[期待する表示]になる
- [ ] [再読み込みなどの条件]で、[データの扱い]を確認できる

AIに実装を頼むときは、この設計メモを参照するように伝えます。「未定」の項目が残っている場合は、先に質問してもらうと、決めていない仕様のまま作業が進むのを避けやすくなります。

実際にどの程度の粒度で書けばよいか、簡単な例で見てみましょう。

• 概要：今日やるべきタスクだけを表示し、完了したら消えていく1画面のタスク管理アプリ。
• 画面一覧：ホーム画面（1画面のみ。設定画面や履歴画面は今回は作らない）。
• 主要機能の詳細：タスクをテキストで入力して追加できる。一覧はチェックボックス付きで表示する。チェックを入れると一覧から消える（削除ではなく非表示扱い）。
• データの形：タスクは「本文（文字列）・作成日時・完了フラグ（真偽値）」を持つ。
• やらないこと：期限設定・通知・カテゴリ分け・複数デバイス間の同期は今回のスコープ外。
• 受け入れ基準：タスクを追加すると一覧に表示される／チェックを入れると一覧から消える／ページを再読み込みしても未完了タスクが残っている。

このくらいの粒度であれば、AIコーディングエージェントは画面数・データの持ち方・完了の扱いについて推測する必要がなくなり、意図に近い実装を返しやすくなります。

小さな完成例：読書メモ

もう一つ、1画面の読書メモを例に、ファイル全体を埋めてみます。以下は説明用の架空のアプリです。保存する場所や入力エラーの扱いまで決めると、完成後に確かめることも具体的になります。

# 読書メモの設計メモ

## 概要
自分が読んだ本の名前と短い感想を、同じブラウザで見返すためのアプリ。
最初の版では、メモの追加と一覧表示を作る。

## 画面一覧
- ホーム：本の名前、感想の入力欄、追加ボタン、保存済みメモの一覧を表示する

## 主要機能の詳細
- 本の名前は必須、感想は任意とする
- 追加ボタンを押すと、入力内容をブラウザ内に保存する
- 本の名前の前後の空白を除き、空になる場合は追加せず「本の名前を入力してください」と表示する
- 保存できたら入力欄を空にし、新しいメモを一覧の先頭に表示する
- 保存に失敗したら入力内容を残し、「保存できませんでした」と表示する
- 一覧は追加日時の新しい順にする
- 再読み込み後も保存済みメモを表示する

## データの形
- id：文字列。メモを区別するための重複しない値
- title：文字列。本の名前
- note：文字列。感想。未入力の場合は空文字
- createdAt：文字列。追加日時
- 初期状態：メモが0件なら「最初の1冊を記録してみましょう」と表示する

## やらないこと
- メモの編集・削除
- ログイン、他の端末との同期、他の人への公開
- 書籍の自動検索

## 受け入れ基準
- [ ] 本の名前を入れて追加すると、一覧の先頭に表示される
- [ ] 感想が空でも、本の名前があれば追加できる
- [ ] 本の名前が空、または空白だけの場合は追加されず、案内が出る
- [ ] 再読み込み後も、保存した本の名前と感想が表示される
- [ ] 保存に失敗した場合、入力内容が残り、失敗したことがわかる

この例の保存先はブラウザ内なので、別の端末との共有やバックアップは対象にしていません。ブラウザのデータを削除するとメモも失われる可能性があります。自分のアプリで保存方法を変える場合は、「主要機能の詳細」と「受け入れ基準」をセットで見直してください。

DESIGN.mdは一度書いたら終わりではありません。実装を進める中で「やっぱりこの機能も必要だった」「この項目は不要だった」と気づくことは自然に起こります。気づいた時点でDESIGN.mdを更新し、常に「今の実装の実態」と一致させておくことが重要です。ズレたままのDESIGN.mdは、後でAIに参照させたときにかえって誤った前提を伝えてしまいます。

機能追加やリファクタリングを頼む際も、まずDESIGN.mdの該当箇所を更新してから指示を出す順番を習慣化すると、AIとの対話全体が安定します。頼み方の具体例はリファクタリングの頼み方でも扱っています。仕様書と合わせてREADMEも実態に一致させておくと、後から見返したときの理解がさらにスムーズになります。詳しくはREADMEとドキュメントをAIに書かせて維持するで解説しています。

• 章立てを埋めることが目的化する：全項目を無理に埋めようとして、実態のない仕様を書いてしまう。わからない箇所は「未定」と正直に書く方が安全です。
• データの形を曖昧にする：「タスク情報を持つ」だけでは項目が定まらず、AIが独自に項目を補ってしまいます。
• 更新を怠る：実装が仕様書から乖離したまま放置し、後で参照したときに誤解のもとになる。

Q1. DESIGN.mdはどのくらいの粒度で書けばよいですか？
AIコーディングエージェントが画面数・データの持ち方・完了の扱いを推測しなくて済む粒度が目安です。この記事のタスク管理アプリの例のように、画面一覧・主要機能・データの形・やらないことまで具体的に書くと、意図に近い実装を返しやすくなります。

Q2. 章立ての項目を全部埋められません。どうすればよいですか？
無理に埋めようとせず、決まっていない箇所は「未定」と正直に書いてください。実態のない仕様を書いてしまうと、後でAIに参照させたときにかえって誤った前提を伝えてしまいます。

Q3. DESIGN.mdはいつ更新すればよいですか？
実装中に「この機能も必要だった」「この項目は不要だった」と気づいた時点で更新します。機能追加やリファクタリングを頼む前に、まずDESIGN.mdの該当箇所を直してから指示を出す順番を習慣化すると安定します。

この記事は無料で読める入門です。仕様書の書き方と、自分のアプリ企画への当てはめ方は全12週のシラバスで実践形式で扱います（成果や収益をお約束するものではありません）。先行案内はこちら。