Claude Code ベストプラクティス完全解説｜公式ドキュメントをエンジニアが実践的に読み解く

はじめまして、もるふぉ@コードをかかないAIエンジニアです。

エンジニアをやりながら、今はほぼコードを書かない開発スタイルに移行しました。

「書けないから書かない」じゃなくて、「書けるから書かなくていい」という話です。

実案件ベースで気づいたことだけ書いています。

よければXもフォローしてもらえると嬉しいです → X(@morphox_ai)

Claude Codeはチャットボットではなく「エージェント」

「Claude Codeに指示出したのに、なんか微妙なコードが返ってきた......」

この経験、ありませんか？

実はその原因、Claude Codeの使い方がChatGPTやCopilot Chatと同じになっていることが多いんです。

Claude Codeは「チャットボット」ではありません。

ターミナルの中で動く自律的なエージェントです。

ファイルを読み、コマンドを実行し、テストを走らせ、必要ならgitコミットまでやってくれる。

自分は10年以上Railsを書いてきたエンジニアですが、Claude Codeと出会ってからは「コードを書く」仕事がほぼなくなりました。

今やっているのは仕様設計とテスト設計、そしてClaude Codeへの的確な指示出しです。

ただ、この「的確な指示出し」が意外と難しいんですよね。

公式ドキュメントにベストプラクティスがまとまっているんですが、量が多いうえに英語なので、正直「読む気にならない」って方も多いんじゃないでしょうか。

読んだとしても「で、具体的にどうすればいいの？」となりがちです。

この記事では、Anthropic公式のClaude Codeベストプラクティスを、実際にプロダクト開発で使い込んでいるエンジニアの視点で噛み砕いて解説します。

「公式ドキュメントを読む時間がない」「読んだけどピンとこなかった」という方は、この記事だけ読んでもらえれば大丈夫です。

従来のAIコーディングツールとの違い

GitHub CopilotやCursorのような補完型ツールは、エディタの中でコードを提案してくれるものです。

主導権はあくまで開発者にあり、1行ずつ、1ファイルずつ作業する。

一方、Claude Codeは「タスク単位」で動きます。

「このAPIエンドポイントを実装して、テストも書いて」と指示すれば、複数ファイルを横断して作業を進めてくれる。

ここが面白いところなんですが、この違いがベストプラクティスの性質を大きく変えるんです。

補完型ツールなら「良い補完が出なかったらTab押さなければいい」で済みますが、エージェント型のClaude Codeでは「間違った方向に10ファイル書き換えた」ということが起こり得る。

つまり、正しい使い方を知っているかどうかで、開発の生産性が天と地ほど変わるんですよね。

すべてのベストプラクティスは「コンテキストウィンドウ」から始まる

公式ドキュメントが最初に強調しているのが、コンテキストウィンドウの管理です。

コンテキストウィンドウとは、Claude Codeが一度に参照できる情報の総量のことです。

あなたが送ったメッセージ、Claudeが読み込んだファイル、実行したコマンドの出力、すべてがこのウィンドウに蓄積されていきます。

そして、このウィンドウが満杯に近づくと、パフォーマンスが明確に低下します。

具体的には、指示の見落とし、以前のやり取りの忘却、コードの品質低下などが起こる。

想像してみてください。

長いセッションで複雑なファイルを何十個も読ませた後のClaude Codeは、明らかに「ぼんやり」し始めます。

いわば、情報を詰め込みすぎて頭がパンクした状態です。

「あれ、さっき言ったこと忘れてない......？」ってなった経験、あるんじゃないでしょうか。

これから紹介するベストプラクティスの多くは、突き詰めると「コンテキストウィンドウをいかに効率的に使うか」という話に帰結します。

この前提を理解しておくと、各テクニックの「なぜ」がすっきり腹落ちするはずです。

では、公式が「最もレバレッジが高い」と言い切っているテクニックから見ていきましょう。

Claude Codeに「自分の作業を検証する方法」を与える

ここ、ちょっと注目してください。

