cc-best-practices

---

Claude Code のベストプラクティス

https://code.claude.com/docs/en/best-practices にある Anthropic 公式ドキュメントに基づいています。

最も重要な制約は、Claude のコンテキストウィンドウはすぐに埋まり、埋まるにつれてパフォーマンスが低下することです。 すべてのベストプラクティスは、ここから導かれます。

---

手順

ステップ 1：Claude が作業を検証できる方法を必ず用意する

Claude が自分で成功を確認できるよう、実行可能なチェック（テストスイート、ビルドの終了コード、リンター、差分スクリプト）を用意します。単なる断言ではなく、証拠（テスト出力、コマンドの結果）を求めます。

ステップ 2：重要なタスクには Explore → Plan → Implement のワークフローを使う

/plan モードに入り、まず Claude にコードベースを読み込ませてから、コードを書く前に計画を作成します。実装に進むときはプランモードを終了します。小規模で明白な変更の場合に限り、この手順を省略します。

ステップ 3：具体的で範囲を明確にしたプロンプトを書く

ファイル名（@filename）を指定し、推測ではなく症状を説明して、既存のパターンを参照します。曖昧なプロンプトからは、曖昧な結果が生まれます。

ステップ 4：CLAUDE.md を短く、実行しやすい内容にする

Claude がコードから推測できないことだけを含めます。各行について、「これを削除すると、Claude は間違いを犯すだろうか？」と問いかけます。そうでなければ、削除します。

ステップ 5：コンテキストを積極的に管理する

無関係なタスクに移る際は /clear を使います。同じ問題に対して修正を 2 回試して失敗したら、コンテキストをクリアして、より良いプロンプトを書きます。焦点を指定して圧縮するには、/compact <hint> を使います。

ステップ 6：調査とレビューにはサブエージェントを使う

サブエージェントに、慣れていないコードの調査や実装のレビューを任せます。サブエージェントは新しいコンテキストで実行されるため、書いたばかりのコードにとらわれずに作業できます。

---

例

例 1：機能を正しく実装する

ユーザーの発言：「Claude に何かを実装するよう頼むと、結果が不安定になることがよくあります」

対応：

1. プロンプトに検証手順を追加します：「validateEmail 関数を書いてください。実装後に既存のテストスイートを実行し、出力を見せてください」
2. テストがない場合：「関数とそのテストを書き、テストを実行して結果を見せてください」
3. テストに合格するまでターンの完了をブロックする Stop フックを設定します

結果：コードが完了したように_見える_だけで停止せず、テストに合格するまで Claude が繰り返し作業します。

例 2：複数ファイルにわたる複雑な変更に取り組む

ユーザーの発言：「10 個のファイルにまたがる大規模なリファクタリングには、どう取り組めばよいでしょうか？」

対応：

1. /plan モードに入ります。Claude は変更を加えずに調査します
2. 次のように依頼します：「影響を受けるファイルを読み、実装手順をまとめた計画を作成してください」
3. 必要に応じて Ctrl+G で計画を直接編集します
4. プランモードを終了します。Claude は計画に沿って実装し、コミットします
5. 新しいコンテキストで差分をレビューするよう、サブエージェントに依頼します

結果：レビュー可能な計画に基づく、構造化されたリファクタリングが実現します。調査と記述を混在させたターンによるコンテキストの混乱もありません。

例 3：Claude が同じ間違いを繰り返す

ユーザーの発言：「同じ問題について Claude を 3 回修正しましたが、何度も間違えます」

対応：

1. /clear を実行して、新しいコンテキストを開始します
2. 元のプロンプトに不足していたもの（制約、例、明確な範囲など）を特定します
3. 制約を明示した新しい初期プロンプトを書きます：「重要：これらのテストではモックを使わず、実際のデータベース接続を使用してください」
4. プロジェクト全体に当てはまる場合は、その制約を CLAUDE.md に追加します

結果：修正を重ねて長くなったセッションよりも、プロンプトが明確な新しいセッションの方が、良い結果を得られます。

---

---

1. Claude が作業を検証できるようにする

作業が完了したように_見える_と、Claude は止まります。実行できるチェックがなければ、あなたが検証のループを担うことになります。Claude が読み取れる合否のシグナルを返すものを用意してください。テストスイート、ビルドの終了コード、リンター、出力を比較するスクリプトなどが該当します。

• 同じプロンプト内でチェックを実行して、繰り返し改善するよう Claude に依頼します。
• 複数ターンにわたる検証には、/goal の条件を設定します。
• Stop hook を使って、スクリプトが合格するまでターンの終了をブロックします。
• 検証サブエージェントを使い、レビュアーに新しいコンテキストを与えます。

成功したと主張するだけではなく、証拠（テストの出力、コマンドの結果、スクリーンショット）を示すよう Claude に依頼してください。

改善例：

変更前："メールアドレスを検証する関数を実装する" 変更後：*"validateEmail 関数を書いてください。テストケース：[email protected] → true、

invalid → false。実装後にテストを実行してください"*

---

2. まず調査し、次に計画してから、コードを書く

プランモード（/plan または UI の切り替え）を使って、読み取りと書き込みを分けます。

1. 調査 — プランモードに入り、Claude に変更を加えずにファイルを読ませます。
2. 計画 — 詳細な実装計画を書くよう Claude に依頼します。Ctrl+G を押すと、計画をエディターで開いて直接編集できます。
3. 実装 — プランモードを終了し、Claude に計画に沿ってコードを書かせ、検証させます。
4. コミット — Claude にコミットして PR を開くよう依頼します。

範囲が明確で修正が小さい場合（誤字、名前の変更、1 行の変更）は、計画を省略してください。プランモードにはオーバーヘッドがあるため、変更が複数のファイルに及ぶ場合や、コードに不慣れな場合に使います。

---

3. プロンプトで具体的なコンテキストを提供する

Claude は意図を推測できますが、あなたの考えを読むことはできません。

戦略	曖昧な指示	具体的な指示
タスクの範囲を指定する	"foo.py のテストを追加する"	"ユーザーがログアウトしている場合のエッジケースを対象に、foo.py のテストを書いてください。モックは避けてください。"
参照元を示す	"ExecutionFactory の API はなぜ変なのですか？"	"ExecutionFactory の git 履歴を調べ、API がどのように変化してきたか要約してください"
パターンを参照する	"カレンダーウィジェットを追加する"	"パターンの参考として HotDogWidget.php を確認し、それに従ってカレンダーウィジェットを実装してください"
症状を説明する	"ログインのバグを修正する"	"セッションのタイムアウト後にログインできないという報告があります。src/auth/ のトークン更新を確認してください。失敗するテストを書いてから修正してください。"

コンテキストを充実させる方法：

• @filename を使ってファイルを直接指定します。
• スクリーンショットを貼り付けるか、画像をプロンプトにドラッグします。
• データをパイプで渡します：cat error.log | claude
• ドキュメントの URL を指定します（/permissions でドメインを許可リストに追加します）。

---

4. 効果的な CLAUDE.md を作成する

CLAUDE.md はすべてのセッションの開始時に読み込まれます。短く、人が読みやすい内容にしてください。肥大化した CLAUDE.md ファイルがあると、Claude は実際の指示を無視するようになります。

含める内容：

• Claude が推測できない Bash コマンド（例：ビルド／テストコマンド）
• 言語のデフォルト設定と異なるコードスタイルのルール
• テストの手順と推奨するテストランナー
• リポジトリのエチケット（ブランチの命名規則、PR の慣例）
• プロジェクト固有のアーキテクチャ上の決定事項
• 開発環境特有の注意点、必要な環境変数
• よくある落とし穴や、わかりにくい動作

含めない内容：

• コードを読めば Claude が把握できること
• Claude がすでに知っている一般的な言語の規約
• 詳細な API ドキュメント（代わりにリンクしてください）
• 「読みやすいコードを書く」のような自明の慣行

各行について、次のように考えてください。「この記述を削除すると、Claude は間違えるだろうか？」 そうでなければ、削除してください。

/context を使って、Claude がファイルを読み込んだことを確認します。CLAUDE.md で @path/to/file インポートを使うと、他のファイルを選択的に取り込めます。

---

5. セッションのコンテキストを積極的に管理する

• /clear — 無関係なタスク間でコンテキストをリセットします。
• /compact <instructions> — 焦点を指定して圧縮します（例：/compact Focus on API changes）。
• Esc + Esc / /rewind — 巻き戻しメニューを開き、会話やコードの状態を任意の以前のチェックポイントに戻します。
• /btw — 手短な補足質問をします。回答はオーバーレイに表示され、会話履歴には入りません。

同じ問題に対する修正が2回失敗したら： /clear を実行し、学んだことを反映した、より良い最初のプロンプトを書いてください。修正が積み重なった長いセッションよりも、より良いプロンプトを使ったクリーンなセッションの方が効果的です。

CLAUDE.md で圧縮をカスタマイズできます。

「圧縮するときは、変更したファイルの完全な一覧とテストコマンドを必ず保持してください」

---

6. 調査とレビューにサブエージェントを使う

サブエージェントは独自のコンテキストウィンドウで動作し、要約を返します。メインの会話をすっきり保てます。

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

実装後：

use a subagent to review this code for edge cases

/code-review スキルを使って、現在の差分を対象にバグに焦点を当てた批判的なレビューを行います。

---

7. 自動化して規模を拡大する

非対話モード — Claude を CI、プリコミットフック、スクリプトに統合します。

claude -p "List all API endpoints" --output-format json
claude -p "Analyze this log file" --output-format stream-json --verbose

複数のファイルに分散して作業する — タスクをループ処理します。

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

並列セッション — Git worktree を使って複数の Claude セッションを実行し、編集内容が衝突しないようにします。ライター／レビュアーのパターン：

• セッション A が機能を実装します。
• セッション B が新しいコンテキストで差分をレビューします（書いたばかりのコードに対する先入観がありません）。

自動モード — バックグラウンドの安全チェックを行いながら、中断せずに実行します。

claude --permission-mode auto -p "fix all lint errors"

---

8. よくある失敗パターンとクイックリファレンス

失敗パターンの一覧表、すべての CLI コマンド、非対話モードの例については、references/commands.md を参照してください。