Claude Codeを真面目に使う：Anthropic公式推奨の最新運用2026

Claude Codeは2025年2月にリサーチプレビューで登場し、同5月に一般提供へ移行したAnthropic公式のエージェント型コーディングツールです。2026年4月時点でCHANGELOG は 2.1.110 まで進み、ほぼ毎日リリースが続いています。ツール自体が急速に姿を変えているため、ネットに散らばる断片情報を追うより、Anthropic の公式ドキュメントとエンジニアリングブログに書かれていることを「原典」として押さえるのが最も事故が少ない使い方になります。

この記事では一次ソースを https://code.claude.com/docs と https://www.anthropic.com/engineering に限定し、2026年4月中旬時点の推奨運用をまとめます。各章は「Anthropicが明示的に言っていること」と「そこから実務に落とすとどうなるか」を分けて書きます。

1. Claude Codeとは何なのか（定義を揃える）

Anthropic公式の説明は非常にミニマルです。Overviewページでは次のように位置づけられています。

• ターミナル上で動くエージェント型コーディングツールである
• コードベース全体を理解して、自然言語で複数ファイルの編集・テスト実行・Git操作・ドキュメント参照・Webサーチまで行う
• エディタ拡張ではない：IDE統合はあくまでオプションで、主戦場はシェル

この定義のポイントは「IDE拡張と同じ使い方をしてはいけない」という含意です。VS Codeの Copilot は「カーソル周辺を補完する」のが基本動作ですが、Claude Codeは「プロジェクト全体をエージェントが読み、タスクを取り、手を動かす」ことを前提に設計されています。同じ延長線で考えると期待値を誤ります。

2.1系で安定している公式機能の一覧は最低限これだけ把握しておけば足ります。

コアツール:  Read / Edit / Write / Glob / Grep / Bash / Agent(=Task) / Plan
拡張機構:    Hooks / Skills / MCP / Plugins / Subagents / Worktrees
セッション制御: /clear /compact /rewind /resume /agents /mcp /hooks
権限モード:  default / acceptEdits / auto / dontAsk / bypassPermissions / plan

2.1.63 で Task ツールが Agent ツールに改名されたなど、既存記事と名称がずれるケースがあります。迷ったら CHANGELOG が一次ソースです。

2. Anthropicが最も強く推奨している3つのこと

Claude Code: Best practices for agentic coding と common-workflows を読んでいくと、Anthropic本体が強調している原則は実は3つに絞れます。

2.1 CLAUDE.md を「共通の前提」として書き切る

プロジェクトルートに置く CLAUDE.md は、すべてのセッション開始時に自動でシステムプロンプト相当のコンテキストとして読み込まれます。Memoryドキュメントで明記されているのは以下の性質です。

• プロジェクト全体の前提（コマンド、コード規約、避けてほしい操作）を書く場所
• ~/.claude/CLAUDE.md はユーザー全体、.claude/CLAUDE.md はプロジェクト、./CLAUDE.md はルート、@import で他ファイルを取り込める
• 長すぎると毎セッションのトークン消費になるので**「AIが知らないと事故る情報」だけを書く**

動く言語が限られたサブモジュールに閉じる場合は、そのディレクトリに CLAUDE.md を置くと Claude Code が走査時に読みに行きます。グローバル1つ＋局所複数の階層構造にすると、全体を重くせず局所のルールを強制できます。

# CLAUDE.md（プロジェクトルート）

## 絶対にやらないこと
- `main` ブランチへの直接push
- `.env*` ファイルのコミット
- ロック不要な修正に対する `prettier --write .` の全体実行

## テスト実行
- バックエンド: `pnpm --filter api test`
- フロント: `pnpm --filter web test -- --watch=false`

## コード規約
- TypeScript の `any` は禁止。代替として `unknown` と型ガード
- React コンポーネントは default export をせず named export

## AIが読むべき補助ファイル
@docs/architecture.md
@docs/domain-glossary.md

