import { Callout } from '@/components/ui/callout';
「GEMINI.md って、何を書けばいいんでしょうか？」— Gemini CLI を使い始めた方からよくいただく質問です。公式の説明を読むと「プロジェクトのコンテキストを書いてください」と書かれているのですが、いざ自分のリポジトリで書き始めると、何を入れて何を入れないべきか迷うところがたくさん出てきます。
私自身、複数のプロジェクトで GEMINI.md を試行錯誤してきた中で、「プロジェクトの種類ごとに効くテンプレートが違う」という肌感覚が出てきました。Next.js のフロントエンド開発と Python のデータ分析では、エージェントに知ってほしいことの優先順位がまったく異なります。
ここでは4つの代表的なプロジェクトタイプそれぞれについて、実際に動かしてみて効果のあった GEMINI.md のテンプレートを共有します。コピペして自分のプロジェクトに合わせて書き換えていただければ、初期立ち上げの時間がかなり短縮できるはずです。
GEMINI.md が「効く」ファイルになるための原則
実例に入る前に、書き方の軸を3つだけ共有させてください。これを押さえると、どんなプロジェクトでもブレずに書けます。
第一に、「コードを読めば分かること」は書かない こと。package.json や pyproject.toml を読めば分かる依存関係、ファイルツリーから明らかなディレクトリ構造を逐一書き出すと、コンテキストウィンドウが圧迫されるだけで価値が出ません。GEMINI.md の役割は「コードに書かれていない暗黙のルール」を伝えることです。
第二に、禁止事項を明示する こと。「○○してください」よりも「○○はしないでください」の方が、エージェントの暴走を防ぐ効果が高いです。私の経験では、このネガティブ指示が GEMINI.md の品質を3〜4割上げます。
第三に、1ファイル500〜1500トークン以内に収める こと。これは Gemini CLI の出力品質と直結します。長いほど良いわけではなく、本当に必要な情報だけを残すと、エージェントの判断速度と精度が上がります。
実例1: Next.js + TypeScript の Web アプリ
最も需要が高いケースです。フロントエンド・バックエンド・データベースが絡むため、設計思想を伝えないとエージェントが余計なリファクタリングを始めがちです。
# プロジェクト概要
このリポジトリは Next.js 16 (App Router) + TypeScript + Tailwind CSS で構築された
SaaS ダッシュボードです。Cloudflare Workers にデプロイし、Stripe で課金処理を行います。
## アーキテクチャの前提
- App Router を使用。Pages Router 形式（`pages/` ディレクトリ）には絶対に変換しない
- Server Components が基本。useState/useEffect が必要なときだけ "use client" を付ける
- データフェッチは Server Actions または Route Handlers を優先。SWR や React Query は使わない
- 認証は Auth.js v5（旧 NextAuth）。Clerk や Firebase Auth に置き換えない
## ディレクトリの役割
- `src/app/` — App Router のルート定義
- `src/components/ui/` — 再利用可能な UI コンポーネント（shadcn/ui ベース）
- `src/lib/` — ビジネスロジック・DB クライアント・Stripe ヘルパー
- `src/server/` — サーバー専用コード（クライアントから import 禁止）
## やってはいけないこと
- `any` 型の使用（`unknown` + 型ガードを使う）
- `useEffect` でのデータフェッチ（Server Components で完結させる）
- `process.env` への直接アクセス（`src/lib/env.ts` の zod 検証を経由）
- `console.log` を本番コードに残す（Sentry でログを送る）
## テストとリント
- 修正後は必ず `pnpm tsc --noEmit` と `pnpm lint` を通す
- ユニットテストは Vitest、E2E は Playwright
- マイグレーションは `pnpm db:generate` → `pnpm db:migrate` の順ポイントは「禁止事項」の明示です。Next.js は新旧 API が混在しているため、useEffect でフェッチしたり、pages/ にファイルを作ったりするコードを生成されると、後から修正するコストが大きくなります。
実例2: Python のデータ分析・機械学習プロジェクト
Jupyter Notebook と .py ファイルが混在するプロジェクトでは、「再現性」と「メモリ管理」がコアになります。
# プロジェクト概要
EC サイトの購買ログから顧客セグメンテーションを行う ML パイプラインです。
学習データは BigQuery、特徴量ストアは Feast、モデルレジストリは MLflow を使用します。
## 環境
- Python 3.12（Poetry 管理）
- 主要ライブラリ: pandas 2.x, polars 0.20+, scikit-learn 1.5+, lightgbm 4.x
- GPU は使わない（コスト都合）。XGBoost や LightGBM の CPU 学習で完結する
## データ規模と注意点
- 購買ログ: 月次 800万行、年間1億行規模
- pandas で全件ロードするとメモリが爆発する。**polars または DuckDB を優先**
- BigQuery クエリは必ず `LIMIT` を付けて検証してから本番実行する
- パーティション列（`event_date`）でフィルタしないとフルスキャンになり高額
## 実験管理
- 全ての実験は MLflow に記録する。ローカルで完結させない
- 特徴量は Feast に登録してから使う。Notebook 内で生成した DataFrame を直接モデルに食わせない
- ランダムシードは `RANDOM_STATE = 42` を必ず固定する
## やってはいけないこと
- `pandas.read_csv()` で 100MB 超のファイルをロードする（→ polars または chunksize 指定）
- `for` ループでの DataFrame 操作（→ ベクトル化または `.apply()`）
- `pickle` でのモデル保存（→ MLflow.sklearn.log_model）
- `notebook` セル内での認証情報のハードコード（→ `.env` + `python-dotenv`）
## コードスタイル
- 型ヒント必須（`from typing import ...`）
- docstring は Google スタイル
- フォーマッタ: ruff（black 互換設定）データ分析プロジェクトでは「データ規模を伝える」のが特に効きます。「100行のサンプルデータで動く実装」と「1億行で動く実装」はコードの書き方がまったく違うため、規模感を最初に共有しておかないと、エージェントが小規模前提のコードを生成してしまいます。
実例3: CLI ツール・ライブラリ開発
OSS として公開する CLI やライブラリは、「ユーザー体験」と「後方互換性」がコアです。
# プロジェクト概要
ターミナルから Markdown ファイルを PDF に変換する Rust 製 CLI ツールです。
crates.io で公開しており、毎月約 2,000 ダウンロードされています。
## ユーザー層
- Markdown でドキュメントを書く開発者・テクニカルライター
- 大半は macOS / Linux ユーザー（Windows サポートも維持）
- インストールは `cargo install` または Homebrew
## 設計原則
- **後方互換性は最優先**: コマンドライン引数の名前を絶対に変えない
- 新機能はオプトイン（既存の挙動を変更しない）
- エラーメッセージは英語のみ（i18n は導入しない）
- バイナリサイズは 5MB 以下を維持（依存ライブラリ追加時は注意）
## ディレクトリ
- `src/main.rs` — CLI エントリポイント（clap でパース）
- `src/lib.rs` — ライブラリとしての API
- `src/converter/` — 変換ロジック（テスト容易にするため切り出し）
- `tests/` — 統合テスト（cargo test で実行）
## やってはいけないこと
- 既存のコマンドライン引数（`--input`, `--output`, `--theme`）の名前変更
- 依存ライブラリの追加（特に C バインディング系）— 追加するなら相談
- `unsafe` ブロックの使用
- `.unwrap()` を含む panic（Result + 適切なエラー型を返す）
## リリースフロー
1. `Cargo.toml` のバージョンを更新（semver 厳守）
2. `CHANGELOG.md` に変更内容を記載
3. `cargo publish --dry-run` で確認
4. PR をマージ後、GitHub Actions が自動で crates.io に公開公開ライブラリでは「壊さないこと」が最重要です。エージェントは便利な機能を勝手に足したり、API を整理したりしがちなので、明示的に止める指示が効果を発揮します。
実例4: React Native / Expo のモバイルアプリ
iOS と Android の差異、ネイティブモジュールの扱いに気を配る必要があります。
# プロジェクト概要
iOS / Android 向けの瞑想・睡眠アプリです。Expo SDK 53 + React Native 0.76 を使用し、
EAS Build でビルド、TestFlight / Google Play Internal Testing でテスト配信しています。
## 技術スタック
- Expo SDK 53（managed workflow）
- React Native 0.76（New Architecture 有効）
- 状態管理: Zustand（Redux は使わない）
- ナビゲーション: Expo Router v3
- データベース: Supabase（PostgreSQL + Realtime）
- 課金: RevenueCat
## プラットフォーム差異の扱い
- iOS / Android で挙動が異なる箇所は `Platform.OS` で分岐し、必ずコメントを残す
- iOS の SafeArea は `useSafeAreaInsets()` を使用（`SafeAreaView` は使わない）
- Android のステータスバーは `expo-status-bar` で制御
- 通知音・触覚フィードバックは `expo-haptics` 経由のみ
## やってはいけないこと
- `react-native-` 系のネイティブモジュール追加（Expo managed が壊れる）
- `eject` の提案
- iOS only / Android only の機能を `Platform.OS` チェックなしで実装
- アプリ起動時の `AsyncStorage` への大量読み書き（起動が遅くなる）
## ストア審査対策
- アプリ内課金はすべて RevenueCat 経由（Apple/Google の規約遵守）
- ヘルスケア系の表現は控えめに（「治療」「効果」などの言葉を避ける）
- プライバシーポリシーへのリンクを設定画面に表示
## ビルド・配信
- 開発: `npx expo start`
- 本番ビルド: `eas build --platform all --profile production`
- ストア提出: `eas submit`モバイルアプリの GEMINI.md では「ストア審査対策」を入れておくと、AI が生成するコピーや表現も自然と安全側に寄ります。これは思わぬ副次効果でした。
共通の改善テクニック
4つの実例を見比べると、効くパターンが見えてきます。
「ダメな例 → 良い例」のセットを2〜3個入れる のは、どのプロジェクトタイプでも有効でした。例えば「useEffect でのデータフェッチ → Server Components」のような対比形式は、長い説明文より遥かに伝わります。
「どこに何を置くか」を明示する ことも重要です。src/components/ui/ と src/components/feature/ の違いを書いておかないと、エージェントは適当な場所にファイルを作りがちです。
バージョンを明記する のも効きます。「React Native 0.76」「Next.js 16」のように具体的に書くと、エージェントは古い API（componentWillMount など）を提案しなくなります。
GEMINI.md の更新タイミングについては、GEMINI.md の作り方入門 で紹介している draft.md → 本番 GEMINI.md の2ステップ方式が便利です。draft.md に思いついたメモを溜めておいて、月に1度 Gemini CLI に整形させるサイクルを回すと、メンテナンスが負担になりません。
全体を振り返って
GEMINI.md のテンプレートをいくつ持っているかが、Gemini CLI を使った開発生産性を直接左右します。今回紹介した4つのテンプレートをベースに、自分のプロジェクトに合わせて30分ほど書き換えてみてください。エージェントの提案精度が変わることを、おそらく初日に実感していただけるはずです。
Gemini CLI の周辺機能をもっと知りたい方は、Gemini CLI 完全ガイド や Gemini CLI Plan Mode の活用法 も合わせて読んでいただくと、エージェント運用全体の流れがつかめます。