はじめに
ども！AIとの開発をがっつり初めて2か月で毎日Claude Codeとお話している龍ちゃんです。本業とは別で開発を進めているのですが、今まで1週間で頑張って1件の検証開発しかできなかったんですが、2日で検証したいことをサンプル付きで作成できるので最高ですね。これまでの開発経験で技術記事も数多く書いてきましたが、今回は特に効果を実感したAIとの協働について書いていこうと思います。
ちなみに「Claude Code革命！3フェーズ開発で効率的な開発：計画→実装→検証術」Claudeに実装させるフェーズを分割して開発をする手法を紹介しています。今回はそこの計画書執筆フェーズのお話です。
皆さんは、仕様書を書くことに対してどんな印象をお持ちですか？正直に言うと、入社して4年ですが、いまだに仕様書を書くという作業に対して苦手意識があります。仕様書を書くのが好きというエンジニアに個人的にあったことがありません。「完璧な仕様書を書くぞ～！」というモチベーションを持ったとしてもアレルギーといいますか、「完璧な仕様書」というものを書くのはハードルが高いですね。
背景・課題説明
仕様書が必要な理由
その一方でAIと共同で開発を進めていくためには「仕様書」があったほうが良いです。コード規約やLinter/Formatterが整備されているプロジェクトであれば、コードが仕様書の機能を持つことがありますが、プロジェクト初期の段階であれば仕様書を読み込ませて開発をするほうが圧倒的に開発効率が良いです。Vibe Codingで単純なプロンプトで100-300文字のプロンプトで作成するのは不可能です。
機能開発中によくあるのが、検討不足や考慮不足によって開発中にSlackでの相談やミーティングを挟んだり、手が止まって考え込んだりすることではないでしょうか。コードの書き方で悩むのは問題ありませんが、事前に決めておくべき情報が未確定なために発生する手戻りは避けたいものです。
仕様書アレルギーの原因分析
仕様書を書くことに対してアレルギーがある原因を個人的に分析をしてみると、仕様書を読み込んだ経験があまりないことがあります。より良い仕様書を書くためには、良い仕様書のお手本が必要です。じゃあそのより良い仕様書ってどこにあるのって話ですよね。完璧超人が執筆した仕様書があれば理想ですね。（レビューなしで完璧な仕様書を書ける人がいるならあってみたい…）
そんな可能性はないので、プロジェクトではレビューを重ねてより良い仕様書を目指していくのが、普通の流れになると思います。ということを踏まえて、皆さんの周りに仕様書ってありますか？仕様書を読み込む経験ってあまりないんじゃないでしょうか？
技術選択の理由：なぜAIと協力するのか
そこで提案です！小さく仕様書を書いてみませんか？いきなり完璧な仕様書なんて不可能ですし、レビューアーを確保するのも大変ですよね。そこでAIを活用します。
AIを活用した仕様書作成フロー
AIに仕様書を書いてもらい、それをレビューする。私たちは意図を伝えて仕様書を作成してもらい、人間がレビュアーとして参加し、AIと協力する形で仕様書を作成していくフローです。
実装詳細
CLAUDE.mdの具体的な記述例
前提としてAIはコードを書きたがります。設計段階では、目的や禁止事項をCLAUDE.mdに定義しています。
実際に私が使っているCLAUDE.mdの中身を見てみましょう：
# 設計フェーズのルール
## 目的
AIに人間の意図を適切に伝えて効率的な開発を行う
## 設計フェーズで行うこと
- 型定義の設計
- データベース構造の設計
- API 仕様の定義
- アーキテクチャ設計
- 機能要件の明確化
- 非機能要件の定義
## 設計フェーズで禁止すること
- ❌ 実装コードの記述禁止
- ❌ 具体的なロジックの記述禁止
- ❌ ライブラリの選定禁止
- ❌ 具体的な関数実装禁止
## レビューポイント
- 要件の抜け漏れはないか
- 設計の整合性は取れているか
- スケーラビリティは考慮されているか
- セキュリティ要件は満たしているかこのように明確にルールを定義することで、AIが設計に集中してくれます。
仕様書作成の具体的な手順
- 要件の整理：何を作りたいかを箇条書きで整理
- AIとの対話：CLAUDE.mdのルールに基づいて仕様書を依頼
- レビューと修正：作成された仕様書を人間の視点でレビュー
- 反復改善：不足部分や曖昧な部分を繰り返し修正
仕様書のテンプレート例
# 機能仕様書：[機能名]
## 概要
[機能の目的と概要]
## 機能要件
- [要件1]
- [要件2]
- [要件3]
## 非機能要件
- パフォーマンス要件
- セキュリティ要件
- 可用性要件
## データ構造
[必要なデータ構造の定義]
## API仕様
[エンドポイントの定義]
## 制約事項
[技術的制約や業務的制約]動作確認・検証
実際の効果を検証してみた
従来の開発フローと比較してみました：
| 項目 | Before（従来の人間だけでの開発） | After（AIと協力した仕様書駆動） |
|---|---|---|
| 仕様検討 | 開発中に随時（割り込み多数） | 事前に1-2時間 |
| 開発時間 | 1週間 | 2日 |
| 手戻り回数 | 平均3-4回 | 平均1回 |
特に開発時間の短縮と手戻り回数が顕著に現れました！
まだまだ検証中の段階なので、小規模な検証なことは留意しておいてください。
AIと協力する副次的効果
仕様書を書くことの効果は、開発前に作成したい機能の整理ができることです。
AIと一緒に仕様書を作成する副次的効果として、AIが作った仕様書をレビューする経験が得られます。仕様書の段階で、こちらの意図が適切に伝わっていなければレビューして修正します。これにより開発前に検討不足や考慮不足を抑えることができます。完璧なレビューは不可能ですが、それは経験を重ねることで改善していくものですね。
成功事例：実際のプロジェクトから
最近の検証プロジェクトでは、以下のような成果が得られました：
- ユーザー認証システム：仕様書作成1時間 → 実装1.5日
- データ分析ダッシュボード：仕様書作成2時間 → 実装2日
- API統合機能：仕様書作成1.5時間 → 実装1日
いずれも従来の3-4倍の速度で完成させることができました。
課題と今後の展望
現在の制限事項と改善案
まだ完璧ではありません。AIの理解度に依存する部分があり、複雑な業務ロジックは人間の補完が必要です。また、チーム内での標準化やレビュー観点の統一も課題ですね。
短期的には仕様書テンプレートの標準化とAIプロンプトの最適化を進めています。いっそのこと、将来的にはAIが要件定義から運用まで一貫してサポートしてくれるような環境を構築したいですね。
まとめ
今回は、AIと協力した仕様書作成フローについて詳しく見てきました。
「仕様書アレルギー」を克服し、効率的な開発を実現する方法として：
- 小さく始める仕様書作成：完璧を目指さず、まずは基本的な要件から
- AIとの協働レビュープロセス：AIに作成してもらい、人間がレビューする
- 設計フェーズでの明確なルール設定：CLAUDE.mdでの禁止事項と目的の明示
- 段階的な開発プロセス：設計→開発→ブラッシュアップの3段階
これらの知識を活かして、皆さんもAIと一緒に仕様書作成にチャレンジしてみてください！最初は慣れないかもしれませんが、開発効率の向上を実感できると思います。
実際のプロジェクトでどちらを選ぶべきか、迷うところですよね。でも、一度この方法を試してみれば、その効果を実感していただけるはずです。
次回は、実際の開発フェーズでのAI活用術について書く予定です。お楽しみに！
