仕様駆動開発はやめた方がええ
前回記事から1ヶ月くらい経ったのでその間に得られた知見からの所見を述べる。
やっぱり実装に関するドキュメントはいらん。仕様は全てコードにある。コードをSSoT(Single Source of Truth)とすべきだ。ドキュメントとコードの二重管理はコストが大きすぎる。特にドキュメント側の管理コストが大きく、どれだけagentにドキュメントを修正しろと指示を出してもドキュメント修正の実行が確率的であるし、ドキュメントを更新するトークン数が無駄。コード読めばわかることを自然言語にわざわざ起こさんでいい。仕様がわからんくなったらclaudeに聞けばいいのでドキュメントを永続化する必要性が皆無すぎる。ドキュメント書かせるくらいならclaudeさんに感謝のメッセージを送った方がいい。限りある電力を無駄にするな。結論として仕様駆動開発はウソです。少なくともおれにとってはウソでした。手間の割に効用を実感しがたすぎる。
任意のドキュメントがいらないかというとそうではない。まず、プランファイルはあった方がいい場合がある。特に、compactionが起きるようなロングランの実装では最初に立てたプランを永続化しないとcompactionで実装計画や受け入れ条件を忘れる。なので外部化する手段としてドキュメント化は有効。ただし、このドキュメントは短期的なもので実装が終わったら速やかに破棄していい。おれは .claude/plans をそもそもgitignoreしてる。ドキュメント不要過激派の場合はgithubのissueに逃して永続化するのもおすすめ。これならローカルにドキュメントを一切残さないで済むのでclaudeがignoreされてるplanファイルを読んでコンテキスト汚染されることを防げる。
ビジネス要件とかはドキュメント化すべきだろ、という話もあるが、おれはこれは半々くらいです。ケースによってはあってもいいかもね、くらいの気持ちでいる。ビジネスロジックであるならコードの中にインラインコメントするなりdocstringに埋めるなりすれば良く、ドキュメントとして独立させる旨みはそんなにない。コードに近接したところに置くことでビジネスロジック変更時にagentが迷わずdead codeを粉砕できるようになるという利点もある。コメントやdocsrtingをドキュメントに含めるとおっしゃるならばビジネス要件に関してはドキュメントが必要です。あとはあれですね、全体に通底する横断的なビジネス要件（PIIの持ち方とかレスポンス速度とか）に関しては CLAUDE.md に書いといた方がいい気はします。
またおれの中で CLAUDE.md, skills, rules に関してはドキュメント枠に入ってません。実装の手続きのドキュメントはガシガシ作るべきです。自分好みのagentの挙動を再現性を持って行わせるためにはこの辺りの整備は必須です。おれは CLAUDE.md を整える行為を盆栽と呼んでいます。
微妙なラインがrunbook（運用マニュアル）で、これはskillにしちゃえばいいんじゃない？という気持ちです。人が介入するにしてもskillのワークフローの中で人間をagent呼び出しすればいいんでね。なのでこれも原則不要派です。少なくともskill以外に明示的に置く意味はない。ただし、物理的にサーバーいじる必要あるとかそういうプロジェクトではあっていいと思います。少なくともclaudeに向けたrunbookをskill以外に置く必要ないよね、という認識です。
あとclaudeに聞いたら「アーキテクチャの全体図とかはあってもええんちゃう？」と言っていたけど、これはどうなんだろ。IaCでインフラ管理してるなら実装見りゃいいし。IaCの管理から漏れる場所があるのであればそれは部分的にドキュメント必要ですね。でも基本はIaCで全管理だしいらんでしょ。多分。
Discussion
アジャイルならこんなもんだろうね。
ただ、新しいメンバーが入ると一気にペースが崩れるので、
設計資料はあった方がいいと思う。
いちいち説明しなくても「これ読んでおいて」で済むし、
ある程度の規模になるとシステム全体を理解するのは
時間も手間もかかるからね。
それと、コメントが増えるとコードが汚くなるので、
そのあたりはほどほどがいいかな。
ならば新人向けにリポ説明を動的に作成するskillを置けばいいと思います
新人にはリポ情報渡して、AI使ってキャッチアップする世界観
仕様駆動での仕様書はコードを書く前のスケッチのようなもので、実装後は破棄というか凍結したら良いのではと思いました。変更が必要になったら新しく差分だけ書くとか。
それは仕様駆動とは呼ばないのではないですか？
マスター仕様書を作らないタイプもあるので試してみたらどうでしょ。cc-sdd とか
自分も仕様書は無視したコードは書くし、管理コストは上がるしでいるのか？と思っていました。
普通にclaudeが読むものではなく人間が読むものでいいんじゃね？と思いました。
この記事を見てスッキリしましたm(_ _)m
コードと一対一対応したドキュメントは私も不要だと思いますが、
複数ファイル読まなければ分からない概念を1つのドキュメントに端的にまとめておくと、
ClaudeCodeが読むトークン量を減らせるので使い方次第ではないかと思いますよ。
コンテキストをcompactした情報をキャッシュとして残しておくようなドキュメントです。
記事の問題意識である「ドキュメントとコードの同期コストが高い」という点にはすごく共感します。
ただ、この記事で批判されているのって「仕様駆動開発」というより、実装ドキュメントの運用の話になっている気がしました。
例えば「必要ならdocstringに書けばいい」という話は、コードの意図や説明を書く方法としてはその通りだと思います。
ただ、それって「仕様」の代わりにはならないですよね。
仕様って本来は、APIの振る舞いとか外部連携時の取り決め、要求される性能の要件や制約みたいな、コードが満たすべき外側のルールだと思っています。
docstringはあくまで「このコードはこういう意図で書いてます」という実装側の説明なので、役割が少し違う気がしました。
なのでこの記事は、仕様駆動開発そのものの話というより、
コードと実装ドキュメントの同期コストの問題に近いのかな、という印象です。
私も概ね同意です。
この記事の指す「仕様」が「実装の翻訳・要約ドキュメント」と狭義に捉えられているのではないかと思います。
Howを多く記述すると、割とそれだけで翻訳・要約ドキュメントっぽくなりますね。
本来はWhy/Whatを中心にしたものを仕様と言うのだろうなと思います。
あくまでも私の観測範囲だけの余計なことを言いますが、日本出身エンジニアの仕様書って割とHow傾向が強い傾向にある気がします。欧米出身エンジニアは割とWhy/Whatを仕様と呼んでいます。彼らと20年くらい一緒に働いてきた僕目線の統計的な感覚値ですが…。本来のSpecification-Drivenは、そう言う意味なんじゃないかなと思います。
How傾向が強いことに同意です。
すぐに「どう実現するか」ばかり考えてしまい、結局それが「なぜ必要だったのか」や、「何を要求されているか」を忘れてしまう方が多い気がします。
これは、仕様と設計、要求と要件を混同する方が多いのも要因のひとつなのかなと感じています。
おっしゃっていることはSDDではなく単なるヴァイブコーディングの範疇の話に見えます。実装の翻訳がいらないのはその通りですが、ソースコードをSSOTとするなら、何を元にそのソースコードは作られたのかという話になります。AI開発は、各フェーズの承認ゲートの質にも左右されますし、そもそも一発で100%の完成度が出るはずがないので作ってから手直しが発生するのは当然です。そのため何を正とするかの評価指標として仕様が存在すると思っています。(動く動かないだけの話ではなくユーザストーリーの受け入れ基準も含め。特に非機能要件はソースコードでは読み取れません。)
仮にソースコードが常に真であるとした場合に、何を正解としてテストは実施するんでしょうか。冗談ではなくバグと仕様の区別すらつかないなんてことになりかねません。
お仕事なので指示書の通りに働くのは必然と言えます。
課題は指示書の質やそれに従う実装者の質かと思います。
指示書に執念を込めるのはたいてい夢みがちな上級サラリーマンで、それを受け止めるのは無自覚にキーボードを叩くだけの実装者である事が多いです。
どちらも役割に対して忠実ですが、双方、あるいは業界全体としての課題は実装技術の軽視でしょう。
設計書をはじめとするドキュメントも、試行錯誤を続けながら正解から遠ざかっていく開発プロセスも実装技術に着目できない事が不毛な議論と試行を繰り返しているように見えます。