ドキュメントファーストで回すスペック駆動開発

ドキュメントファーストで回す スペック駆動開発 AI×Backend − 実用化を支える技術と効率化の現在地 Nstock株式会社 / 田中 清

本日のアジェンダ 1 AIを活用した開発のよくある課題 2 解決の方向性 3 スペック駆動開発の具体例 4 Subagentの役割分担と運用 5 まとめ ● ● 金融系の新規プロダクト開発プロジェクトで実施中のお話をします Claude Code をベースにお話しますが、アプローチ自体は他のAIツールでも活用できるかと思います

AIを活用した開発のよくある課題

AIにコード書いてもらう → 何か違う …

AIのコードがしっくりこないのはコンテキストが 不足しているから 現時点でチームが“正”とするドキュメントはどれ？ • ドメイン知識が分散 → 唯一の参照先の不在 • 判断基準が未整備 → 優先度のブレ • ドキュメントが最新化されない → コンテキストの陳腐化 “唯一の参照先（Single Source of Truth）”が不在

本質的な問題 “ 相手がAIでも人間でも、成果の差は コンテキスト共有の精度 で決まる ※ここでの精度＝ 最新性・一貫性・可探索性 （迷わず辿れる）

解決の方向性

プロジェクト共通ドキュメント管理 • docは「ナレッジ」「ルール」「スタンス」の3層構造で整理するとバランスが取りやすい • stance：不確実性への対処姿勢や意思決定の基準、 判断基準や優先順位 を明文化 ・例：優先度原則： 規制遵守＞安全性＞性能＞開発速度 • rules： 明確な判断基準や制約、 コーディング規約やテスト方針 を定義 ・例：テスト方針の合格基準： 重要 APIの回帰テスト必須 • knowledge：ドメイン知識や技術仕様など、 蓄積された具体的知識 をまとめる ・例：外部システム連携時の実装パターン ナレッジ、ルール、スタンスの考え方参考 @Fukahire109 の X 投稿。詳細 → https://x.com/fukahire109/status/1924617985899319702

ドキュメントファーストな軽量ループ PRで得た判断や学びをコメントで終わらせずdoc に継続的に還流させる • 唯一の参照先＝ doc を起点に、学びを 即還流 する • ループ：doc → spec → PR → doc • 完了条件 ・doc → spec：判断の根拠が明文化 されている ・PR：PRに判断の痕跡 （理由・代替案）が残っている ・PR → doc：学びがdocに還流 されている この原則を開発プロセスに落とし込むために「スペック駆動開発」を活用しています ※副次効果：議論の行き先が 1つになり、解釈差が減る

スペック駆動開発の具体例

スペック駆動開発（本資料の定義と全体像） プロセスの核は doc→spec→PR→doc。Subagentは補助として必要に応じて活用 • 作業定義 • 仕様（spec）を先に構造化し、それを拠り所に設計・実装・テストを進め、変更は必ず spec／doc に還流させる • 完了基準 • ✅ doc が唯一の参照先 になっている • ✅ 判断の痕跡 （理由・代替案）が PR に残っている • ✅ PR の学びが doc に反映されている • 開発規模に応じた具体的な開発の進め方 （詳細は次ページで） • 小規模（判断少 / 影響局所） ： /spec:mini • 中〜大規模（判断多 / 影響広範） ： /spec:plan → /spec:implement • 補足：/spec について • /spec はこのプロセスを実行しやすくする “カスタムスラッシュコマンド例 ”で採用は任意。プロセス自体は /spec なしでも同じ

