ai-docs

Best practices for Claude Code

Properties1
tagsclaude-code, workflow, context, verification, subagents

15 min read

一行要約

Claude Code のベストプラクティスはほぼすべて**「context window はすぐ埋まり、埋まるほど性能が落ちる」という単一の制約**から導かれる。したがって中心的な技能は、検証手段を与えること・文脈を意図的に捨てること・調査を別コンテキストに追い出すことである。

要点

全体を貫く前提

Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills. ほとんどのベストプラクティスは、ひとつの制約に基づいている。Claude の context window はすぐ埋まり、埋まるにつれて性能が落ちる、という制約である。

context window には会話全体（全メッセージ、読んだ全ファイル、全コマンド出力）が入る。デバッグセッション1回やコードベース探索1回で数万トークンを消費しうる。埋まってくると Claude は以前の指示を「忘れ」始め、誤りが増える。context window は最も重要な管理対象リソース。

1. 検証手段を与える (Give Claude a way to verify its work)

  • Claude は「終わったように見えたら」止まる。実行できるチェックがないと、「見た目が完了」が唯一のシグナルになり、人間が検証ループそのものになる。
  • pass/fail を返すものを渡せば、ループは自律的に閉じる: テストスイート、build の exit code、linter、fixture との差分スクリプト、ブラウザのスクリーンショット比較。
  • 停止をどれだけ強く縛るかで4段階:
    1. 1つのプロンプト内: 「実装したらテストを走らせて直せ」と同一メッセージで指示
    2. セッション全体: /goal の条件として設定。別の evaluator が毎ターン再チェックし、成立するまで作業が続く
    3. 決定的なゲート: Stop hook がスクリプトとしてチェックを実行し、通るまでターン終了をブロック（8回連続ブロックで Claude Code 側が上書きして終了）
    4. セカンドオピニオン: 検証用 subagent や dynamic workflow に、作業した本人ではないモデルが採点させる
  • 主張ではなく証拠を出させる: テスト出力、実行したコマンドとその戻り値、結果のスクリーンショット。証拠のレビューは自分で再実行するより速く、見ていなかったセッションにも効く。

2. Explore → Plan → Code → Commit

  • いきなりコードを書かせると「間違った問題」を解いたコードが出てくる。plan mode で探索と実行を分離する。
  • 手順: Explore（Shift+Tab で plan mode、または claude --permission-mode plan）→ Plan（Ctrl+G でプランをエディタで直接編集できる）→ Implement → Commit
  • ただし plan mode にはオーバーヘッドがある。「diff を1文で説明できるならプランは飛ばす」。プランが効くのは、アプローチが不確かなとき、複数ファイルにまたがるとき、対象コードに不慣れなとき。

3. プロンプトに具体的な文脈を入れる

戦略BeforeAfter
タスクをスコープする”add tests for foo.py""write a test for foo.py covering the edge case where the user is logged out. avoid mocks.”
情報源を指す”why does ExecutionFactory have such a weird api?""look through ExecutionFactory’s git history and summarize how its api came to be”
既存パターンを参照させる”add a calendar widget""look at how existing widgets are implemented… HotDogWidget.php is a good example. follow the pattern…”
症状を述べる”fix the login bug""users report that login fails after session timeout. check src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it”
  • ただし曖昧なプロンプトが有効な場面もある。探索段階で軌道修正のコストを払えるなら、"what would you improve in this file?" は自分では思いつかなかった論点を掘り出す。
  • リッチな入力の渡し方: @ でファイル参照 / 画像を直接ペースト / URL を渡す（/permissions でドメインを allowlist）/ cat error.log | claude でパイプ / 「必要なものは自分で取ってこい」と指示する

4. CLAUDE.md の書き方

  • /init で雛形を生成し、育てる。/context で読み込まれたか確認できる。
  • 毎セッション読み込まれるので、広く適用されるものだけを入れる。ときどきしか関係しない知識は skills に置く（オンデマンドで読まれる）。

Keep it concise. For each line, ask: “Would removing this cause Claude to make mistakes?” If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions! 簡潔に保て。各行について問え。「この行を消したら Claude はミスをするようになるか？」 ならないなら削れ。肥大した CLAUDE.md は、Claude に実際の指示を無視させる原因になる。

✅ 入れる❌ 入れない
Claude が推測できない Bash コマンドコードを読めば分かること
デフォルトと異なるコードスタイル規則Claude が既に知っている標準的な言語慣習
テスト手順と使うテストランナー詳細な API ドキュメント（リンクにする）
リポジトリの作法（ブランチ命名、PR 規約）頻繁に変わる情報
プロジェクト固有のアーキテクチャ決定長い説明やチュートリアル
開発環境の癖（必須の環境変数）コードベースのファイル別説明
非自明な挙動・よくある落とし穴「きれいなコードを書く」など自明なこと

診断法。CLAUDE.md に書いてあることを聞き返してくる場合は、表現が曖昧なほう。

If Claude keeps doing something you don’t want despite having a rule against it, the file is probably too long and the rule is getting lost. それを禁じるルールがあるのに Claude が同じことをし続けるなら、おそらくファイルが長すぎて、そのルールが埋もれている。

  • 「IMPORTANT」「YOU MUST」で強調すると遵守率が上がる。git に入れてチームで育てる。
  • 配置場所: ~/.claude/CLAUDE.md（全セッション）/ ./CLAUDE.md（git 共有）/ ./CLAUDE.local.md（個人用、gitignore）/ 親ディレクトリ（monorepo）/ 子ディレクトリ（そのディレクトリのファイルを読むときオンデマンド）
  • @path/to/import 構文で他ファイルを取り込める。

