対象初心者〜中級者

達成目標最適な指示ファイル設計

前提知識Ch.1完了

所要時間20分

プロジェクト構成設計

GEMINI.md、.agent/ディレクトリ、AGENTS.md互換性の最適設計。プロジェクト固有の指示でエージェントの品質を最大化します。

GEMINI.md の設計

GEMINI.md はAntigravityエージェントがプロジェクトを理解するための最も重要なファイルです。プロジェクトのルートディレクトリに配置し、エージェントが参照する「プロジェクトの取扱説明書」として機能します。

役割

コンテキスト提供 — プロジェクトの目的、アーキテクチャ、技術スタックをエージェントに伝える
品質制御 — コーディング規約、命名規則、テストポリシーを定義する
ガードレール — 禁止パターン、やってはいけない操作を明確にする
効率化 — よく使うコマンド、デプロイ手順、ディレクトリ構成を記述し、毎回の説明を省略する

推奨構造（80〜120行）

GEMINI.md

# GEMINI.md

## プロジェクト概要
ECサイトのバックエンドAPI。Go 1.22 + Echo v4。
PostgreSQL 16をデータベースに使用。

## ディレクトリ構成
- cmd/          - エントリーポイント
- internal/api/ - HTTPハンドラ
- internal/domain/ - ビジネスロジック（純粋関数）
- internal/infra/ - DB・外部API連携
- migrations/   - SQLマイグレーション

## コーディング規約
- エラーは必ずラップして返す: fmt.Errorf("xxx: %w", err)
- テーブル駆動テストを使用する
- internal/domain/ に外部依存を含めない（interface経由）
- コミットメッセージは Conventional Commits に従う

## 禁止パターン
- panic() の使用禁止（main.goの初期化以外）
- グローバル変数の追加禁止
- ORM（GORM等）の使用禁止（sqlxのみ）
- 本番DBへの直接接続禁止

## よく使うコマンド
- make test       # 全テスト実行
- make lint       # golangci-lint
- make migrate-up # マイグレーション適用
- make dev        # ローカルサーバー起動（ホットリロード）

## デプロイ
Cloud Run + Cloud SQL。mainブランチへのマージでCI/CDが自動実行。

⚠️ Warning

/init で自動生成されるGEMINI.mdはそのまま使わないでください。デフォルトの内容は汎用的すぎて、エージェントの出力品質が著しく低下します。上記のように、プロジェクト固有の情報を具体的に記述することが重要です。

効果的なGEMINI.mdの書き方

原則	悪い例	良い例
具体的に	コードをきれいに書いてください	関数名はcamelCase、変数名はsnake_caseで書く
行動指示型	テストは重要です	新しい関数には必ずテーブル駆動テストを書く
禁止を明示	安全に書いてください	panic()の使用禁止。errors.Newでエラーを返す
短く保つ	200行以上の詳細説明	80〜120行に要点を凝縮

技術スタック別テンプレート: Node.js / TypeScript

GEMINI.md（Next.js + Prisma プロジェクト）

# プロジェクト概要
Next.js 15 + TypeScript + Prisma + PostgreSQLのWebアプリケーション

## 技術スタック
- Runtime: Node.js 22 LTS
- Framework: Next.js 15 (App Router)
- ORM: Prisma 6
- DB: PostgreSQL 16

## コーディング規約
- TypeScript strict mode必須
- Server ComponentsをデフォルトとしuseClientは最小限に
- Prisma schemaの変更時はmigrationファイルを必ず生成
- ESLint + Prettierの設定に従うこと

技術スタック別テンプレート: Python / Django

GEMINI.md（Django REST Framework プロジェクト）

# プロジェクト概要
Django 5.1 + Django REST Framework + Celery + PostgreSQLのAPI

## 技術スタック
- Python: 3.12
- Framework: Django 5.1 + DRF 3.15
- Task Queue: Celery + Redis
- DB: PostgreSQL 16

## コーディング規約
- Type hints必須 (PEP 484)
- ruff format + ruff checkに従うこと
- モデル変更時はmakemigrations→migrateの順で実行
- ViewSetはModelViewSetを継承し、permissionsを明示

.agent/ ディレクトリ

.agent/ ディレクトリはAntigravityの設定・スキル・ワークフローを格納する専用ディレクトリです。プロジェクトのルートに作成し、Gitで管理します。

ディレクトリ構成例

my-project/
├── .agent/
│   ├── config/
│   │   ├── settings.json      # エージェント設定
│   │   ├── models.json        # モデル選択設定
│   │   └── permissions.json   # 権限設定
│   ├── skills/
│   │   ├── deploy/
│   │   │   └── SKILL.md       # デプロイスキル定義
│   │   ├── review/
│   │   │   └── SKILL.md       # コードレビュースキル
│   │   └── test/
│   │       └── SKILL.md       # テスト実行スキル
│   ├── workflows/
│   │   ├── pr-review.yaml     # PRレビューワークフロー
│   │   └── daily-standup.yaml # 日次レポート
│   └── templates/
│       ├── commit-message.md  # コミットメッセージテンプレート
│       └── pr-description.md  # PR説明テンプレート
├── GEMINI.md
├── AGENTS.md                   # 互換性ファイル（オプション）
└── src/