具体例①： /spec:mini 小規模変更は1セッションで「 要件 → 実装 → PR → doc還流」を一気通貫 • いつ使う • 小規模（目安： <= 100行） • 判断少／影響局所 • 既存パターン流用可 • 開発手順 • task-summary.md を作成（What / How / Tests / Rollback） • 既存パターン踏襲で TDD→実装→テスト • PRに判断の要点（理由・代替案） → docへ即還流 • 切り替え基準 • 2時間超 or 判断が増えたら spec:plan へ /spec:mini プロンプト（記載ポイント） Context - 参照doc: <docs/knowledge|rules|stance/...> 目的/現状(1–2行) - 変更理由 : 不具合/要望/規制対応 などを簡潔に Change - 何をどう変えるか： UI/API/DB/設定のどこが、どう変わる？ - 既存パターン流用の前提（類似パスを 1つ記載） Constraints（必須条件） - 規制/セキュリティ /互換/性能: 例) 監査ログ保持・後方互換・ SLO 等 Impact scope（影響範囲） - 変更行数目安（ ≤100行）・影響モジュール /DB/外部IF - 影響が広がる兆候 or 2h超・判断増は mini中止 → /spec:plan へ Agents（最小限／並列） - domain: ドメイン影響の整合確認 - compliance: 規制・監査観点（必要時） ※security/testerは必要時のみ Outputs - .scratch/specs/<task>/task-summary.md（背景 / What / How / 既存パターン / Tests） - 更新対象 doc: <requirements.md | design.md>（必要箇所のみ更新） - PRノート: 理由・代替案・却下基準を 1行ずつ

具体例②： /spec:plan → /spec:implement 設計判断がある場合は 計画 → 実装 を分離して確実に。 planで要件・設計・実装計画 を固め、implementで段階実装＋検証 • いつ使う • 複数レイヤ横断／新規 API／設計判断が多い • 規模が大きい（目安：＞ 100行） • 計画＋実装の 2セッション以上 が妥当 • 開発手順 • /spec:plan で計画ドキュメントを生成 • handover-prompt を添えて実装へ引き継ぎ • /spec:implement で計画ドキュメントを順に読み込み実装 • PRに判断の要点（理由・代替案） → docへ即還流 • 切り替え基準 • 実装が1セッションに収まらない / 判断が増える場合は 別セッションに引き継ぎ /spec:plan プロンプト（記載ポイント） Context - 参照doc: <docs/knowledge|rules|stance/...> 目的/現状(1–2行) Plan Phase 0 準備 .scratch/specs/<task>/requirements.md などのひな型作成 Phase 1 要件（並列： domain, compliance） 確認：削除 /保持の区別・構成の整合・出力矛盾なし 承認：requirements.md を確認 → Phase2 へ Phase 2 設計（並列： domain, security, perf, migration） 確認：Phase1との整合・各出力の矛盾なし・影響範囲明確 承認：design.md を確認 → Phase3 へ Phase 3 実装計画（並列： tester, migration） 確認：実装手順≒要件 / 設計一致・削除対象・ Rollback基準明確化 承認：implementation.md 確認 → Phase4へ Phase 4 実装へ引き継ぎ handover-prompt.md を生成（実装セッション開始用） Parallel Check（毎フェーズ） 単一メッセージで複数エージェントを同時起動（順番実行は NG）

参考）生成ドキュメントと取り扱い • 生成物ドキュメント（ /spec:plan で作成、/spec:implement に引き継ぎ） .scratch/specs/<task>/ ├─ requirements.md # 1. 要件定義（機能・非機能・規制） ├─ design.md # 2. 設計（アーキ/API契約） ├─ implementation.md # 3. 実装計画（タスク分解・優先度） ├─ handover-prompt.md # 4. 実装用 新規セッション引き継ぎ内容 └─ agents/ # Subagent分析（domain/security/perf/compliance/...） • 取り扱いの原則 • 一時 → 恒久：.scratch は下書きの扱い。正はプロジェクト共通 docとして管理 • 即還流：PRマージ時に学びをdocへ反映 • 品質ループ ：誤り、齟齬を検知したら作業停止 → 原因分析 → doc更新 → 再開 • 補足 • 人とAIの参照先は常にプロジェクト共通doc • 実装者によるレビューでは 整合（要件=設計=計画） と 引き継ぎの明確さ を見る

Subagentの役割分担と運用

