Zenn
🍊

AI駆動開発の実践ガイド：Gemini CLIとのペアプログラミングによるNext.jsアプリ構築の全記録

に公開
AI
tech
CLI
Gemini
tech

はじめに

AI開発支援ツールが普及する中、その活用法はコード補完や単純な質疑応答に留まりがちです。しかし、AIの真価は、開発環境と連携し、プロジェクトの文脈を理解する「開発パートナー」として機能する際に発揮されます。

この記事は、Googleの「 Gemini CLI 」を、単なるツールとしてではなく、開発プロセス全体を共に進める「エージェント」 として活用し、Next.js製のWebアプリケーションをゼロから構築した実践記録です。設計、実装、トラブルシューティング、UI改善、ドキュメント作成まで、AIとの具体的な対話を通じて、その能力を最大限に引き出す方法を解説します。

完成したプロダクト

この開発プロセスを通じて完成したのが、この「色当てクイズゲーム」です。

Image from Gyazo

GitHubリポジトリ: https://github.com/kazuki13070311/color-quiz-game

第1章：Gemini CLIの基本原理 - AIとの対話の前提知識

Gemini CLIを効果的に活用するには、その論理的な思考と行動のサイクルを理解することが不可欠です。

1.1. Geminiの行動サイクル

Geminiは指示を受けると、「観測→方向付け→意思決定→行動→学習」 というサイクルを繰り返します。これは、状況を把握し（ls, pwd）、関連情報を収集し（read_file）、行動計画を立て、それを実行し（run_shell_command, write_file）、結果から学ぶという、自己完結したプロセスです。

1.2. プロジェクトの文脈を与える：GEMINI.mdの役割

GEMINI.mdは、AIにプロジェクト固有のコンテキストを教えるための重要なMarkdownファイルです。これはAIの行動指針となり、開発の一貫性と効率を大幅に向上させます。

主な役割:

  • 技術スタックの明記: 使用するフレームワーク、ライブラリ、パッケージマネージャー（例: pnpm）を定義します。
  • コーディング規約の設定: ファイル配置のルールやコミットメッセージの形式（例: Conventional Commits）などを指定します。
  • プロジェクト固有の指示: その他、AIに遵守してほしいルールや背景情報を記述します。

Gemini CLIは、カレントディレクトリから親ディレクトリを遡り、GEMINI.mdを階層的に読み込みます。これにより、プロジェクト全体の設定と、特定のサブディレクトリでの設定を使い分けることも可能です。

このプロジェクトで実際に使用したGEMINI.mdは、リポジトリのルートで確認できます。

第2章：設計フェーズ - AIとの対話による仕様の具体化

優れたプロダクト設計は、明確な仕様から生まれます。Gemini CLIは、抽象的なアイデアを具体的な設計図に落とし込むプロセスで、強力な壁打ち相手となります。

2.1. ユーザーストーリーからのアプローチ

「色当てゲームを作りたい」という最初の曖昧な要求に対し、Geminiはまず ユーザーストーリー の定義を提案しました。これは、AIが単に言われたことをこなすだけでなく、プロダクトの目的（Why）から思考を始める能力を持つことを示しています。

この対話を通じて、「プレイヤーが達成感を感じられる」「スムーズな操作性を持つ」といった具体的な目標が設定され、それが後の機能実装の指針となりました。

2.2. 設計のドキュメント化

議論を通じて固まった仕様は、構造化されたドキュメントとして出力させることが重要です。これにより、思考のプロセスが具体的な成果物として記録され、開発チーム（人間とAI）全体での共通認識が形成されます。

プロンプト例: 「ここまでの議論を基に、要件定義書とコンポーネント設計を含む、Markdownドキュメントを作成してください。」

このプロセスを通じて、docs/details.mdが生成され、後の実装フェーズで参照するべき「仕様書」となりました。

第3章：実装フェーズ - AIによるコード生成とリファクタリング

設計図が完成すれば、実装に移ります。Gemini CLIのファイル操作能力とコード生成能力を活用することで、開発を高速に進めることができます。

3.1. トップダウンな実装戦略

まず、touchコマンドでプロジェクトに必要なコンポーネントの空ファイル群を一括で作成させ、全体の構造を定義しました。その後、各コンポーネントを 「静的UIの実装 → ロジックの注入 → コンポーネント間の連携」 という反復的なサイクルで、一つずつ具体化していきました。

このトップダウンかつ反復的なアプローチは、AIにとっても人間にとっても理解しやすく、着実に開発を進めるための効果的な戦略です。

3.2. AIによるリファクタリング

