Anthropic 公式ドキュメントにある Best Practices のページを読む
最重要ルール：コンテキストウィンドウの管理
なぜコンテキストが重要か
ほとんどのベストプラクティスは一つの制約に基づいている：
Claude のコンテキストウィンドウはすぐに埋まり、埋まると性能が低下する
コンテキストウィンドウには以下が含まれる：
- 会話全体
- Claude が読んだすべてのファイル
- すべてのコマンド出力
一回のデバッグセッションやコードベース探索で、数万トークンを消費することもある
コンテキストが埋まると起きること
| 状態 | 影響 |
|---|---|
| 余裕あり | 正確な応答、指示の遵守 |
| 埋まりつつある | 初期の指示を「忘れ」始める |
| 満杯に近い | ミスの増加、矛盾した出力 |
対策
- カスタム statusLine でコンテキスト使用量を常時監視
/clearコマンドで定期的にクリア- サブエージェントで調査を分離
ここで、カスタム statusLine とは ~/.claude/statusline.sh を作って ~/.claude/settings.json に
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}
と記載しておくと、以下のような表示をさせておけるというもの
https://code.claude.com/docs/en/statusline
Claude Code statusline完全ガイド｜設定方法とカスタマイズ例 #ClaudeCode - Qiita
原則1: 検証手段を与える
最もレバレッジの高い行動
テスト、スクリーンショット、期待される出力を提供し、Claude が自分自身をチェックできるようにする
検証手段がないと、Claude は「正しそうに見える」が実際には動かないものを生成する可能性がある
すべてのフィードバックループが人間依存になり、すべてのミスに人間の注意が必要になる
Before / After 比較
| 戦略 | Before | After |
|---|---|---|
| 検証基準の提供 | 「メールアドレスを検証する関数を実装して」 | 「validateEmail関数を書いて。テストケース: user@example.com → true, invalid → false, user@.com → false。実装後にテストを実行して」 |
| UI変更の視覚的検証 | 「ダッシュボードを見やすくして」 | 「[スクリーンショット貼付] このデザインを実装して。結果のスクリーンショットを撮って元と比較。差異をリストアップして修正」 |
| 根本原因への対処 | 「ビルドが失敗している」 | 「ビルドがこのエラーで失敗: [エラー貼付]。修正してビルド成功を確認。エラー抑制ではなく根本原因に対処」 |
検証方法の例
検証手段の種類 ├── テストスイート ├── リンター ├── スクリーンショット比較 ├── 出力をチェックするBashコマンド └── Chrome拡張でのUI検証
原則2: 探索 → 計画 → 実装
なぜ段階を分けるか
Claude にいきなりコーディングさせると、間違った問題を解決するコードが生成されることがある。Plan Mode を使って探索と実行を分離する
推奨ワークフロー
Phase 1: 探索（Plan Mode） ↓ Phase 2: 計画（Plan Mode） ↓ Phase 3: 実装（Normal Mode） ↓ Phase 4: コミット
各フェーズの詳細
Phase 1: 探索
Plan Mode に入り、Claude にファイルを読ませ、変更なしで質問に答えさせる
/src/auth を読んで、セッションとログインの処理方法を理解して。 シークレット用の環境変数の管理方法も確認して。
Phase 2: 計画
詳細な実装計画を作成させる
Google OAuthを追加したい。どのファイルを変更する必要がある？ セッションフローは？計画を作成して。
Ctrl+G でテキストエディタで計画を開き、直接編集可能
Phase 3: 実装
Normal Mode に戻り、計画に沿って実装させる
計画に基づいてOAuthフローを実装して。 コールバックハンドラのテストを書いて、テストスイートを実行し、 失敗があれば修正して。
Phase 4: コミット
説明的なメッセージでコミットしてPRを開いて
計画をスキップすべきとき
| スキップOK | 計画すべき |
|---|---|
| タイポ修正 | アプローチが不確実 |
| ログ行追加 | 複数ファイルの変更 |
| 変数名変更 | 不慣れなコードの修正 |
| 1文でdiffを説明可能 | 複雑なリファクタリング |
原則3: 具体的なコンテキストを提供
曖昧さを減らす
Claude は意図を推測できるが、心を読むことはできない
具体的なファイル参照、制約の言及、パターンの指示が重要
Before / After 比較
| 戦略 | Before | After |
|---|---|---|
| タスクのスコープ | 「foo.pyのテストを追加して」 | 「foo.pyのテストを書いて。ユーザーがログアウトしている場合のエッジケースをカバー。モックは避けて」 |
| ソースの指定 | 「ExecutionFactoryのAPIがなぜ変なの？」 | 「ExecutionFactoryのgit履歴を調べて、APIがどのようにして今の形になったかまとめて」 |
| 既存パターンの参照 | 「カレンダーウィジェットを追加して」 | 「ホームページの既存ウィジェットの実装パターンを見て。HotDogWidget.phpが良い例。同じパターンでカレンダーウィジェットを実装して」 |
| 症状の記述 | 「ログインバグを直して」 | 「ユーザーがセッションタイムアウト後にログイン失敗と報告。src/auth/の認証フローをチェック、特にトークンリフレッシュ。問題を再現する失敗テストを書いてから修正」 |
リッチコンテンツの活用
| 方法 | 説明 |
|---|---|
@ でファイル参照 |
コードの場所を説明する代わりに |
| 画像を直接貼付 | コピペまたはドラッグ&ドロップ |
| URLを提供 | ドキュメントやAPI参照用 |
| データをパイプ | cat error.log | claude |
原則4: コンテキストの効率的な管理
サブエージェントの活用
コンテキストが最も重要な資源である以上、サブエージェントは最も強力なツールの一つ
サブエージェントを使って、認証システムがトークンリフレッシュを どのように処理しているか調査して。再利用できる既存のOAuth ユーティリティがあるかも確認して。
サブエージェントの利点：
| 側面 | メインセッション | サブエージェント |
|---|---|---|
| コンテキスト | 共有（埋まる） | 分離（報告のみ） |
| 用途 | 実装 | 調査・レビュー |
| 出力 | 詳細なコード | サマリー |
チェックポイントと巻き戻し
Claude は変更前に自動的にチェックポイントを作成。Escape を2回押すか /rewind で巻き戻しメニューを開く
復元オプション ├── 会話のみ復元 ├── コードのみ復元 ├── 両方を復元 └── 選択したメッセージから要約
リスキーなことを試して、うまくいかなければ巻き戻して別のアプローチを試すことが可能
セッションの再開
claude --continue # 最新の会話を再開 claude --resume # 最近の会話から選択
/rename でセッションに説明的な名前を付けて後で見つけやすくする（例: "oauth-migration", "debugging-memory-leak"）
自動化とスケーリング
ヘッドレスモード
claude -p "プロンプト" で対話なしに実行。CI パイプライン、pre-commit フック、自動化ワークフローに統合可能
# 単発クエリ claude -p "このプロジェクトが何をするか説明して" # スクリプト用の構造化出力 claude -p "すべてのAPIエンドポイントをリスト" --output-format json # リアルタイム処理用ストリーミング claude -p "このログファイルを分析" --output-format stream-json
並列セッション
| 方法 | 説明 |
|---|---|
| Claude Desktop | 複数のローカルセッションを視覚的に管理 |
| Claude Code on the web | Anthropic のセキュアクラウドで分離VMで実行 |
| Agent teams | 共有タスク、メッセージング、チームリードによる自動調整 |
Writer/Reviewer パターン
| Session A (Writer) | Session B (Reviewer) |
|---|---|
APIエンドポイント用のレートリミッターを実装して |
|
@src/middleware/rateLimiter.ts のレートリミッター実装をレビュー。エッジケース、レースコンディション、既存ミドルウェアパターンとの一貫性を確認 |
|
レビューフィードバック: [Session Bの出力]。これらの問題に対処して |
ファンアウト（大規模処理）
# 1. タスクリストを生成
# 例: 「移行が必要な2,000個のPythonファイルをリスト」
# 2. ループスクリプト
for file in $(cat files.txt); do
claude -p "$file をReactからVueに移行。OKかFAILを返して" \
--allowedTools "Edit,Bash(git commit *)"
done
# 3. 最初の2-3ファイルでテスト、その後本番実行
よくある失敗パターン
1. キッチンシンクセッション
症状: 1つのタスクで始め、無関係なことを聞き、また最初のタスクに戻る。コンテキストが無関係な情報で埋まる。
対策: 無関係なタスク間で /clear
2. 繰り返しの修正
症状: Claude が間違える → 修正指示 → まだ間違い → 再度修正。コンテキストが失敗したアプローチで汚染される。
対策: 2回失敗したら /clear して、学んだことを組み込んだより良い初期プロンプトを書く
3. 過剰指定の CLAUDE.md
症状: CLAUDE.md が長すぎて、重要なルールがノイズに埋もれて Claude が半分を無視する。
対策: 容赦なく剪定。Claude が指示なしで正しく行うことは削除するかフックに変換
4. 信頼してから検証のギャップ
症状: Claude がもっともらしい実装を生成するが、エッジケースを処理していない。
対策: 常に検証手段（テスト、スクリプト、スクリーンショット）を提供。検証できないものは出荷しない
5. 無限の探索
症状: スコープを限定せずに「調査して」と依頼。Claude が数百のファイルを読み、コンテキストが埋まる。
対策: 調査を狭くスコープするか、サブエージェントを使って探索がメインコンテキストを消費しないようにする
直感を育てる
パターンは出発点
このガイドのパターンは固定されたルールではない
一般的にうまく機能する出発点だが、すべての状況に最適とは限らない
コンテキストを蓄積させるべき時: - 1つの複雑な問題に深く取り組んでいて、履歴が価値を持つ場合
計画をスキップすべき時: - タスクが探索的で、Claude にまかせて様子を見たい場合
曖昧なプロンプトが適切な時: - 制約をかける前に Claude がどう解釈するか見たい場合
学びを蓄積する
- Claude が優れた出力を生成したとき、何をしたかに注目（プロンプト構造、提供したコンテキスト、モード）
- Claude が苦労したとき、なぜかを問う（コンテキストがノイジー？プロンプトが曖昧？タスクが大きすぎ？）
時間とともに、ガイドでは捉えられない直感が育つ。
まとめ
Claude Code ベストプラクティスの要点
| 原則 | キーポイント |
|---|---|
| コンテキスト管理 | 最も重要な資源。使用量を監視し、定期的にクリア |
| 検証手段を提供 | 最もレバレッジの高い行動。テスト、スクリーンショット、期待出力 |
| 探索→計画→実装 | 間違った問題を解決しないために段階を分ける |
| 具体的なコンテキスト | 曖昧さを減らし、修正回数を減らす |
| サブエージェント活用 | 調査を分離してメインコンテキストをクリーンに |
| 自動化とスケーリング | ヘッドレスモード、並列セッション、ファンアウト |
