背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

一言でいうと何か

環境設定・プロンプトの書き方・セッションの管理・並列実行まで、Claude Code を効果的に使うためのパターンをまとめたガイドページです。個別機能の使い方ではなく「どう使うと成果が出やすいか」の指針を集めたもので、元ページはそのほとんどが 1 つの制約、つまり「コンテキストウィンドウは満杯に近づくほど性能が落ちる」ことに由来すると述べています。

どういう場面で役立つか

Claude Code を触り始めて、指示は通るものの手戻りが多い・思ったコードにならないと感じるとき。「検証方法を与える」「探索と実装を分ける」「具体的なコンテキストを与える」といった、修正回数そのものを減らすための考え方が整理されています。

CLAUDE.md・フック・スキル・サブエージェントなどをどう設定すればセッション全体で効くのかを知りたいとき。各機能を「いつ・何のために」使い分けるかの判断材料と、設定ファイルの具体例が載っています。

1 つの Claude では回らない規模の作業(大量ファイルの移行、無人での自律実行、レビューの並列化など)に進みたいとき。非対話型モード、並列セッション、ファンアウト、オートモード、敵対的レビューといったスケール手法がまとまっています。

不要・向かないケース：元ページ自身が末尾で述べているとおり、これらは「すべての状況で一般的にうまく機能する出発点であり、すべての状況に最適とは限らない」ものです。差分を 1 文で説明できるような小さな修正(タイプミス、ログ行追加、変数リネーム)では、計画や検証の作法をわざわざ持ち込むとオーバーヘッドのほうが大きくなります。また、特定機能の詳細な操作手順が欲しい場合は、このページより各機能の個別ページを見るほうが向いています。

実例と解説

このページには前提となる OS やバージョンの指定はありませんが、一部の手法は外部ツールを前提にします(GitHub 連携には gh CLI、無人でのファンアウト実行には --allowedTools によるツール制限など)。該当箇所で触れます。

以下、元ページの流れに沿って、実用頻度の高い項目を引用・解説します。掲載コードはすべて元ページのもので、改変していません。

1. Claude に自分の作業を検証する方法を与える

元ページが最初に挙げる指針です。Claude は「完了したように見える」時点で止まるため、テスト・ビルド・スクリーンショット比較など、合否シグナルを返すチェックを与えると、Claude 自身がチェックを実行し合格するまで反復するようになります。人間が検証ループになる状態を避けられます。

チェックをどの程度厳密に「停止のゲート」にするかは段階的に選べる、と説明されています。(1) 1 つのプロンプト内で実行・反復させる、(2) /goal 条件として設定し毎ターン別評価者に再チェックさせる、(3) Stop フック(ターン終了直前に走るフック)でスクリプトを合否ゲートにする、(4) 検証サブエージェントや動的ワークフローに第二の意見を出させる、の 4 段階です。プロンプト版は今すぐ任意のタスクで使え、/goal と Stop フック版は無人実行を正しく完了させるためのもの、という違いがあります。あわせて「成功を主張させるのではなく、テスト出力・実行コマンドと戻り値・スクリーンショットなどの証拠を示させる」ことが推奨されています。

2. 最初に探索し、次に計画し、その後コーディングする

いきなりコーディングさせると間違った問題を解くコードが出ることがあるため、プランモード(編集せずに読み取りと計画だけを行う権限モード)で探索と実装を分けます。推奨ワークフローは「探索 → 計画 → 実装 → コミット」の 4 フェーズで、それぞれのプロンプト例が載っています。

探索フェーズ(プランモード):

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

計画フェーズ(プランモード):

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

実装フェーズ(デフォルトモード):

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

コミットフェーズ(デフォルトモード):

commit with a descriptive message and open a PR

前半の 2 つはプランモードで実行し、コードを変更せずに既存実装の理解と計画作成だけをさせます。元ページによれば、計画フェーズで Ctrl+G を押すと計画をテキストエディタで開いて直接編集できます。後半の 2 つはプランモードを抜けてから実行し、作成した計画に沿って実装・テスト・コミットまで進めます。なお元ページは、スコープが明確で小さい修正では計画を省いて直接実行するよう補足しています。

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

指示が正確なほど手戻りが減ります。元ページは「タスクをスコープする(どのファイル・どのシナリオ・テスト設定を指定)」「答えの出せるソースを指す(例:なぜこの API はこうなっているか→git 履歴を調べさせる)」「既存パターンを参照する(良い実装例のファイル名を挙げる)」「症状を説明する(症状・想定箇所・あるべき修正像を渡す)」という改善例を、曖昧な指示と対比して示しています。あわせて、リッチな入力を渡す手段として、@ によるファイル参照、画像の貼り付け、ドキュメント URL の指定(/permissions で頻用ドメインを許可)、cat error.log | claude のようなデータのパイプ、そして Claude 自身にコンテキストを取得させる方法が挙げられています。