2.2 「Explore → Plan → Code → Commit」の4フェーズで動かす

ベストプラクティス記事の核心はこのワークフローです。手順は common-workflows#use-plan-mode に公式手順として書かれています。

1. Explore: 関連ファイルを読み、コードベースを把握させる。このときコードを書かせない（Plan Mode あるいは読み取り専用の subagent を使う）
2. Plan: 何をどう変えるか言語化させ、ユーザーが承認する
3. Code: 承認された計画に沿って実装させる
4. Commit: 変更を1つ以上のコミットに分割し、PRを作る

Anthropicが強調しているのは「Explore と Code の間に Plan を挟むかどうかで成果物の質が段違いに変わる」という点です。Planを挟まないと、Claude Code は最初に目に入った実装案に飛びつく傾向があります。逆にPlan段階で「ここは◯◯パターンで」「この関数は壊さない」と1往復だけ入れておけば、後の実装の手戻りが劇的に減ります。

Shift + Tab を2回押すと Plan Mode に入れます。Plan Mode では Read / Grep / Glob / Agent(Explore) だけ許可され、Write / Edit / Bash が無効化されるため「読み込みだけさせたい」意図を構造的に強制できます。

2.3 Verify Your Work：AIの成果を信じない

ベストプラクティス記事で繰り返されているのが「Claude Codeが自分の出力を検証する仕組みを最初に用意しろ」というメッセージです。具体的には次の組み合わせを作ります。

Anthropicの言い方を借りると「Claude に実装させた後、Claude 自身にテストとdiffを確認させる」までが1タスクです。これを Plan Mode から要件として最初に握っておくと、ハルシネーション的な「動いたつもり」のコミットが減ります。

3. 効くのはプロンプトより「運用」

中級者がハマりがちなのは、「良いプロンプト」を探し続けることです。ベストプラクティス記事は最後の方にプロンプト例を載せていますが、それ以上に多くのページがコンテキスト管理・権限・ファイル構成の運用に割かれています。これは偶然ではなく、Claude Code のアーキテクチャが「LLMに何を見せるか」で性能が決まる構造になっているためです。

具体的には、こちら側で制御できる変数は次の順で重要度が高いと整理できます（一次情報から推測した私の解釈）。

1. コンテキストに何を入れて何を入れないか（CLAUDE.md, 添付ファイル, subagentの分離）
2. どの権限モードで動かすか（plan / default / auto / bypassPermissions）
3. どのツール・Hookを有効にしているか（MCPサーバー, Skills, Hooks）
4. 実際のプロンプト文言

「この指示どう書くべき？」の前に「このタスクを解く材料が全部セッション内にあるか？」を確認するのが正しい順番です。

4. コンテキスト管理：Claude Codeで一番効くレバー

4.1 コンテキストを意図的にリセットする

Claude Code のセッションは長くなるほど「無関係な情報」が累積し、後続のタスク精度を下げます。公式が用意している制御は3段階です。

• /clear — 履歴を完全に破棄して、CLAUDE.mdだけ残った状態に戻す
• /compact — 履歴を要約して圧縮する（前の議論が必要なときに使う）
• /rewind — 直近のアシスタント発言まで巻き戻す（誤ったツール実行のロールバックに使う）

経験則として、タスクの切り替え時は必ず /clear、長時間の議論を続けたいが暴走しかけた時だけ /compact、という使い分けです。/compact はトークンを節約しますが、要約の過程で重要な制約が落ちるリスクがあります。

4.2 Subagents でコンテキストを分離する

Subagents ドキュメントには「副作用のある探索をメインスレッドから追い出す」という明確な用途が書かれています。組み込みで用意されているのは3つです。

自作する場合は .claude/agents/<name>.md に frontmatter 付きMarkdownで定義します。name と description が必須、残りはオプションです。

---
name: security-reviewer
description: セキュリティ観点のコードレビュー担当。脆弱性検出とハードニング提案。
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
---

