AIに設計書・コード・テストを全部書かせたとき、現場で起きること
AIが「全部書ける」時代に、何かがずれている
最近、「AIに設計書もコードもテストもすべて書かせて半年間開発してみた」という体験記が話題になった。読んでいて、「ああ、これは多くのチームが辿る道だな」と感じた。
AIが実際に動くコードを書ける。テストコードを自動生成できる。設計書の下書きも作れる。それは事実だ。でも、現場で試してみると「なんか思ったより大変だった」という感想になりがちだ。
なぜか。
結論から言うと、AIは「書けるか書けないか」の問題ではなく、「何を書かせるか」の問題だ。設計書・コード・テストのどれを自動化するかより、それらをつなぐ「意図の構造」をどう管理するかのほうが、はるかに重要だということを、現場で痛感している。
半年試して、何が起きるか
AIに開発の上流から下流まで一貫して任せた場合、最初の数週間は非常に順調に見える。コードは出てくる。設計書もそれらしい体裁になる。テストも通る。
ところが、2〜3ヶ月が経った頃から、特定のパターンが現れ始める。
1. コードと設計書が静かに乖離していく
AIが生成した設計書は、コードを書いた瞬間の状態を反映している。しかし開発が進み、仕様が変わり、リファクタリングが入ると、設計書はその変更を追いかけない。
人間がコードを書いていた頃でも同じ問題はあった。ただ、AIがコードを書く速度は人間の5〜10倍速い。変更の速度が上がるほど、設計書の陳腐化も加速する。
「設計書を更新してください」とAIに頼むと、確かに更新してくれる。でも、そのAIは「現在のコードがどういう意図で書かれているか」を本当に理解しているわけではない。コードを読んで、それっぽい説明を生成しているだけだ。
結果 として、設計書とコードは「表面的には似ている」けれど「意図は違う」という状態になる。
2. テストが通っているのに品質が怪しい
AIが書いたテストは、AIが書いたコードに対して非常に相性がいい。そのコードの実装に合わせてテストを書くので、当然カバレッジは高くなる。
問題は、テストが「コードが何をしているか」を検証しているのか、「コードが何をすべきか」を検証しているのかが、曖昧になることだ。
実装に引きずられたテストは、実装が間違っていても通る。「動いている」と「正しい」は別の話だ。この区別をつけるためには、「あるべき動作」を独立して定義する必要がある。それが設計書であり、仕様だ。
3. 変更が怖くなる
半年経つと、多くのチームが「大きな変更に踏み切れなくなる」という状況に陥る。
コードもテストもAIが書いており、設計書との整合性は曖昧。何かを変えると、どこに影響が出るかがわからない。AIに「この変更の影響範囲を教えて」と聞いても、コードを読んだ推測しか返ってこない。
つまり、スピードが上がるほど、変更のコストも上がっていくという逆転現象が起きる。
問題の根っこは「上流」にある
これらの問題には、共通の原因がある。
設計書・コード・テストのどれを自動化するかという話ではなく、それらをつなぐ「意図」が明示されていないことだ。
AIは与えられたコンテキストに基づいて出力を生成する。コードを書けと言えばコードを書く。テストを書けと言えばテストを書く。設計書を書けと言えば設計書を書く。
しかし、「なぜこの機能が必要なのか」「この設計でどういう制約を満たさなければならないのか」「このテストケースはどういる要求を検証しているのか」という意図のレイヤーを、AIは自律的に管理してくれない。
管理の本質がここにある。
上流工程をAIに「任せる」と「使う」の違い
よく混同されるのが、「AIに上流工程を任せる」と「上流工程でAIを使う」という2つのアプローチだ。
任せる：AIが決める
- 「要件定義書を書いて」→ AIが自由に書く
- 「設計書にまとめて」→ AIがそれらしい文書を生成する
- 「テスト仕様を考えて」→ AIが網羅的なケースを列挙する
これは速い。でも、「AIが書いたもの」になる。チームの意図・制約・文脈が入らない。
使う：人間が決める、AIが整理する
- チームで合意した要件を、AIが構造化する
- 議論で出た設計の意図を、AIがドキュメントに落とす
- テストしたい「振る舞い」を人間が定義し、AIがテストコードに変換する
この違いは小さく見えるが、半年後の結果は大きく違う。
後者のアプローチでは、設計書はチームの意図の記録になる。コードはその意図に基づいて生成される。テストは意図した振る舞いを検証する。整合性が取れた状態が維持される。
「AIが読める仕様書」とは何か
ここで重要になるのが、「AIが読める仕様書」という概念だ。
AIが読めない仕様書というのは、人間の感覚では理解できるが、AIが処理しようとすると文脈が欠けているものだ。
例えばこんな記述。
ユーザー管理機能
- ユーザーの登録・編集・削除ができる
- 権限に応じた制御を行うこれを読んで「よし、コードを書こう」とAIに渡すと、AIはそれなりにコードを書く。でも、「権限に応じた制御」の具体的なルール、ユーザー削除時の関連データの扱い、エラー時の挙動などは、AIが推測で埋めることになる。
その推測がチームの意図と合っていれば問題ない。ずれていると、後でレビューや修正が必要になる。
AIが読める仕様書は、こういった「暗黙の前提」を明示する構造を持っている。
## ユーザー管理機能
### 権限モデル
- admin: 全操作可能
- editor: 自分以外の閲覧は可能、編集・削除は不可
- viewer: 閲覧のみ
### ユーザー削除時の挙動
- 論理削除（物理削除はしない）
- 関連するコメント・投稿は削除ユーザーのまま保持
- セッションを即時無効化
### エラーハンドリング
- 権限エラー: 403を返す（詳細なエラーメッセージは出さない）
- 存在しないユーザーへの操作: 404を返すこの構造であれば、AIは推測する余地がなくなる。意図通りのコードが出てくる確率が格段に上がる。
実務で使えるアプローチ
では、具体的にどう変えればいいか。
1. 仕様に「なぜ」を入れる
多くの設計書には「何を作るか」 は書いてあるが「なぜそう決めたか」が抜けている。
AIにコードを書かせる場合、「なぜ」がないと実装の方向性がぶれる。「レスポンスタイムを200ms以内にする」という制約があるなら、その理由（ユーザー体験の閾値）と優先順位（他の要件とトレードオフになるとき何を選ぶか）を明示するべきだ。
2. 変更の影響範囲を仕様レベルで管理する
コードの依存関係はAIが解析できる。でも、仕様の依存関係は明示しないとわからない。
「このAPIの仕様を変えると、フロントエンドの画面Aと、バッチ処理Bに影響する」という関係を、仕様書レベルで記録しておく。これにより、変更時にAIが「この変更の影響範囲」を正確に把握できるようになる。
3. AIとのレビューサイクルを短くする
設計書→コード→テストという大きな単位で任せるのではなく、「この関数の仕様を確認してからコードを書く」というサイクルを短くする。
一度に大量のコードを生成させると、後からずれを修正するコストが大きくなる。小さい単位で意図を確認しながら進むほうが、結果的に速い。
なぜ上流が重要か、改めて
AIがコード を書ける時代になって、上流工程の重要性は下がっていない。むしろ上がっている。
コードは生成できる。テストも生成できる。でも、「何を作るべきか」「どういう品質を担保すべきか」という意思決定は、AIには代替できない。
そして、その意思決定をAIに正しく伝えるためのフォーマット、つまり「構造化された仕様書」の重要性が、AIが普及するほど際立ってくる。
「AIに全部任せてみた」という実験の結論が「やっぱり上流が大事だった」になるのは、偶然ではない。AIが高速にアウトプットを生成できるからこそ、インプットの質が問われる。
まとめ
AIに設計書・コード・テストをすべて書かせる実験から見えてくるのは、自動化の難易度ではなく、意図の伝え方の問題だ。
- 設計書とコードの乖離 → 仕様の構造化が解決する
- テストが通るのに品質が怪しい → 「あるべき振る舞い」の明示が解決する
- 変更が怖くなる → 仕様レベルの依存関係管理が解決する
AIを活用した開発で本当に必要なのは、「AIに何かを書かせる技術」よりも「AIが理解できる仕様を作る技術」だ。
アツメルが開発している Kakusill は、この「AIが読める仕様書」の作成・管理を支援するためのプロダクトだ。要件定義の段階から仕様を構造化し、AIとの協働を効率化することを目指している。AIを使った開発をさらに加速させたい方は、ぜひ試してみてほしい。
