# Everything Claude Code 長文ガイド

![Header: The Longform Guide to Everything Claude Code](./assets/images/longform/01-header.png)

---

> **前提条件**: このガイドは[Everything Claude Code 簡潔ガイド](./the-shortform-guide.md)を基に構成されています。スキル、フック、サブエージェント、MCP、プラグインのセットアップがまだの場合は、先にそちらをお読みください。

![Reference to Shorthand Guide](./assets/images/longform/02-shortform-reference.png)
*簡潔ガイド - まずこちらを読んでください*

簡潔ガイドでは、基礎的なセットアップをカバーしました：スキルとコマンド、フック、サブエージェント、MCP、プラグイン、そして効果的なClaude Codeワークフローのバックボーンとなる設定パターン。それはセットアップガイドであり、基盤インフラでした。

この長文ガイドでは、生産的なセッションと無駄なセッションを分ける技術に踏み込みます。簡潔ガイドを読んでいない場合は、戻って設定を先に行ってください。以下は、スキル、エージェント、フック、MCPが既に設定され動作していることを前提としています。

ここでのテーマ：トークンエコノミクス、メモリ永続化、検証パターン、並列化戦略、そして再利用可能なワークフロー構築の複利効果。これらは10ヶ月以上の日常使用で磨き上げたパターンであり、最初の1時間でコンテキスト劣化に悩まされるか、何時間も生産的なセッションを維持できるかの違いを生みます。

簡潔ガイドと長文ガイドで取り上げたすべてのものはGitHubで利用可能です：`github.com/affaan-m/everything-claude-code`

---

## ヒントとコツ

### 一部のMCPは代替可能で、コンテキストウィンドウを解放できる

バージョン管理（GitHub）、データベース（Supabase）、デプロイメント（Vercel、Railway）などのMCPについて — これらのプラットフォームのほとんどは、MCPが本質的にラップしているだけの堅牢なCLIを既に持っています。MCPは便利なラッパーですが、コストが伴います。

MCPを実際に使用せずにCLIをMCPのように機能させるには（それに伴うコンテキストウィンドウの縮小なしに）、機能をスキルとコマンドにバンドルすることを検討してください。MCPが公開する便利なツールを取り出して、コマンドに変換してください。

例：常にGitHub MCPをロードする代わりに、好みのオプションで `gh pr create` をラップする `/gh-pr` コマンドを作成。Supabase MCPにコンテキストを消費させる代わりに、Supabase CLIを直接使用するスキルを作成。

遅延読み込みにより、コンテキストウィンドウの問題はほぼ解決されています。しかし、トークン使用量とコストは同じようには解決されていません。CLI + スキルアプローチは依然としてトークン最適化手法です。

---

## 重要な内容

### コンテキストとメモリ管理

セッション間でメモリを共有するには、進捗を要約してチェックインし、`.claude`フォルダの`.tmp`ファイルに保存してセッション終了まで追記するスキルまたはコマンドが最善策です。翌日にはそれをコンテキストとして使用し、中断した箇所から再開できます。古いコンテキストが新しい作業を汚染しないよう、各セッションごとに新しいファイルを作成してください。

![Session Storage File Tree](./assets/images/longform/03-session-storage.png)
*セッションストレージの例 -> <https://github.com/affaan-m/everything-claude-code/tree/main/examples/sessions>*

Claudeが現在の状態を要約するファイルを作成します。レビューし、必要に応じて編集を依頼し、新しく開始。新しい会話では、ファイルパスを提供するだけです。コンテキスト制限に達して複雑な作業を継続する必要がある場合に特に便利です。これらのファイルには以下を含めるべきです：
- うまくいったアプローチ（エビデンス付きで検証可能）
- 試みたが機能しなかったアプローチ
- まだ試みていないアプローチと残りの作業

**コンテキストの戦略的クリア：**

計画が設定されコンテキストがクリアされたら（Claude Codeの計画モードのデフォルトオプション）、計画に基づいて作業できます。実行にもはや関連しない多くの探索コンテキストが蓄積された場合に便利です。戦略的な圧縮には、自動圧縮を無効化してください。論理的な間隔で手動圧縮するか、それを行うスキルを作成してください。