config/ ディレクトリ

エージェントの動作を制御する設定ファイルを格納します。

.agent/config/settings.json

{
  "agent": {
    "mode": "agent-assisted",
    "model": "gemini-3-pro",
    "temperature": 0.1,
    "maxTokens": 8192
  },
  "indexing": {
    "exclude": ["node_modules", "dist", ".git", "*.lock"],
    "maxFileSize": "1MB"
  },
  "terminal": {
    "shell": "/bin/zsh",
    "timeout": 30000
  }
}

skills/ ディレクトリ

各スキルは独自のサブディレクトリに SKILL.md を持ちます。詳細はCh.4「Agent Skills」で解説します。

workflows/ ディレクトリ

複数ステップからなる自動化ワークフローをYAMLで定義します。CI/CDパイプラインのようなイメージで、エージェントが順次実行します。

✅ Tip

.agent/ ディレクトリはGitにコミットして、チーム全体で共有してください。エージェントの設定をコードとして管理（Configuration as Code）することで、チームメンバー全員が同じ品質のエージェント支援を受けられます。

AGENTS.md 互換性

Antigravity v1.20.3以降、AGENTS.md ファイルを認識します。これにより、Claude Code（CLAUDE.md）やCursor（.cursorrules）と共通の指示ファイルを維持しつつ、Antigravity固有の設定を追加できます。

読み込み優先順位

GEMINI.md（最優先 — Antigravity固有）
AGENTS.md（マルチツール共通指示）
CLAUDE.md（Claude Code互換 — フォールバック）
.cursorrules（Cursor互換 — フォールバック）

📝 Note

複数ファイルが存在する場合、上位のファイルの指示が優先されます。矛盾がある場合は GEMINI.md の記述が採用されます。

マルチツール対応の戦略

推奨ファイル構成

my-project/
├── AGENTS.md        # 共通指示（コーディング規約、アーキテクチャ方針）
├── GEMINI.md        # Antigravity固有（モデル設定、Skills参照、ワークフロー）
├── CLAUDE.md        # Claude Code固有（Hooks設定、Plugin参照）
└── .cursorrules     # Cursor固有（UI設定）

チームで複数のAIコーディングツールを使用している場合、AGENTS.md に共通のコーディング規約を記述し、ツール固有の設定は各ファイルに分離するのがベストプラクティスです。

AGENTS.md（共通指示の例）

# AGENTS.md - マルチツール共通指示

## コーディング規約
- TypeScript strict mode必須
- 関数は30行以内に収める
- any型の使用禁止
- console.log はデバッグ目的のみ（本番コードでは削除）

## テストポリシー
- ユニットテストカバレッジ80%以上
- E2Eテストはユーザーストーリー単位

## Git規約
- Conventional Commits（feat:, fix:, docs:, refactor:, test:）
- PRは1機能/1バグ修正に限定

マルチツール対応マトリクス

各AIコーディングツールがどの設定ファイルを読み込むかの一覧です。

ファイル	Antigravity	Claude Code	Codex	Cursor
`GEMINI.md`	✅ 読込	❌	❌	❌
`AGENTS.md`	✅ 読込	❌	✅ 読込	✅ 読込
`CLAUDE.md`	❌	✅ 読込	❌	❌
`.cursorrules`	❌	❌	❌	✅ 読込
`copilot-instructions.md`	❌	❌	❌	❌ (Copilot用)

✅ Tip

AGENTS.mdは最も汎用性が高く、Antigravity・Codex・Cursorの3ツールで共有できます。マルチツール環境ではAGENTS.mdを共通ルールファイルとして活用し、ツール固有の設定はGEMINI.mdやCLAUDE.mdに分離するのが推奨パターンです。

スコープ設計

Antigravityの設定はワークスペーススコープとグローバルスコープの2層で管理できます。

ワークスペーススコープ

プロジェクトごとの設定。.agent/ ディレクトリと GEMINI.md が該当します。Gitにコミットしてチーム共有できます。

ワークスペース設定の場所

my-project/.agent/config/settings.json
my-project/.agent/skills/
my-project/GEMINI.md

グローバルスコープ

全プロジェクト共通の設定。~/.gemini/antigravity/ に配置します。個人の好みやグローバルなスキルを定義するのに適しています。

グローバル設定の場所

~/.gemini/antigravity/
├── config/
│   ├── global-settings.json    # 全PJ共通設定
│   └── model-preferences.json  # モデル優先順位
├── skills/
│   ├── git-workflow/
│   │   └── SKILL.md            # Git操作の汎用スキル
│   └── code-review/
│       └── SKILL.md            # コードレビュー汎用スキル
└── templates/
    └── commit-message.md       # コミットメッセージテンプレート

