はじめに

Claude Code と Gemini CLI を使って「設計は Gemini、実装は Claude」という役割分担で並列開発する環境を構築・運用してきました。

本記事では、実際のプロジェクト運用から得たベストプラクティスを 設定ファイル一式とともに公開 します。テンプレート化してあるので、新しいプロジェクトにそのまま展開できます。

この記事で得られるもの

Claude Code のグローバル設定（~/.claude/）の設計パターン
マルチエージェント間の引き継ぎプロトコル
コンテキスト消費を抑える MCP vs CLI の使い分け原則
セッション管理のカスタムコマンド一式
すぐ使えるプロジェクトテンプレート

前提環境

Windows（Claude Code は Windows ネイティブ）
Claude Code インストール済み
Gemini CLI（または Gemini へのアクセス）
Git

~/.claude/ は Windows では %USERPROFILE%\.claude\ に該当します（例: C:\Users\<username>\.claude\）。
設定ファイル内のパス区切りは / を推奨します。

全体アーキテクチャ

設定は グローバル層（全 PJ 共通）と プロジェクト層（PJ 固有）の 2 層構造です。

~/.claude/                          ← グローバル層（全PJ共通）
├── CLAUDE.md                      ← 行動原則・TDD・マルチエージェント・MCP vs CLI
├── PRINCIPLES.md                  ← ソフトウェア工学原則（オンデマンド参照）
├── RULES.md                       ← 行動ルール詳細・判断ツリー（オンデマンド参照）
├── settings.json                  ← 権限・環境変数・hooks
└── commands/
    ├── session-start.md           ← セッション開始チェックリスト
    ├── session-end.md             ← セッション終了チェックリスト
    └── tdd-cycle.md               ← TDDサイクル実行手順

<project>/                          ← プロジェクト層（PJ固有）
├── CLAUDE.md                      ← ペルソナ・役割分担・ファイル所有権
├── GEMINI.md                      ← Gemini側の行動原則
├── CHANGELOG.md                   ← セッション成果記録
├── DECISIONS.md                   ← 設計判断記録
├── .claude/
│   ├── settings.local.json        ← PJ固有の権限
│   └── commands/                  ← PJ固有カスタムコマンド
├── .agents/
│   └── handoff/                   ← エージェント間引き継ぎバトン
│       ├── claude_to_gemini.md
│       └── gemini_to_claude.md
├── docs/                          ← 仕様書（Single Source of Truth）
├── src/                           ← 実装コード
└── tests/                         ← テストコード

この 2 層分離により、 グローバル CLAUDE.md を一度整えれば、新しいプロジェクトはテンプレートをコピーしてプレースホルダーを書き換えるだけ で環境が完成します。

CLAUDE.md の棲み分け

コンテキストトークンの消費を抑えるため、ファイルの役割を明確に分けています。

ファイル	役割	読み込みタイミング
`CLAUDE.md`	原則（What / Why）	毎セッション自動読み込み
`RULES.md`	詳細と判断ツリー（How）	必要時にオンデマンド参照
`PRINCIPLES.md`	ソフトウェア工学原則	必要時にオンデマンド参照

CLAUDE.md は常時読み込まれるため 簡潔に保つ ことが重要です。詳細は RULES.md に逃がし、Claude が必要に応じて参照する設計にしています。

Step 1: グローバル設定

settings.json — 権限・環境変数・hooks

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git:*)"
    ]
  },
  "hooks": {
    "Notification": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"📝 Reminder: Record results in CHANGELOG.md before ending session\" >&2'"
          }
        ]
      }
    ]
  }
}

ポイントは 3 つです。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: これを "1" にすると、Claude Code が .agents/ ディレクトリの引き継ぎファイルを認識します。マルチエージェント体制の前提条件です。

パーミッションのワイルドカード: Bash(git:*) のように書けば、git status, git diff, git log 等をすべてカバーできます。Bash(git status:*), Bash(git diff:*) と個別に列挙する必要はありません。

Notification hook: セッション終了時に CHANGELOG の記録を促すリマインダーです。

グローバル CLAUDE.md — 行動原則の定義

グローバル CLAUDE.md には、全プロジェクト共通の行動原則を定義します。

TDD 絶対遵守