4. 環境を設定する

セッションをまたいで効く設定群です。中心は CLAUDE.md(Claude が毎回の会話開始時に読む特別なファイル)です。/init を実行するとコードベースを分析してスターター CLAUDE.md を生成できます。形式は自由ですが短く保つことが推奨され、例として次が挙げられています。

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

コードスタイルやワークフローなど、Claude がコードから推測できない永続的なルールを書きます。元ページは「各行について『これを削除すると Claude が間違えるか?』を問い、そうでなければ削除する」よう勧め、膨らんだ CLAUDE.md は実際の指示を無視させる原因になると注意しています。ドメイン知識やたまにしか使わないワークフローは CLAUDE.md ではなくスキルに置き、オンデマンドで読み込ませます。

CLAUDE.md は @path/to/import 構文で他ファイルを取り込めます。

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

配置場所も複数あり、ホーム(~/.claude/CLAUDE.md、全セッション)、プロジェクトルート(./CLAUDE.md、git 共有用)、./CLAUDE.local.md(個人用、.gitignore 対象)、親/子ディレクトリ(モノレポで自動的に取り込み)を使い分けます。

環境設定として、このほかに次が紹介されています。パーミッションは中断を減らす 3 方法(オートモード=分類器が承認を代行、ホワイトリスト=/permissions で安全なコマンドを許可、/sandbox=OS レベルの分離)。CLI ツールは最もコンテキスト効率のよい外部連携手段で、GitHub なら gh をインストールしておくと Claude が issue 作成や PR オープンに使えます(未導入だと未認証 API がレート制限に達しやすい)。MCP サーバー(外部ツール/データを接続する仕組み)は claude mcp add で追加します。

フック(ワークフロー内の特定ポイントでスクリプトを自動実行する仕組み)は、CLAUDE.md の指示と違って決定論的に「必ず起きること」を保証します。Claude にフック自体を書かせることもでき、.claude/settings.json で設定、/hooks で確認します。

スキル(ドメイン知識や再利用ワークフローで Claude を拡張する仕組み)は .claude/skills/ に SKILL.md を置いて作ります。知識を持たせる例と、直接呼び出すワークフローの例が載っています。後者を引用します。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

$ARGUMENTS に渡した値を使い、/fix-issue 1234 のように呼び出します。副作用があり手動でトリガーしたいワークフローでは、disable-model-invocation: true を付けて Claude による自動起動を止めます。

サブエージェント(独自のコンテキストと許可ツールで動く下位エージェント)は .claude/agents/ に定義します。多くのファイルを読むタスクや専門的な焦点が要るタスクを、メインの会話を汚さずに委譲できます。

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

tools で使えるツールを、model で使うモデルを絞ったセキュリティレビュー用サブエージェントの定義です。使うときは「サブエージェントを使ってこのコードをセキュリティ観点でレビューして」のように明示的に指示します。

最後にプラグイン(スキル・フック・サブエージェント・MCP を 1 つのインストール単位にまとめたもの)を /plugin でマーケットプレイスから導入できると紹介されています。

5. 効果的にコミュニケーションする

新しいコードベースでは、別のエンジニアに尋ねるのと同じ質問(ロギングの仕組み、特定行が何をしているか、なぜこの関数を呼ぶのか等)を Claude に直接投げるのが有効なオンボーディング手段だとされています。

大きめの機能では、逆に Claude 側に質問させる方法が挙げられています。

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.

AskUserQuestion ツールを使って技術・UX・エッジケース・トレードオフを Claude から質問させ、仕様を SPEC.md に書き出させるプロンプトです。元ページは、仕様が固まったら新しいセッションを開始して実装させる(クリーンなコンテキストで実装に集中できる)ことを勧めています。

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

会話は永続的で可逆的である、という性質を活かす節です。方向がずれたら早く直すのが基本で、Esc(途中停止・コンテキストは保持)、Esc + Esc または /rewind(巻き戻しメニュー)、「Undo that」、/clear(無関係タスク間でコンテキストをリセット)が手段として挙げられます。同じ問題で 2 回以上修正したら、コンテキストが失敗アプローチで散らかっているサインなので、/clear して学んだことを盛り込んだプロンプトで再開するほうがよいとされています。

