Gemini CLI Workflow:Markdownを活用する

概要

Gemini 3 の登場で Gemini CLI を使う場面が増えてきました。Gemini CLI 特有のコマンドやテクニックがないか模索していたところ、Google Cloud Tech 公式動画が参考になりましたので紹介と改善について記載しています。

https://www.youtube.com/watch?v=4U3nfVxlwlM

動画では大きく４つのワークフローハックとして紹介がありましたが、今回はPlan ,Markdownファイルについて紹介したいと思います。

Markdown ファイル活用術：とりあえずまとめ

結論として、アイデアや要求定義を扱うための Markdown ファイルを作成し、それらをローカルメモリとして活用する手法が提案されていました。CLI ツールに慣れた方であればすでに取り入れている人も多いと思いますが、今回あらためて公式からその有効性が説明された点は良かったです。

FEATURES.md：ユーザーのアイデアや要求を集約するファイル
PRD.md：AI によって整理・構造化された要件定義

動画ではモデル切り替えやカスタムコマンドなど、他の活用事例も紹介されていましたが、特に重要な役割を持つ 3 種類の Markdown ファイルに焦点を当てて紹介します。これらを適切に使い分けることで、「散らかった思考」を「動くアプリケーション」へと変換するプロセスが明瞭になります。今回紹介しているワークフローは、以下の Gemini CLI ドキュメントの日本語化の際にも実際に利用しました。

FEATURES.md：散らかったアイデアの受け皿

開発の初期段階では、アイデアは断片的で散らかっているものです。

  • 役割: 思いつき、機能案、メモ書きを一時的にプールするために使用されます。

  • 活用法: プロンプトから @features.md と参照することで、この雑多なメモをインプットとして、次のステップである仕様書作成を Gemini に依頼します。

PRD.md：AI への正式な設計図

FEATURES.md を元に、Gemini に生成させるのがこの「製品要求定義書（PRD）」です。

  • 役割: アプリケーション構築に必要な技術的詳細を定義するドキュメント。

  • メリット:

    • 再現性: もし実装アプローチが気に入らなくても、この PRD があれば何度でもゼロから再生成を試行できます。

    • 自己文書化: 開発プロセス自体がドキュメント作成を兼ねるため、ドキュメント不足を防げます。

GEMINI.md：AI への「振る舞い」指示書

プロジェクトやユーザー固有の設定ファイルです。

  • 役割: システムプロンプト、コーディング規約、守るべきルール。

  • 活用例:

    • 行動指針: 「コードを書く前には必ず PRD を確認する」

    • 知識の分離: ルールはここに書き、膨大な知識データは外部参照にすることで、コンテキストを節約しつつ精度を高めます。

  • 前述のPRD , FEATURES の振る舞い指示

## 1. ドキュメント管理システム開発プロセスは、以下の3つのドキュメントによって管理される。### 1-1. FEATURES.md（アイデア & リクエスト）- **目的**：開発の「エントリーポイント」。ユーザーのアイデア、機能リクエスト、バグ報告、TODO を保存する。- **使用方法**：  - ユーザーからの指示やエージェントの洞察から得たアイデアを記録する。  - ここにある内容はタスク実行のトリガーとして機能する。  - 低優先度項目や将来の拡張コンセプトもここに記録する。### 1-2. PRD.md（プロダクト要件ドキュメント）- **目的**：「仕様書」。Gemini（エージェント）が作成する仕様ドキュメント。- **使用方法**：  - Plan Mode の議論で仕様が固まった後にこのファイルを更新する。  - `FEATURES.md` のアイデアを基にした具体的な実装内容を記述する。  - 特定のフォーマットは必要ないが、必要に応じて整理して構造化する。- **ワークフロー**：この流れが中心となる    `FEATURES.md（アイデア） -> PRD.md（仕様） -> 実装（Impl）`

メモ

