はじめに
正直に言うと、私がAIツールを使っていて毎回イライラするのが、プロジェクトの規約やコードスタイル、技術スタックを何度も説明しなければならないことなんですよね。まるで毎日、物忘れの激しい同僚に「俺は誰だっけ？」と説明するようなもので、時間の無駄どころかミスの元にもなります。
そんな時に発見したのが、Gemini CLIの隠れた機能であるGEMINI.mdファイルです。一見ただのMarkdownファイルに見えますが、実はこれがGemini CLIの「記憶システム」なんです。プロジェクトのルールをこのファイルに書いておくだけで、AIがあなたの好みを覚えてくれて、生成されるコードやドキュメント、PRの説明文までもがプロジェクトのスタイルに合ったものになります。
Tip：API Keyやパスワードなどのセンシティブな情報はここに書かないでください。環境変数やシークレット管理を使った方が安全です。
これで、AIにプロジェクトの説明を繰り返す必要がなくなり、その時間を使ってもっとコードを書いたり、ロジックの設計に集中したりできるようになりますよ！
一、GEMINI.mdとは何か？
簡単に言うと、GEMINI.mdはAIのための「プロジェクト説明書」です。このファイルでAIに伝えられること：
- プロジェクトのコーディング規約とベストプラクティス
- コードスタイルの好み
- よく使うライブラリとフレームワーク
- プロジェクトの背景とビジネスロジック
例えば、私がReact + TypeScriptのプロジェクトで使う場合、コンポーネントの命名規則、状態管理の方法、テストカバレッジの要件などをすべて書いておくと、AIが生成するコードはほとんど修正不要になります。
経験談：私は「必須」のルールを明確に書き、「好み」はオプションとして明示するようにしています。そうすることで、AIがコードを生成する際に迷わなくなります。
動作の仕組み
Gemini CLIは起動時に自動的にGEMINI.mdファイルを検索し、その内容をコンテキスト（つまりAIの「記憶」）としてロードします。検索は再帰的に行われ、現在のディレクトリからプロジェクトのルートディレクトリまで遡って、見つかったすべてのGEMINI.mdファイルが統合されます。その際、現在のディレクトリに近い設定ほど優先されます。
チームでの実践例：サブディレクトリの優先度が高いのは非常に重要です。特定のモジュールには特別なルールが必要で、それがプロジェクト全体の規約に影響を与えないようにできるからです。
二、階層化設定——AIにプロジェクトをより深く理解させる
3層の設定システム
Gemini CLIは階層化されたGEMINI.md設定をサポートしており、優先度の低いものから高いものへと以下のように分類されます：
- グローバル設定：
~/.gemini/GEMINI.md（すべてのプロジェクトに適用される共通ルール） - プロジェクト設定：現在のディレクトリからプロジェクトのルートディレクトリまでの間にある
GEMINI.mdファイル - サブディレクトリ設定：特定のコンポーネントやモジュール用の専用指示（ローカルオーバーライド）
実際の設定例
以下は私が複数のプロジェクトでよく使う3つの階層の例です：
- グローバル設定（
~/.gemini/GEMINI.md）：
# 私の開発環境設定
## 共通コーディング規約
- すべてのコードに詳細なコメントを含める
- 関数名はキャメルケースを使用
- JavaScriptよりTypeScriptを優先
- エラー処理はtry-catchブロックを使用
## 好みの技術スタック
- フロントエンド：React + TypeScript + Tailwind CSS
- バックエンド：Node.js + Express + MongoDB
- テスト：Jest + React Testing Library
経験談：あまり変更されない「スタイル/好み」はグローバルに置くと、各プロジェクトで繰り返し書く手間が省けます。
- プロジェクトルートディレクトリの設定（
./GEMINI.md）：
# ECサイトプロジェクト
## プロジェクト概要
これはマイクロサービスアーキテクチャに基づくECサイトで、ユーザー管理、商品管理、注文処理などの主要機能を含みます。
## プロジェクト固有の規約
- APIはRESTful設計に従う
- すべてのデータベース操作にはPrisma ORMを使用
- フロントエンドコンポーネントはレスポンシブデザインをサポート
- 決済関連コードには追加のセキュリティチェックが必要
## ディレクトリ構造
-`/src/components/` - 再利用可能なReactコンポーネント
-`/src/pages/` - ページレベルのコンポーネント
-`/src/api/` - API定義
-`/src/utils/` - ユーティリティ関数
- コンポーネントディレクトリの設定（
./src/components/GEMINI.md）：
# コンポーネント開発規約
## コンポーネント設計原則
- 各コンポーネントには対応する.stories.jsファイルが必要
- コンポーネントはダークモードをサポート
- すべてのpropsにはTypeScriptの型定義が必要
- コンポーネントには単体テストを含める
## スタイル規約
- Tailwind CSSのクラス名を使用
- インラインスタイルは避ける
- レスポンシブデザインを優先
経験談：ローカルルール（コンポーネントディレクトリなど）の優先度が最も高く、共通ルールの「例外」をカバーするのに適しています。
三、モジュール化管理——設定をより優雅に
プロジェクトが複雑になると、@file.md構文を使って他のMarkdownファイルをインポートし、設定をモジュール化できます。これによりGEMINI.mdがより管理しやすくなり、チームでの協業も容易になります。
@import構文の使用例
- メイン設定ファイル（
GEMINI.md）：
# フルスタックプロジェクト
## 基本設定
@./docs/coding-standards.md
@./docs/git-workflow.md
## 技術スタック固有の設定
@./frontend/react-guidelines.md
@./backend/api-guidelines.md
@./database/schema-guidelines.md
- フロントエンド規約（
./frontend/react-guidelines.md）：
# React開発規約
## コンポーネント構造
- 関数コンポーネントとHooksを使用
- カスタムHookは「use」で始める
- コンポーネントのファイル名はパスカルケース
## 状態管理
- シンプルな状態にはuseState
- 複雑な状態にはuseReducer
- グローバル状態にはZustand
経験談：共通の規約は
docs/に、モジュール/サービス固有のものは対応するサブディレクトリに置きます。CIでも必要なモジュールファイルだけを同期できます。
四、実践例——ゼロから完璧な協業まで
例1：React + TypeScriptプロジェクトの設定
プロジェクトを作成し、GEMINI.mdを初期化します：
mkdir my-react-app
cd my-react-app
# メイン設定ファイルを作成
vim GEMINI.md
完全なプロジェクト設定：
# React TypeScriptプロジェクト
## プロジェクト情報
- プロジェクト名：モダンTodoアプリ
- 技術スタック：React 18 + TypeScript + Vite + Tailwind CSS
- 状態管理：Zustand
- ルーティング：React Router v6
## 開発規約
### コードスタイル
- インデントは2スペース
- 文字列は単一引用符を優先
- コンポーネントのpropsは分割代入を使用
- any型の使用を避ける
### コンポーネント規約
- コンポーネントファイルは.tsx拡張子を使用
- コンポーネント名はパスカルケース
- コンポーネントはデフォルトエクスポートとして出力
- 各コンポーネントには対応する型定義が必要
### スタイル規約
- Tailwind CSSでスタイル設計
- レスポンシブデザイン優先（モバイルファースト）
- ダークモードをサポート
- テーマカラーにはCSS変数を使用
### テスト要件
- 各コンポーネントには単体テストが必要
- React Testing Libraryを使用
- テストカバレッジは80%以上
## プロジェクト固有の指示
- 生成されるコードには詳細なJSDocコメントを含める
- API呼び出しにはエラー処理を含める
- フォームバリデーションにはreact-hook-form + zodを使用
- すべての非同期操作にはReact Queryを使用
経験談：具体的であればあるほど良いです。例えば、JSDocの形式やパラメータの命名規則を明確にすると、AIがより一貫性のあるコメントを生成します。
例2：フルスタックプロジェクトの階層設定
複雑なフルスタックプロジェクトでは、ルートディレクトリを「契約」として、サブディレクトリでローカルオーバーライドを行います：
- プロジェクトルートディレクトリ（
./GEMINI.md）：
# フルスタックECサイト
## プロジェクトアーキテクチャ
- フロントエンド：Next.js 14 + TypeScript
- バックエンド：Node.js + Express + Prisma
- データベース：PostgreSQL
- デプロイ：Docker + Kubernetes
## 共通規約
@./docs/general-guidelines.md
@./docs/security-guidelines.md
@./docs/performance-guidelines.md
## 環境設定
- 開発環境：ローカルPostgreSQL
- テスト環境：インメモリデータベース
- 本番環境：クラウドデータベース
- フロントエンド設定（
./frontend/GEMINI.md）：
# フロントエンド開発規約
## Next.js固有の規約
- App Router使用（Pages Routerではない）
- サーバーコンポーネント優先、クライアントコンポーネントは必要に応じて
- 画像にはnext/imageコンポーネントを使用
- フォントはnext/fontで最適化
## 状態管理
- サーバー状態：TanStack Query
- クライアント状態：Zustand
- フォーム状態：React Hook Form
- バックエンド設定（
./backend/GEMINI.md）：
# バックエンド開発規約
## API設計
- RESTful原則に厳密に従う
- OpenAPI 3.0仕様を使用
- すべてのAPIには入力検証が必要
- エラーレスポンスは統一フォーマットを使用
## データベース操作
- Prisma ORMを使用
- すべてのクエリにはエラー処理を含める
- センシティブな操作はログを記録
- 複雑な操作にはトランザクションを使用
経験談：API管理においては、Apidogを併用してAPIドキュメントとテストを維持しています。バックエンドの
GEMINI.mdで定義されたAPIは、Apidogで直接APIドキュメントとテストケースを生成できるため、フロントエンドとバックエンドのコラボレーション効率が大幅に向上します。新しいチームメンバーもドキュメントを見るだけですぐに作業を始められ、APIの詳細について何度も質問する必要がなくなります。
五、高度なテクニックとベストプラクティス
動的コンテキスト管理
/memory showコマンドを使用して、現在ロードされているすべてのコンテキストを確認できます：
gemini
> /memory show
これにより、ロードされたすべてのGEMINI.mdファイルの内容が表示され、設定が正しいかどうかを確認できます。
経験談：
GEMINI.mdを変更した後は、まず/memory showを実行して新しいコンテキストがロードされていることを確認します。ロードされていない場合は、CLIキャッシュをチェックするかセッションを再起動します。
条件付き設定
開発段階によって、異なる設定ファイルを作成できます：
# 開発段階設定
## 現在の開発フォーカス
- ユーザー認証モジュールを開発中
- 機能実装を優先し、パフォーマンス最適化は後で
- デバッグにはconsole.logを使用可能
## 一時的なルール
- 一時的にany型の使用を許可（開発完了後に修正）
- APIはモックデータを返すことが可能
経験談：「一時的なルール」には期限やissue番号を追加すると、クリーンアップを忘れません。
チーム協業設定
チーム用の標準化された設定テンプレート：
# チーム開発規約 v2.1
## コードレビュー要件
- すべてのPRは少なくとも2人のレビューが必要
- 新機能にはテストケースを含める
- 破壊的変更にはドキュメントの更新が必要
## コミット規約
- Conventional Commits形式を使用
- コミットメッセージにはissue番号を含める
- 各コミットは1つの論理的変更のみを含む
## ブランチ戦略
- mainブランチ：本番環境コード
- developブランチ：開発環境コード
- feature/*：機能開発ブランチ
- hotfix/*：緊急修正ブランチ
実践アドバイス：
GEMINI.mdをチーム合意の一部として扱い、リポジトリに保存してPRレビューを強制します。これにより、AIがPR説明、コミットメッセージ、コードを生成する際にチームのワークフローを参照できます。
六、よくある問題と解決策
問題一：設定が反映されない
症状：AIが生成したコードがGEMINI.mdの規約に従っていない
解決策：
- ファイルパスと名前が正しいか確認
-
/memory showを使用して設定がロードされているか確認 - 設定の説明が十分に明確で具体的であることを確認
さらなるチェック：ファイルがUTF-8形式か、BOMがないか、権限が正しいか、ファイル末尾に隠れた文字がないかを確認します。
問題二：設定の競合
症状：異なる階層の設定が矛盾している
解決策：
- 優先順位を理解する：サブディレクトリ > プロジェクト > グローバル
- 明示的な上書き文を使用
- 古い設定を定期的にクリーンアップ
アドバイス：各サブディレクトリの
GEMINI.mdの冒頭に「上書き説明」を書き、なぜこのファイルが親ルールを上書きするのかを説明します。
問題三：設定が複雑すぎる
症状：GEMINI.mdファイルが管理しにくくなる
解決策：
-
@import構文でモジュール化 - 定期的にリファクタリングして設定を簡素化
- 本当に必要なルールだけを残す
私は通常、四半期ごとに「設定レビュー」を行い、古くなったり使われなくなったりしたルールを削除して、メンテナンスの負担を軽減しています。
七、応用シナリオ
シナリオ一：多言語プロジェクト設定
# 多言語フルスタックプロジェクト
## 言語固有の規約
### Pythonバックエンド
- PEP 8規約に従う
- type hintsを使用
- ドキュメント文字列はGoogle形式
### Goマイクロサービス
- gofmtでフォーマット
- エラー処理は無視しない
- API設計はGoの慣例に従う
### TypeScriptフロントエンド
- 厳格モードを有効
- any型を禁止
- ESLint + Prettierを使用
実践アドバイス：各言語のCI/CDパイプラインにlint/formatプロセスを追加すると、AIがこれらのチェックに準拠したコードを生成する傾向が強まります。
シナリオ二：AIによるリファクタリング支援
# コードリファクタリングプロジェクト
## リファクタリング目標
- クラスコンポーネントを関数コンポーネントに移行
- jQueryの依存を削除し、ネイティブJavaScriptを使用
- パフォーマンスを最適化し、再レンダリングを減らす
## リファクタリング原則
- 機能を変更しない
- 段階的に移行し、大規模な書き換えを避ける
- リファクタリング後は完全なテストを実行
- 既存のAPIを維持
実践アドバイス：リファクタリングの範囲（ファイルリスト、単体テスト要件）を明確にし、AIにロールバック可能なパッチ形式の変更を出力させます。
シナリオ三：ドキュメント生成設定
# ドキュメント生成規約
## APIドキュメント要件
- OpenAPI 3.0形式を使用
- リクエスト/レスポンス例を含める
- エラーコードの説明を完全に
- 認証情報を含める
## コードドキュメント要件
- すべての公開メソッドにJSDocを付ける
- 複雑なアルゴリズムには詳細なコメントを
- 使用例を含める
- パラメータの型と戻り値を説明
実践アドバイス：
GEMINI.mdに実際の例（リクエスト/レスポンス）を1、2個添付すると、AIがドキュメントを生成する際にこれらのサンプルを再利用し、品質が向上します。
まとめ
GEMINI.mdファイルは単なる設定ファイルではなく、あなたとAIアシスタントの間の「契約」です。丁寧に設計された設定により、次のことが可能になります：
Tip：私はApidogを使ってAPIドキュメントとテストを管理することが多いです。これにより、
GEMINI.mdのルールをAPI生成と検証プロセスに直接マッピングでき、開発効率とコラボレーション体験が大幅に向上します。
- 開発効率の向上：繰り返しの説明が不要になり、AIが直接あなたの要件を理解
- コード品質の保証：統一された規約でチーム協業がスムーズに
- 学習コストの削減：新しいチームメンバーが設定を通じてプロジェクト規約を素早く理解
- パーソナライズ：AIアシスタントがあなたの開発習慣に完全に適応
良いGEMINI.md設定は以下のようであるべきです：
- 明確で具体的：曖昧な説明を避ける
- 段階的：シンプルから始めて徐々に改善
- 定期的に更新：プロジェクトの発展に合わせて設定を調整
- チームの合意：すべてのメンバーが理解し従う
今すぐあなたのプロジェクトにGEMINI.mdファイルを作成しましょう！Gemini CLIをあなたを本当に理解するインテリジェントなプログラミングパートナーにしましょう！