**上級：動的システムプロンプト注入**

私が身につけたパターン：CLAUDE.md（ユーザースコープ）や`.claude/rules/`（プロジェクトスコープ）にすべてを入れる代わりに — 毎セッション読み込まれる — CLIフラグを使ってコンテキストを動的に注入。

```bash
claude --system-prompt "$(cat memory.md)"
```

これにより、どのコンテキストをいつ読み込むかについて、より外科的に対応できます。システムプロンプトの内容はユーザーメッセージより権限が高く、ユーザーメッセージはツール結果より権限が高いです。

**実践的なセットアップ：**

```bash
# 日常開発
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'

# PRレビューモード
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'

# リサーチ/探索モード
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'
```

**上級：メモリ永続化フック**

メモリに役立つ、ほとんどの人が知らないフックがあります：

- **PreCompactフック**: コンテキスト圧縮の前に、重要な状態をファイルに保存
- **Stopフック（セッション終了）**: セッション終了時に学習内容をファイルに永続化
- **SessionStartフック**: 新しいセッションで前回のコンテキストを自動読み込み

これらのフックを構築し、リポジトリの`github.com/affaan-m/everything-claude-code/tree/main/hooks/memory-persistence`に置いています。

---

### 継続学習 / メモリ

プロンプトを複数回繰り返す必要があり、Claudeが同じ問題に遭遇したり以前聞いた回答を返す場合 — そのパターンはスキルに追加すべきです。

**問題：** トークンの浪費、コンテキストの浪費、時間の浪費。

**解決策：** Claude Codeが自明でないことを発見した場合 — デバッグ技術、回避策、プロジェクト固有のパターンなど — その知識を新しいスキルとして保存。次回同様の問題が発生した際、スキルが自動的に読み込まれます。

この機能を実現する継続学習スキルを構築しました：`github.com/affaan-m/everything-claude-code/tree/main/skills/continuous-learning`

**なぜStopフック（UserPromptSubmitではなく）：**

重要な設計判断は、UserPromptSubmitではなく**Stopフック**を使用すること。UserPromptSubmitはすべてのメッセージで実行され、すべてのプロンプトにレイテンシーを追加します。Stopはセッション終了時に1回実行 — 軽量で、セッション中の速度を落としません。

---

### トークン最適化

**主要戦略：サブエージェントアーキテクチャ**

使用するツールを最適化し、タスクに十分な最も安価なモデルに委任するよう設計されたサブエージェントアーキテクチャ。

**モデル選択クイックリファレンス：**

![Model Selection Table](./assets/images/longform/04-model-selection.png)
*さまざまな一般的タスクにおけるサブエージェントの仮想セットアップと選択理由*

| タスクタイプ | モデル | 理由 |
|-------------|--------|------|
| 探索/検索 | Haiku | 高速、低コスト、ファイル検索には十分 |
| 単純な編集 | Haiku | 単一ファイルの変更、明確な指示 |
| マルチファイル実装 | Sonnet | コーディングに最適なバランス |
| 複雑なアーキテクチャ | Opus | 深い推論が必要 |
| PRレビュー | Sonnet | コンテキストを理解し、ニュアンスを検出 |
| セキュリティ分析 | Opus | 脆弱性の見逃しは許されない |
| ドキュメント作成 | Haiku | 構造はシンプル |
| 複雑なバグのデバッグ | Opus | システム全体を頭に入れる必要がある |

コーディングタスクの90%はSonnetをデフォルトに。最初の試みが失敗した場合、タスクが5ファイル以上にまたがる場合、アーキテクチャの意思決定、またはセキュリティクリティカルなコードの場合にOpusにアップグレード。

**価格リファレンス：**

![Claude Model Pricing](./assets/images/longform/05-pricing-table.png)
*出典: <https://platform.claude.com/docs/en/about-claude/pricing>*

**ツール固有の最適化：**

grepをmgrepに置き換え — 従来のgrepやripgrepと比較して平均約50%のトークン削減：