公式ドキュメントが「最もレバレッジが高い」と明記しているのが、検証手段を与えることです。

これは自分の実感としても強く同意します。

テストなしでClaude Codeを使うと、本当に暴走します。

一見動いているように見えるコードを量産するんですが、エッジケースは無視、型の整合性も怪しい、既存のテストは壊れている──そんな状態になりがちです。

「動くけどプロダクションには出せないコード」が量産される、あの感じ。

経験したことがある方も多いんじゃないでしょうか。

検証なし vs 検証ありでの品質差（Before/After表）

この表の右側、何が嬉しいかっていうと、「Claude Codeが自分自身で正しさを確認できる手段」が含まれているんです。

つまり、人間がいちいちチェックしなくても、AIが自走して品質を担保してくれる。

検証ありとなしでは、手戻りの回数が体感で半分以下になりますよ。

テスト・スクリーンショット・Bashコマンドの活用パターン

検証手段は大きく3つあります。

1. テスト実行

最も強力な検証手段です。

自分のワークフローでは、機能を実装する前にまずテストコードを書かせます。

このAPIエンドポイントのRSpecテストを先に書いて。
正常系：ステータス200で期待するJSONが返ること
異常系：認証なし401、権限なし403、存在しない404
テストが書けたら、そのテストを通す実装を書いて。

これが地味にすごいんですよ。

テスト駆動でAIを制御すると、暴走が劇的に減ります。

テストが落ちればClaude Codeは自分で気づいて修正してくれるからです。

つまり、今まで「実装 → 手動テスト → バグ発見 → 修正」だったのが、「テスト定義 → 自動実装 → 自動修正」になるんです。

2. スクリーンショットの貼り付け

UI関連の作業では、スクリーンショットが非常に有効です。

Claude Codeはターミナルアプリですが、画像を貼り付けることができます。

「現在こう見えている。こう変えてほしい」と画像で示すと、言葉だけで説明するよりはるかに精度が上がります。

UIの問題を文章だけで伝える大変さ、エンジニアならわかりますよね。

「余白がちょっと......」って言葉で伝えるより、スクショ1枚のほうが100倍早いです。

3. Bashコマンドでの出力確認

ビルドやリントの結果を確認させるのも効果的です。

変更後に以下のコマンドを実行して、エラーがないことを確認して：
- bundle exec rspec
- bundle exec rubocop
- yarn lint

こうすると、Claude Codeは自動的にコマンドを実行し、エラーがあれば自分で修正に入ります。

「検証 → 修正 → 再検証」のループが自律的に回るわけです。

ここまでが「最もレバレッジが高い」テクニックでした。

次は、そのレバレッジをさらに高める「ワークフロー」の話に入ります。

Claude Codeで実践する探索→計画→実装→コミットの4フェーズ

公式ドキュメントが推奨するワークフローは、明確に4つのフェーズに分かれています。

1. 探索（Explore）: コードベースを理解する
2. 計画（Plan）: 実装方針を決める
3. 実装（Implement）: コードを書く
4. コミット（Commit）: 変更を確定する

「そんなの当たり前じゃないか」と思うかもしれません。

でも、Claude Codeを使い始めると、つい「実装よろしく」と丸投げしがちなんですよね。

正直に言うと、自分も最初はそうでした。

その結果、既存のコード規約を無視した実装が出てきたり、不要な依存ライブラリが追加されたりしていました。

「AIが書いてくれるなら計画いらないでしょ」──この考え、めちゃくちゃ危険です。

Plan Modeの使い方と活用場面

ここが面白いところなんですが、Claude CodeにはPlan Modeという機能があります。

Shift+Tab を押すとパーミッションモードが循環し、Plan Modeに切り替わります。

Plan Modeでは、Claude Codeはファイルの読み取りや分析はできますが、ファイルの書き込みやコマンド実行はしません。

つまり「安全に調査・計画だけさせる」モードです。

いわば、地図を見て作戦会議をしている段階で、まだ一歩も動いていない状態ですね。

