# Gemini CLI 制御マニュアル（司令塔のための実行手順）

エージェント（Antigravity）が Gemini CLI を「手足」として使うための技術手順。

---

## 1. 基本コマンド形（クイックリファレンス）

| 目的 | コマンド |
|------|----------|
| **Plan 作成・調査** | `gemini -p "プロンプト" --approval-mode=plan` |
| **ファイル編集・作成** | `gemini -p "プロンプト" --approval-mode=yolo` |
| **読み取り・解析のみ** | `gemini -p "プロンプト"` |
| **JSON 出力取得** | `gemini -p "プロンプト" --output-format json` |

- **注意**: `--yolo` よりも `--approval-mode=yolo` を優先して使用する。
- **ターミナル起動後**: コマンドを送る前に**少し待つ**（シェルが準備できるまで。目安 1〜2 秒程度）。起動直後に送ると取りこぼすことがある。
- **コマンドは複数一度に送らない**: `cd ... && gemini ...` のように `&&` でつなげず、**まず `cd` だけ送り、その実行が済んでから**別のコマンドとして `gemini -p "..."` を送る。
- 実行前に **プロジェクトルートに `cd`** し、ディレクトリ・パスの指定ミスを防ぐ。

---

## 2. Windows 環境での最適解

Antigravity + Windows 環境では **Git Bash** での実行を標準とする。詳細は [terminal-recommendation.md](terminal-recommendation.md)。CMD / PowerShell を使う場合は、まず絶対パスで移動してから実行する。

1.  **Git Bash を開く**: `cd /c/Users/.../project` のように **Unix 形式（`/c/` 始まり・スラッシュ区切り）** で移動する。**`c:\Users\...` やバックスラッシュの Windows パスは Git Bash では失敗するので使わない**。
2.  **CMD / PowerShell の代替**: `cd /d "C:\path\to\project"` または `Set-Location "C:\path\to\project"` のように、まず絶対パスで移動する。
3.  **chcp について**: **`chcp 65001` は CMD 用のコマンド**。Git Bash には存在しないため、Git Bash で実行するとエラーになる。Git Bash では不要（UTF-8 前提）。CMD で実行する場合のみ、文字化け対策で `chcp 65001` を実行する。
4.  **相対パスの活用**: プロンプト内では「リポジトリルートからの相対パス」を指定し、日本語を含む絶対パスの使用を避ける。
5.  **引用符の処理**: プロンプトに `!` を含む場合はシングルクォート `'...'` で囲むか `\!` でエスケープ（bash の履歴展開を防ぐ）。通常は `"..."` で囲み、内部の二重引用符は `\"` でエスケープする。

---

## 2.1. シェル別の短い定型手順

### Git Bash の場合

1. ターミナルを開き、少し待つ。
2. `cd /c/.../project` のように **`/c/` 形式の絶対パス**でプロジェクトルートへ移動する。
3. `cd` の完了を確認してから、別送で `gemini -p "..."` を実行する。
4. 実行後は**同じターミナルの最新出力**を取得し、`stdout / stderr / exit code` を確認する。
5. まだ実行中なら短く待って、同じターミナルの出力を再取得する。

### CMD の場合

1. ターミナルを開き、必要なら `chcp 65001` を実行して少し待つ。
2. `cd /d "C:\...\project"` のように **Windows の絶対パス**でプロジェクトルートへ移動する。
3. `cd` の完了を確認してから、別送で `gemini -p "..."` を実行する。
4. 実行後は**同じターミナルの最新出力**を取得し、`stdout / stderr / exit code` を確認する。
5. まだ実行中なら短く待って、同じターミナルの出力を再取得する。

### PowerShell の場合

1. ターミナルを開き、少し待つ。
2. `Set-Location "C:\...\project"` または `cd "C:\...\project"` のように **Windows の絶対パス**でプロジェクトルートへ移動する。
3. 移動の完了を確認してから、別送で `gemini -p "..."` を実行する。
4. 実行後は**同じターミナルの最新出力**を取得し、`stdout / stderr / exit code` を確認する。
5. まだ実行中なら短く待って、同じターミナルの出力を再取得する。

---

## 3. プロンプト設計の3要素

効果的な「指示出し」を行うためのプロンプト構成。

1.  **作業コンテキスト**: 「プロジェクトルートで」「カレントディレクトリで」と明示。
2.  **対象（Scope）**: 具体的なファイルパスやディレクトリ名（`@src/lib/` など）。
3.  **具体的な指示**: 「○○を××に変更して」「この箇所のバグを修正してプランを立てて」など、一意のゴールを指示。

---

## 4. トークン消費の最適化（司令塔の知恵）

-   **ピンポイント指定**: ファイル全体（`@file`）を渡さず、「○行目の関数 `foo()`」と範囲を限定する。
-   **不要なディレクトリを渡さない**: `@dir/` は中身が膨大になるため、必要なファイルだけを列挙（`@a.ts @b.ts`）する。
-   **セッションの最小化**: 重い分析と実装を 1 回で行わず、分析結果を Antigravity 側で要約して、次の実装用プロンプトに「要約のみ」を反映させる。

---

## 5. タスク別の呼び出し例