Subagentの連携モデル ・Domainエージェントをリード役として、各専門エージェントが連携する構成にしている ・各Subagentの提案はDomainエージェントが最終判断し、合意内容は specへ直ちに反映 エージェント 専門性 主な役割 domain ドメイン専門家 兼 ソフトウェアアーキテクト • ドメインモデル整合性 • 優先度の最終判定 compliance 金融コンプライアンス専門家 • 金融規制準拠 • 監査要件確認 security セキュリティエンジニア • 認証・認可系実装 • 脆弱性検出 tester テストエンジニア • 必要最小限のテスト戦略 • 既存テストパターン活用 perf パフォーマンスアナリスト • ボトルネック特定 • インデックス提案 migration データベース専門家 • マイグレーション作成 • DB変更計画 Subagentの分割粒度は悩みどころ。色々試した結果、採用職種レベルの粒度での分割が一番しっくりきた

Subagentの活用方法 各フェーズで適したSubagentを同時実行し多角的な検証を行う フェーズ 同時実行エージェント 目的 実行ログ例 （各Subagentが提案＋根拠＋優先度を出す） 要件定義 domain + compliance 規制の網羅性を先に担保 設計 domain + security + perf + migration 安全性・性能・移行の三重観点で検証 実装計画 tester + migration 実装方針と共に、テスト設計/ DB変更の整合 もチェック 実装後の確認 compliance + tester + security + perf 規制×品質の最終クロスチェック ・domain: ドメイン影響分析 ・compliance: 監査ログポリシー確認

Subagentの活用方法 • 優先度の統一基準 → 各エージェン間レビューで使う統一判断ルール：Subagentごとに基準がぶれないように • CRITICAL：24時間以内に対応（規制違反・金銭的損失のリスク） • HIGH：1–2スプリント内に対応（主要機能への影響、監査ログ欠落 など） • MEDIUM：運用開始前まで（品質・保守性：例 テストカバレッジ未達、重複コード） • LOW：将来検討（理想だが必須ではない：例 <100ms改善、コメント充実） Domainをハブに、レビューでは優先度の統一基準で判断を揃える Domainが妥当性を確認（必要ならSubagentへ差し戻す）し、合意内容は specドキュメントへ反映

Subagent：運用上の注意とアンチパターン • 過度な指摘（オーバースペック）を避ける工夫 • 過剰最適化を避ける ：既存パターン最優先／最小実装を推奨 • 迷子防止 ：各Subagentのmdファイルに「困ったらこの Subagentに聞け」 • アンチパターン例として「やらないこと」も明記 • 全部CRITICAL化、将来問題の過大評価、 3箇所未満の抽象化、実測前の最適化 • どこまでやるべきか、やらないべきかの合意が重要 • 設計をしっかりやりすぎるとオーバーエンジニアリングしがちになる場合がある • ただ、逆に設計の手を抜くと浅い実装にもなったりもする

参考）上手くいかなかった例 判断ミスがあり設計中断して原因分析・対策整理を行い、その内容をドキュメントに反映してPR作成 何が起きた？ ・実装計画の記述を誤解し、削除不可モジュールを削除 対象に 原因は？ ・設計で特定の Subagent の示唆を深掘りせず進行 ・フェーズ間の整合性確認が不足 対策は？ ・「Phase完了時の確認」を追加（→1） ・Subagent出力の検証プロトコルを定義・交差チェック （→2） ・システムメンテナンス定義書に5フェーズのチェックリスト （→3）

まとめ

軽量ループで AIツールの迷いをなくす • 軽量ループ（継続的改善）の仕組み • ドキュメントファーストで `doc → spec → PR → doc` を日常運用し、 学びを即還流 する • 効果（個人 → チーム） • AIツールの迷いがなくなる ：ドキュメントが唯一の参照先 • チーム全体にも効果 ：議論の行き先が 1つになり、解釈差が減り、品質が安定 • 導入の進め方 • まずは 1人で小さく回す： 導入 → 反復 → 自動化 → 標準化（プロジェクト全体へ） • 今日から始める： プロジェクトドキュメント整備、ドキュメントファースト PR 開発チームに、立ち上がりが驚くほど速いエンジニアが加わったと思えばちょうど良い その実力を成果に変える条件は、ドキュメントを “最新・一貫・可探索（迷わず辿れる） ” に保つこと