使い方の例：

（Plan Modeで）
このプロジェクトの認証周りの実装を調査して。
どのファイルが関連しているか、現在の認証フローはどうなっているか、
まとめてから実装計画を立てて。

Plan Modeで計画を確認してから、通常モードに切り替えて実装に入る。

この流れだけで、手戻りが大幅に減ります。

何が嬉しいかっていうと、Plan Mode中は「どれだけ調査させても実害がない」んです。

ファイルを壊す心配がゼロだから、安心して探索させられる。

計画をスキップしていい場面・してはいけない場面

とはいえ、すべてのタスクでPlan Modeを使う必要はありません。

スキップしていい場面：

• タイポの修正
• 単一ファイルの小さな変更
• 明確なバグ修正（エラーメッセージがはっきりしている）
• READMEの更新

スキップしてはいけない場面：

• 複数ファイルにまたがる変更
• アーキテクチャに影響する変更
• 既存のテストが壊れる可能性がある変更
• 外部APIとの連携実装
• データベースマイグレーション

判断基準はシンプルで、「間違えたときの修正コスト」です。

修正コストが低いならスキップしてOK。

高いなら計画を立てる。

これを守るだけで開発効率が全然違いますよ。

では次に、その計画をClaude Codeに伝える「プロンプトの書き方」を見ていきましょう。

プロンプトに具体的なコンテキストを与える

Claude Codeの出力品質は、入力するプロンプトの具体性にほぼ比例します。

これは大げさではなく、実感としてそうです。

「パフォーマンスを改善して」と言うのと、「このメソッドのN+1クエリを直して」と言うのでは、返ってくるコードの品質がまるで違います。

「なんかイマイチなコードが出てくるな......」と感じている方、プロンプトの具体性を見直すだけで世界が変わるかもしれません。

曖昧なプロンプト vs 具体的なプロンプト（比較表）

具体的なプロンプトのポイントは4つです。

1. タスクをスコープする: 「全体を改善」ではなく「このファイルのこのメソッド」
2. ソースを指し示す: ファイルパス、行番号、エラーメッセージを添える
3. 既存パターンを参照する: 「既にあるこのファイルと同じ方法で」
4. 症状を正確に説明する: 再現手順やエラーログを含める

何が嬉しいかっていうと、Claude Codeが「推測」する余地が減るんです。

推測が減れば、的外れな実装も減る。

いわば、タクシーで「いい感じのところに行って」と言うか、「渋谷駅のハチ公前まで」と言うかの違いですね。

@ファイル参照・画像貼り付け・データパイプの活用

Claude Codeでは、プロンプト内で @ を使ってファイルを直接参照できます。

@app/models/user.rb のバリデーションを見て、
@app/models/article.rb にも同じパターンのバリデーションを追加して

コマンド出力をパイプで渡すことも可能です。

cat error.log | claude "このエラーログの根本原因を特定して修正して"

画像もドラッグ＆ドロップで貼り付けられるので、UIの問題は言葉で説明するより画像を見せたほうが圧倒的に早いです。

Claudeにインタビューさせる技法

これは意外と知られていないテクニックなんですが、要件が曖昧なときは、自分が仕様を全部書くのではなく、Claude Codeに質問させるんです。

ユーザー通知機能を実装したい。
実装を始める前に、仕様を固めるために必要な質問をしてください。

すると、Claude Codeが「通知のトリガーは何ですか？」「メール通知ですか、アプリ内通知ですか？」「通知の既読管理は必要ですか？」といった質問を投げてくれます。

これに答えていくと、自然と仕様が固まっていく。

自分一人で仕様書を書くより、対話形式のほうが抜け漏れが減ることも多いです。

いわば、優秀なPMに壁打ちしてもらっている感覚ですね。

ここまでで「プロンプトの書き方」を押さえました。

次は、セッションを横断して効く「CLAUDE.md」の話です。

公式が「最も過小評価されている機能」と呼んでいるので、ここは必ず押さえておいてください。