AIの能力は、新規コードの生成に留まりません。既存コードの構造的な改善、つまりリファクタリングにおいてもその価値を発揮します。

プロンプト例: 「GameContainer.tsxが肥大化してきました。ゲームラウンドの管理ロジックを、useGameRoundという名前のカスタムフックに抽出してリファクタリングしてください。」

この指示に基づき、Geminiは関連ロジックを新しいファイルに移動し、既存のコンポーネントがそのフックを利用するように修正しました。これにより、コンポーネントの関心事が分離され、コードの可読性とメンテナンス性が向上しました。

第4章：Gemini CLIを使いこなすための実践的テクニック

Gemini CLIの能力を最大限に引き出すには、質の高い対話が不可欠です。ここでは、AIとの協業を成功に導くための、具体的な戦略とテクニックを紹介します。

4.1. 構造化トップダウンアプローチ：AIを迷わせない開発の羅針盤

今回の開発で最も効果的だったのが、AIを迷わせず、プロジェクトを一貫して正しい方向に導くためのトップダウンアプローチです。複雑なプロジェクトを依頼する際に、この手法はAIの能力を最大限に引き出します。

  1. ステップ1：要件定義と要件定義書の作成

    • 目的: 「何を作るのか（What）」と「なぜ作るのか（Why）」をAIと合意形成します。
    • 実践: 曖昧なアイデア（「色当てゲームを作りたい」）から始め、AIとの対話を通じてユーザーストーリーを明確化します。そして、その内容を要件定義書としてドキュメント化させます。これにより、プロジェクトのゴールが明確に定義されます。

  2. ステップ2：設計と設計書の作成

    • 目的: 「どうやって作るのか（How）」を具体化します。
    • 実践: 合意した要件に基づき、コンポーネントの構成、データフロー、使用する技術の詳細などをAIに設計させ、設計書としてドキュメント化します。これにより、技術的な実装の青写真が完成します。

  3. ステップ3：TODOリストの作成

    • 目的: 設計書を、具体的な実行ステップに分解します。
    • 実践: 完成した設計書を基に、「実行のためのTODOリストを作成して」と指示します。AIは、プロジェクトのセットアップからコンポーネント実装、仕上げまでの詳細なタスクリストを生成します。これが、AI自身がこれから実行するべき**「開発の羅針盤」**となります。

この構造化されたアプローチは、AIが大規模で複雑なタスクの文脈を見失うのを防ぎ、一つ一つのステップに集中させることを可能にします。これにより、開発者は「指揮者」としてプロジェクト全体を俯瞰し、AIは「実行者」として各タスクを正確に遂行するという、理想的な協業関係が生まれるのです。

4.2. 思考プロセスの要求

複雑なタスクを依頼する際は、まずAIにその計画を説明させることで、意図の齟齬を防ぎます。

プロンプト例: 「framer-motionを導入してダイアログにアニメーションを追加したい。まず、実装計画をステップ・バイ・ステップで説明してください。私の承認後、実際のファイル変更を行ってください。」

4.2. Google検索の活用

Gemini CLIは、google_web_searchツールを通じて、Web上の最新情報にアクセスする能力を持っています。これにより、LLMの知識のカットオフ問題を克服し、リアルタイムの情報に基づいた回答を得ることが可能です。

プロンプト例: 「Next.jsで状態管理を行うためのライブラリを探しています。2025年現在のトレンドを考慮し、ZustandとJotaiを比較する記事をGoogleで検索し、その内容を要約して、それぞれの長所と短所を報告してください。」

この機能は、新しい技術の調査や、ライブラリの最新のAPI仕様を確認する際に極めて有効です。

4.3. 自己修正を促すフィードバック

AIが誤った情報や意図しないコードを生成した場合、その結果を具体的にフィードバックすることで、自己修正を促します。

プロンプト例: 「そのreplaceコマンドは失敗しました。old_stringが見つからなかったようです。これが現在のapp/layout.tsxの全内容です。[ファイル内容を貼り付け]。これを基に、もう一度正確なreplaceコマンドを生成してください。」

結論：AIとの協業による、新しい開発の姿

Gemini CLIとの一連の開発プロセスを通じて見えてきたのは、開発者の役割の変化です。我々の仕事は、コードを書く「作業」から、 AIという強力なエージェントに対し、的確な問いを立て、その能力を引き出し、プロジェクト全体の品質と方向性に責任を持つ「設計者」であり「指揮者」 へとシフトしていきます。

AIの思考プロセスを理解し、質の高い対話を通じて信頼関係を築くこと。これこそが、これからのソフトウェア開発において、生産性と創造性を飛躍させる鍵となるでしょう。

Discussion