GEMINI.md 以外は決められたファイル名ではありません。
これらは Claude や他の CLI ツールを使われている方は定番の要素かもしれません。
私も別名で似たような利用をしておりました。
公式でも言ってくれるとやっぱり良かったんだと思ってなんか安心しました。この機会に私のプロジェクトは上記命名に変更しました。

公式フローの限界と改善

上記の features → PRD という流れはスムーズですが、実際の開発、特に規模が大きくなったり反復処理が増えたりすると、たいていうまく行きません。
うまくいっても時間がかかりすぎます。

直面した課題

  • 無限ループへの突入: 修正を繰り返すうちにゴールを見失い、終わらない修正ループに陥る。

  • コンテキスト溢れ: 会話が長引くと初期の指示が忘れ去られ、精度が低下する。

  • Gemini のフリーズ: 処理量が多すぎると応答が停止してしまう。

  • シングルタスクのため、本来並行実行できることが待たされる。

A potential loop was detected （潜在的なループが検出されました）

  • 1. Keep loop detection enabled (esc)
    （1. ループ検出を有効のままにする [Escキー]）

  • 2. Disable loop detection for this session
    （2. このセッションではループ検出を無効にする）

解決策：明確なタスクリストの導入

これも定番ですが別途タスクリストをいれて解決します。AGENT_TASK_LIST.md

【拡張されたワークフロー】

  1. FEATURES.md: アイデア出し

  2. PRD.md: 要件定義

  3. AGENT_TASK_LIST.md: 実行タスクの細分化と管理 👈 NEW!

  4. 実装開始

GEMINI.md への追記

 ### 1-3. AGENT_TASK_LIST.md（タスク可視化 & 状態共有）
- **目的**：
  - ユーザーおよびチームに「現在の状態」と「進行状況」を可視化する。
  - エージェントの内部エラーやセッション切断時の進捗理解や復旧を助ける。
  - これはエージェントの内部思考や短期記憶（プラン管理）を置き換えるものではなく、「外部共有」と「永続化」のチェックポイントとして機能する。
- **運用ルール**：
  - **タスクID**：各タスクに一意のインデックス（ID）を必ず割り当てる（例：`[T-001]`, `[TASK-10]`）。
  - **更新タイミング**：`PRD.md` 更新後、新しい作業が生じたとき、タスク完了時に更新する。
  - **行数制限**：ファイルサイズが100行を超えた場合、完了したタスクの削除（アーカイブ）についてユーザーに確認する。
    - **禁止事項**：エージェントは許可なく過去ログを削除してはならない。
  - **タスク粒度**：変数名修正やインデント調整などの「微小タスク」は記載しない。  
    意味のある進捗単位（例：機能実装完了、テスト完了、主要バグ修正）でタスクを定義・管理する。

タスクリスト運用のメリット

  • ステートレスな進行管理:

    • タスクリストがあることで、「どこまで終わったか」「次は何か」が可視化されます。Gemini がフリーズしたり中断したりしても、すぐに復帰できます。

  • マルチエージェント連携:

    • 明確なタスクがあれば、他のエージェント（例えば Codex など）に「このタスクだけお願い」と切り出して並行依頼することが容易になります。

  • 今回 Gemini CLI のドキュメントをすべて翻訳したのですが、一部の翻訳タスクなどは Codex に分担させることで効率化できました。
    そもそも Gemini CLI では大量のファイルを翻訳したり、一律処理させると大抵止まる問題があります。 今回は単純な翻訳作業でしたが、上記３つのファイルでスムーズに作業できました。

    (https://github.com/catnipglitch/google-gemini-cli-jp)

まとめ

Gemini CLI は、適切な Markdown ファイル群（設計図や指示書）を渡すことで、CLI作業環境のみでスムーズな作業進行がしやすくなります。公式推奨の「ドキュメント駆動」開発に加え、実用的な「タスク管理」を組み合わせることで、より複雑な開発も安定して進められるようになりそうです。

🔗 参考リンク