あなたはシニアセキュリティエンジニアです。指定されたdiffを読み、
OWASP Top 10の観点で問題点を列挙してください。実装は一切行わず、
`重大度 / 問題箇所 / 修正方針` の3列で報告してください。

2.1系の重要な追加として、subagentに isolation: worktree を指定すると一時的なgit worktreeでそのsubagentを動かせるようになりました。親セッションのワーキングツリーを汚さずに探索・試作ができるため、壊れる可能性がある変更を任せるときに有効です。

4.3 Plan Mode を制約として使う

Plan Mode は「安全装置」と見られがちですが、実務的にはコンテキスト汚染を防ぐ仕組みでもあります。Shift + Tab 2回で入る plan モードでは Write/Edit/Bash が落ちているので、Claude Code は「コードを書きたい」衝動を抑えて探索に集中せざるを得ません。結果として Plan が深く・具体的になり、続く Code フェーズの命中率が上がります。

5. 機構の連動：Hooks / MCP / Skills / Plugins / IDE

ここからはClaude Codeを拡張する5つの公式機構を整理します。それぞれ単独で紹介されがちですが、実務では組み合わせて使って初めて効果が出るものが多いです。

5.1 Hooks：決定論でAIの挙動を縛る

Hooks guide と Hooks reference には、セッション内のイベントに自前のコマンドを差し込んでAIの挙動を強制する仕組みが書かれています。

PreToolUse       ツール実行直前。拒否や書き換えができる
PostToolUse      ツール実行直後。ログ取りや検証に使う
Stop             セッション終了時
SessionStart     セッション開始時
UserPromptSubmit ユーザー入力送信前
Notification     通知送信時
FileChanged      ファイル変更検知
WorktreeCreate   worktree作成時
PreCompact       /compact実行前

実用例は「.env* に触ろうとしたら PreToolUse で拒否する」「コードを編集するたびに PostToolUse で prettier --check を走らせる」です。Hook自体は command / http / prompt / agent の4種類があり、if フィールドで条件指定できます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "if": "tool_input.file_path matches '.*\\\\.env.*'",
        "type": "command",
        "command": "echo 'Refusing to touch .env files' >&2; exit 1"
      }
    ]
  }
}

Hooks は「AIが注意深いかどうか」に依存しない決定論的な仕組みです。AIを信頼する前に配管で縛るのが鉄則で、セキュリティやコンプライアンスは全てHookに寄せるべきです。

5.2 MCP：外部ツールへの統一されたアクセス路

Connect Claude Code to tools via MCPではModel Context Protocolの接続手段が3種類示されています。

# HTTP（推奨）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# stdio（ローカルツール）
claude mcp add --transport stdio --env GITHUB_TOKEN=xxx github -- npx -y @mcp/github

# SSE（非推奨だが残置されている）
claude mcp add --transport sse asana https://mcp.asana.com/sse

スコープは local（自分のみ、プロジェクト単位）/ project（.mcp.json でチーム共有）/ user（自分の全プロジェクト）の3つ。チームで使うものは .mcp.json に入れてバージョン管理、個人のPATは local に入れる、が定石です。

Windowsのネイティブ環境でstdioを使う場合、cmd /c ラッパーが必要という落とし穴が公式ドキュメントに明記されています。npx を直接呼ぶと「Connection closed」エラーになります。

# Windowsの場合は cmd /c を噛ませる
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

MCPサーバーは 10,000 トークンを超える出力を返すと警告されます。巨大な結果を返すMCP（SQLクエリなど）には MAX_MCP_OUTPUT_TOKENS を事前に上げるか、サーバー側で要約してから返す設計にしておきます。

5.3 Skills：段階的開示で常時コストを抑える

Skillsは Claude Code のカスタム手順書です。Skills ドキュメント に書かれている設計思想はprogressive disclosure——必要な時だけコンテキストに展開する——というものです。

skills/pr-reviewer/
├── SKILL.md            # エントリポイント。frontmatterとサマリだけ常時読み込み
├── checklist.md        # 必要になったら Read で開く
└── examples/
    └── good-pr.md

