👨‍💻

【個人開発】AI とペアプロして「コンテキストエンジニアリング」を意識したら、開発体験がよくなった話

に公開
個人開発
Gemini
コンテキストエンジニアリング
idea

はじめに

こんにちは、個人開発で英語学習アプリ「wata-voca」をリリースした 鮭のあて です。

今回は、アプリの技術的な話ではなく、「どうやってAI（Gemini 3.0 Pro）と協力して開発を進めたか」 という 「開発プロセス」に焦点を当ててみたいと思います。

AIコーディング支援ツールが当たり前になってきましたが、

  • 「指示した通りのコードが出てこない」
  • 「修正を頼むと、別の場所が壊れる」
  • 「会話が長くなると、AIが前の設定を忘れる」

こんなことがよくありました。

しかし今回のプロジェクトでは、「コンテキストエンジニアリング（ドキュメント駆動開発）」という手法を（見よう見まねで）試してみたところ、開発スピードと品質が劇的に変わりました。
「AI(ちょっとコミュニケーションが苦手なエンジニア)」とうまく付き合うための、私の試行錯誤の記録を共有します。

なぜ「コンテキスト」が大事だと感じたか

まず、対比としてプロンプトエンジニアリングだと以下のような問題が多々起きていました。

  • 「あれ、さっきAって言ったのに、なんでBの実装になってるの？」
  • 「そのライブラリは使わないって言ったじゃん…」

これは一つのチャット内トークンを使い尽くし、AIが以前の情報を忘れてしまっていることが原因です。

優秀なエンジニアでも、口頭で「いい感じにやっといて」と曖昧に指示されたら困りますし、仕様書が残っていなければ直すのにはとてつもない工数がかかります。
ましてやAIは、「技術力は超一流だが、空気を読むのが少し苦手な『The 理系エンジニア』」タイプの人材だと思っています。(個人の意見ですのでご理解ください。。)

そのため必要なのは、曖昧な指示ではなく、「いつでも参照できる、正確な仕様書（コンテキスト）」です。

私が試した4つの「コンテキスト・エンジニアリング」

今回、私が意識して実践したのは以下の4点です。

1. ファイル構造で「話の区切り」を作る

今回は徹底してフォルダ分けしました。

docs/
├── requirements/      # 要件定義
├── design/
│   ├── overview/      # 概要設計
│   ├── detailed/      # 詳細設計
│   └── common/        # 共通仕様
└── ...

こうすることで、AIに指示を出すときに
「認証機能については docs/design/detailed/auth.md を読んで実装して」
と明確に参照先を指定できます。

関係ない情報をAIに読ませない（ノイズを減らす）ことで、回答の精度が目に見えて上がりました。

2. まずドキュメントを書いてもらう（ドキュメント駆動）

ここが一番のポイントです。
「いきなりコードを書かせない」 というルールを自分に課しました。

私が実践したフローはこんな感じです。

  1. ディレクトリ構成の提案: まず「どんなファイルが必要？」とAIに聞いて、mkdir してもらう。
  2. 概要設計の作成: 空ファイルに、AIに設計内容（マークダウン）を書かせる。
  3. 人間によるレビュー:
    • ここが重要です！ AIが書いた設計書を私が読みます。
    • 「認証にはSupabaseを使いたいから書き直して」「エラーハンドリングの仕様が抜けてるよ」と突っ込みます。
  4. 実装: 設計書の認識が合って初めて、コーディングを依頼する。

実際、共通機能の定義ファイル (common_functions.md) を作成する際、私の意図と違う内容が提案されたことがありました。
その場で「共通機能とはAPIだけでなく、ロガーやエラーハンドリングも含めてほしい」と指摘し、ドキュメントを修正してもらいました。

この 「設計段階でのすり合わせ」があるおかげで、いざコードを書く段階での手戻りが激減しました。

3. TODOリストで「今なにやってるの？」を共有

AIは爆速で資料作成やコーディングをしてくるため、どこまで進めてくれたのかがわからなくなることが多々あります。
そこで、docs/todo.md を作成し、常に現在のタスク状況を記録するようにしました。

工夫したのは、単にTODOを羅列するのではなく、以下のように開発フェーズ（Phase）ごとにタスクを分割したことです。

# TODO List

## Phase 1: 要件定義・概要設計
- [x] 要求分析 (requirements/business_requirements.md)
- [x] システム構成案の作成 (requirements/system_requirements.md)

## Phase 2: 詳細設計
- [ ] DBスキーマ設計
- [ ] API設計

## Phase 3: 実装
...

こうすることで、「今はPhase 1が終わったから、次はPhase 2のこのタスクだね」と、AIと私の間で現在地と次のタスクの認識を常に合わせることができました。
進捗が見える化されるのは精神衛生上も安心できるやり方だったと思います。

4. 仕様の共通化 (DRY)

プロンプトエンジニアリングの要件なども、毎回チャットで打つのではなく、docs/design/common 配下のファイルにまとめました。
また、Antigravityを利用していたので、プロジェクト内のルールは 「Customizations」の設定からあらかじめ指定するようにしておきました。

まとめ

最初にドキュメント環境を整えたり、設計書を書いたりするのは、一見遠回りに見えます。
でも、その「コンテキスト」さえ共有できていれば、AI は爆速で正確なコードを書いてくれます。

「AIは優秀だけど指示出しが難しい…」と感じている方は、ぜひ 「AIと人間を繋ぐドキュメント作り」を試してみてください。
きっと、彼らは頼れる「最高の相棒」に変わるはずです。

最後まで読んでいただきありがとうございました。

余談ですが、今回の開発手順で作ったアプリが以下になります。
よければ触っていただけると嬉しいです！

https://wata-voca.com

Discussion