コンテキスト管理では、制限に近づくと自動でコンパクション(会話履歴の要約圧縮)が走ること、/compact <instructions> で焦点を指定して圧縮できること、/rewind で会話の一部だけを「ここから要約/ここまで要約」できること、会話履歴に残したくない小さな確認は /btw を使えることが説明されています。

調査はサブエージェントに委譲するのが強力だとされ、次の例が挙がっています。

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」)。

このほか、送信するプロンプトごとにチェックポイントが作られ会話/コード/両方を復元できること(ただしチェックポイントは Claude の変更のみを追跡し、Bash や外部プロセスの変更は対象外で git の代替ではない)、claude --continue / claude --resume でセッションを再開でき /rename で名前を付けて管理できることが紹介されています。

7. 自動化とスケール

1 つの Claude で効果を出せたら、並列化で出力を増やす段階です。非対話型モード(ヘッドレス)は claude -p "プロンプト" でセッションなしに実行します。

# One-off queries
claude -p "Explain what this project does"

# Structured output for scripts
claude -p "List all API endpoints" --output-format json

# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json --verbose

--output-format で出力をプレーンテキスト/JSON/ストリーミング JSON から選び、スクリプトから結果を解析できます。CI パイプラインやプリコミットフックへの組み込みに使います。

並列セッションは、必要な調整量に応じて worktree(分離した git チェックアウト)、デスクトップアプリ、Web 版、エージェントチーム(共有タスクとメッセージングを持つ複数セッションの自動調整)から選びます。新しいコンテキストは直前に書いたコードに偏らないため、Writer/Reviewer のように書き手と review 役を分ける品質向上パターンにも使えます。

大規模移行では多数の claude -p 呼び出しに作業を分散します(ファンアウト)。

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

ファイル一覧をループし、各ファイルの移行を個別の Claude 呼び出しに投げるスクリプトです。--allowedTools で Claude ができる操作を制限しており、無人実行では重要だと元ページは強調しています。まず 2〜3 ファイルで試してプロンプトを改善してから全件に広げる手順が示されています。

無人での自律実行にはオートモードを使います。

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

分類器モデルが実行前にコマンドをレビューし、スコープの逸脱・未知のインフラ・敵対的なコンテンツ由来の操作をブロックしつつ、ルーチン作業はプロンプトなしで進めます。ただし -p の非対話型実行では、分類器が操作を繰り返しブロックしたときにフォールバックする人間がいないため、オートモードは中止すると説明されています。

自律実行が長くなるほど、完了と見なす前の独立チェックが重要になります。正確性チェックには同梱の /code-review スキル(新しいサブエージェントで現在の diff をバグ観点でレビューし結果を返す)を使い、計画との突き合わせには自分でレビュープロンプトを書きます。

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.

「対象の作業」「突き合わせる計画」「何をギャップとみなすか」を明示したレビュー指示です。元ページは、ギャップを探せと指示されたレビュアーは健全な作業でも何かしら報告するため、正確性や記載要件に影響するギャップだけをフラグさせ、残りは任意扱いにするよう注意しています(すべて対応すると過剰実装になりやすい)。

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

元ページは 5 つの典型的失敗とその修正を挙げています。無関係な質問を混ぜてコンテキストを汚す「キッチンシンクセッション」(→/clear)、直しても直らず失敗アプローチで散らかる「何度も修正」(→2 回失敗したら /clear して初期プロンプトを改善)、長すぎてルールが埋もれる「過度に指定された CLAUDE.md」(→容赦なく削除)、もっともらしいがエッジケースを外す「信頼してから検証のギャップ」(→常に検証を用意し、検証できないなら出荷しない)、スコープなしの調査でコンテキストが埋まる「無限探索」(→スコープを狭めるかサブエージェントを使う)です。

まとめ

ベストプラクティスのほとんどは「コンテキストウィンドウは満杯に近づくほど性能が落ちる」という 1 つの制約に由来します。だからこそ、検証手段を与えて反復を自動化し、探索と実装を分け、具体的なコンテキストを渡し、無関係な文脈は /clear やサブエージェントで切り離す、という各手法がつながっています。環境設定(CLAUDE.md・フック・スキル・サブエージェント)でセッション横断の土台を作り、慣れてきたら非対話型モードや並列セッションで水平にスケールさせます。元ページは最後に、これらは出発点にすぎず、具体化すべき時と開放的にすべき時などの直感を自分で養うよう促しています。

次回は、本ページで繰り返し登場した検証・自律実行の設定のうち未執筆のもの(たとえば /goal 条件やチェックポイントまわり)を取り上げる予定です。

---

この記事は執筆時点の公式ドキュメントに基づいています。最新の情報は必ず公式ドキュメントをご確認ください。