Gemini CLI に Gemini CLI 自体のソースコードを読ませつつ、高度な使い方を分析させたもの
Gemini CLIは、単なる対話ツールではありません。その設計の核心を理解することで、私たちはGemini CLIを、自らの開発ワークフローに最適化された、強力な自動化エンジンへと変貌させることができます。このガイドでは、基本的な使い方から、コードリーディングによって明らかになった高度な実践テクニックまでを解説します。
これからGemini CLIを使い始める方は、以下の基本的なコマンドとコンセプトを覚えましょう。
-
対話を開始する:
- ターミナルで、操作したいプロジェクトのルートディレクトリに移動し、
gemini
と入力します。 - これで対話モードが開始され、プロンプト(
>
)が表示されます。
- ターミナルで、操作したいプロジェクトのルートディレクトリに移動し、
-
質問と指示:
- コードについて質問する:
このプロジェクトのアーキテクチャを説明して
- ファイル操作を依頼する:
src/components/Button.tsx を作成して
- コマンドを実行させる:
npm run test を実行して結果を教えて
- コードについて質問する:
-
ツール実行の承認:
- Geminiがファイル変更やコマンド実行などの操作を行おうとすると、確認ダイアログが表示されます。
y
(Yes) /n
(No) /a
(Always) /d
(Details) で応答します。安全のため、何が起きるか分からない場合はd
で詳細を確認しましょう。
-
ワンショット実行:
- 対話モードに入らず、単一のタスクを実行させることもできます。
gemini "README.mdを日本語に翻訳して"
cat main.go | gemini "このコードの要約を教えて"
-
設定ファイルの作成:
- 初回起動時に
~/.gemini/settings.json
が作成されます。このファイルを編集することで、テーマの変更や特定のツールを無効化するなど、基本的なカスタマイズが可能です。
- 初回起動時に
Gemini CLIの真価は、その内部設計を理解し、カスタマイズすることで発揮されます。
GEMINI.md
は、単なるAI向けドキュメントではありません。これは、そのリポジトリにおけるAIの振る舞いを規定する**「憲法」**です。getCoreSystemPrompt
の実装が示すように、このファイルの内容は最優先でシステムプロンプトに組み込まれます。
- 何を記述すべきか?
- コーディング規約: 「インポートは常に絶対パスで」「
any
型は禁止」など、リンターではチェックしきれない規約。 - アーキテクチャの原則: 「状態管理はZustandを使い、Reduxは使わない」「コンポーネントはAtomic Designに従う」といった設計思想。
- プロジェクト固有の注意点: 「
legacy_api.js
は変更禁止」「新しい機能は必ずFeatureFlag
でラップすること」といった、そのプロジェクト特有のルール。
- コーディング規約: 「インポートは常に絶対パスで」「
これを最初に定義することで、AIはあなたのプロジェクトの「文化」を理解し、より質の高い、規約に準拠したコードを生成するようになります。
これは、Gemini CLIの最も強力かつドキュメント化されていない機能かもしれません。あなたは、自分自身のスクリプトを、Gemini CLIのネイティブツールとして追加できます。
-
仕組み:
- 発見スクリプトを作成: ツールの定義(名前、説明、引数スキーマ)をJSON形式で標準出力に書き出すスクリプト(例:
scripts/discover_tools.sh
)を作成します。 - 実行スクリプトを作成: ツールが呼び出されたときに、実際の処理を行うスクリプト(例:
scripts/run_tool.sh
)を作成します。これはツール名と引数を標準入力から受け取ります。 - 設定ファイルで登録:
.gemini/settings.json
に以下のように記述します。{ "toolDiscoveryCommand": "bash scripts/discover_tools.sh", "toolCallCommand": "bash scripts/run_tool.sh" }
- 発見スクリプトを作成: ツールの定義(名前、説明、引数スキーマ)をJSON形式で標準出力に書き出すスクリプト(例:
-
ユースケース:
- 「DBマイグレーションを実行して、スキーマ定義を更新する」という複合タスクを単一のツールとして登録する。
- 社内のチケットシステムと連携し、「JIRA-123の仕様を読み込んで、実装の雛形を作成して」といったコマンドを実現する。
これにより、Gemini CLIは汎用アシスタントから、あなたのプロジェクト専用の超有能なジュニア開発者へと進化します。
runNonInteractive
の実装は、Gemini CLIが単なるワンショットコマンドではないことを示しています。内部のwhile (true)
ループは、AIが自律的にタスクを完遂する**「エージェント」**として機能します。
- 挙動を理解する:
cat prompt.txt | gemini
を実行した際、AIがツールを要求すれば、CLIはユーザーの確認なしでそのツールを実行し、結果を再びAIに渡します。この対話ループは、AIが「もうツールは必要ない」と判断するまで自動で継続されます。 - 活用法:
- 「
src
ディレクトリ以下の未使用CSSクラスを全て検出し、該当するファイルを修正して、最後にnpm run lint -- --fix
を実行する」といった複数ステップのタスクを、単一のプロンプトファイルに記述して一括実行する。 - CI/CDパイプラインに組み込み、「新機能のコードを読んで、ドキュメントのドラフトを生成する」といった処理を自動化する。
- 「
prompts.ts
に書かれたシステムプロンプトは、AIの思考フローを定義しています。このフローに沿って指示を出すことで、AIの能力を最大限に引き出すことができます。
-
AIの思考フロー:
- 理解 (Understand):
glob
,search_file_content
- 計画 (Plan): (ユーザーへの提示)
- 実行 (Implement):
edit
,write_file
,run_shell_command
- 検証 (Verify):
run_shell_command
(テストやリンターの実行)
- 理解 (Understand):
-
悪い指示: 「このボタンのバグを直して」
-
良い指示: 「
Button.tsx
コンポーネントのクリックイベントにバグがあるようです。まずsearch_file_content
で関連する処理をリストアップし、修正計画を立ててください。」
後者のように、AIの思考プロセスを導くことで、より的確で効率的な応答が期待できます。
AIに情報を記憶させる方法は2つあり、その使い分けが重要です。
save_memory
ツール:- 用途: プロジェクトを横断する、ユーザー個人に関する永続的な事実。「僕の好きなライブラリはVueだ」「僕のGitHubハンドルはmizchiだ」など。
- 保存先:
~/.gemini/memory.json
GEMINI.md
ファイル:- 用途: そのプロジェクト固有の、チームで共有されるべきコンテキストやルール。
- 保存先: プロジェクトのルートディレクトリ
この2つを正しく使い分けることで、AIは「ユーザーmizchiはVueを好むが、このプロジェクトではReactを使うべきだ」という、高度なコンテキスト判断が可能になります。
GEMINI_SANDBOX
環境変数は、ツールの安全性を担保する上で最も重要な機能です。その挙動は巧妙な「自己再起動」と「動的プロンプト」によって実現されています。
-
仕組み:
- 起動と再起動:
gemini
コマンドを実行すると、gemini.tsx
はまず!process.env.SANDBOX
という条件で、自身がサンドボックスの外にいるかを確認します。もし外であれば、utils/sandbox.ts
のstart_sandbox
関数を呼び出します。この関数はdocker
やpodman
を使ってコンテナを起動し、その中でGemini CLI自身を再実行します。そして、元のプロセスは即座に終了します。 - 無限ループの防止:
start_sandbox
は、コンテナ内で再実行されるプロセスに対し、SANDBOX=true
という環境変数を設定します。これにより、再起動されたプロセスは自身が既にサンドボックス内にいることを認識し、無限ループに陥るのを防ぎます。 - AIへの状況伝達:
core/prompts.ts
はprocess.env.SANDBOX
の存在を検知します。もし存在すれば、システムプロンプトに「# Sandbox\nあなたはサンドボックスコンテナ内で実行されています...」という一節を動的に追加します。これにより、AI自身がサンドボックス内にいることを自覚し、ファイルアクセス制限などでコマンドが失敗した場合に、より的確な原因をユーザーに説明できるようになります。
- 起動と再起動:
-
活用法:
- 常に安全を確保するため、
.env
ファイルやシェルの設定でexport GEMINI_SANDBOX=true
をデフォルトにしておくことを強く推奨します。これにより、意識することなく常に安全な環境でGemini CLIを利用できます。
- 常に安全を確保するため、