スコープ	場所	Git管理	用途
ワークスペース	`.agent/`	チーム共有推奨	PJ固有の規約・スキル・ワークフロー
グローバル	`~/.gemini/antigravity/`	個人（dotfiles管理可）	個人の好み・汎用スキル・モデル設定

📝 Note

ワークスペース設定がグローバル設定より優先されます。同じキーが両方に定義されている場合、ワークスペースの値が使用されます。

ルール適用モード

Antigravityでは、ルールファイルの適用タイミングを4つのモードで制御できます。用途に応じて適切なモードを選択することで、コンテキストの無駄遣いを防ぎます。

モード	動作	ユースケース
Always On	常にコンテキストにロードされる	セキュリティルール、コーディング規約など絶対に守るべきルール
Model Decision	AIがルールの説明を読み、関連性がある場合のみロード	特定フレームワーク向けルール、テスト規約など
Glob	特定のファイルパスパターンに一致する場合のみ適用	`.test.ts` に対するテストルール、`src/api/*` のAPI規約など
Manual	ユーザーが明示的に呼び出した場合のみ適用	デプロイ手順、マイグレーションガイドなど頻度の低い作業

.agents/rules/ でモードを指定する例

# .agents/rules/security.md
---
description: セキュリティに関する必須ルール
mode: always
---

# セキュリティルール
- APIキーをコードに直接記述しないこと
- ユーザー入力は必ずバリデーションすること

# .agents/rules/testing.md
---
description: テストファイル作成時のルール
mode: glob
globs: ["**/*.test.ts", "**/*.spec.ts"]
---

# テストルール
- describeブロックで機能単位にグループ化
- 1テスト1アサーションを原則とする

AGENTS.md の推奨テンプレート

プロジェクトルートの AGENTS.md には、セッションライフサイクル・ワークフロールール・メモリプロトコルを含む包括的な指示を定義します。

AGENTS.md 推奨テンプレート

# AGENTS.md

## Session Lifecycle
- セッション開始時にプロジェクト構造を確認すること
- 大きな変更の前にPlanを提示し承認を得ること
- セッション終了時に未完了タスクをまとめること

## Workflow Rules
- コード変更後は必ずテストを実行すること
- 新規ファイル作成時は既存の命名規約に従うこと
- PRは1つの論理的変更につき1つにすること

## Memory Protocol
- 重要な設計判断はコメントとして残すこと
- TODO/FIXME/HACKタグで技術的負債を追跡すること

## Boundaries
- 本番環境のデータベースに直接接続しないこと
- 外部APIの認証情報はすべて環境変数経由とすること
- node_modules/ と dist/ は変更しないこと

✅ Tip

AGENTS.md はClaude Code・Codex・Cursorでも読み込まれるため、チームで複数ツールを使う場合のクロスツール共通指示ファイルとして最適です。

ベストプラクティス

GEMINI.mdと.agent/ディレクトリの設計で最大の効果を得るためのベストプラクティスです。

具体的で短く書く

GEMINI.mdは80〜120行が理想。長すぎるとエージェントのコンテキストウィンドウを無駄に消費し、重要な指示が埋もれます。抽象的な哲学より、具体的なルールを書きましょう。

行動指示型で書く

「〜は重要です」ではなく「〜してください / 〜は禁止」のように、明確な行動指示を書きます。エージェントは曖昧な指示を無視する傾向があります。

禁止パターンを明示する

やるべきことだけでなく「やってはいけないこと」を明確に列挙します。特にプロジェクト固有のアンチパターンは必ず記述してください。

定期的に更新する

プロジェクトの進化に合わせてGEMINI.mdを更新します。新しいパッケージの追加、アーキテクチャ変更、チームルールの変更を反映しましょう。月1回の見直しを推奨します。

チームでレビューする

GEMINI.mdの変更はPRとしてレビューします。コーディング規約と同じ重要度で扱い、チーム全体の合意を得てからマージしましょう。

悪い例

GEMINI.md（曖昧な指示）

# ルール
コードの品質を高く保つこと。
テストを書くこと。
セキュリティに注意すること。
パフォーマンスを意識すること。

良い例

GEMINI.md（具体的で検証可能な指示）

# コーディング規約
- any型の使用禁止。unknown + 型ガードを使うこと
- console.logでのデバッグ禁止。logger.debug()を使うこと
- API関数には必ずエラーハンドリングを実装すること
- 新規コンポーネントには単体テストを必須とする

# 禁止パターン
- node_modules/、dist/、.env* への書き込み禁止
- git push --force 禁止
- rm -rf / 禁止

⚠️ Warning

曖昧な指示はエージェントに無視されます。「品質を高く保つ」ではなく「any型禁止」「console.log禁止」のように、具体的で検証可能なルールを書きましょう。

✅ Tip

GEMINI.mdのテンプレートを社内で標準化すると、新規プロジェクトの立ち上げが高速化します。セクション構成（概要・ディレクトリ・規約・禁止・コマンド・デプロイ）をテンプレートとして共有しましょう。

← 前のページ

Getting Started

Editor & Manager