効果的なCLAUDE.mdを書く

CLAUDE.mdは、Claude Codeの設定ファイルのようなものです。

プロジェクトのルートに置いておくと、セッション開始時に自動で読み込まれます。

ここに書いた内容が、そのプロジェクトでのClaude Codeの振る舞いを決めます。

公式ドキュメントでは「最も過小評価されているが最も重要な機能の1つ」とまで言われています。

自分もこれには完全に同意です。

CLAUDE.mdの質が、Claude Codeの出力品質を根本的に左右します。

たとえるなら、CLAUDE.mdは「新しく入ったメンバーに渡すオンボーディング資料」です。

良い資料があれば即戦力になるし、なければ毎回同じ質問をされる。

CLAUDE.mdの役割と読み込み場所

CLAUDE.mdは以下の4箇所に配置できます。

プロジェクトルートのCLAUDE.mdが最も重要です。

チームで共有するなら、このファイルをGitにコミットしておけば全員が同じルールでClaude Codeを使えます。

書くべき内容 vs 書かなくていい内容（対比表）

公式ドキュメントは「短く、人間が読める状態に保つ」ことを繰り返し強調しています。

CLAUDE.mdが長すぎると、それ自体がコンテキストウィンドウを圧迫するからです。

ここ、自分がやらかした話をさせてください。

最初はCLAUDE.mdに200行以上書いていた時期がありました。

プロジェクトの詳細な歴史、すべてのAPI仕様、コーディング規約の全文──全部詰め込んだんです。

結果、Claude Codeがその内容を処理するだけでコンテキストの一部を消費してしまい、肝心の実装作業の精度が落ちました。

200行から50行に削ったら、出力品質が明らかに上がったんです。

「書けば書くほど良い」わけじゃない、という逆説がここにあります。

CLAUDE.mdのサンプルテンプレート

実際のプロジェクトで使っている構成に近いテンプレートを共有します。

# CLAUDE.md

## プロジェクト概要
Ruby on Rails 8.0アプリケーション。記事管理プラットフォーム。

## 技術スタック
- Ruby 3.4 / Rails 8.0 / MySQL 8.4 / Redis
- フロントエンド: Bootstrap 5, Hotwire, ESBuild
- テンプレート: HAML

## 必須コマンド
- テスト実行: `bundle exec rspec`
- リント: `bundle exec rubocop`
- JSリント: `yarn lint`
- マイグレーション: `rails db:migrate`

## アーキテクチャルール
- コントローラは薄く。ビジネスロジックはapp/services/に置く
- ビューロジックはapp/decorators/（Draper）を使う
- バックグラウンド処理はSidekiqジョブ

## コーディング規約
- ビューはHAML（ERBではない）
- テストはRSpec（Minitestではない）
- 変数名は英語、コメントは日本語OK

## 注意事項
- コード修正後は必ずrspec, rubocop, yarn lintを実行すること
- db/schema.rbは手動編集禁止

ポイントは「Claude Codeが判断に迷いそうなこと」だけを書くことです。

Railsの一般的な知識はClaude Code自身が持っているので、わざわざ書く必要はありません。

「HAML？ERB？どっち？」「テストはRSpec？Minitest？」──こういう判断に迷うポイントだけ押さえておけばOKです。

複数CLAUDE.mdの階層設計

大規模なプロジェクトでは、サブディレクトリにも個別のCLAUDE.mdを置くと効果的です。

project/
├── CLAUDE.md              # プロジェクト全体のルール
├── app/
│   └── javascript/
│       └── CLAUDE.md      # JS固有のルール（ESBuild、モジュール構成）
├── spec/
│   └── CLAUDE.md          # テスト固有のルール（ファクトリ、VCR設定）

Claude Codeは作業中のディレクトリに応じて、該当するCLAUDE.mdを自動で読み込みます。

全体のルールは薄く、各モジュール固有のルールはそのディレクトリに置く。