SKILL.md のfrontmatterで disable-model-invocation（Claude が自動起動しない）、user-invocable（/skill-name でユーザーが手動起動）、allowed-tools（そのSkillが使えるツール）を制御できます。CLAUDE.md にルールを詰め込みすぎて肥大化させるよりも、独立した手順はSkillに切り出すのがスケーラブルです。

5.4 Plugins：配布可能なバンドル

Pluginsは subagents / skills / hooks / MCP設定を1パッケージにまとめて配布できる仕組みです。チーム内での統一や、公開リポジトリからの導入に使えます。.claude/plugins/<plugin> に置いて有効化すると、そのプラグインが束ねる全機構が一括で使えます。セキュリティ上の注意として、プラグインの subagent は hooks / mcpServers / permissionMode を設定できないことが明記されています。これは任意のフックを任意のプラグインが強制できてしまうと危険なためです。

5.5 IDE統合：VS Codeでのインライン体験

IDE integrations ページにある通り、VS Code / JetBrains拡張はあくまで既存のターミナルセッションと連動するものです。拡張は単独のチャットUIではなく、次の役割を担います。

• 現在開いているファイル・選択範囲を自動でコンテキストに渡す
• 編集結果をインラインdiffで表示する
• Claude Code が提案した変更を手元でApply/Rejectできる

つまりターミナルの Claude Code が主、IDE拡張が従という構造です。IDE側から直接操作できる範囲は限られます。

6. 最新の拡張方向（2.1.97〜2.1.110）

CHANGELOGを見ると、ここ数週間の変更の重心がどこにあるかがはっきりわかります。2.1.97以降の目立つ変更を抜粋します（いずれも公式CHANGELOG）。

2.1.110  agent teams での teammate 指定を JSON 経由で許可
2.1.108  /rewind をツール実行レベルで巻き戻せるように
2.1.105  subagent への memory スコープ追加（user / project / local）
2.1.103  MCP list_changed で動的にツール更新
2.1.100  Hooks に if 条件でファイル名マッチを許可
2.1.97   Subagent isolation: worktree が正式サポート

方向性は明らかで、「長時間・自律的・並列」のコーディングに振っています。単発の補完ではなく、複数のエージェントが並列で進行し、必要に応じて worktree を切り、失敗したら rewind し、結果をまとめて報告する——という運用像が前提になってきています。

7. 上級運用：並列・長時間・ハーネス

7.1 並列セッションと worktree

claude -w <name> でgit worktreeを切った上でClaude Codeを起動できます。common-workflows#run-parallel-claude-code-sessions の通り、同じリポジトリを複数のworktreeに分け、異なるタスクを独立したClaudeセッションに任せる運用が紹介されています。

# 別々のタスクを並行で走らせる
claude -w refactor-auth    # 認証周りのリファクタリング
claude -w feature-billing  # 請求機能の実装
claude -w fix-flaky-tests  # flakyテストの修正

Anthropic のエンジニアリングブログが以前触れていた「C言語コンパイラを全部AIに書かせる実験」で採用されていたのがまさにこのパターンでした。1つの巨大タスクを壊れにくい独立したサブタスクに分割し、それぞれ独立したworktreeで並列に走らせ、merge戦略は人間が握る。個人開発でも効果が大きく、メインスレッドの認知負荷をドロップできるのが最大の利点です。

7.2 Non-interactive mode と fan-out

claude -p "プロンプト" で非対話モードで1ショット実行できます。CIに組み込んだり、多数のファイルに同じ処理をかけたりするのに使えます。

# 全posts ファイルに同じチェックをかける
for f in src/content/posts/*.md; do
  claude -p "このファイルのfrontmatterを検証してfrontmatter違反があれば報告: $f"
done

claude -p は出力が標準出力に流れるため、xargs や parallel と組み合わせて fan-outできます。ただしそれぞれのセッションは別の認証・課金に乗るため、コスト管理は明示的に行う必要があります。

7.3 ハーネス設計

「ハーネス(harness)」はAnthropicが最近使い始めている用語で、Claude Code を長時間・自律的に走らせるための足場を指します。基本構成は次のとおりです。

• 入力契約: タスクをどう渡すか（issue / Markdown / JSON）
• 出力契約: 成果物の形式（PR / diff / レポート）
• 検証ループ: テスト、lint、ビルドで自動検証し、失敗したら再試行
• タイムアウトと予算: 実行時間・コストの上限をHookで強制
• ログとobservability: PostToolUse Hookで全ツール呼び出しを記録

ハーネス設計の肝は**「AIを賢くしようとせず、AIに失敗の逃げ場がない構造を作る」**ことです。Claude Code 単体の能力は既に十分で、問題のほとんどは「何を知らないか」と「どこで止められるか」の設計不足から来ています。

8. 実務の始め方

はじめてClaude Codeを本格導入する場合の最小ステップは次のとおりです。いきなり全機能を使わず、3段階で広げます。

Step 1: CLAUDE.md を書く／Plan Mode に慣れる
Step 2: Hooks で `.env` や main ブランチ直push を禁止
Step 3: MCP は1つだけ入れる（GitHubかNotionが実用度高い）
Step 4: Subagent を1つ作る（code-reviewer 系が初心者向け）
Step 5: worktree で2セッションを並列運用してみる

Step 1と2は同時に入れて問題ないですが、Step 3以降は一度に1機能ずつにしてください。MCP・Skill・Hookが同時に動いていると、問題が起きたときに原因切り分けが一気に難しくなります。

9. 落とし穴

最後に、公式ドキュメントに散らばっている注意点で実務でよくハマるものをまとめます。

• CLAUDE.md を長くしすぎる: 毎セッション読むコストが積み上がる。200〜400行までを目安にし、詳細はSkillsか@importで分離
• Subagent に無制限な権限を継承させる: デフォルトは親のツールを継承するので、Read-only で済むsubagentには明示的に tools を絞る
• MCPの bypassPermissions を常用する: 確認を省略できるが、プロンプトインジェクション経由の任意コマンド実行リスクが跳ね上がる。必ずHookで禁止コマンドを二重化する
• Plan Modeを飛ばして auto で走らせる: 試作段階では速いが、大きな変更では必ず意図とズレた実装が混入する
• /compact で重要制約を失う: 要約過程で CLAUDE.md の内容は保持されるが、議論中に合意した追加制約は落ちることがある。大事な制約はCLAUDE.md側に書き戻す
• Windowsネイティブでstdio MCPを直接npxで呼ぶ: cmd /c を噛ませないとConnection closedになる
• Hooks の正規表現: tool_input.file_path matches は正規表現。パスセパレータに注意（Windowsではバックスラッシュのエスケープが必要）

まとめ

2026年4月時点のClaude Codeを最大限に使い倒す要点は、**「強力なLLMの能力をどう引き出すか」ではなく「LLMが間違える余地をどう潰すか」**です。CLAUDE.mdで前提を揃え、Plan Modeで探索と実装を分離し、SubagentとHooksでコンテキストと権限を物理的に制約し、最後にverify手続きで成果物を検証する——この一連の運用が、公式が繰り返し伝えているメッセージの本質です。

Anthropic自身が毎日のようにCHANGELOGを更新していることからわかる通り、ツールはまだ固まっていません。細かいショートカットは変わり続けますが、「コンテキストと権限の設計が最も効くレバーである」という構造は当面変わらないはずです。プロンプト技を探すより、運用の骨格を先に作ることにエネルギーを使う方が、長期的な回収効率は高いと断言できます。

---

参考（すべてAnthropic公式）:

• Claude Code: Best practices for agentic coding — 本記事の核となる一次ソース
• Overview / Common workflows
• Memory (CLAUDE.md) / Subagents
• Hooks guide / Hooks reference
• Skills / MCP / IDE integrations
• CHANGELOG.md