会話は流れるがファイルは残る：Requirements/Design/Tasksによる「時間軸」管理術

TL;DR

• 仕様書が腐る原因は「変化率の異なる情報」を1ファイルに混ぜていること
• Requirements（不変）/ Design（計画）/ Tasks（現在） の3層に分離すれば、Documentation Drift を構造的に防げる
• AIエージェントへの指示は「どのファイルを読め」の一文で済み、コンテキスト精度が劇的に上がる

The Pain: ドキュメントが腐る問題

「仕様書を書こう」と決めても、開発が進むにつれてドキュメントとコードが乖離していく Documentation Drift が発生します。特にAI開発では実装速度が速いため、この乖離が致命傷になります。

前回の記事では「チャットログを仕様の拠り所にするのが根本原因」という話をしました。では仕様ファイルさえ書けば解決するのかというと、そう単純ではありません。

原因は、「不変なもの（Why）」と「可変なもの（How/Status）」を同じファイルに混ぜてしまっていることにあります。1つのファイルに「目的」「設計」「進捗」を全部書くと、更新頻度の違いからファイル全体が信用できなくなるのです。

ありがちなアンチパターン

The Solution: 時間軸による3層分離

SDD（Spec Driven Development）では、ドキュメントを情報の「変化率（更新頻度）」に応じて3つに分離します。

この分離の本質は 「更新頻度の異なる情報を異なるファイルに置く」 というシンプルな原則です。データベースの正規化と同じ発想で、ドキュメントの変更衝突を最小化します。

なぜ「3つ」なのか

2層（要件+タスク）だと、設計判断の経緯が残りません。4層以上にすると認知負荷が上がり、AIエージェントが参照すべきファイルを迷います。3層は「判断の根拠を追跡できる最小構成」です。

意思決定の記録をさらに厳密に管理したい場合は、意思決定ログと証拠管理の型も参考にしてください。

The Implementation: specディレクトリの構造

プロジェクトルートに spec/ ディレクトリを作成し、この3ファイルを配置します。

project-root/
├── spec/
│   ├── requirements.md   # 変更しない「憲法」
│   ├── design.md          # 議論して更新する「設計図」
│   └── tasks.md           # 毎日書き換える「Todoリスト」
├── src/
└── ...

各ファイルの書き方テンプレート

requirements.md の例

# Requirements

## 目的
ユーザーが記事を検索し、3クリック以内に目的の記事へ到達できること。

## 非目的
- リアルタイム検索は対象外
- 多言語対応は Phase 2 以降

## 制約
- レスポンスタイム: p95 < 200ms
- 外部APIへの依存は最小限にすること

Issueテンプレートと組み合わせると、要件の解像度がさらに上がります。詳しくはIssueテンプレで要件解像度を上げる方法を参照してください。

tasks.md の例

# Tasks

## In Progress
- [ ] 検索APIのエンドポイント実装 (#42)

## Done
- [x] 検索インデックスの設計レビュー (#38)

## Blocked
- [ ] 全文検索ライブラリの選定 → Design.md の決定待ち

AIエージェントへの指示

この3層構造があれば、AIへの指示はワンライナーで済みます。

requirements.md の要件を満たすように、
design.md の設計に従って、
tasks.md の未完了タスクを1つ実行してください。

この一文だけで、AIはコンテキストの優先順位を正しく理解します。

• requirements.md = 絶対守るべき制約（変更不可）
• design.md = 提案して修正可能な案（議論の余地あり）
• tasks.md = 自分が埋めるべき空欄（即座に着手）

一枚岩 vs 3層分離の比較

仕様品質を維持する運用のコツ

3層に分けても、ファイルの中身が曖昧なら意味がありません。仕様品質マネジメントの運用モデルで体系的に整理していますが、ここでは最低限押さえるべき3つのルールを紹介します。

1. requirements.md は「判断可能」な粒度で書く: 「使いやすいUI」ではなく「3クリック以内に到達」のように、合否判定できる表現にする
2. design.md は選択肢と棄却理由をセットで記録する: 後から「なぜこの設計なのか」を追えるようにする
3. tasks.md は毎日棚卸しする: 完了タスクの放置が信頼性を下げる最大の原因

The Takeaway: 時間軸で分ければドキュメントは腐らない

• Requirements: ぶれない軸（過去の決定）
• Design: 柔軟な思考（未来の計画）
• Tasks: 確実な実行（現在の行動）

この3つを混ぜずに管理することで、AIエージェントは「迷子」にならず、常に正しい方向へ自律的に進むことができます。

仕様の「箱」が整ったら、次は人間の役割です。SDDの下で人間が担うべきは「コードを書くこと」ではなく「承認すること」。続きはHuman-in-the-loopワークフローで解説しています。

関連記事

• SDDシリーズ全体のハブページ
• なぜAIエージェントは仕様書を無視するのか
• Human-in-the-loopワークフロー
• Issueテンプレで要件解像度を上げる
• 意思決定ログと証拠管理の型
• 仕様品質マネジメントの運用モデル