この設計で、CLAUDE.mdの肥大化を防ぎつつ、必要な情報を必要なタイミングで提供できます。

さて、CLAUDE.mdで「プロジェクトの知識」を与える方法はわかりました。

でも、もっと動的に、もっと柔軟にClaude Codeの能力を拡張する方法があるんです。

Claude Codeのサブエージェントとスキルを使い分ける

コンテキストウィンドウの管理で強力な武器になるのが、サブエージェントとSkillsです。

この2つは似て非なる機能で、混同しやすいポイントなので丁寧に説明しますね。

サブエージェントが解決する問題

サブエージェントとは、メインのClaude Codeセッションから別のClaude Codeインスタンスを呼び出す機能です。

サブエージェントは独自のコンテキストウィンドウを持つので、メインセッションのコンテキストを消費しません。

ここ、ちょっと注目してください。

たとえば「このプロジェクトのディレクトリ構造を把握したい」という場面を考えてみてください。

サブエージェントなしの場合：

1. Claude Codeが数十個のファイルを読み込む
2. メインセッションのコンテキストが一気に消費される
3. その後の実装作業で精度が落ちる

サブエージェントありの場合：

1. サブエージェントが数十個のファイルを読み込む（メインのコンテキストは無傷）
2. 調査結果の「要約だけ」がメインセッションに返ってくる
3. メインセッションはクリーンな状態で実装に入れる

この差は、複雑なプロジェクトになるほど大きくなります。

いわば、自分で全部の会議に出るか、部下に出てもらって要点だけ報告を受けるか、の違いですね。

メインのコンテキストが汚れないっていうのが、本当にありがたいんですよ。

カスタムサブエージェントの設定方法

カスタムサブエージェントは .claude/agents/ ディレクトリにMarkdownファイルで定義します。

YAML frontmatterで名前・説明・使用ツールを指定する形式です。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: コードレビュアーとして、変更されたファイルをレビューする
tools: Read, Grep, Glob
---

## レビュー観点
- セキュリティリスク（SQLインジェクション、XSS等）
- パフォーマンス問題（N+1クエリ、不要なループ）
- テストカバレッジ（テストが不足している箇所の指摘）
- コーディング規約違反

## 出力形式
- 重要度: High / Medium / Low
- ファイル名と行番号
- 問題の説明と修正案

このエージェントを「今回の変更をcode-reviewerでレビューして」と指示すれば、定義した観点でレビューしてくれます。

Markdownファイルを1つ置くだけで、専属のレビュアーが手に入るわけです。

しかもそのレビュアーはメインのコンテキストを消費しない。

Skillsとは何が違うのか

Skillsはサブエージェントとは別の機能です。

サブエージェントが「独立したコンテキストで動く別インスタンス」なのに対して、Skillsは「Claude Codeに追加の知識を与える再利用可能なルールセット」です。

Skillsは .claude/skills/<スキル名>/SKILL.md という形式で定義します。

ディレクトリ名がスキル名になります。

# .claude/skills/api-conventions/SKILL.md
---
name: api-conventions
description: このプロジェクトのREST API設計規約
---

## エンドポイント命名規則
- リソース名は複数形（/users, /articles）
- ネストは2階層まで（/users/:id/articles まで）

## レスポンス形式
- 成功: { data: {...}, meta: {...} }
- エラー: { errors: [{ code: "...", message: "..." }] }

使い分けの目安はシンプルです。

• サブエージェント: 調査・レビュー・検証など、コンテキストを汚したくない重い作業
• Skills: API規約・コーディングルール・プロジェクト固有の知識など、頻繁に参照させたいルール

「コンテキストを守るか、知識を与えるか」──この軸で考えると迷わなくなりますよ。

サブエージェントの調査・レビュー・検証での使い分け

サブエージェントの活用パターンは主に3つです。

調査: コードベースの理解、依存関係の把握、ログの分析

このプロジェクトの決済処理の全体フローを調査して、
どのファイルが関連しているかリストアップしてまとめて。