5. 環境の設定

  • permissions: 承認の連打は「10回目にはもうレビューしていない」。減らす手段は3つ — auto mode（分類器モデルがリスクのあるものだけブロック）/ allowlist（npm run lint など）/ sandboxing（OSレベルの隔離）
  • CLI ツール: 外部サービスと話すのに最もコンテキスト効率が良い。gh を入れる。知らない CLI も Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C. で学習させられる。
  • hooks: CLAUDE.md の指示は advisory だが、hooks は決定的。「例外なく毎回起きなければならないこと」に使う。
  • skills: .claude/skills/<name>/SKILL.md。disable-model-invocation: true で副作用のあるワークフローを手動起動限定にできる。
  • subagents: .claude/agents/*.md。独自のコンテキストと許可ツールを持つ。

6. コミュニケーション

  • コードベースへの質問: 新しいコードベースへのオンボーディングに使う。「シニアエンジニアに聞くような質問」をそのまま聞く。特別なプロンプトは不要。
  • Claude に自分をインタビューさせる: 大きめの機能では、最小限のプロンプトから AskUserQuestion ツールでインタビューさせ、SPEC.md を書かせる。その後 fresh session で実装する（クリーンなコンテキスト + 書かれた仕様）。良い spec は自己完結していて、関係するファイルとインターフェースを名指しし、スコープ外を明示し、end-to-end の検証手順で終わる。

7. セッション管理

  • 早く頻繁に軌道修正する: Esc（中断、コンテキストは保持）/ Esc+Esc or /rewind（会話とコードの状態を復元、または選択メッセージから要約）/ "Undo that" / /clear
  • 同じ問題で2回以上修正したら /clear。コンテキストが失敗したアプローチで汚染されている。「学んだことを盛り込んだより良いプロンプトでのクリーンなセッション」は「修正が積み上がった長いセッション」にほぼ常に勝つ。
  • コンテキスト管理: /clear を無関係なタスク間で頻繁に / /compact <instructions> で方向を指定 / Esc+Esc から “Summarize from here” / “Summarize up to here” / CLAUDE.md に compaction 時の保持指示を書ける / 文脈に残したくない質問は /btw
  • 調査には subagent: 「context が根本的な制約であるがゆえに、subagent は最も強力なツールのひとつ」。別のコンテキストで探索し、要約だけ返す。
  • checkpoint: プロンプトごとに checkpoint が作られる。慎重に計画する代わりに、危ないことを試させて駄目なら rewind するという進め方ができる。ただし checkpoint が追跡するのは Claude のファイル編集ツール経由の変更のみで、Bash 経由や外部プロセスの変更は含まれない。git の代替ではない。
  • セッションの再開: claude --continue / claude --resume / /rename で名前を付けてブランチのように扱う。

8. 自動化とスケール

  • 非対話モード: claude -p "prompt"。--output-format json / stream-json --verbose。CI、pre-commit hook に組み込む。
  • 並列セッション: worktrees / Desktop app / web / agent teams。fresh context はコードレビューを改善する（自分が書いたコードに引きずられない）。Writer/Reviewer パターン、テスト先行パターン。
  • ファイル横断の fan out: タスクリストをファイルに書かせ、for file in $(cat files.txt); do claude -p "..." --allowedTools "..."; done。まず2〜3ファイルで試してプロンプトを直してから全体に流す。
  • adversarial review: 完了とみなす前に、fresh subagent に diff だけを見せてレビューさせる。ただし**「ギャップを探せ」と言われたレビュアーは、健全な成果物に対しても何かを報告する**。全ての指摘を追うと over-engineering になる。「正しさと明示要件に影響するギャップだけを挙げよ」と縛る。

9. よくある失敗パターン

パターン内容対処
The kitchen sink session1つのタスクの途中で無関係なことを聞き、また戻る無関係なタスク間で /clear
Correcting over and over修正しても直らず修正を重ねる2回失敗したら /clear して初期プロンプトを書き直す
The over-specified CLAUDE.md長すぎて半分無視される容赦なく刈り込む。指示なしで正しくできるなら消すか hook にする
The trust-then-verify gapもっともらしいがエッジケースを扱えていない実装必ず検証手段を渡す。検証できないなら出荷しない
The infinite explorationスコープなしの「調査して」で数百ファイル読ませる調査を狭くスコープするか subagent に出す

The over-specified CLAUDE.md. If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise. 過剰に書き込まれた CLAUDE.md。長すぎると、重要なルールがノイズに埋もれるため、Claude はその半分を無視する。

10. 直感を育てる

これらは出発点であって不変の規則ではない。文脈を溜めるべきときもあり、プランを飛ばすべきときもあり、曖昧なプロンプトが正解のときもある。うまくいったときに何をしたか、詰まったときに何が原因か（文脈のノイズ？プロンプトの曖昧さ？タスクが大きすぎた？）を観察する。

そのまま使える具体例

インタビューさせて spec を書かせるプロンプト:

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
 
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
 
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

調査を subagent に出す:

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

プランに対する adversarial review:

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

fan out:

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク