システム開発を進める中で、 「仕様書とコードの整合性が取れなくなる」 というのは、多くのエンジニアが直面する課題です。
昨今のAI技術の発展により、コーディングや仕様書の作成は劇的に効率化されました。しかし、AIに頼りすぎるあまり、指示を重ねるごとにコードが複雑化したり、意図しない修正が紛れ込んだりして、かえって管理が難しくなった経験はないでしょうか？ また、AIが生成したコードに合わせて仕様書を手動で更新するのが面倒になり、結局仕様書が形骸化してしまうことも少なくありません。
この記事では、仕様書とコードの整合性を常に保ちながら、AIを「迷わせない」ようにコントロールして機能追加を進める開発フローの一例を紹介します。AIにコードを書かせる前に、まずAI自身に仕様書を更新させることで、常に最新のドキュメントを維持しつつ、精度の高いコード生成を実現する方法を解説します。
対象の読者
- 最近AIを使ってプログラミングすることを検討している、または始めてみた人。
- AIにいまいち思ったような結果を出させられず、「そうじゃなくてこんな感じで...」という会話を重ねて疲弊している人。
- 指示していないつもりの部分も、AIが勝手にソース修正してしまい困っている人。
- 「 AIにコードを書かせるのはいいが、仕様書がどんどん古くなっていく 」というジレンマを抱えている人。
開発フローの概要：AIに「仕様書」を育てさせる
結論から言うと、AIにいきなりコード生成させるのではなく、まず仕様書を作成・更新させ、その仕様書をもとにコードを書かせる という手順を踏みます。
具体的には、実現したい機能について以下のステップを分けて指示します。一度の会話でお願いするのはいずれかのステップのみにするのがポイントです。
-
方針の相談: 「〇〇機能を追加したい。どのような方法がありますか？」
→ AIが仕様レベルで案A、案B、案Cを回答。 -
仕様変更の指示: 「案Bでいきたいです」
→ AIが 仕様書ファイル を更新。 -
コード反映の指示: 「仕様書の更新も問題ないようなので、コードに反映して」
→ AIが実際のソースコードを修正。
このサイクルを回すために、ステップごとのルールと仕様書を1つのファイル（以下 ai_context.md）にまとめておき、会話の先頭で読み込ませてから各ステップの指示を行います。
実践！ステップバイステップで構築する
では、実際にどのように進めるのか、筆者が PHP と MySQL で掲示板を作ってみた際の例をもとに解説します。
筆者は VSCode と Gemini Code Assist を使いましたが、Cursor や GitHub Copilot など、プロジェクト内のファイルをコンテキストとして読み込める AI ツールであれば、同様のフローで進めることが可能です。
VSCode と Gemini Code Assist の環境構築については、以下の記事などが参考になります。
Step 1: 共通ルールファイル ai_context.md の作成
まず、AIがプロジェクトの全体像や振る舞いを正しく理解するためのコンテキストファイル ai_context.md を作成します。このファイルには、ステップごとのルールと、仕様書を記載します。AIとの会話の最初に読み込ませるファイルで、フォルダやファイル名に特に決まりはありません。
開発をスタートする段階では、ステップごとのルール部分は以下をコピペ、仕様書部分は大まかにやりたいことを記述しておけば十分です。あとはAIが書き足していってくれます。
コピペ用: ai_context.md の初期イメージ
Gemini Code Assist 向けの指示テキストです。
- 方針の相談の時:
- ai_context.mdもソースコードも修正しないようにしてください。
- 仕様変更の指示時:
- ai_context.md のみを修正し、他ファイルは変更しないでください。
- 修正が必要なファイル一覧を報告してください。
- コード反映の指示時:
- ai_context.md の内容に従い、対象ファイルを修正してください。
# プロジェクト概要
さくらのレンタルサーバ上で動作する、スレッド形式の掲示板の開発。
# 技術スタック
- PHP 8.1.29
- MySQL 8.0
# ディレクトリ構成
提案してください
# 機能要件
提案してください
# データベース設計
提案してください
上記からスタートして、筆者が実際に掲示板を作る過程で後述の Step 2~4 を繰り返した結果、AIが育ててくれた ai_context.md は以下のようになります。
仕様書部分はほぼAIが書いてくれています。必要に応じて、ステップごとのルール部分も修正しています。
（参考）AIが育てた後の ai_context.md 全文はこちら
https://github.com/yymmt/bbs-test/blob/main/docs/ai_context.md
仕様書の細かい部分は、システム開発の初心者には難しく感じるかもしれませんが、後述の Step 2〜4 を繰り返す中でAIが解説してくれるので、少しずつポイントが分かってくると思います。最初は、「AIがシステムの全体像を把握するためのメモなんだ」くらいの認識でもOKです。なお、AIへの指示の中で、以下のようなポイントを意識して、AIが迷わず書けるように仕向けることで、回答精度がより安定します。
1. 技術スタックの明記
AIが迷わないよう、使用するライブラリやバージョンを固定します。サーバー環境などでバージョンが決まっているものは明記すべきですが、CDN経由で常に最新版を利用したいライブラリなどは、あえてバージョンを書かずに「最新版を使用」と指示するのも手です。
# 技術スタック
- PHP 8.1.29
- MySQL 8.0
:
直接バージョン番号を書かなくても、「さくらのレンタルサーバのスタンダードプランでデフォルトで使えるPHPとMySQLのバージョンで」といった指示でも、AIが上記を書いてくれることが多いです。
2. 制約事項を明確化
「何をやらないか」を明確にすることで、AIの過剰な提案や、プロジェクトの方針に合わないコード生成を防ぎます。
# 制約事項
- Laravel等のフレームワークや外部ライブラリは極力使用しない（標準関数中心で実装）。
- ソースコードへのコメント記述は最小限にする。
:
筆者は、今回は「ファイルが増えすぎない方がAIにとって分かりやすいのではないか」と考えフレームワークを極力排した方針にして進めていましたが、後述するようにAIはフォルダ構成も把握してくれるので、フレームワークありでも特に問題なさそうです。
3. データ構造（DB設計）の明示
これがあることで、AIはバックエンドとフロントエンドの整合性を保ちやすくなります。テーブル定義やカラム名が明記されていれば、SQLの生成ミスも激減します。
# データベース設計 (詳細設計)
## posts テーブル
- id: INT AUTO_INCREMENT PRIMARY KEY
- thread_id: INT NOT NULL
- user_uuid: VARCHAR(36) NOT NULL
- body: TEXT NOT NULL
:
開発初心者にとっては、どういうテーブル構造がよいのか、型とは... 正規化とは... といったところが難しいかもしれませんが、後述の 相談 のステップでAIと相談しながら、やりたいことを細分化していく中で適切なテーブル構造をAIが決めてくれます。
4. ファイル一覧の管理
「どのファイルに何が書かれているか」の地図を持たせることで、AIが迷子になるのを防ぎます。プロジェクトが大きくなると、全てのファイルを一度にAIに読み込ませるのは難しくなりますが、この一覧があれば、AIは 「どのファイルを読み込むべきか」を自分で判断できる ようになります。
# ディレクトリ構成
- /docs/
- ai_context.md
- /public/
- index.html
- main.js
- style.css
- api.php
:
今回はファイルが増えすぎない構成で説明しています。採用するフレームワークによって、フォルダ構成は大きく変わりますが、これもAIと相談していく中でAIが書いてくれます。
Step 2: 方針の相談
準備ができたら、開発を始めましょう。VSCodeで Gemini Code Assist パネルを開き、ai_context.md を添付（@ で指定）して、「方針の相談」をしてみます。以下は、すでにある程度開発が進んだ状態からの機能追加を例に説明しますが、まっさらな状態から開発を始める場合は、はじめに作りたい最小限の機能について「方針の相談」をしてみてください。
会話例:
User:
@ai_context.md
掲示板に「いいね」機能を追加したいです。どのような実装方針が考えられますか？
「方針の相談」として回答してください。
Gemini:
「いいね」機能の実装方針として、以下の3案を提案します。
- likesテーブル作成案: ユーザーIDと投稿IDを紐付けるテーブルを作成する（正規化された設計）。
- postsテーブルにカラム追加案: カンマ区切りなどで保存する（簡易的だが拡張性が低い）。
- ...
ここでAIはコードを書きません。あくまで設計の相談相手になってもらいます。
このように、AIの振る舞いを意図的に制限しておくことがポイントです。これがないと、AIは気を利かせて一気にコード生成まで進んでしまうことがあります。
よくある失敗例として、「こういう機能が作りたい」という指示に対して、AIが即座に生成したコードをそのまま取り込んでしまうケースがあります。しかし、対話を重ねるうちに、既存コードの細かな作法や意図を無視した「それっぽいだけの修正」が積み重なり、プロジェクトが収拾のつかない状態に迷走し始めることが多々あります。
「相談の時は相談だけ」とフェーズを区切ることで、こうした 「AIによるコードの継ぎはぎ」 を防ぎ、一貫性を保つことができます。
VSCodeでの操作は以下のようになります。
「いいね」機能1つとっても、仕様として落とし込む際には上記のように様々な考慮ポイントがあることがわかります。 「誰が」「いつ」「どの投稿に」 いいねしたかを管理するのか、といった細かい部分でも、認識の相違が後から雪だるま式に大きくなって、修正が困難になる場合があります。仕様修正やコーディングに入る前に、AIとイメージをすり合わせることが非常に重要です。
Step 3: 仕様書の更新
方針が決まったら、AIに仕様書（ai_context.md）を更新させます。
会話例:
User:
案1の「likesテーブル作成案」で進めます。「仕様変更の指示」として、ai_context.mdを更新してください。
Gemini:
承知しました。ai_context.mdを更新します。
ここで人間が差分を確認し、問題なければファイルを保存します。これで「仕様書」が最新の状態になりました。
なぜコードより先に仕様書を直すのか？
AIは「直近の会話」を重視する性質があります。コードを先に直してしまうと、AIはその場限りの修正案に引っ張られ、プロジェクト全体の整合性を軽視し始めます。まず「正解」である仕様書を確定させ、AIに 「これからあなたが書くコードの根拠は、このファイル（ai_context.md）にある」 と認識させることで、デグレード（先祖返り）や矛盾したコードの生成を劇的に減らすことができます。
また、この時点でAIが「修正が必要なファイル一覧」を報告してくれるので、人間は影響範囲を事前に把握できるメリットもあります。
ここで人間がしっかりと仕様書の差分をレビューし、認識のズレを正すことが、後のコード生成の品質を決定づけます。
開発初心者には慣れない部分があるかもしれませんが、Step 2〜4を繰り返すうちに、「やりたいこと」と「仕様」の粒度の違い（こんなに細かいんだ！）が分かってくると思います。AIが回答した仕様の変更箇所を見て、実際にシステムがどのように動くか想像力を働かせ、 「まてよ、こういう順序で操作したら矛盾が生じるのでは...」 といったことにいち早く気がついて軌道修正することが肝心です。後になってから「実は1週間前のあの変更が問題だった」と原因を探るのは経験者でも大変ですが、「たった今の変更のここが問題だ」と気づければ修正は容易です。
次のステップはコード（プログラミング言語）の修正ですが、ここまでのステップは日本語でのやり取りですので、レビューのハードルが低いというのも大きなポイントです。
Step 4: コードへの反映
ai_context.md の仕様書部分が更新されたら、コードの生成を依頼します。
会話例:
User:
仕様書の更新内容に基づいて、実際のコードに反映してください。
「コード反映の指示」として実行してください。
Gemini:
承知しました。以下のファイルを修正・作成します。
db/migrations/002_create_likes_table.sql(新規作成)public/index.php(いいね数の表示とボタン追加)
...
AIは ai_context.md に書かれた最新の仕様（テーブル定義など）を参照しながらコーディングするため、整合性の取れたコードが出力されます。
Step 2〜4 を繰り返して成長させる
1つの機能が完成したら、また Step 2（方針の相談）に戻ります。これを繰り返すことで、ai_context.md はプロジェクトの成長に合わせて自動的に「最新の仕様書」として育っていきます。
もしAIが生成したコードが意図と違った場合は、コードを直接直すのではなく、Step 3 に戻って仕様書の記述をより具体的に修正させてください。そうすることで、AIの「勘違い」を根本から断つことができます。
開発をスムーズに進めるためのTips
仕様書に書ききれない「微調整」のコツ
「ボタンの余白をもう少し広く」といった、仕様書に書くほどではないがこだわりたいポイントは、ソースコードに直接 「// 微調整指示: 〇〇」 のようにコメントを残し、AIに「コメントの内容に従って微調整して」と指示するのが効率的です。
この例では「ボタンの余白の調整」をHTMLのコメントで指示していますが、既存のソースコードに応じて、HTMLのclass属性の修正が適切か、CSSの修正が適切か、AIが判断してくれます。
ai_context.md の肥大化について
Gemini 1.5 Pro の時点で、数万行レベルのコンテキストも問題なく扱えるようです。
筆者が実際に、スレッド機能、招待機能（QRコード含む）、ユーザー管理、Web Push通知、AIアシスタント機能（要約・チェックリスト生成）といった機能を盛り込んだ掲示板を作成した際も、ai_context.md は300行程度に収まりました。中規模な個人開発であれば、容量を心配する必要はほとんどありません。
ai_context.md にディレクトリ構成が明記されていれば、AIは修正が必要なファイルを自分で判断して読み込んでくれます。もし将来的にAIの反応が鈍くなったと感じたら、仕様が安定した共通機能を別ファイルに切り出したり、リファクタリングを行って「AIが一度に把握すべき情報量」を整理したりする工夫を検討してみてください。
一度に修正するコード量を制限する
Gemini Code Assist にコード修正を依頼する際、 「一度の回答でのコード修正は30行程度を目安とし、修正箇所が多い場合は分割して提示してください。続きがある場合は、ユーザーに『続きをお願いします』と促すようにしてください」 といった制約を書き添えると、コードの品質が向上するように思われます。
Gemini自身に聞いてみたところ、以下の3つのメリットがあるようです。
- 「注意の分散」を防げる: AIは一度に大量のコードを出力しようとすると、後半になるほど「計算リソース（アテンション）」が薄れ、変数名の書き間違いや論理的な破綻が起きやすくなります。範囲を絞ることで、1行あたりの精度（密度）を高めることができます。
-
コンテキストの劣化を防ぐ: 一度に出力できるトークン数には限界があります。長いコードを無理に1回で出そうとすると、途中で省略（
// ... rest of code）されたり、重要な前後の繋がりを無視したりすることがあります。分割することで、こうした省略によるバグを防げます。 - 「思考の連鎖」の維持: 「30行ずつ」という制約は、AIにとって適度なタスク分割になります。人間が「一気に全部やって」と言われるより「まずはここだけ完璧にして」と言われる方がミスが減るのと同様に、プロンプトエンジニアリングにおける「最小タスク化」が効果を発揮します。
現時点では、効率（スピード）が多少落ちるものの、確実性と品質が向上する有効なハック、と言えるかもしれません。（この辺も数年もしないうちに問題にならなくなる気もしますが。）
まとめ
このフローの最大のメリットは、「AIとの会話履歴」ではなく「仕様書ファイル」にプロジェクトの記憶を持たせる 点にあります。
チャット形式のAIは、会話が長くなると前の文脈を忘れたり、混乱したりしがちです。しかし、この方法なら常に「最新の ai_context.md」という正解を渡してから指示を出すため、開発が進んでもAIの回答精度が落ちません。
「急がば回れ」の精神で、いきなりコードを書かせずに仕様書を整備するこのフロー、ぜひ試してみてください。AIが単なる「コード生成機」から、頼もしい「開発パートナー」に変わるはずです。