レビュー: コード変更の確認、セキュリティチェック

今回のPRで変更されたファイルを確認して、
セキュリティ上の懸念がないかレビューして。

検証: テスト実行、動作確認の代行

spec/models/ 配下のテストを全部実行して、
失敗しているものがあれば原因を報告して。

メインセッションでは「設計と指示」に集中し、手間のかかる調査や検証はサブエージェントに任せる。

このスタイルが定着すると、コンテキストの枯渇に悩むことがほとんどなくなります。

ここまでで「コンテキストを守る」方法を見てきました。

次は、もう少し実践的な環境設定の話に入ります。

ここからの設定は、一度やれば毎日のセッションすべてに効いてくるので、コスパが非常に高いですよ。

環境を整えてClaude Codeのすべてのセッションを効率化する

Claude Codeの真の力を引き出すには、環境設定が欠かせません。

ここでの「環境」は、パーミッション、MCPサーバー、Hooks、Skillsなど、セッション横断で効く設定のことです。

一度設定すれば、毎回のセッションが自動的に効率化される。

「初期投資は大きいけどリターンが毎日返ってくる」タイプの作業です。

パーミッション設定（Auto mode / ホワイトリスト / サンドボックス）

Claude Codeのパーミッション設定は3つの方法で調整できます。

1. Auto mode

ファイル操作やコマンド実行を確認なしで自動実行します。

claude --auto で起動するか、セッション中に Shift+Tab でモードを切り替えることで有効化できます。

「え、確認なしで大丈夫なの？」って思いますよね。

実はAuto modeといっても「何でも通る」わけではありません。

別の分類器モデルがコマンドを事前にレビューし、スコープの逸脱・未知のインフラへのアクセス・敵対的なコンテンツによる操作を自動的にブロックします。

自分は基本的にAuto modeで使っています。

テスト駆動で開発しているなら、間違った変更はテストが検知してくれるので、いちいち確認する必要がないんです。

毎回「y」を押す手間から解放されるだけで、体感の快適さが全然違いますよ。

2. パーミッションホワイトリスト

特定のコマンドやディレクトリだけを許可リストに登録する方法です。

「このディレクトリへの書き込みは確認不要」「このコマンドは常に許可」といった細かい設定ができます。

Auto modeほど全開放はしたくないが、特定の操作では確認を省きたい場面に適しています。

3. サンドボックス

OSレベルの分離を有効にして、ファイルシステムやネットワークへのアクセスを制限する方法です。

/sandbox コマンドで有効化できます。

本番環境のデータに触れるリスクがある場合や、チームの新人に使わせる場合に有効です。

MCPサーバー・Hooks・Skillsの活用

環境設定の中でも、特にインパクトが大きいものを紹介します。

MCPサーバー

MCP（Model Context Protocol）サーバーを接続すると、Claude Codeの能力が拡張されます。

たとえば、データベースに直接クエリを投げる、Slackにメッセージを送る、Figmaのデザインを参照する──といったことが可能になります。

つまり、今まで「ターミナルの中だけ」だったClaude Codeの守備範囲が、外部サービスにまで広がるんです。

これ、地味にすごくないですか？

MCPサーバーの追加は claude mcp add コマンドで行います。

プロジェクトスコープで設定する場合は、プロジェクトルートの .mcp.json に記述します。

// .mcp.json
{
  "servers": {
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Hooks

Hooksは、Claude Codeの特定のアクションの前後に自動でスクリプトを実行する機能です。

たとえば「ファイルを保存するたびにフォーマッターを実行する」「セッション開始時にgit pullする」といった自動化ができます。

設定は .claude/settings.json の hooks セクションに記述します。

/hooks コマンドで現在の設定を確認できます。

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bundle exec rubocop -a $CLAUDE_FILE_PATHS",
        "description": "ファイル保存後に自動フォーマット"
      }
    ]
  }
}

これを設定しておくだけで、Claude Codeがファイルを変更するたびに自動でRubocopが走ります。

