Skip to content

Instantly share code, notes, and snippets.

@mizchi

mizchi/gemini-cli-usages-from-gemini-cli.md

Last active July 5, 2025 00:24
Show Gist options
  • Save mizchi/53fee8a015bb8f74a3e832bf92661fb5 to your computer and use it in GitHub Desktop.
Save mizchi/53fee8a015bb8f74a3e832bf92661fb5 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
gemini-cli-usages-from-gemini-cli.md

Gemini CLI に Gemini CLI 自体のソースコードを読ませつつ、高度な使い方を分析させたもの

Gemini CLI 実践ガイド: 基本から応用まで

Gemini CLIは、単なる対話ツールではありません。その設計の核心を理解することで、私たちはGemini CLIを、自らの開発ワークフローに最適化された、強力な自動化エンジンへと変貌させることができます。このガイドでは、基本的な使い方から、コードリーディングによって明らかになった高度な実践テクニックまでを解説します。

基本的な使い方: まずはここから

これからGemini CLIを使い始める方は、以下の基本的なコマンドとコンセプトを覚えましょう。

  1. 対話を開始する:

    • ターミナルで、操作したいプロジェクトのルートディレクトリに移動し、geminiと入力します。
    • これで対話モードが開始され、プロンプト（>）が表示されます。

  2. 質問と指示:

    • コードについて質問する: このプロジェクトのアーキテクチャを説明して
    • ファイル操作を依頼する: src/components/Button.tsx を作成して
    • コマンドを実行させる: npm run test を実行して結果を教えて

  3. ツール実行の承認:

    • Geminiがファイル変更やコマンド実行などの操作を行おうとすると、確認ダイアログが表示されます。
    • y (Yes) / n (No) / a (Always) / d (Details) で応答します。安全のため、何が起きるか分からない場合は d で詳細を確認しましょう。

  4. ワンショット実行:

    • 対話モードに入らず、単一のタスクを実行させることもできます。
    • gemini "README.mdを日本語に翻訳して"
    • cat main.go | gemini "このコードの要約を教えて"

  5. 設定ファイルの作成:

    • 初回起動時に ~/.gemini/settings.json が作成されます。このファイルを編集することで、テーマの変更や特定のツールを無効化するなど、基本的なカスタマイズが可能です。

高度な実践テクニック

Gemini CLIの真価は、その内部設計を理解し、カスタマイズすることで発揮されます。

1. 「憲法」を制定する: GEMINI.mdによるAIの教育

GEMINI.mdは、単なるAI向けドキュメントではありません。これは、そのリポジトリにおけるAIの振る舞いを規定する**「憲法」**です。getCoreSystemPromptの実装が示すように、このファイルの内容は最優先でシステムプロンプトに組み込まれます。

  • 何を記述すべきか？
    • コーディング規約: 「インポートは常に絶対パスで」「any型は禁止」など、リンターではチェックしきれない規約。
    • アーキテクチャの原則: 「状態管理はZustandを使い、Reduxは使わない」「コンポーネントはAtomic Designに従う」といった設計思想。
    • プロジェクト固有の注意点: 「legacy_api.jsは変更禁止」「新しい機能は必ずFeatureFlagでラップすること」といった、そのプロジェクト特有のルール。

これを最初に定義することで、AIはあなたのプロジェクトの「文化」を理解し、より質の高い、規約に準拠したコードを生成するようになります。

2. 「手足」を自作する: toolDiscoveryCommandによる無限の拡張

これは、Gemini CLIの最も強力かつドキュメント化されていない機能かもしれません。あなたは、自分自身のスクリプトを、Gemini CLIのネイティブツールとして追加できます。

  • 仕組み:

    1. 発見スクリプトを作成: ツールの定義（名前、説明、引数スキーマ）をJSON形式で標準出力に書き出すスクリプト（例: scripts/discover_tools.sh）を作成します。
    2. 実行スクリプトを作成: ツールが呼び出されたときに、実際の処理を行うスクリプト（例: scripts/run_tool.sh）を作成します。これはツール名と引数を標準入力から受け取ります。
    3. 設定ファイルで登録: .gemini/settings.json に以下のように記述します。 
      {
  "toolDiscoveryCommand": "bash scripts/discover_tools.sh",
  "toolCallCommand": "bash scripts/run_tool.sh"
}

  • ユースケース:

    • 「DBマイグレーションを実行して、スキーマ定義を更新する」という複合タスクを単一のツールとして登録する。
    • 社内のチケットシステムと連携し、「JIRA-123の仕様を読み込んで、実装の雛形を作成して」といったコマンドを実現する。