- **単一ファイルの編集**: 対象ファイルと変更内容を 1 文で。「`src/index.ts` の先頭に `// generated` を 1 行追加して」
- **複数ファイル**: 「`src/a.ts` と `src/b.ts` の両方で、import パスを `@/lib` に統一して」のように範囲を明示。
- **解析・要約**: 「プロジェクトルートの `README.md` を読んで 3 行で要約して。ファイルは編集しない」
- **検索・一覧**: 「`src/` 以下で `TODO` を含む行を列挙して。編集はしない」
- **段階的作業**: まず「現状を分析して」で 1 回、出力を見てから「その結果を踏まえて ○○ を修正して」で 2 回目、のように分ける。
- **Plan を詰める複数ターン**: Plan 作成時は `--approval-mode=plan` のみ（`--yolo` は付けない。併用不可）。1 回目 `gemini -p "要件は○○。まず実装プランを立てて" --approval-mode=plan` → Antigravity が出力を取得して**内容を精査** → 2 回目「前回のプランの○○を修正して」「ここを具体化して」と依頼して再実行 → 必要なら繰り返す。毎回、前回の CLI の出力（または要約）をプロンプトに含める。**Plan が返ってきたら実装には進まず**、精査・修正依頼を繰り返し、了承後にのみ実装ターンへ。判断と fallback（429 / Unauthorized tool call 時の通常モード切り替え）は [agent-behavior.md](agent-behavior.md) 7.1 を参照。
- **JSON 出力**: `--output-format json` を付け、プロンプトで「次のキーだけの JSON オブジェクトを返して: version, deps」のように形式を指定する。

---

## 5.1. 会話往復型の実運用手順（曖昧要件・条件衝突）

要件が曖昧なときや、途中で条件が増えて衝突しうるときは、**実装せずに複数ターンで詰める**。

1. **1 回目（不足情報の質問）**: CLI に「実装はしない。不足している情報を質問リスト（3〜7 個程度）で返して」と依頼（`--approval-mode=plan` または通常の `-p`）。出力を取得し、ユーザーに回答してもらう。
2. **2 回目（仮プラン）**: ユーザー回答を要約してプロンプトに含め、「前提: ○○。この前提で実装プランだけ返して。ファイルは編集しない」と依頼。Plan を取得して精査する。
3. **3 回目（条件反映後の修正版 plan）**: 追加条件や衝突の整理結果を渡し、「前回のプランに次の条件を反映した修正版プランだけ返して。実装はまだしない」と依頼。精査して了承できるまで繰り返す。
4. **4 回目（実装）**: 最終 Plan を了承したあと、別ターンで `--approval-mode=yolo` を使って実装を依頼する。

**長いプロンプト・要約の渡し方**: 作業ディレクトリはプロジェクトルートに合わせ、プロンプト内のパスは**相対パス**（例: `test-03/`）にする。前回の CLI 出力は**要約（3〜5 文）**にしてから次のプロンプトに含め、全文を貼らない。Git Bash で長文を渡すときは `gemini -p "$(cat prompt.txt)"` や here-string を利用する。定型は [prompt-templates.md](prompt-templates.md) の「曖昧要件の質問返し」「衝突条件の整理」「追加条件を反映した plan 再作成」を参照。典型フローと質問観点は [conversation-patterns.md](conversation-patterns.md) を参照。

---

## 6. セッション再開（--resume）の判断

- **原則**: エージェントからヘッドレスで 1 タスクずつ渡す運用では、**1 タスク 1 回の `gemini -p`** で完結させるのを推奨。セッションをまたぐと状態管理が複雑になる。
- **使う場合**: 同一タスクの「続き」（例: 1 回目で分析、2 回目でその結果を踏まえた修正）を、CLI 側の会話履歴を活かしたいときだけ `gemini -r latest -p "..."` を検討する。その場合も、プロンプトに「前回の出力では ○○ だった。それを踏まえて…」と文脈を短く含めると安全。

---

## 6.1. Plan から実装へ進む条件

- **Antigravity が司令塔**: Gemini CLI が作った Plan をそのまま実行させず、Antigravity が**必ず先に読む・理解する・必要なら直させる**。
- **実装開始の条件**:
  - Plan の不足・誤り・曖昧さが解消されている
  - 対象ファイル・実装範囲・検証方法が十分に明確
  - 必要ならユーザーにも要約して確認済み
- **禁止**: Plan の返答を受け取った直後に、そのまま `gemini -p "実装して"` を投げること。
- **実装に進むとき**: 最終 Plan を短く要約してから、別ターンで編集用プロンプトを送る。

---

## 7. エラー・特殊状況

- **429 / Plan Mode の Unauthorized tool call など**: 再試行・fallback の判断は [agent-behavior.md](agent-behavior.md) 5 および 7.1 を参照。実行例のみ: 429 時は `-m flash` で 1 回再試行し、Plan ターンで繰り返すなら `--approval-mode=plan` を外して `gemini -p "…プランだけ返して。ファイル編集はしない"` へ。Unauthorized 時も同様に通常モードへ切り替える。
- **権限エラー / write がブロック**: 編集系なら `--approval-mode=yolo` を付けたか確認。付いていれば対象パス・指示の曖昧さを見直す。信頼フォルダ未設定時は [trusted-folder.md](trusted-folder.md) を参照し、`/permissions` をユーザーに案内する。
- **タイムアウト・中断**: タスクを小さく分けて再実行するか、プロンプトを短く・具体的にする。
- **出力が期待と違う**: 次のプロンプトで「前回の出力を踏まえて、○○だけやり直して」と範囲を限定して再実行。
- **終了コード**: `0` 成功、`1` 一般エラー、`42` 入力エラー、`53` ターン超過。詳細は [reference.md](reference.md)。

---

## 8. 参照

- **振る舞い・判断・安全**: [agent-behavior.md](agent-behavior.md)
- **オプション・IDE・クォータ・コマンド一覧**: [reference.md](reference.md)
- **詳細ガイド・公式リンク**: [detailed-guide.md](detailed-guide.md)
- **公式**: https://geminicli.com/docs/