手動でフォーマットをかける手間がゼロになるんです。

「あ、また規約違反のコードが出てきた......」というストレスから解放されますよ。

Skills

Skillsは再利用可能なルールセットです。

.claude/skills/<スキル名>/SKILL.md にMarkdownで定義しておくと、Claude Codeが特定のタスクで参照できます。

サブエージェントがコンテキスト分離のための仕組みであるのに対して、Skillsは「知識を与えるための仕組み」です。

このすみ分けを意識して使い分けると、環境設定の効果が最大化されます。

さて、環境は整いました。

ここからは、日々の運用で差がつく「セッション管理」のテクニックです。

Claude Codeのセッション管理でパフォーマンスを保つ

コンテキストウィンドウの管理をさらに実践的に掘り下げます。

セッション管理のコマンドを知っているかどうかで、Claude Codeの使い心地が大きく変わります。

「なんか最近Claude Codeの精度が落ちてきた気がする......」という方、コンテキストの溢れが原因かもしれません。

ここで紹介するコマンドは、覚えるだけですぐに使えるものばかりです。

/clear・/compact・Escの使い分け

/clear - セッションをリセット

コンテキストを完全にクリアして、新しいセッションを開始します。

CLAUDE.mdは再読み込みされるので、プロジェクトの設定は維持されます。

「話が噛み合わなくなってきたな」と感じたら、迷わず /clear してください。

これだけで劇的に改善することが多いです。

自分の中では「困ったらまず/clear」が合言葉になっていますね。

/compact - コンテキストを圧縮

会話の履歴を要約して、コンテキストの消費量を減らします。

/clear ほど極端ではなく、重要な文脈は保持したまま圧縮してくれます。

長いセッションの途中で「まだこのセッションは続けたいけど、コンテキストが厳しくなってきた」という場面で使います。

いわば、ノートの余白がなくなったときに、今までの内容を要約して新しいページにまとめ直す感覚です。

Esc（1回） - 現在の応答を中断

Claude Codeの出力を途中で止めます。

間違った方向に進んでいると気づいたら、すぐにEscで止めて軌道修正するのが効率的です。

Esc（2回）または /rewind - 巻き戻しメニューを開く

巻き戻しメニューが表示され、会話のみ・コードのみ・両方の復元・特定メッセージからの要約、といった選択肢から復元方法を選べます。

Claude Codeは変更を加える前にチェックポイントを作成しているので、ファイルの変更も元に戻せます。

チェックポイントで安全に実験する

Claude Codeのチェックポイント機能は、地味ですが非常に強力です。

Claude Codeがファイルを変更するたびに、内部的にチェックポイントが作成されます。

Escを2回押すか /rewind を使うと巻き戻しメニューが開き、以前のチェックポイントを選んで復元できます。

つまり「とりあえず試してみて、ダメだったら戻す」が安全にできるんです。

git stashやgit checkoutを手動でやる必要がありません。

自分はこの機能を多用しています。

「この方針でいけるかな？」と思ったら、まず実装させてみて、結果を見てからEsc×2で戻すか、そのまま進めるか判断する。

この「試行錯誤のコスト」が限りなくゼロに近いのが、Claude Codeの強みなんですよ。

「失敗しても一瞬で戻せる」と思えると、攻めた指示も出しやすくなりますよね。

会話の再開と命名

セッションを閉じた後でも、会話を再開できます。

# 直前のセッションを再開
claude --continue

# 過去のセッション一覧から選んで再開
claude --resume

頻繁に中断・再開するプロジェクトでは、この機能を覚えておくと便利です。

さて、ここまで「うまくいくやり方」を見てきました。

次は逆に、「やりがちな失敗パターン」を見ていきましょう。

自分も全部やらかしたことがあるので、反面教師にしてください。

Claude Codeでよくある失敗パターンと対策

公式ドキュメントには「一般的な失敗パターン」セクションがあります。

ここに書かれている内容は、自分自身も全部やらかしたことがあるものばかりです。