これにより、Gemini CLIは汎用アシスタントから、あなたのプロジェクト専用の超有能なジュニア開発者へと進化します。

3. 「エージェント」として使う: 非インタラクティブモードの自動対話ループ

runNonInteractiveの実装は、Gemini CLIが単なるワンショットコマンドではないことを示しています。内部のwhile (true)ループは、AIが自律的にタスクを完遂する**「エージェント」**として機能します。

  • 挙動を理解する: cat prompt.txt | gemini を実行した際、AIがツールを要求すれば、CLIはユーザーの確認なしでそのツールを実行し、結果を再びAIに渡します。この対話ループは、AIが「もうツールは必要ない」と判断するまで自動で継続されます。
  • 活用法:
    • 「srcディレクトリ以下の未使用CSSクラスを全て検出し、該当するファイルを修正して、最後にnpm run lint -- --fixを実行する」といった複数ステップのタスクを、単一のプロンプトファイルに記述して一括実行する。
    • CI/CDパイプラインに組み込み、「新機能のコードを読んで、ドキュメントのドラフトを生成する」といった処理を自動化する。

4. AIのように思考する: システムプロンプトに沿った対話

prompts.tsに書かれたシステムプロンプトは、AIの思考フローを定義しています。このフローに沿って指示を出すことで、AIの能力を最大限に引き出すことができます。

  • AIの思考フロー:

    1. 理解 (Understand): glob, search_file_content
    2. 計画 (Plan): (ユーザーへの提示)
    3. 実行 (Implement): edit, write_file, run_shell_command
    4. 検証 (Verify): run_shell_command (テストやリンターの実行)

  • 悪い指示: 「このボタンのバグを直して」

  • 良い指示: 「Button.tsxコンポーネントのクリックイベントにバグがあるようです。まずsearch_file_contentで関連する処理をリストアップし、修正計画を立ててください。」

後者のように、AIの思考プロセスを導くことで、より的確で効率的な応答が期待できます。

5. 賢く記憶させる: save_memoryとGEMINI.mdの使い分け

AIに情報を記憶させる方法は2つあり、その使い分けが重要です。

  • save_memoryツール:
    • 用途: プロジェクトを横断する、ユーザー個人に関する永続的な事実。「僕の好きなライブラリはVueだ」「僕のGitHubハンドルはmizchiだ」など。
    • 保存先: ~/.gemini/memory.json
  • GEMINI.mdファイル:
    • 用途: そのプロジェクト固有の、チームで共有されるべきコンテキストやルール。
    • 保存先: プロジェクトのルートディレクトリ

この2つを正しく使い分けることで、AIは「ユーザーmizchiはVueを好むが、このプロジェクトではReactを使うべきだ」という、高度なコンテキスト判断が可能になります。

6. サンドボックスの挙動を理解して使う: GEMINI_SANDBOX

GEMINI_SANDBOX環境変数は、ツールの安全性を担保する上で最も重要な機能です。その挙動は巧妙な「自己再起動」と「動的プロンプト」によって実現されています。

  • 仕組み:

    1. 起動と再起動: geminiコマンドを実行すると、gemini.tsxはまず!process.env.SANDBOXという条件で、自身がサンドボックスの外にいるかを確認します。もし外であれば、utils/sandbox.tsのstart_sandbox関数を呼び出します。この関数はdockerやpodmanを使ってコンテナを起動し、その中でGemini CLI自身を再実行します。そして、元のプロセスは即座に終了します。
    2. 無限ループの防止: start_sandboxは、コンテナ内で再実行されるプロセスに対し、SANDBOX=trueという環境変数を設定します。これにより、再起動されたプロセスは自身が既にサンドボックス内にいることを認識し、無限ループに陥るのを防ぎます。
    3. AIへの状況伝達: core/prompts.tsはprocess.env.SANDBOXの存在を検知します。もし存在すれば、システムプロンプトに「# Sandbox\nあなたはサンドボックスコンテナ内で実行されています...」という一節を動的に追加します。これにより、AI自身がサンドボックス内にいることを自覚し、ファイルアクセス制限などでコマンドが失敗した場合に、より的確な原因をユーザーに説明できるようになります。

  • 活用法:

    • 常に安全を確保するため、.envファイルやシェルの設定でexport GEMINI_SANDBOX=trueをデフォルトにしておくことを強く推奨します。これにより、意識することなく常に安全な環境でGemini CLIを利用できます。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment