なぜあなたのClaude Codeはコンテキストを無視するのか？｜公式ベストプラクティスで解決する

Posted at 2026-01-24

はじめに

Claude Codeは、Anthropic社が開発したエージェント型コーディングツールです。ターミナル上で動作し、コードの探索・編集・実行・デバッグを自律的に行います。

本記事では、Anthropic公式ブログ「Claude Code: Best practices for agentic coding」および公式ドキュメントを参照しながら、Claude Codeを最大限に活用するためのベストプラクティスを体系的にまとめます。

この記事で扱うトピック

下記に4つの違いについて理解して、コンテキストをどうやって渡したらよいか整理します。

対象読者

Claude Codeをこれから使い始める方
Claude Codeを使っているが、より効率的な使い方を知りたい方
CLAUDE.md / SKILL.md / サブエージェントの違いを理解したい方

1. セットアップのカスタマイズ

基本的な内容は省略します。
下記の記事が分かりやすいので参考にしてください。

Claude Codeはエージェント型のコーディングアシスタントであり、プロンプトに自動的にコンテキストを取り込みます。このコンテキスト収集には時間とトークンを消費するため、環境をチューニングすることで最適化できます。

1.1 CLAUDE.mdファイルの作成

CLAUDE.mdは、Claude Codeが会話を開始する際に自動的にコンテキストに取り込む特別なファイルです。プロジェクト固有の情報を記載する場所として最適です。

最新のベストプラクティスではコンテキストウィンドウを圧迫しないようCLAUDE.mdには最小限の指示のみにとどめて、
細かいコンテキストはdocsフォルダに分離するのが推奨されています。

記載すべき内容の例

プロジェクト内で守ってほしいルール
コーディング規約
開発環境
プロジェクト固有の注意事項

CLAUDE.mdの例

CLAUDE.md

# Bashコマンド
- npm run build: プロジェクトをビルドする
- npm run typecheck: 型チェッカーを実行する

# コードスタイル
- CommonJS (require) ではなく、ESモジュール (import/export) 構文を使用する
- 可能な場合はインポートを分割代入する（例: import { foo } from 'bar'）

# ワークフロー
- 一連のコード変更が完了したら、必ず型チェックを行う
- パフォーマンスのため、テストスイート全体ではなく、単一のテストを実行することを推奨する

CLAUDE.mdの配置場所によって意味が異なるので気をつけましょう

1.2 CLAUDE.mdのチューニング

CLAUDE.mdはClaudeのプロンプトの一部になるため、通常のプロンプトと同様に最適化が必要です。使っていく中でもっと〇〇してほしい。ということが出てくるので都度修正しながら開発していきます。

1.3 .claude/rules/ によるモジュール化

CLAUDE.mdが大きくなりすぎた場合、.claude/rules/ディレクトリを使ってルールをモジュール化できます。

ディレクトリ構造の例

your-project/
├── .claude/
│   ├── CLAUDE.md          # メインの指示
│   └── rules/
│       ├── code-style.md  # コードスタイル
│       ├── testing.md     # テスト規約
│       └── security.md    # セキュリティ要件

パス固有のルール設定

frontmatterのpathsを使って、特定のファイルパターンにのみ適用されるルールを定義できます。

api-rules.md

---
paths:
  - "src/api/**/*.ts"
---
# API開発ルール
- すべてのAPIエンドポイントには入力検証を含めること
- 標準のエラー応答形式を使用すること
- OpenAPIドキュメントコメントを含めること

globパターンの例

**/*.ts - 全てのTypeScriptファイル
src/**/* - srcディレクトリ以下すべて
src/**/*.{ts,tsx} - TypeScriptとTSXファイル

1.4 許可ツールリストの管理

Claude Codeはデフォルトで、システムを変更する可能性のある操作（ファイル書き込み、特定のbashコマンドなど）に対して許可を求めます。.claude/settings.jsonを編集することでプロジェクト内で共通の権限を作ることができます。

許可ツールを管理する方法

方法	説明
セッション中に「Always allow」を選択	その場で許可リストに追加
`/permissions`コマンド	対話的に許可を追加・削除
`.claude/settings.json`を編集	チームで共有可能
`--allowedTools`フラグ	セッション固有の許可

許可設定の例

Edit - ファイル編集を常に許可
Bash(git commit:*) - git commitを許可
mcp__puppeteer__puppeteer_navigate - Puppeteer MCPサーバーのナビゲーションを許可

1.5 gh CLIのインストール

GitHubを使用している場合、gh CLIをインストールすることで、ClaudeがIssueの作成、プルリクエストの操作、コメントの読み取りなどを行えるようになります。

# macOS
brew install gh

# インストール後に認証
gh auth login

2. SKILL.md：Claudeの能力を拡張する

Skillは、Claude Codeの能力を拡張するための再利用可能なモジュールです。ドメイン固有の専門知識、ワークフロー、ベストプラクティスをClaudeに教えることができます。ruleとの違いは必要なときにだけ読み込まれるということです。

2.1 Skillとは

従来のカスタムスラッシュコマンドとの違い

機能	カスタムスラッシュコマンド	Skill
配置場所	`.claude/commands/`	`.claude/skills/<skill-name>/`
構成	単一のMarkdownファイル	`SKILL.md`＋サポートファイル
呼び出し制御	ユーザーのみ	ユーザー/Claude/両方
サブエージェント実行	不可	可能（`context: fork`）
動的コンテキスト	不可	可能（`!`コマンド）

Skillは、単なるプロンプトテンプレート以上の機能を持ち、Claude自身が状況に応じて自動的に呼び出すことも可能です。

2.2 Skillの作成方法

基本的なSkillの構造

my-skill/
├── SKILL.md              # メイン指示（必須）
├── template.md           # テンプレート
├── examples/
│   └── sample.md         # 出力例
└── scripts/
    └── validate.sh       # 実行スクリプト

SKILL.mdの例

~/.claude/skills/explain-code/SKILL.md

name: explain-code
description: コードを視覚的な図や比喩で説明します。コードの動作を説明する際、コードベースについて教える際、またはユーザーが「これはどう動くの？」と尋ねた時に使用します。
---
コードを説明する時は、必ず以下を含めてください：

1. **比喩から始める**：コードを日常生活の何かに例える
2. **図を描く**：ASCIIアートでフロー、構造、関係性を示す
3. **コードを順を追って説明する**：何が起きるかを段階的に解説する
4. **注意点（gotcha）を強調する**：よくある間違いや誤解は何か？

説明は会話調を心がけましょう。複雑な概念には複数の例えを用いること。

Skillの配置場所

配置場所	説明
`~/.claude/skills/<skill-name>/SKILL.md`	ユーザーレベル（全プロジェクトで利用可能）
`.claude/skills/<skill-name>/SKILL.md`	プロジェクトレベル（チームで共有可能）

3. サブエージェント：専門AIを生み出す

サブエージェントは、特定のタスクに特化した独立したAIエージェントです。メインの会話とは別のコンテキストで動作し、コンテキストの肥大化を防ぎながら専門的なタスクを実行できます。

3.1 サブエージェントとは

組み込みサブエージェント

名前	モデル	ツール	用途
Explore	Haiku（高速）	読み取り専用	ファイル探索、コード検索
Plan	継承	読み取り専用	計画立案のためのリサーチ
General-purpose	継承	全ツール	複雑なリサーチ、コード修正

カスタムサブエージェントの利点

メインの会話コンテキストを保持
ツールアクセスの制限によるセキュリティ向上
特定ドメインに特化したシステムプロンプト
Haikuなど軽量モデルによるコスト削減

3.2 サブエージェントの作成方法

/agentsコマンドでの作成

# Claude Code内で
/agents

/agentsコマンドで対話的にサブエージェントを作成・編集・削除できます。
でもこの方法で作らないほうが良いと思います。
私は下記のように普通にMDで作る派です。

.claude/agents/ への配置

.claude/agents/code-reviewer.md

---
name: コードレビュアー
description: コードの品質とベストプラクティスをレビューする
tools: Read, Glob, Grep
model: sonnet
---
あなたはコードレビュアーです。呼び出されたら、コードを分析し、品質、セキュリティ、ベストプラクティスに関する具体的かつ実行可能なフィードバックを提供してください。

frontmatterフィールド
フィールドを細かく書くことを推奨します

フィールド	説明
`name`	サブエージェント名
`description`	Claudeがデリゲート判断に使用
`tools`	許可するツール（Read, Grep, Glob, Bash, Editなど）
`disallowedTools`	禁止するツール
`model`	`sonnet`, `opus`, `haiku`, `inherit`
`permissionMode`	`default`, `acceptEdits`, `dontAsk`, `bypassPermissions`など
`skills`	プリロードするSkill

配置場所

配置場所	説明
`~/.claude/agents/`	ユーザーレベル（全プロジェクトで利用可能）
`.claude/agents/`	プロジェクトレベル（チームで共有可能）
`--agents`フラグ	CLIからJSON形式で指定

4. Claudeにツールを追加する

4.1 Bashツールとの連携

Claude Codeはbash環境を継承するため、インストール済みのツールをすべて利用できます。

カスタムツールを教える方法

ツール名と使用例を伝える
--helpを実行させてドキュメントを確認させる
頻繁に使うツールはCLAUDE.mdに記載

4.2 MCPの活用

Claude CodeはMCPクライアントとして機能し、外部のMCPサーバーに接続できます。

MCP設定の配置場所

プロジェクト設定（ディレクトリ固有）
グローバル設定（全プロジェクト共通）
.mcp.jsonファイル（チームで共有可能）

.mcp.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-puppeteer"]
    }
  }
}

--mcp-debugフラグを使うと、MCP設定の問題を診断できます。

5. 実践ワークフロー

5.1 探索 → 計画 → コーディング → コミット

多くの問題に適用できる汎用的なワークフローです。

各ステップの詳細

探索: 関連ファイルを読ませる。「まだコードを書かないで」と明示する
- サブエージェントを積極的に活用して詳細を調査
計画: いきなり実装せずに計画を立てさせる
- 計画をドキュメントやIssueに保存しておくと、後で戻れる
実装: 実装を進めながら妥当性を確認させる
コミット: コミットとPR作成。READMEやCHANGELOGの更新も依頼

ステップ1〜2は重要です。省略するとClaudeはすぐにコーディングを始めてしまい、最適でない解決策になる可能性があります。

5.2 テスト駆動開発（TDD）

テスト駆動開発は、エージェント型コーディングと特に相性が良いワークフローです。

テストを書かせる（入出力ペアを明示）
テストの失敗を確認（実装コードはまだ書かせない）
テストをコミット
テストを通すコードを書かせる（テストは変更させない）
サブエージェントで過学習を検証
コードをコミット

Claudeには明確な反復目標（テストケース、ビジュアルモック）を与えると、最もパフォーマンスが発揮されます。

5.3 スクリーンショットを活用した反復開発

ビジュアルターゲットを使った開発ワークフローです。

スクリーンショット取得手段を提供（Puppeteer MCPサーバーなど）
デザインモックを画像で渡す
実装 → スクリーンショット → モックとの比較 → 修正を繰り返す
満足したらコミット

5.4 Safe YOLO モード

--dangerously-skip-permissionsは、データ損失やシステム破損のリスクがあります。インターネットアクセスのないコンテナ内での使用を推奨します。

claude --dangerously-skip-permissions

lint修正やボイラープレート生成など、監視なしで完了させたいワークフローに有効です。

5.5 コードベースQ&A

新しいコードベースのオンボーディングにClaude Codeを活用できます。

質問例

「ロギングはどのように機能している？」
「新しいAPIエンドポイントはどう作る？」
「foo.rsの134行目のasync move { ... }は何をしている？」
「CustomerOnboardingFlowImplはどんなエッジケースを処理している？」

5.6 Git / GitHub連携

Git操作

git履歴の検索（「v1.2.3に何が入った？」など）
コミットメッセージの作成
リベースコンフリクトの解決

GitHub操作

PRの作成（「pr」と略語でOK）
コードレビューコメントへの対応
失敗したビルドの修正
オープンIssueの分類

6. ワークフローの最適化

6.1 具体的な指示を出す

具体的な指示は成功率を大幅に向上させます。

❌ 「これを直して」
⭕ 「src/auth/login.tsのvalidateCredentials関数で、空のパスワードが渡された場合にエラーをスローするよう修正して」

6.2 画像・ファイル・URLの活用

画像を渡す方法

スクリーンショットをペースト（macOS: cmd+ctrl+shift+4でクリップボードに、ctrl+vでペースト）
画像をドラッグ＆ドロップ
ファイルパスを指定

ファイル・URL

タブ補完でファイルを素早く参照
URLをプロンプトに貼り付け
/permissionsで許可ドメインを管理

6.3 早めの軌道修正

軌道修正の4つの方法

方法	説明
計画を先に確認	「コーディング前に計画を見せて」と明示
`Escape`キー	思考中・ツール実行中・編集中に中断してリダイレクト
`Escape`2回	履歴を戻って別の方向を探索
「元に戻して」	変更をundoして別アプローチを試す

6.4 /clearでコンテキストを整理

長いセッションではコンテキストウィンドウが無関係な内容で埋まり、パフォーマンスが低下します。

/clear

タスク間で頻繁に/clearを実行してコンテキストをリセットしましょう。

まとめ

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up