【翻訳】Claude Codeハッカソン優勝者が教える上級テクニック完全ガイド
Shuです。普段はAIツール、特にClaude CodeやOpenCodeを使ってAI駆動のソフトウェア開発を行っています。
先日、Claude Codeハッカソンの優勝者である @affaanmustafa 氏が公開した「The Longform Guide to Everything Claude Code」という記事を読みました。この記事は、氏が以前公開した「The Shorthand Guide to Everything Claude Code」（基本設定ガイド：スキル、コマンド、フック、サブエージェント、MCP、プラグインの設定方法）の続編で、10ヶ月以上の日常使用で磨き上げた実践テクニックが詰まっています。
元記事のテーマは「トークン経済学、メモリ永続化、検証パターン、並列化戦略、そして再利用可能なワークフロー構築の複利効果」。これらのパターンが、最初の1時間でコンテキストが腐敗するセッションと、何時間も生産的に作業できるセッションの違いを生むとのこと。
今回は、この記事の内容を日本語でまとめて紹介します。
この記事で紹介するテクニック
- コンテキスト＆メモリ管理 - セッション間でのメモリ共有と戦略的コンパクト
- 動的システムプロンプト注入 - タスク別のコンテキスト切り替え
- メモリ永続化フック - フックを使った自動的な状態保存
- 継続学習/メモリ - 学習した知識をスキルとして保存
- トークン最適化 - モデル選択とコスト削減テクニック
- 検証ループと評価 - 出力品質の担保方法
- 並列化 - Git Worktreeを使った複数インスタンス運用
- 初期設定（Groundwork） - 新規プロジェクトの効率的な立ち上げ
- エージェント＆サブエージェント - 効果的なエージェント設計
- Tips & Tricks - MCPの代替手段など
それぞれ詳しく見ていきましょう。
1. コンテキスト＆メモリ管理
セッション間メモリ共有の仕組み
Claude Codeはセッションごとにコンテキストがリセットされます。これを乗り越えるには、セッションの進捗を要約して .claude/ フォルダ内の .tmp ファイルに保存するスキル/コマンドを使うのがベストです。
翌日はそのファイルをコンテキストとして読み込んで、前回の続きから作業を再開できます。
保存すべき内容:
- うまくいったアプローチ（証拠付き）
- 試したけどダメだったアプローチ
- まだ試していないアプローチ
- 残りのタスク
戦略的コンパクト
自動コンパクトは任意のタイミング（タスクの途中など）で発生してしまう問題があります。
手動コンパクトの利点:
- 探索フェーズの後、実行フェーズの前にコンパクト
- マイルストーン完了後、次のタスク開始前にコンパクト
- 論理的なフェーズを通じてコンテキストを保持できる
以下は、戦略的なタイミングでコンパクトを提案するスクリプトの例です（PreToolUseフックでEdit/Write操作にフックして使用）：
#!/bin/bash
# Strategic Compact Suggester
# 自動コンパクトではなく手動コンパクトを推奨する理由：
# - 自動コンパクトはタスクの途中など任意のタイミングで発生
# - 戦略的コンパクトは論理的なフェーズを通じてコンテキストを保持
# - 探索後、実行前にコンパクト
# - マイルストーン完了後、次のタスク開始前にコンパクト
COUNTER_FILE="/tmp/claude-tool-count-$$"
THRESHOLD=${COMPACT_THRESHOLD:-50}
# カウンターの初期化または増分
if [ -f "$COUNTER_FILE" ]; then
count=$(cat "$COUNTER_FILE")
count=$((count + 1))
echo "$count" > "$COUNTER_FILE"
else
echo "1" > "$COUNTER_FILE"
count=1
fi
# 閾値到達時にコンパクトを提案
if [ "$count" -eq "$THRESHOLD" ]; then
echo "[StrategicCompact] $THRESHOLD tool calls reached - consider /compact if transitioning phases" >&2
fi
2. 動的システムプロンプト注入
@file 参照 vs --system-prompt の違い
| 方法 | 動作 | 優先度 |
|---|---|---|
@memory.md |
Read ツール経由で読み込み（ツール出力として） | 低 |
.claude/rules/ |
同上 | 低 |
--system-prompt |
会話開始前にシステムプロンプトに注入 | 高 |
命令の優先度ヒエラルキー:
システムプロンプト > ユーザーメッセージ > ツール結果
実用的なセットアップ例
タスクの種類に応じて異なるコンテキストを自動的に注入するaliasを設定できます：
# 日常開発
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)"'
各コンテキストファイルの役割:
-
dev.md: 実装に集中 -
review.md: コード品質・セキュリティに集中 -
research.md: 行動前の探索に集中
3. メモリ永続化フック
フックを使うと、セッション間で自動的に状態を保存・復元できます。
セッション間の流れ
セッション1 セッション2
───────── ─────────
[開始] [開始]
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ SessionStart │ │ SessionStart │◄── 前回のコンテキスト
│ Hook │ │ Hook │ を自動読み込み
└──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
[作業中] [作業中]
│ （情報を持っている）
▼
┌──────────────┐
│ PreCompact │──► コンパクト前に
│ Hook │ 状態を保存
└──────┬───────┘
│
▼
[コンパクト完了]
│
▼
┌──────────────┐
│ Stop Hook │──► ~/.claude/sessions/
│ (セッション終了)│ に永続化
└──────────────┘
フック設定
{
"hooks": {
"PreCompact": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "~/.claude/hooks/memory-persistence/pre-compact.sh"
}]
}],
"SessionStart": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "~/.claude/hooks/memory-persistence/session-start.sh"
}]
}],
"Stop": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "~/.claude/hooks/memory-persistence/session-end.sh"
}]
}]
}
}
各スクリプトの役割:
-
pre-compact.sh: コンパクトイベントをログ、アクティブセッションファイルにタイムスタンプ更新 -
session-start.sh: 直近7日間のセッションファイルをチェック、利用可能なコンテキストと学習済みスキルを通知 -
session-end.sh: 日次セッションファイルを作成/更新、開始・終了時刻を記録
4. 継続学習/メモリ
問題
同じ問題でClaudeが同じミスを繰り返す → 毎回「軌道修正」のプロンプトが必要 → トークンの無駄、時間の無駄、ストレス
解決策
Claude Codeが非自明な発見（デバッグテクニック、回避策、プロジェクト固有のパターン）をしたとき、その知識を新しいスキルとして保存。次に似た問題が発生したら、そのスキルが自動的にロードされます。
なぜ Stop フックを使うのか？
| フック | タイミング | オーバーヘッド |
|---|---|---|
| UserPromptSubmit | 毎メッセージ送信時 | 高（レイテンシ増加） |
| Stop | セッション終了時のみ | 低 |
Stop フックはセッション全体を評価できるので、断片的ではなく包括的な分析が可能です。
手動抽出: /learn コマンド
セッション終了を待たずに、非自明な問題を解決した直後に /learn コマンドを実行。パターンをその場で抽出し、スキルファイルのドラフトを作成、確認後に保存します。
セッションログのパターン
ファイル名: ~/.claude/sessions/YYYY-MM-DD-topic.tmp
内容:
- 現在の状態
- 完了項目
- ブロッカー
- 重要な決定
- 次のセッションのためのコンテキスト
その他の自己改善メモリパターン
@RLanceMartin のアプローチ: セッションログを振り返り、ユーザーの好みを抽出する「日記」を構築。各セッション後に振り返りエージェントが、うまくいったこと・失敗したこと・修正したことを抽出し、次のセッションで読み込むメモリファイルを更新。
@alexhillman のアプローチ: セッション終了を待たずに15分ごとにシステムが改善を提案。エージェントが最近のやり取りをレビューし、メモリ更新を提案。承認/却下のパターンから学習していく。
5. トークン最適化
モデル選択クイックリファレンス
| モデル | 入力コスト | 出力コスト | 用途 |
|---|---|---|---|
| Haiku | 安い | 安い | 反復的タスク、明確な指示、ワーカーエージェント |
| Sonnet | $3/M | $15/M | 90%のコーディングタスク |
| Opus | $5/M | $25/M | 複雑なアーキテクチャ、セキュリティ重要コード |
コスト差:
- Haiku vs Opus: 5倍の差
- Sonnet vs Opus: 1.67倍の差
→ Haiku + Opus の組み合わせが最もコスト効率が良い
モデル選択の指針:
- Sonnetをデフォルトに90%のコーディングタスク
- Opusにアップグレード: 最初の試行が失敗、5ファイル以上にまたがるタスク、アーキテクチャ決定、セキュリティクリティカルなコード
- Haikuにダウングレード: 反復的なタスク、明確な指示、マルチエージェントの「ワーカー」として使用
エージェント定義でモデル指定
---
name: quick-search
description: Fast file search
tools: Glob, Grep
model: haiku # 安くて速い
---
ツール固有の最適化
mgrep を使う: 従来の grep/ripgrep と比較して、平均で約50%のトークン削減が可能です。
バックグラウンドプロセス
Claudeに出力全体をストリーミングさせる必要がない場合、tmuxでバックグラウンド実行。必要な部分だけコピーするか、要約します。
コストの大部分は入力トークン（Opus 4.5 で $5/M トークン）なので、ここを削減するのが効果的です。
モジュラーなコードベースの利点
| ファイルサイズ | 問題 |
|---|---|
| 数千行 | 複数のツール呼び出しで読み込み、途中で情報を失う可能性、再読み込みでトークン追加消費 |
| 数百行 | 一度で読める、情報損失なし、トークン効率良好 |
推奨プロジェクト構造:
root/
├── src/
│ ├── apps/ # エントリーポイント
│ │ ├── api-gateway/
│ │ └── cron-jobs/
│ │
│ ├── modules/ # コアシステム（自己完結型）
│ │ ├── ordering/
│ │ │ ├── api/
│ │ │ ├── domain/
│ │ │ ├── infrastructure/
│ │ │ ├── use-cases/
│ │ │ └── tests/
│ │ ├── catalog/
│ │ └── identity/
│ │
│ └── shared/ # 全モジュール共通
│ ├── kernel/
│ ├── events/
│ └── utils/
リーンなコードベース = 安いトークン
コードベースがスリムであるほど、トークンコストは下がります。デッドコードを特定し、スキルを使って継続的にリファクタリングすることが重要です。定期的にコードベース全体を眺めて、目立つものや反復的に見えるものを手動でピックアップし、そのコンテキストをClaudeに与えてリファクタリングさせるのも効果的です。
6. 検証ループと評価
観測可能性の方法
- tmux プロセス: スキルがトリガーされたときに思考ストリームと出力をトレース
- PostToolUse フック: Claudeが何を実行し、正確な変更と出力を記録
ベンチマークワークフロー
[同じタスク]
│
┌─────┴─────┐
▼ ▼
┌───────────┐ ┌───────────┐
│ Worktree A │ │ Worktree B │
│ スキルあり │ │ スキルなし │
└─────┬─────┘ └─────┬─────┘
│ │
▼ ▼
[出力 A] [出力 B]
│ │
└──────┬───────┘
▼
[git diff]
│
▼
┌────────────────┐
│ ログ比較、 │
│ トークン使用量、 │
│ 出力品質 │
└────────────────┘
評価パターンの種類
チェックポイントベース評価
明確なマイルストーンがある線形ワークフローに適しています。
[タスク 1]
│
▼
┌─────────┐
│Checkpoint│◄── 基準を検証
│ #1 │
└────┬────┘
│ 合格?
┌──┴──┐
yes no ──► 修正
│
▼
[タスク 2]
...
継続評価
長時間セッション、探索的リファクタリングに適しています。
[作業中]
│
▼
┌─────────┐
│ タイマー/ │
│ 変更検出 │
└────┬────┘
│
▼
┌──────────┐
│テスト実行 │
│ + Lint │
└────┬─────┘
│
┌───┴───┐
pass fail
│ │
▼ ▼
[続行] [停止して修正]
グレーダーの種類（Anthropic より）
| タイプ | 特徴 | 利点 | 欠点 |
|---|---|---|---|
| コードベース | 文字列マッチ、バイナリテスト、静的解析 | 速い、安い、客観的 | 有効なバリエーションに脆弱 |
| モデルベース | ルーブリック採点、自然言語アサーション | 柔軟、ニュアンスを処理 | 非決定的、高コスト |
| 人間 | SMEレビュー、クラウドソース判断 | ゴールドスタンダード品質 | 高コスト、遅い |
重要なメトリクス
pass@k: k回の試行のうち少なくとも1回成功
- k=1: 70%
- k=3: 91%
- k=5: 97%
→ kが高いほど成功確率上昇
pass^k: k回すべて成功が必要
- k=1: 70%
- k=3: 34%
- k=5: 17%
→ kが高いほど難しい（一貫性テスト）
使い分け:
- pass@k: 動けばOK、検証フィードバックがあれば十分
- pass^k: 一貫性が重要、ほぼ決定的な出力品質が必要
7. 並列化
著者の推奨パターン
- メインチャット: コード変更
- フォーク: コードベースに関する質問、外部サービスのリサーチ、ドキュメント取得、GitHub検索など
任意のターミナル数に対する警告
Boris（Claude Code作成者）は「ローカル5インスタンス + 上流5インスタンス」を提案していますが、個人的には反対意見です：
「ターミナルとインスタンスの追加は、真の必要性と目的があるときだけ。スクリプトで処理できるならスクリプトを使え。ほとんどの場合、私は2〜3インスタンスで十分。」
Git Worktree を使った並列インスタンス
# 並列作業用の worktree を作成
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-refactor refactor-branch
# 各 worktree で Claude インスタンスを起動
cd ../project-feature-a && claude
利点:
- インスタンス間で git コンフリクトなし
- それぞれクリーンな作業ディレクトリ
- 出力を簡単に比較可能
- 同じタスクを異なるアプローチでベンチマーク可能
カスケードメソッド
複数の Claude Code インスタンスを実行するときの整理パターン：
- 新しいタスクは右側の新しいタブで開く
- 左から右へスイープ（古い→新しい）
- 一貫した方向フローを維持
- 必要に応じて特定のタスクをチェック
- 3〜4タスクに集中 — それ以上は生産性より精神的オーバーヘッドが増加
8. 初期設定（Groundwork）
2インスタンスキックオフパターン
空のリポジトリから始めるとき、2つの Claude インスタンスを開きます：
インスタンス1: スキャフォールディングエージェント
- スキャフォールドと基盤を構築
- プロジェクト構造を作成
- 設定をセットアップ（CLAUDE.md、ルール、エージェント）
- 規約を確立
- スケルトンを配置
インスタンス2: ディープリサーチエージェント
- すべてのサービス、Web検索などに接続
- 詳細な PRD を作成
- アーキテクチャの Mermaid 図を作成
- 実際のドキュメントからのクリップを含む参照を収集
llms.txt パターン
多くのドキュメントサイトで /llms.txt を追加すると、LLM最適化されたクリーンなバージョンが取得可能です。
例: https://www.helius.dev/docs/llms.txt
哲学: 再利用可能なパターンを構築する
@omarsar0 からの洞察：
「初期に再利用可能なワークフロー/パターンを構築するのに時間を費やした。構築は面倒だったが、モデルとエージェントハーネスが改善されるにつれて驚異的な複利効果があった。」
投資すべきもの:
- サブエージェント
- スキル
- コマンド
- 計画パターン
- MCPツール
- コンテキストエンジニアリングパターン
複利効果の理由:
「最も良い点は、これらすべてのワークフローが Codex などの他のエージェントに転用可能なこと。」
→ パターンへの投資 > 特定モデルのトリックへの投資
9. エージェント＆サブエージェントのベストプラクティス
サブエージェントのコンテキスト問題
サブエージェントはコンテキストを節約するために要約を返しますが、オーケストレーターが持つ意味的コンテキスト（なぜそのリクエストをしたか）が欠けています。
@PerceptualPeak のアナロジー：
「上司があなたを会議に送り、要約を求める。要約を報告すると、10回中9回はフォローアップの質問がある。あなたの要約には上司が持つ暗黙のコンテキストがないから、必要なものすべては含まれない。」
反復的取得パターン
┌─────────────────┐
│ オーケストレーター │
│ (コンテキストあり) │
└────────┬────────┘
│ クエリ + 目的を渡す
▼
┌─────────────────┐
│ サブエージェント │
│ (コンテキストなし) │
└────────┬────────┘
│ 要約を返す
▼
┌─────────────────┐ ┌─────────────┐
│ 評価：十分? │─no─►│ フォローアップ │
│ │ │ 質問 │
└────────┬────────┘ └──────┬──────┘
│ yes │
▼ │
[受け入れ] サブエージェントが
回答を取得して戻る
◄──────────────┘
(最大3サイクル)
順次フェーズパターン
| フェーズ | エージェント | 入力 | 出力 |
|---|---|---|---|
| 1. RESEARCH | Explore | 要件 | research-summary.md |
| 2. PLAN | planner | research-summary.md | plan.md |
| 3. IMPLEMENT | tdd-guide | plan.md | コード変更 |
| 4. REVIEW | code-reviewer | コード変更 | review-comments.md |
| 5. VERIFY | build-error-resolver | レビュー結果 | 完了またはループバック |
重要なルール:
- 各エージェントは1つの明確な入力を受け取り、1つの明確な出力を生成
- 出力は次のフェーズの入力になる
- フェーズをスキップしない — 各フェーズに価値がある
- エージェント間で
/clearを使ってコンテキストをフレッシュに保つ - 中間出力をファイルに保存（メモリだけでなく）
エージェント抽象化ティアリスト（@menhguin より）
Tier 1: 直接バフ（使いやすい）
| 抽象化 | 説明 |
|---|---|
| サブエージェント | コンテキスト腐敗防止とアドホック特化の直接バフ。マルチエージェントの半分の有用性だが、複雑さははるかに少ない |
| メタプロンプティング | 「20分のタスクをプロンプトするのに3分かける」安定性を改善し、仮定を健全性チェック |
| 最初にユーザーにもっと質問 | 一般的にバフ（プランモードで質問に答える必要はある） |
Tier 2: 高スキルフロア（うまく使うのが難しい）
| 抽象化 | 説明 |
|---|---|
| 長時間実行エージェント | 15分 vs 1.5時間 vs 4時間タスクの形とトレードオフを理解する必要。非常に長い試行錯誤 |
| 並列マルチエージェント | 非常に高い分散、高度に複雑または良く分割されたタスクでのみ有用 |
| ロールベースマルチエージェント | 「モデルはハードコードされたヒューリスティクスには進化が速すぎる」テストが難しい |
| コンピュータ使用エージェント | 非常に初期のパラダイム、扱いが必要 |
10. Tips & Tricks
MCPはCLI + スキルで置き換え可能
GitHub、Supabase、Vercel、Railway などの MCP は、基本的に既存の堅牢な CLI をラップしているだけです。MCP は便利なラッパーですが、コンテキストウィンドウを消費するコストがあります。
代替案: MCPが公開するツールをコマンド/スキルに変換し、CLIのように機能させる
- GitHub MCP →
/gh-prコマンド（gh pr createをラップ） - Supabase MCP → Supabase CLI を使うスキル
機能は同じ、利便性も似ている、でもコンテキストウィンドウが解放されます。
レイジーローディングについて
最近のClaude Codeアップデート（Borisとチームの功績）でMCPのレイジーローディングが導入され、コンテキストウィンドウの問題はほぼ解決しました。以前は最初からウィンドウを消費していたのが、必要なときだけロードされるようになりました。
しかし、トークン使用量とコストの問題は同じ方法では解決されていません。CLI + スキルアプローチは依然として有効なトークン最適化方法です。
特に重い MCP 操作（データベースクエリ、デプロイメントなど）は、インコンテキストではなく CLI 経由で実行するとトークン使用量を大幅に削減できます。
まとめ
今回紹介した10のテクニックを再掲します：
-
コンテキスト＆メモリ管理:
.tmpファイルでセッション間メモリを共有、戦略的タイミングで手動コンパクト -
動的システムプロンプト注入:
--system-promptオプションでタスク別コンテキストを注入 - メモリ永続化フック: SessionStart/PreCompact/Stopフックで自動的に状態を保存・復元
-
継続学習/メモリ: 学習した知識をスキルとして保存、
/learnコマンドで手動抽出 - トークン最適化: Haiku + Opusの組み合わせ、モジュラーなコードベース、mgrepの活用
- 検証ループと評価: Git Worktreeでベンチマーク、チェックポイント評価と継続評価の使い分け
- 並列化: 2〜3インスタンスに抑える、カスケードメソッドでタブ管理
- 初期設定: 2インスタンスキックオフ（スキャフォールディング + リサーチ）、再利用可能なパターンに投資
- エージェント運用: Tier 1パターンから始める、順次フェーズパターンで明確な入出力を定義
- Tips: MCPはCLI + スキルで代替可能、重い操作はCLI経由でトークン削減
Claude Codeを使いこなすほど、これらのテクニックの重要性が実感できるようになります。特にパターンへの投資は、モデルやツールが進化しても資産として残り続けます。
なお、元記事には前編「The Shorthand Guide to Everything Claude Code」があり、スキル、コマンド、フック、サブエージェント、MCPの基本設定が解説されています。本記事の内容を実践する前に、そちらで基盤を整えておくことをおすすめします。
ぜひ試してみてください。
𝕏フォローしてくれると嬉しいです
𝕏でも情報発信しているので、フォローしていただけると励みになります！
参考文献
Discussion