### TDD 絶対遵守
- RED → GREEN → REFACTOR のサイクルを厳守
- テストなしのコード変更は禁止
- REFACTOR 6項目 (命名・責務・重複・複雑度・テスト品質・ドキュメント) を毎回チェック
- **適用範囲**: テスト可能なコード（src/ 配下のロジック）が対象。
  設定ファイルのみの変更、ドキュメント更新、データ分析スクリプト等は適用外

「適用範囲」を明記しているのがポイントです。当初は「全コード変更に TDD 必須」としていましたが、設定ファイル変更やドキュメント更新でも TDD を求められると現実的でないため、スコープを限定しました。

能動的行動原則（Proactive Behavior）

Claude をパッシブなツールではなく、状況を認識して能動的に動くエージェントとして定義します。行動を 3 段階に分類しています。

レベル	定義	例
🟢 自動実行	確認なしで即座に実行	`git status`, CHANGELOG追記, TDDフロー遵守
🟡 提案→確認→実行	理由を説明し承認後に実行	`/compact` 提案, SPEC作成提案
🔴 慎重実行	保全措置＋明示的確認を必須	`/clear`, `git push`, 破壊的操作

特に効果があったのは 🟢 自動実行アクション の定義です。

| トリガー | アクション | 理由 |
|---------|-----------|------|
| セッション最初の発話 | `/user:session-start` を実行 | 最新状況の確認 |
| 実装を指示された | `/user:tdd-cycle` フローに従う | TDD手順漏れ防止 |
| タスク完了時 | CHANGELOG.md に成果を追記 | 記録漏れ防止 |
| 重要な設計判断をした時 | DECISIONS.md に D-NNN で追記 | 判断の追跡可能性 |
| セッション終了指示 | `/user:session-end` を実行 | 記録更新を強制 |

これにより「セッション開始時に前回の引き継ぎを読み忘れる」「タスク完了時にCHANGELOGを書き忘れる」といった問題が解消されました。

コンテキスト管理

Claude Code 最大の課題であるコンテキスト枯渇に対処するため、使用率に応じた行動基準を定めています。

| 使用率 | Claude の行動 |
|--------|-------------|
| 0-50%  | 通常作業 |
| 50-70% | タスク完了後に `/clear` を検討提案 |
| 70-80% | 「⚠️ 70%超」と報告し `/compact` を提案 |
| 80%+   | 「🔴 80%超」と警告し `/clear` を慎重実行 |

Step 2: MCP vs CLI の使い分け原則

MCP サーバーはツール定義だけで数千トークンを消費します。実運用で顕著にコンテキストを圧迫することがわかったため、ツール選択原則を定めました。

| 優先度 | 手段 | 使う場面 |
|--------|------|----------|
| 1 | CLI（コマンドライン） | 同等の操作がCLIで完結する場合 |
| 2 | MCP サーバー | 外部サービスとの常時接続・双方向通信が必要な場合に限定 |

具体例を挙げると:

ツール	CLI利用（優先）	MCP利用（必要時のみ）
Playwright	`npx playwright test`	ブラウザの対話的制御が必要な場合
GitHub	`gh pr create`, `gh issue list`	— (CLIで十分)
Docker	`docker compose up`	— (CLIで十分)
データベース	`sqlite3`, `psql`	リアルタイム補完等が必要な場合
Slack等	—	常時接続・監視が必要 ✅

判断フローもシンプルです。

ツールが必要になった
  → CLI で同等の操作ができるか？
    → Yes → Bash 経由で CLI を使う
    → No  → MCP サーバーを有効化

この原則を入れてから、不要な MCP サーバーの無効化提案が自然に行われるようになりました。

Step 3: マルチエージェント並列開発

役割分担

	Gemini（設計・調査）	Claude（実装・品質）
担当	アーキテクチャ、分析方針、仕様策定	実装、テスト、リファクタリング
管理ファイル	`docs/`	`src/`, `tests/`
禁止事項	テストコードの直接変更	仕様の勝手な変更

引き継ぎプロトコル: バトンリレー方式

エージェント間の引き継ぎは .agents/handoff/ 配下のマークダウンファイルで行います。

Gemini セッション終了
  → .agents/handoff/gemini_to_claude.md を上書き更新
  → ユーザーが Claude セッション開始を指示

