0. 目次
1. はじめに
2. SDD導入当初の開発ワークフロー
3. Issueドキュメントを積み上げることのつらみ
4. つらみを減らすために、仕様ファイルの残し方を変えた
5. 何をプロダクトドキュメントに移し、何をIssueドキュメントに残すか
6. この運用に変えて、何がよくなったか
7. おわりに
1. はじめに
こんにちは、AgVenture Labの山田です。
この記事では、仕様駆動開発（以下、SDD）を導入したあと、Issueごとに作っていた仕様ファイルの残し方を見直した話を書きます。
まず、この話の前提として、うちのチームの開発の進め方を簡単に説明します。
うちのチームでは、アジャイル開発の中で、Issue単位に機能追加や改善を進めています。
設計整理、実装計画、実装補助では、AIに仕様ファイルや既存コードを渡しながら開発しています。
ここでいうSDDは、実装前に、そのIssueの要求、設計との対応関係、実装計画を文書化し、それをもとに開発を進めるやり方です。
導入した目的は、実装前に考えを整理することと、AIに渡す前提を明確にすることでした。
SDDを入れた直後は、Issueごとに必要な情報を整理できるので、かなり進めやすく感じていました。
ただ、Issueドキュメントが増えるにつれて、次のような困りごとが出てきました。
主な悩み
- 仕様ファイルが増えると、今も有効な前提を見つけにくい
- 古い仕様ドキュメントがAIに渡す文脈のノイズになる
- 一時的な検討メモと、長く残すべき仕様が混ざる
人が読むときにも、AIに文脈として渡すときにも、今の判断に不要な情報が混ざりやすくなっていました。
そこで、Issueドキュメントを「作業中の判断や検討を置く場所」、プロダクトドキュメントを「今後も参照したい前提を残す場所」として分けることにしました。
なお、本記事では特定ツールの比較はしません。
うちではCodexと独自に作成したスキルを使っていますが、この記事ではツールの違いではなく、「Issueごとの文書をどう残すか」に絞って話します。
2. SDD導入当初の開発ワークフロー
まず、SDDを入れ始めたころの開発ワークフローです。
この流れでは、Issueごとに次のようなファイルを作っていました。
-
spec.md：そのIssueで実現したい要求を整理する -
design_mapping.md：要求と既存設計・既存コードの対応関係を整理する -
plan.md：実装方針や作業順を整理する -
tasks.md：実装時に進める作業を細かく分ける
機能追加を続けると、ディレクトリ構成は次のようになります。
├── specs
│ ├── 20260101101112_add-xx-feature
│ │ ├── spec.md
│ │ ├── design_mapping.md
│ │ ├── plan.md
│ │ └── tasks.md
│ ├── 20260102101112_add-yy-feature
│ └── ...
└── src
本記事では、specs/xxx/配下に作られるこれらのファイル一式を、Issueドキュメントと呼びます。
このようにIssueごとにファイルを分けること自体は、作業中には便利でした。
要求、設計との対応関係、実装計画を分けて整理できるため、Issue単位で開発を進めやすくなります。
AIに渡す情報もIssueごとにまとまるため、実装前の整理や実装補助にも使いやすいです。
ただ、作業中に便利な形と、Issueが終わったあとも扱いやすい形は別でした。
機能追加を重ねるうちに、Issueドキュメントは少しずつ扱いづらくなっていきました。
3. Issueドキュメントを積み上げることのつらみ
扱いづらくなった理由は、性質の違う情報が同じ場所に残り続けたためです。
たとえば、実装後も有効な業務ルールや画面仕様。
その一方で、そのIssueだけで必要だった比較メモ、実装時に迷った内容、途中で採用しなかった案。
こういった情報が、同じIssueドキュメントの中に入っていました。
Issueを進めている間は、それでも困りません。
そのIssueの中で考えたことを、まとめて追えるからです。
ただ、Issueが終わったあとも同じ場所に残り続けると、あとから見るたびに「これは今も有効な仕様なのか」「そのIssueの中だけで閉じた検討メモなのか」を読み分ける必要が出てきます。
AIに文脈として渡す場合も同じです。
古い検討メモや途中で採用しなかった案が混ざると、それらも今の判断材料に含まれやすくなります。
最初は、Issueドキュメントの数が増えたこと自体が問題だと思っていました。
しかし、実際に見直してみると、問題はファイル数ではありませんでした。
問題は、情報の役割が違うものを、Issue単位という同じまとまりで残し続けていたことでした。
Issueを進めるための情報は、そのIssueの中では必要です。
しかし、Issueが終わったあとに現在の仕様として扱いたい情報とは限りません。
それにもかかわらず、すべてを同じIssueドキュメントの中に残していたため、現在の前提と過去の検討経緯が混ざって見えるようになっていました。
ここが、Issueドキュメントを積み上げる中で一番大きな課題でした。
4. つらみを減らすために、仕様ファイルの残し方を変えた
課題が見えてきたからといって、仕様を書くこと自体をやめたわけではありません。
見直したのは、Issueごとに作った仕様ファイルを、Issueが終わったあともそのまま現在の仕様として扱い続けることです。
そこで、Issueドキュメントとプロダクトドキュメントの役割を分けました。
Issueドキュメントは、Issueを前に進めるための作業場所です。
要求を整理したり、設計との対応関係を確認したり、実装計画を立てたりするために使います。
プロダクトドキュメントは、Issueが終わったあとも使い続ける知識の置き場です。
用語の定義、業務ルール、制約、非機能要件など、今後の開発でも参照したい前提を残します。
大きく分けると、Issueドキュメントには「そのIssueを進めるための情報」を置き、プロダクトドキュメントには「今後も参照したい情報」を置く、という分け方です。
変更後の構成は、たとえば次のような形です。
docs/product/
├── glossary.md
├── domain-rules.md
├── business-constraints.md
├── non-functional-requirements.md
└── features/
docs/product/には、今後も参照したい前提や、Issueをまたいで使う仕様を置きます。
作業中のIssueドキュメントはspecs/配下に置き、Issueが完了したらspecs/archive/へ移します。
ここで大事なのは、クローズしたIssueドキュメントを削除しないことです。
過去の検討経緯まで消してしまうと、あとから「なぜこの判断をしたのか」を追えなくなるためです。
そのため、過去のIssueドキュメントはspecs/archive/に残します。
ただし、普段AIに渡す文脈や、現在の仕様を確認する場所からは外します。
これで、現在の仕様を見る場所と、過去の検討経緯を見る場所を分けられるようになりました。
5. 何をプロダクトドキュメントに移し、何をIssueドキュメントに残すか
運用を変えるときに迷ったのは、どの情報をdocs/product/へ移すかでした。
今は、迷ったときに「次のIssueでも前提として参照したいか」で判断しています。
次のIssueでも参照したい情報なら、docs/product/へ移します。
たとえば、用語の定義、業務ルール、権限制約、他機能にも影響する画面仕様、非機能要件や運用上の制約などです。
一方で、そのIssueの中だけで必要だった比較メモ、途中で採用しなかった案、実装時に迷った内容は、無理にプロダクトドキュメントへ移しません。
そうした情報は、Issue完了後にspecs/archive/で参照できればよいと考えています。
すべてをきれいに整理しようとすると、運用が重くなります。
そのため、最初から完璧を目指さず、「次のIssueでも参照したいか」を基準にして、残す情報を選ぶようにしています。
6. この運用に変えて、何がよくなったか
一番よかったのは、目的によって参照先を分けられるようになったことです。
以前は、過去のIssueドキュメントを見るたびに、「これは今も有効な仕様なのか」「そのIssueだけの検討メモなのか」を読み分ける必要がありました。
今は、Issueをまたいで参照したい前提はdocs/product/を見る。
過去の判断経緯を確認したいときはspecs/archive/を見る。
この使い分けができるようになりました。
AIに渡す文脈も選びやすくなりました。
閉じたIssueの検討メモをまとめて渡すのではなく、今も有効な前提を中心に渡せるため、AIに不要な過去情報を読ませる場面を減らせました。
特に、AIに「現在の仕様を前提にして考えてほしい」ときに、どのファイルを渡すべきか判断しやすくなったのは大きいです。
以前は、過去Issueの中から今も有効な情報を探して渡す必要がありました。
今は、まずdocs/product/を渡し、必要に応じてspecs/archive/から過去の経緯を補う、という使い分けができます。
一方で、Issue完了後に、今後も残すべき内容をdocs/product/へ反映する手間は増えました。
何をプロダクトドキュメントへ移すかは、今も運用しながら調整しています。
それでも、「今の仕様」と「そのときの検討メモ」を同じ重さで並べ続ける状態は減らせました。
人が読む場合も、AIに文脈として渡す場合も、「まず何を見るべきか」を判断しやすくなったことが、この運用に変えて一番大きな効果でした。
7. おわりに
SDDを導入して感じたのは、仕様を書くことだけでなく、書いた仕様をどう残すかまで考える必要があるということでした。
Issueドキュメントは、Issueを進めるためには便利です。
ただ、Issueが終わったあともそのまま積み上げ続けると、現在の前提と過去の検討経緯が混ざりやすくなります。
今回は、Issueドキュメントとプロダクトドキュメントの役割を分けることで、この状態を見直しました。
同じような運用を試すなら、最初から大きく変えなくてもよいと思います。
まずは直近で完了したIssueドキュメントを1つ見直して、「次のIssueでも前提として参照したい情報」だけをdocs/product/へ移してみる。
それだけでも、現在の仕様と過去の検討経緯を分けるきっかけになります。
同じように、SDD導入後の仕様ファイル運用で悩んでいる方の参考になればうれしいです。
少しでも参考になったら、いいねやストックをしてもらえると励みになります。