Claude Code ベストプラクティスまとめ

出典：Best practices for Claude Code（Anthropic公式）

目次

大前提：コンテキストウィンドウが一番大事なリソース

ベストプラクティスのほとんどは「コンテキストはすぐ埋まり、埋まるほど性能が落ちる」という制約から来ている。会話・読み込んだファイル・コマンド出力はすべてコンテキストを消費する。満杯に近づくと前の指示を「忘れる」、ミスが増える、といったことが起こる。

1. Claudeが自分で検証できるようにする（最重要）

  • テスト、ビルド、linter、スクリーンショット比較など、合否が返ってくるチェックを用意する。チェックがないと、間違いに気づく役はすべて自分になる。
  • 例：「validateEmail関数を書いて。テストケースは〇〇。実装後にテストを実行して」
  • 症状を抑えるのではなく根本原因を直すよう指示する（「エラーを握りつぶさないで」）。
  • 強制の度合いは段階的に上げられる：
    1. プロンプト内で「チェックを実行して通るまで繰り返して」と指示
    2. /goal で条件を設定（毎ターン後に別の評価器が再チェック）
    3. Stopフックで機械的にゲート（通るまでターンを終わらせない）
    4. 検証用サブエージェントでセカンドオピニオン
  • 「できました」と言わせるのではなく、テスト出力・実行コマンド・スクショなどの証拠を見せてもらう。

2. 探索 → 計画 → 実装 → コミット

  1. 探索：Shift+Tab で plan mode に切り替える（または claude --permission-mode plan で起動）。Claudeはファイルを変更せずに読み込みと回答だけを行う。
  2. 計画：詳細な実装計画を作らせる。Ctrl+G でエディタを開いて計画を直接編集できる。
  3. 実装：plan mode を抜けて実装させ、計画に照らして検証させる。
  4. コミット：説明的なメッセージでコミットさせ、PRを作らせる。

小さな修正（typo、ログ1行追加、変数名変更など）には不要。差分を1文で説明できるなら計画は飛ばしてよい。

3. プロンプトは具体的に

戦略BeforeAfter
範囲を絞る「foo.pyのテストを追加して」「ログアウト状態のエッジケースをカバーするfoo.pyのテストを書いて。モックは使わないで」
情報源を示す「なぜこのAPIは変なの？」「git履歴を見てAPIの経緯を要約して」
既存パターンを参照「カレンダーウィジェットを追加して」「HotDogWidget.phpを参考に同じ流儀で実装して」
症状を伝える「ログインバグを直して」「セッションタイムアウト後にログインが失敗する。src/auth/のトークン更新を確認し、再現する失敗テストを書いてから修正して」

リッチな入力の渡し方：

  • @ でファイルを参照する
  • 画像を貼り付ける・ドラッグ&ドロップする
  • ドキュメントのURLを渡す
  • cat error.log | claude -p "explain this error" でパイプ入力する
  • Claude自身にBash/MCPで情報を取りに行かせる

大きな機能では：AskUserQuestionで自分にインタビューさせて SPEC.md を書かせ、新しいセッションで実装する。良い仕様書は、関係するファイルとインターフェースを明記し、対象外を書き、最後にE2Eの検証手順を含む。

4. 環境を整える

CLAUDE.md

  • /init で雛形を作り、育てていく。/context で読み込まれているか確認できる。
  • 短く保つ。 各行について「消したらClaudeがミスするか？」と問い、ミスしないなら削る。長すぎると肝心のルールが埋もれて無視される。
✅ 入れるもの❌ 入れないもの
推測できないBashコマンドコードを読めば分かること
デフォルトと違うコードスタイル一般的な言語の慣習
テスト方法・好みのテストランナー詳細なAPIドキュメント（リンクにする）
ブランチ名・PRの規約頻繁に変わる情報
プロジェクト固有の設計判断長い解説やチュートリアル
開発環境のクセ（必要な環境変数など）ファイルごとの説明
ハマりどころ・直感に反する挙動「きれいなコードを書く」のような自明なこと
  • どうしても守られない1行だけ「IMPORTANT」などで強調する（多用すると効果がなくなる）。
  • gitにコミットしてチームで育てる。@path/to/file で他のファイルをインポートできる。
  • 一時的にしか使わない知識は Skills に分けると、必要なときだけ読み込まれる。