![mgrep Benchmark](./assets/images/longform/06-mgrep-benchmark.png)
*50タスクのベンチマークで、mgrep + Claude Codeはgrepベースのワークフローと同等以上の品質で約2倍少ないトークンを使用。出典：@mixedbread-aiによるmgrep*

**モジュラーコードベースの利点：**

メインファイルが数千行ではなく数百行の、よりモジュラーなコードベースを持つことは、トークン最適化コストと初回でタスクを正しく完了する両方に役立ちます。

---

### 検証ループと評価

**ベンチマークワークフロー：**

スキルありとなしで同じことを依頼し、出力の違いを確認して比較：

会話をフォークし、一方でスキルなしのワークツリーを開始、最後にdiffを取り出して、記録された内容を確認。

**評価パターンタイプ：**

- **チェックポイントベースの評価**: 明示的なチェックポイントを設定、定義された基準に対して検証、進む前に修正
- **継続的な評価**: N分ごとまたは大きな変更後に実行、フルテストスイート + リント

**主要メトリクス：**

```
pass@k: k回の試行のうち少なくとも1回が成功
        k=1: 70%  k=3: 91%  k=5: 97%

pass^k: k回の試行すべてが成功する必要がある
        k=1: 70%  k=3: 34%  k=5: 17%
```

とにかく動けばよい場合は**pass@k**を使用。一貫性が重要な場合は**pass^k**を使用。

---

## 並列化

マルチClaude端末セットアップで会話をフォークする際は、フォークと元の会話のアクションのスコープを明確に定義してください。コード変更の重複を最小限にすることを目指しましょう。

**私の推奨パターン：**

メインチャットでコード変更、フォークでコードベースの現状に関する質問や外部サービスのリサーチ。

**任意のターミナル数について：**

![Boris on Parallel Terminals](./assets/images/longform/07-boris-parallel.png)
*Boris（Anthropic）が複数のClaudeインスタンスの実行について*

Borisは並列化のヒントを持っています。ローカルで5つ、上流で5つのClaudeインスタンスを実行するようなことを提案しています。任意のターミナル数の設定は推奨しません。ターミナルの追加は本当の必要性から生まれるべきです。

目標は：**最小限の並列化で最大限の成果を得ること。**

**並列インスタンス用Gitワークツリー：**

```bash
# 並列作業用にワークツリーを作成
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-refactor refactor-branch

# 各ワークツリーに独自のClaudeインスタンス
cd ../project-feature-a && claude
```

インスタンスのスケーリングを開始し、複数のClaudeインスタンスが互いに重複するコードで作業する場合、gitワークツリーを使用し、各インスタンスに非常に明確な計画を持つことが不可欠です。`/rename <名前>`を使用してすべてのチャットに名前を付けてください。

![Two Terminal Setup](./assets/images/longform/08-two-terminals.png)
*初期セットアップ：左ターミナルでコーディング、右ターミナルで質問 - /renameと/forkを使用*

**カスケード方式：**

複数のClaude Codeインスタンスを実行する際は、「カスケード」パターンで整理：

- 新しいタスクは右側の新しいタブで開く
- 左から右へ、古いものから新しいものへスイープ
- 同時に最大3〜4タスクに集中

---

## 基礎固め

**2インスタンスキックオフパターン：**

自分のワークフロー管理として、空のリポジトリで2つのClaudeインスタンスを開いて開始するのが好きです。

**インスタンス1：スキャフォールディングエージェント**
- スキャフォールドと基礎を構築
- プロジェクト構造を作成
- 設定をセットアップ（CLAUDE.md、ルール、エージェント）

**インスタンス2：ディープリサーチエージェント**
- すべてのサービスに接続、Web検索
- 詳細なPRDを作成
- アーキテクチャのMermaidダイアグラムを作成
- 実際のドキュメント抜粋で参照をコンパイル

**llms.txtパターン：**

利用可能な場合、多くのドキュメントリファレンスのドキュメントページで `/llms.txt` を実行することで `llms.txt` を見つけることができます。これにより、LLMに最適化されたクリーンなドキュメントバージョンが得られます。

**哲学：再利用可能なパターンの構築**

@omarsar0より：「早い段階で再利用可能なワークフロー/パターンの構築に時間を費やしました。構築は面倒でしたが、モデルとエージェントハーネスが改善されるにつれ、驚異的な複利効果をもたらしました。」

**投資すべきもの：**

- サブエージェント
- スキル
- コマンド
- 計画パターン
- MCPツール
- コンテキストエンジニアリングパターン

---

## エージェントとサブエージェントのベストプラクティス

**サブエージェントのコンテキスト問題：**

サブエージェントは、すべてをダンプする代わりにサマリーを返すことでコンテキストを節約するために存在します。しかし、オーケストレーターにはサブエージェントが持たないセマンティックコンテキストがあります。サブエージェントはリテラルなクエリのみを知り、リクエストの背後にある目的は知りません。

**反復的検索パターン：**

1. オーケストレーターがすべてのサブエージェントの返答を評価
2. 受け入れる前にフォローアップの質問をする
3. サブエージェントがソースに戻り、回答を取得して返す
4. 十分になるまでループ（最大3サイクル）

**鍵：** クエリだけでなく、目的のコンテキストを渡す。

**シーケンシャルフェーズを持つオーケストレーター：**

```markdown
フェーズ1: リサーチ（Exploreエージェント使用） → research-summary.md
フェーズ2: 計画（plannerエージェント使用） → plan.md
フェーズ3: 実装（tdd-guideエージェント使用） → コード変更
フェーズ4: レビュー（code-reviewerエージェント使用） → review-comments.md
フェーズ5: 検証（必要に応じてbuild-error-resolver使用） → 完了またはループバック
```

**主要ルール：**

1. 各エージェントは1つの明確な入力を受け取り、1つの明確な出力を生成
2. 出力は次のフェーズの入力になる
3. フェーズをスキップしない
4. エージェント間で `/clear` を使用
5. 中間出力をファイルに保存

---

## 楽しいもの / 重要ではないけど面白いヒント

### カスタムステータスライン

`/statusline` を使って設定できます — Claudeが「まだないけど設定できます」と言い、何を入れたいか聞いてきます。

参照：ccstatusline（カスタムClaude Codeステータスラインのコミュニティプロジェクト）

### 音声入力

音声でClaude Codeと会話。多くの人にとってタイピングより速いです。

- MacではsuperwhisperやMacWhisper
- 音声認識のミスがあっても、Claudeは意図を理解します

### ターミナルエイリアス

```bash
alias c='claude'
alias gb='github'
alias co='code'
alias q='cd ~/Desktop/projects'
```

---

## マイルストーン

![25k+ GitHub Stars](./assets/images/longform/09-25k-stars.png)
*1週間足らずでGitHub 25,000+スター*

---

## リソース

**エージェントオーケストレーション：**

- claude-flow — 54以上の専門エージェントを持つコミュニティ構築のエンタープライズオーケストレーションプラットフォーム

**自己改善メモリ：**

- このリポジトリの `skills/continuous-learning/` を参照
- rlancemartin.github.io/2025/12/01/claude_diary/ - セッション振り返りパターン

**システムプロンプトリファレンス：**

- system-prompts-and-models-of-ai-tools — AIシステムプロンプトのコミュニティコレクション（110k+スター）

**公式：**

- Anthropic Academy: anthropic.skilljar.com

---

## 参考文献

- [Anthropic: AIエージェントの評価を解明する](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
- [YK: 32のClaude Codeヒント](https://agenticcoding.substack.com/p/32-claude-code-tips-from-basics-to)
- [RLanceMartin: セッション振り返りパターン](https://rlancemartin.github.io/2025/12/01/claude_diary/)
- @PerceptualPeak: サブエージェントコンテキストネゴシエーション
- @menhguin: エージェント抽象化ティアリスト
- @omarsar0: 複利効果の哲学

---

*両ガイドで取り上げたすべてのものはGitHubの[everything-claude-code](https://github.com/affaan-m/everything-claude-code)で利用可能です*