「あるある」すぎて笑えないかもしれません。

キッチンシンクセッション

症状: 1つのセッションにあれもこれも詰め込む。

「認証機能を実装して、ついでにデザインも修正して、あとテストも全部書いて」のように、関連性の薄いタスクを1つのセッションに詰め込むパターンです。

コンテキストが汚染されて、すべてのタスクの品質が下がります。

対策: 1セッション1タスクを原則にする。

タスクが終わったら /clear して次のタスクに入る。

複数のタスクを並行させたい場合は、複数のターミナルでClaude Codeを起動すればOKです。

修正ループ地獄

症状: バグを修正 → 別のバグが発生 → それを修正 → また別のバグ、の無限ループ。

Claude Codeが問題の根本原因ではなく表面的な症状を修正しようとするときに起こります。

これ、ハマると本当に抜け出せないんですよね。

30分溶けた、なんてことがザラにあります。

対策: 2回修正しても直らなかったら、一度 /clear する。

そして新しいセッションで、エラーの全文と発生条件を最初からきちんと説明し直す。

「さっきの続きで」と頑張るより、リセットしたほうがずっと早いです。

自分の経験則では、3回以上の修正ループに入ったら、ほぼ確実にリセットしたほうが良い結果になります。

膨らんだCLAUDE.md問題

症状: CLAUDE.mdにあらゆる情報を詰め込みすぎて、逆効果になる。

先ほども触れましたが、CLAUDE.mdが長すぎるとコンテキストを圧迫します。

さらに、矛盾する指示が含まれていると、Claude Codeがどちらに従うべきか迷って品質が下がります。

対策: CLAUDE.mdは定期的に見直して削ぎ落とす。

「この3ヶ月で実際に役立った指示はどれか？」を基準にフィルタリングするのがおすすめです。

検証なしの出荷・無限探索

検証なしの出荷

テストもリントもスクリーンショット確認もなしに「できました」を信じてしまうパターンです。

記事の序盤で述べたとおり、検証手段を与えることが最も重要なベストプラクティスです。

「AIが『できました』って言ったから大丈夫でしょ」──これが一番危ないやつです。

無限探索

「このプロジェクトの全体構造を把握して」のように、スコープが広すぎる指示を出すと、Claude Codeが延々とファイルを読み続けてコンテキストを消費するパターンです。

対策は2つ。

スコープを絞る（「app/models/配下の構造を把握して」）か、サブエージェントに調査を任せるか。

どちらでもコンテキストの浪費を防げます。

ここまで読んで「やらかしたことある......」と思った方、安心してください。

みんな通る道です。

大事なのは、同じパターンにハマらないことですね。

まとめ：直感を磨きながら自分のワークフローを作る

ここまでClaude Codeのベストプラクティスを解説してきましたが、最後に1つ伝えたいことがあります。

公式ドキュメントにも書かれている言葉ですが、「Claude Codeとの作業は直感を養う作業」です。

最初からすべてのベストプラクティスを完璧に実践する必要はありません。

まずはこの3つから始めてみてください。

1. 検証手段を与える: テストを書かせてから実装させる
2. コンテキストを意識する: 長くなったら /clear
3. CLAUDE.mdを書く: 最初は10行でもいいので、よく使うコマンドとルールを書く

どれも5分あれば始められます。

コピペで始められるテンプレートはこの記事の中にあるので、そのまま使ってもらってOKです。

この3つを実践するだけで、Claude Codeの出力品質は劇的に変わります。

そこから先は、自分のプロジェクトに合わせてサブエージェント、Skills、Hooks、MCPサーバーと段階的に導入していけばいい。

大事なのは「使いながら学ぶ」姿勢です。

まずはCLAUDE.mdを1つ作るところから始めてみてください。

やらない理由はないですよね。

この記事が、Claude Codeを使いこなすための第一歩になれば嬉しいです。

参考: Claude Code 公式ベストプラクティス

よければXもフォローしてもらえると嬉しいです → X(@morphox_ai)