Claude Codeエージェント実践 Day 6｜templates/ とドキュメント駆動
TL;DR
-
templates/は5つのテンプレート（ヒアリング記録〜完了報告）で成果物の一貫性を担保 - テンプレートを使うと「何を書くか」で迷わなくなり、エージェントも人間も作業効率が上がる
- Phase ごとにどのテンプレートを使うかを定義し、承認フローと連動させる
作ったもの
GitHub: akira-cloudjob-public/agent-scaffold-factory
# 今日学ぶこと
templates/ フォルダの構造
↓
5つのテンプレートと役割
↓
Phase との連動・承認フロー
Day 5 で knowledge/ のナレッジ管理を見ました。今日は、エージェントが成果物を作るときに使う「テンプレート」を解説します。
検証環境
| 項目 | 値 |
|---|---|
| OS | Windows 11 / macOS |
| Claude Code | 最新版 |
| 検証日 | 2026-02-06 |
なぜテンプレートが必要か
ドキュメント駆動開発の考え方
エージェントに依頼を丸投げすると、毎回異なるフォーマットの成果物が出てきます。
依頼: 「この機能の設計書を作って」
結果A: 箇条書き3行
結果B: 50ページの詳細仕様書
結果C: コードだけ
これでは品質にバラつきが出ますし、レビューする側も「何を確認すればいいのか」がわかりません。
テンプレートを用意すると、エージェントは「このフォーマットに従って埋める」という明確な指示を得られます。成果物の粒度が揃い、レビューも効率化できます。
私が直面した課題
8ヶ月エージェントを運用してきて、テンプレートなしで走ると以下の問題が起きていました。
| 課題 | 具体例 |
|---|---|
| フォーマットの不統一 | 設計書のセクション構成が案件ごとに違う |
| 抜け漏れ | 「承認欄がない」「変更履歴がない」が頻発 |
| レビュー負荷 | 「今回は何を確認すればいい？」を毎回考える |
特に困ったのが「承認フローが機能しない」問題でした。成果物のどこにサインすればいいかわからないので、口頭で「OK」と言って終わり。後から「あれ、承認したっけ？」となることがありました。
これを解決するために、承認欄を含むテンプレートを標準化しました。
templates/ フォルダの全体像
templates/
├── 00_ヒアリング記録.md # Phase 1: ヒアリング
├── 01_要求定義書.md # Phase 2: 要求定義
├── 02_設計書.md # Phase 3: 設計
├── 03_WBS.md # Phase 4: WBS
└── 04_完了報告.md # Phase 6: 完了報告
5つのテンプレートがあり、それぞれ特定の Phase に対応しています。Phase 5 は実装フェーズなので、テンプレートではなく WBS に従ってタスクを進めます。
5つのテンプレートの詳細
1. ヒアリング記録（00_ヒアリング記録.md）
使うタイミング: Phase 1（依頼を受けた直後）
依頼者から聞いた内容を構造化して記録するテンプレートです。
## ヒアリング内容
### Q1: 何を実現したいですか？
A:
### Q2: なぜそれが必要ですか？（背景・目的）
A:
### Q3: 誰が使いますか？
A:
### Q4: いつまでに必要ですか？
A:
### Q5: 制約や前提条件はありますか？
A:
### Q6: 成功の基準は何ですか？
A:
ポイント: 6つの質問で「What / Why / Who / When / Constraint / Success Criteria」を網羅しています。この質問項目は固定しておくと、エージェントが「何を聞けばいいか」で迷わなくなります。
さらに、テンプレートの末尾に「ナレッジ抽出メモ」セクションがあります。
## ナレッジ抽出メモ
（このヒアリングから knowledge/ に追記すべき情報）
### business/ 向け
-
### technical/ 向け
-
### people/ 向け
-
ヒアリングで得た情報のうち、他の案件でも使えそうなものをメモしておく欄です。Day 5 で解説した knowledge/ との連携ポイントになっています。
2. 要求定義書（01_要求定義書.md）
使うタイミング: Phase 2（ヒアリング完了後）
ヒアリング内容を整理し、「何を作るか」を定義するテンプレートです。
| セクション | 内容 |
|---|---|
| 概要 | 目的・背景・スコープ（やること/やらないこと） |
| 要求事項 | 機能要求（F-001, F-002...）と非機能要求（NF-001...） |
| 前提条件 | 成立のために必要な条件 |
| 制約条件 | 技術的・予算的・期間的な制約 |
| 成果物 | 最終的に納品するもの |
| スケジュール | マイルストーン |
| リスク | 想定されるリスクと対策 |
ポイント: 「やること」と「やらないこと」を明記するセクションがあります。スコープの認識ズレを防ぐために、「やらないこと」を書くのが大事です。
### 1.3 スコープ
#### やること
- 売上データの月次集計レポート作成
- CSVエクスポート機能
#### やらないこと
- リアルタイム集計（日次バッチで十分）
- モバイル対応（PC利用のみ）
3. 設計書（02_設計書.md）
使うタイミング: Phase 3（要求定義承認後）
「どう作るか」を定義するテンプレートです。
| セクション | 内容 |
|---|---|
| 設計方針 | アプローチの概要 |
| 全体構成 | 構成図・構成要素 |
| 詳細設計 | 処理フロー・入力・出力 |
| 技術選定 | 言語・フレームワーク・実行環境と選定理由 |
| 考慮事項 | エラー処理・セキュリティ・拡張性 |
| テスト方針 | 正常系・異常系のテスト観点 |
ポイント: 「技術選定」セクションに「理由」の列があります。なぜその技術を選んだかを残しておくと、後から見直すときに判断の根拠がわかります。
## 4. 技術選定
| 項目 | 選定 | 理由 |
|------|------|------|
| 言語 | Python 3.11 | pandas でのデータ処理が主体のため |
| フレームワーク | FastAPI | 軽量でAPIエンドポイントが少ないため |
| 実行環境 | Cloud Run | コールドスタートを許容できるバッチ処理のため |
4. WBS（03_WBS.md）
使うタイミング: Phase 4（設計承認後）
作業を分解し、担当と状態を管理するテンプレートです。Day 4 の /next-phase コマンドで詳しく解説しましたが、WBS もテンプレートとして提供しています。
| セクション | 内容 |
|---|---|
| 作業分解 | タスクを「準備」「調査・分析」「実装」「テスト」「納品」に分類 |
| 担当凡例 | 🤖 Agent / 👤 人間 / 🤝 協働 |
| 状態凡例 | ⬜ 未着手 / 🔄 進行中 / ✅ 完了 / ⏸ 保留 / ❌ 中止 |
| 役割分担の考え方 | エージェントがやるべきこと、人間がやるべきこと |
ポイント: 「役割分担の考え方」セクションで、判断・承認・機密情報は人間、調査・実装・ドキュメントはエージェントという原則を明記しています。
## 役割分担の考え方
### エージェントが担当すべきタスク
- 調査・情報収集
- コード実装
- ドキュメント作成
- テスト実行（自動化可能なもの）
### 人間が担当すべきタスク
- 判断・意思決定
- 承認
- 機密情報の設定
- 本番環境での確認
5. 完了報告（04_完了報告.md）
使うタイミング: Phase 6（実装完了後）
案件の振り返りと成果物一覧をまとめるテンプレートです。
| セクション | 内容 |
|---|---|
| 成果物一覧 | ドキュメント・コード・出力物のリスト |
| 実行結果 | 動作確認の結果 |
| 振り返り | 良かった点・課題・教訓 |
| 次への申し送り | 横展開可能な成果・ナレッジ更新チェック |
ポイント: 「ナレッジ更新」のチェックボックスがあります。案件完了時に lessons/ への追記を忘れないようにするための仕掛けです。
### ナレッジ更新
- [ ] `knowledge/lessons/` に教訓を追記
- [ ] `knowledge/technical/` に技術知識を追記（該当する場合）
承認フローとの連動
各テンプレートの末尾には「承認」セクションがあります。
## 承認
| 役割 | 名前 | 日付 | 承認 |
|------|------|------|------|
| 依頼者 | | | ☐ |
Phase が進むたびに、このチェックボックスを埋めていきます。
承認記録がドキュメントに残るので、後から「誰がいつ承認したか」を追跡できます。
コマンドとの連携
Day 4 で紹介した /next-phase コマンドは、テンプレートと連動しています。
/next-phase REQ-2026-003
このコマンドを実行すると、エージェントは以下を自動で行います。
- 現在の Phase を確認
- 該当する成果物（テンプレートから作成したファイル）の存在をチェック
- 承認状態を確認
- 次の Phase に進み、次のテンプレートを案内
つまり、テンプレートは単なる「ひな形」ではなく、ワークフローの一部として機能しています。
| Phase | テンプレート | 成果物パス |
|---|---|---|
| 1 | 00_ヒアリング記録.md | inputs/REQ-YYYY-NNN/ヒアリング記録.md |
| 2 | 01_要求定義書.md | documents/REQ-YYYY-NNN/01_要求定義書.md |
| 3 | 02_設計書.md | documents/REQ-YYYY-NNN/02_設計書.md |
| 4 | 03_WBS.md | documents/REQ-YYYY-NNN/03_WBS.md |
| 5 | なし（WBS に従う） | outputs/REQ-YYYY-NNN/ |
| 6 | 04_完了報告.md | documents/REQ-YYYY-NNN/04_完了報告.md |
ハマったところ
問題1: テンプレートを細かく分けすぎた
症状: テンプレートが20個以上になり、どれを使えばいいかわからなくなった
原因: 案件の種類ごとにテンプレートを作っていた
解決: 汎用的な5つのテンプレートに統一し、案件固有の情報は記入時に追加する方針に変更
# Before（細分化しすぎ）
templates/
├── ヒアリング記録_新規開発.md
├── ヒアリング記録_改修.md
├── ヒアリング記録_調査.md
├── 要求定義書_新規開発.md
├── 要求定義書_改修.md
... (20ファイル以上)
# After（汎用化）
templates/
├── 00_ヒアリング記録.md
├── 01_要求定義書.md
├── 02_設計書.md
├── 03_WBS.md
└── 04_完了報告.md
教訓: テンプレートは「共通部分」だけを抜き出す。案件固有の部分は埋めるときに追加すればいい。
問題2: 承認欄が形骸化した
症状: 承認欄はあるけど、誰もチェックしない
原因: 承認のタイミングが不明確だった
解決: /next-phase コマンドで「承認済みか」をチェックする仕組みを追加
# CLAUDE.md に追記
## Phase 進行ルール
- 次の Phase に進む前に、現 Phase の成果物の承認欄を確認する
- 承認欄が空欄の場合、「承認をお願いします」と依頼する
- 承認がないまま先に進まない
問題3: テンプレートを更新したら既存ファイルと齟齬が出た
症状: テンプレートにセクションを追加したが、過去の案件ファイルには反映されない
原因: テンプレート更新の運用ルールがなかった
解決: テンプレートの変更履歴を残し、メジャー変更時は版数を上げる
# テンプレート末尾に追記
## 変更履歴
| 版数 | 日付 | 変更内容 | 変更者 |
|------|------|----------|--------|
| 1.0 | 2026-01-01 | 初版作成 | Agent |
| 1.1 | 2026-02-01 | ナレッジ抽出メモセクション追加 | Agent |
運用ルール:
- 既存案件には過去のテンプレートをそのまま使う（後方互換性）
- 新規案件から新しいテンプレートを適用
まとめ
-
templates/は5つのテンプレートで成果物の一貫性を担保- ヒアリング記録 → 要求定義書 → 設計書 → WBS → 完了報告
- テンプレートを使うと「何を書くか」で迷わなくなる
- 承認欄をテンプレートに含めることで、承認フローをドキュメントに組み込める
-
/next-phaseコマンドと連動し、ワークフローの一部として機能
Day 2 で払い出したエージェントの templates/ フォルダ、そのまま使っていますか？
私は最初「テンプレートなんてなくても動く」と思っていました。実際、動きます。でも、案件を10個ほど回したところで「あれ、前はどうやって書いたっけ」「このセクションは何を書くんだっけ」が頻発しました。
テンプレートは、エージェントへの指示でもあり、自分自身へのガイドでもあります。「毎回同じフォーマットで書く」という縛りが、かえって楽にしてくれるという体験でした。
次回予告
Day 7: Week 1 まとめ + 2層のPDCA構造
- Week 1 で学んだ5つのフォルダを振り返り
- エージェント運用における2層のPDCA（案件レベル / 知識レベル）
- ナレッジが循環する仕組み
このシリーズが参考になったら、ぜひ いいね や フォロー をお願いします。試行錯誤の記録なので、「うちはこうしてる」「こっちのほうがいいよ」といったコメントも歓迎です。
シリーズを追いかける
Discussion