07 ベストプラクティス(公式 Best practices の要約)

更新日: 2026-09-29

大前提: コンテキストはすぐ埋まり、埋まるほど性能が落ちる。ほぼ全ての工夫はここから来ている。

1. Claude に「検証手段」を渡す(最重要)

Claude は「終わったように見えたら」止まる。合否が分かるチェック(テスト、ビルド、lint、スクリーンショット比較)を渡せば、合格するまで自分で直し続ける。渡さないと、あなたが検証係になる。

検証の強さの段階:

1. 1回のプロンプトで「チェックを実行して通るまで繰り返して」
2. セッション全体で /goal 条件(別のモデルが毎ターン判定)
3. 決定的に Stop Hook(スクリプトが通るまでターンを終わらせない)
4. 第三者の目で 検証用サブエージェントやワークフロー(作った本人に採点させない)

→ 成功を「宣言」させず、証拠(テスト出力、実行したコマンドと結果、スクショ)を見せてもらう。

2. 調査 → 計画 → 実装 → コミット

いきなりコードを書かせると「違う問題を解く」ことがある。

1. 調査(プランモード): 「src/auth を読んでセッションとログインの仕組みを理解して」
2. 計画: 「Google OAuth を追加したい。どのファイルを変える?フローは?計画を作って」(Ctrl+G で計画を直接編集)
3. 実装(プランモード解除): 「計画通り実装して。コールバックのテストを書いて実行し、失敗を直して」
4. コミット: 「分かりやすいメッセージでコミットしてPRを作って」

※ 1文で差分を説明できる小さな修正(typo、ログ追加、変数名変更)は計画不要。

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

リッチな渡し方: @ファイル、画像を貼る、URL を渡す、cat error.log | claude、「自分で調べて」と任せる。
※ 探索段階ではあえて曖昧な質問(「このファイルで改善するなら?」)も有効。

4. 環境を整える

• CLAUDE.md を書く(/init → 育てる、短く保つ) → 04_CLAUDE.mdとメモリ
• 権限を設定(/permissions で安全なコマンドを許可、/sandbox) → 05_権限とセキュリティ
• CLI ツールを使わせる: gh, aws, gcloud など。外部サービスと最もコンテキスト効率よく連携できる。「foo --help で使い方を調べてから使って」も有効
• MCP を接続: claude mcp add --transport http notion https://mcp.notion.com/mcp
• Hooks: 例外なく毎回やらせたいこと(「編集後に eslint」「migrations フォルダへの書き込み禁止」)。Claude に書かせられる
• Skills: .claude/skills/ に手順や知識を置く
• サブエージェント: .claude/agents/ に専門家を定義
• プラグイン: /plugin で探す。型のある言語ならコードインテリジェンスプラグイン

5. 上手にコミュニケーションする

• 新しいコードベースでは先輩エンジニアに聞くように質問する(「ログはどう動く?」「新しいAPIエンドポイントの作り方は?」)
• 大きな機能は Claude にインタビューさせる:

  [作りたいもの] を作りたい。AskUserQuestion ツールで詳しくインタビューして。
  技術的な実装、UI/UX、エッジケース、懸念、トレードオフについて。自明な質問はせず、
  私が考えていない難しい部分を掘って。全部カバーしたら SPEC.md に仕様を書いて。

  → 仕様ができたら新しいセッションで実装(きれいなコンテキストで)。良い仕様 = 関係ファイルとインターフェースを明記、範囲外を明記、最後にE2E検証手順

6. セッションを管理する

• 早めに・頻繁に軌道修正: Esc で停止、Esc Esc//rewind で巻き戻し、「今のを元に戻して」
• 同じ問題で2回以上訂正したら /clear して、学んだことを入れたより良いプロンプトでやり直す(失敗の履歴で汚れた長いセッションより、きれいな短いセッションが勝つ)
• 無関係な作業の間は /clear
• 調査はサブエージェントに: 「サブエージェントを使って認証のトークン更新の仕組みと、再利用できる OAuth ユーティリティがあるか調べて」
• チェックポイントがあるので大胆な案も試せる
• /rename してセッションをブランチのように扱う

7. 自動化とスケール

• 非対話モード: claude -p "..." --output-format json を CI・スクリプトに → 15_自動化(headless・goal・loop・routines・CI)
• 複数セッション並列: worktree、デスクトップアプリ、クラウド、エージェントビュー → 14_並列作業(Worktree・Agent View・Workflows)
• Writer / Reviewer パターン: セッションAが実装、セッションBが(作った本人のバイアスなしに)レビュー。テストを書くClaudeと実装するClaudeを分けるのも有効
• ファンアウト: /batch 指示、または for file in ...; do claude -p "..." --allowedTools "Edit,Bash(git commit *)"; done(最初の2〜3件で調整してから全件)
• Auto モードで中断なく実行
• 敵対的レビュー: 完了扱いにする前に、サブエージェントに差分をレビューさせる(/code-review や「PLAN.md と比較して抜けを報告して。スタイルの好みでなく正しさに関わる抜けだけ」)。※レビュアーは頼まれると何かしら指摘するので、全部追うと過剰設計になる

よくある失敗パターン

直感を育てる

上記は出発点。深い問題に取り組んでいる時は履歴を残すべきだし、探索的な作業では計画を飛ばしていい。うまくいった時・いかなかった時に「何が違ったか(プロンプト、文脈、モード)」を観察する。

関連

• 02_仕組み(エージェントループ・ツール・コンテキスト)
• 公式: https://code.claude.com/docs/en/best-practices , https://code.claude.com/docs/en/common-workflows