権限

  • /permissions で信頼できるツール（npm run lint、git commit など）を事前許可する。
  • /sandbox でOSレベルの隔離をかけ、範囲内で自由に動かす。
  • 新しいバージョンでは auto mode（分類モデルが危険な操作だけブロックする）がデフォルト。

その他の拡張

  • CLIツール：gh、aws、gcloud、sentry-cli などはコンテキスト効率が最も良い連携手段。未知のツールも --help を読ませれば使いこなせる。
  • MCPサーバー：claude mcp add で Notion、Figma、DB などにつなぐ。
  • Hooks：「毎回例外なく」実行したい処理用。CLAUDE.mdの指示は守られないことがあるが、フックは確実に実行される（例：編集ごとにeslint、migrationsフォルダへの書き込みをブロック）。
  • Skills：.claude/skills/<name>/SKILL.md。関連するときに自動適用されるほか、/skill-name で呼び出せる。副作用のあるワークフローには disable-model-invocation: true を付けて手動起動にする。
  • サブエージェント：.claude/agents/。専用のコンテキストとツールで隔離されたタスクを処理する。
  • プラグイン：/plugin でマーケットプレイスを閲覧する。型付き言語なら code intelligence プラグインがおすすめ。

5. セッション管理

  • 外れたらすぐ修正する
    • Esc：中断（コンテキストは保持される）
    • Esc Esc / /rewind：チェックポイントに戻す（会話・コード・両方を選べる）
    • 「undo that」：変更を戻させる
    • /clear：コンテキストをリセットする
  • 同じ問題を2回以上修正しても直らないときは、/clear してから学んだことを盛り込んだ良いプロンプトで始め直す。
  • コンテキストを積極的に管理する
    • 関係ないタスクの間には /clear
    • /compact <指示> で圧縮の方向を指定する（例：/compact Focus on the API changes）
    • CLAUDE.mdに「圧縮時は変更ファイル一覧とテストコマンドを必ず残す」などと書ける
    • 脇道の質問は /btw で聞く（答えが履歴に残らない）
  • 調査はサブエージェントに任せる：「use subagents to investigate X」と頼むと、別コンテキストで調べて要約だけ返してくる。
  • チェックポイント：大胆な試行をして、ダメなら戻せばいい。
    • ⚠️ 戻せるのはClaudeの編集ツールによる変更だけで、Bash経由の変更は追跡されない。gitの代わりにはならない。
  • 再開：/rename でセッションに名前を付け、claude --continue / claude --resume で再開する。

6. 自動化とスケール

  • 非対話モード：claude -p "..." で CI、pre-commit、スクリプトから実行できる。
    • --output-format json / --output-format stream-json --verbose
  • 並列セッション：worktree、デスクトップアプリ、クラウド実行、claude agents（Agent view）、Agent teams（実験的機能）。
  • Writer/Reviewerパターン：書いたセッションとは別の新しいコンテキストでレビューさせると、自分の書いたコードへの偏りが出ない。テストを書く役と実装する役に分けるのも有効。
  • ファンアウト：

    • /batch <指示> で5〜30個のサブエージェントに分割する（それぞれ別のworktreeで作業）

    • または claude -p をループで回す：

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

    • 最初は2〜3ファイルで試し、プロンプトを直してから全体に回す。

  • auto mode：claude --permission-mode auto -p "fix all lint errors"
  • 敵対的レビュー：完了扱いにする前に、サブエージェントで差分をレビューさせる（/code-review）。
    • ⚠️ 「穴を探して」と頼むと何かしら必ず指摘してくる。正しさや要件に関わるものだけに絞らせ、それ以外は任意扱いにしないと過剰設計になる。

よくある失敗パターン

パターン対策
キッチンシンク：1つのセッションに無関係なタスクを詰め込むタスクの間に /clear
修正の繰り返し：何度直しても間違う2回失敗したら /clear してプロンプトを改善
CLAUDE.mdが長すぎる容赦なく削る。必須のものはフックに移す
信頼してから検証するギャップ：もっともらしいがエッジケースで壊れる必ず検証手段を用意する。検証できないものは出さない
終わらない探索：範囲を決めない「調査」でコンテキストが溢れる範囲を絞るか、サブエージェントに任せる

最後に

これらはあくまで出発点。うまくいったときに何をしていたか、うまくいかなかったのはなぜか（コンテキストが雑多すぎた？プロンプトが曖昧？タスクが大きすぎた？）を観察して、自分なりの勘を育てていくことが大事。

0件のページ

    バックリンク