Claude セッション開始
  → .agents/handoff/gemini_to_claude.md を読み込み
  → 実装作業

Claude セッション終了
  → .agents/handoff/claude_to_gemini.md を上書き更新
  → ユーザーが Gemini セッション開始を指示

運用で重要なのは「上書き型」であること。追記型にすると引き継ぎファイルが肥大化してコンテキストを圧迫します。永続的な設計情報は docs/ に書き、引き継ぎファイルには「直近の変更」「残課題」「次にやってほしいこと」の差分情報のみを書きます。

引き継ぎテンプレート（Claude → Gemini）

# Claude から Gemini への引き継ぎ事項

**日時**: YYYY-MM-DD
**宛先**: Gemini
**送信元**: Claude

## 1. 本セッションの成果
<!-- 今回やったことを簡潔に -->

## 2. 現在のシステム状態
| 項目 | 状態 |
|------|------|
| テスト | passed / failed |
| 主要な変更 | — |

## 3. Geminiへのお願い
<!-- 設計レビュー、仕様追加、方針決定など -->

## 4. 注意事項
<!-- 既知の問題、制約事項など -->

引き継ぎテンプレート（Gemini → Claude）

# Gemini から Claude への引き継ぎ事項

**日時**: YYYY-MM-DD
**宛先**: Claude
**送信元**: Gemini

## 1. 設計・調査の成果
<!-- 今回の設計変更、リサーチ結果を簡潔に -->

## 2. docs/ の更新内容
<!-- 変更した仕様書とその概要 -->

## 3. Claudeへの実装依頼
<!-- 具体的な実装タスクと優先順位 -->

## 4. 注意事項
<!-- 実装時に気をつけるべきポイント -->

2 つのテンプレートを非対称にしているのは意図的です。Claude からは「実装結果・テスト状態」を、Gemini からは「設計変更・実装依頼」を重点的に伝える構造にしています。

ファイル所有権

マルチエージェント最大の問題は ファイル編集の競合 です。これを「所有権ルール」で解決しています。

# Geminiが主に管理（Claudeは提案のみ、直接編集は合意後）
docs/01_requirements.md
docs/02_architecture.md

# Claudeが主に管理
src/**/*.py
tests/**/*.py

# 共有ファイル（編集前にユーザーに確認）
README.md
CLAUDE.md
GEMINI.md

Step 4: カスタムコマンド

グローバルコマンド（~/.claude/commands/）

全プロジェクト共通で使うコマンドは 3 つです。

/user:session-start — セッション開始時にペルソナ適用 → 引き継ぎ確認 → docs 読み込み → テスト状態確認 → サマリ報告。

/user:session-end — MEMORY.md 更新 → CHANGELOG 追記 → 引き継ぎファイル上書き → 未コミット確認 → 最終報告。

/user:tdd-cycle — 仕様理解 → テスト作成 → RED → GREEN → REFACTOR（6 項目チェック）→ 全パス確認 → git commit。

プロジェクトコマンド（.claude/commands/）

PJ 固有のコマンドは 5 つをテンプレートとして用意しています。

コマンド	用途
`/project-start`	引き継ぎ確認 → docs読み込み → git状態確認 → タスク確認
`/project-end`	変更棚卸し → docs同期確認 → コミット確認 → 引き継ぎ作成
`/handoff`	Geminiへの引き継ぎコンテキスト生成
`/sync-docs`	src/ と docs/ のズレを検出し修正提案
`/test [file]`	テスト実行と結果レポート

コマンドファイルの形式は以下の通りです。allowed-tools で使用ツールを限定するのがポイントで、不要な権限を渡さない最小権限の原則を適用しています。

---
description: セッション終了。変更サマリー作成、docs同期確認、引き継ぎメモ生成
allowed-tools: Read, Glob, Grep, Bash(git:*)
---

## セッション終了チェックリスト
### 1. 変更内容の棚卸し
...

Step 5: プロジェクトテンプレートの使い方

テンプレートのコピーとプレースホルダー置換

テンプレート内の {{...}} を実際の値に置換するだけでセットアップ完了です。

プレースホルダー	説明	例
`{{PROJECT_NAME}}`	プロジェクト名	`my-app`
`{{PERSONA_NAME}}`	Claude側ペルソナ名	`魔法使いノンアララ`
`{{PERSONA_DESCRIPTION}}`	ペルソナの説明	語尾に「〜ルン」をつける…
`{{GEMINI_PERSONA_NAME}}`	Gemini側ペルソナ名	`アンサーキュウ`
`{{GEMINI_PERSONA_DESCRIPTION}}`	Gemini側の説明	—
`{{PROJECT_PATH}}`	プロジェクトのパス	`C:\Tools\my-app`

ペルソナを使わない場合は、該当セクションを丸ごと削除すればグローバルのデフォルトペルソナが適用されます。

settings.local.json のカスタマイズ

テンプレートには Python プロジェクト向けの最小限の権限のみ含まれています。

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(python:*)",
      "Bash(python3:*)",
      "Bash(pip install:*)",
      "Bash(ruff check:*)",
      "Bash(cd:*)",
      "Bash(head:*)",
      "Bash(tail:*)",
      "Bash(wc:*)"
    ]
  }
}

技術スタックに応じて追加します。

// Web系プロジェクト
"Bash(npm:*)",
"Bash(npx:*)"

// データ分析プロジェクト
"Bash(jupyter:*)"

ワイルドカードの活用が重要です。 Bash(python:*) があれば Bash(python -m pytest tests/ -v 2>&1) のような個別パターンは不要です。

ペルソナ活用のヒント

マルチエージェント体制でペルソナを設定すると、以下の効果があります。

エージェントの役割意識が強化される（「設計者」と「実装者」の人格分離）
引き継ぎファイルの送信元が直感的にわかる
ユーザーがどちらのエージェントと会話しているか即座に判別できる

プロジェクト CLAUDE.md にペルソナを書くと、そちらがグローバルのデフォルトペルソナより優先されます。

## ペルソナ設定: ノンアララ

このプロジェクトのセッションを開始する際、AIアシスタントは魔法使い「ノンアララ」のペルソナを採用します。
語尾に「〜ルン」をつけて、明るく元気な口調で応答してください。

設計上の判断と学び

なぜ引き継ぎファイルは「上書き型」なのか

最初は追記型（ログ形式）で運用していました。しかし数セッション後に引き継ぎファイルが数百行に膨れ上がり、それだけでコンテキストの大部分を消費してしまいました。永続情報は docs/ に書き、引き継ぎファイルは「使い捨てのバトン」として毎回上書きする方式に変更したところ、問題が解消しました。

なぜ RULES.md を分離したのか

当初はすべてを CLAUDE.md に書いていましたが、ファイルが肥大化し、毎セッション読み込むトークン量が増加しました。「原則（What/Why）」は CLAUDE.md に残し、「詳細な判断ツリー（How）」は RULES.md に分離してオンデマンド参照にすることで、通常セッションのコンテキスト消費を削減しています。

CHANGELOG.md と DECISIONS.md の自動追記

グローバル CLAUDE.md の 🟢 自動実行ルールで「タスク完了時に CHANGELOG に追記」「設計判断時に DECISIONS に追記」と定義しています。これにより、セッション終了後に「何をやったか思い出せない」「なぜこの設計にしたか不明」という問題を防いでいます。

まとめ

本記事で紹介した設定のポイントをまとめます。

2 層構造（グローバル＋プロジェクト）で設定の再利用性を最大化
能動的行動原則（🟢🟡🔴 の 3 段階分類）で Claude を「待ち」から「自律的」に変える
バトンリレー方式の引き継ぎで、マルチエージェント間のコンテキスト共有を軽量に保つ
ファイル所有権で、エージェント間の編集競合を防止
MCP vs CLI の選択原則で、コンテキスト消費を抑制
カスタムコマンドで、セッション開始/終了の手順を自動化

テンプレート一式は本記事のコードブロックからコピーして使えます。プレースホルダーを置換するだけで、すぐにマルチエージェント並列開発を始められます。

実際に運用してみると、設定の調整は繰り返し必要になります。この記事の設定も完成形ではなく、プロジェクトの特性に合わせて進化させていくものです。ぜひ自分のワークフローに合わせてカスタマイズしてみてください。