こんにちは、ENECHANGEエンジニアの藤巻です。
この記事は、Claude Code 公式ドキュメントの Best Practices for Claude Code を参考に、要点を日本語でまとめたものです。「自分の作業を検証させる」「まず探索、次に計画、それからコード」「セッションを管理する」など、Claude Code を効果的に使うための9つのポイントを紹介します。
あわせて本記事では、これらのプラクティスを実際の作業フローに適用し、サブエージェントを用いたレビュー実践を通じて、実務の中でどのように機能するのかも検証した結果を紹介します。
はじめに
私は ENECHANGE に入社してから Claude に触り始めました。最近は Claude Code を使って業務に取り組んでいるものの、効率的な使い方ができているか少し不安を感じていました。
これまでの自分の使い方としては、commands や skills をいくつか作成・活用しています。例えば、Claude Code との会話をトピックごとに体系的に管理する仕組みを作り、以前「Claude Codeの会話を体系的に管理する仕組みを作ってみた」で紹介しました。
ただ、こうした個別の工夫はしているものの、Claude Code の使い方全体としてベストプラクティスに沿えているのかは自信がありませんでした。そこで、公式ドキュメントのベストプラクティスをまとめることで理解を深めつつ、業務へよりよく活かせたらと思い、この記事を書くことにしました。
公式ドキュメントでは、すべてのベストプラクティスの根底にある制約として コンテキストウィンドウの管理 を挙げています。この制約を念頭に置くと、9つのプラクティスがより理解しやすくなるはずです。
各セクションはそれぞれ内容が長いため折りたたんでいます。気になる箇所を適宜開いて確認してみてください。
1. Claude に自分の作業を検証させる
最もレバレッジの高い実践 として挙げられているのが、Claude が自分で作業を検証できる手段を与えることです。
テスト、スクリーンショット、期待される出力などを提供すると、Claude は自分の結果をチェックできます。検証手段がないと、見た目は正しいけど実際には動かないコードを生成するリスクがあります。
Before / After の例:
| 戦略 | Before | After |
|---|---|---|
| 検証基準を与える | 「メールアドレスをバリデーションする関数を実装して」 | 「validateEmail 関数を書いて。テストケース: user@example.com は true、invalid は false、user@.com は false。実装後にテストを実行して」 |
| UI変更をビジュアルで検証 | 「ダッシュボードの見た目を良くして」 | 「[スクリーンショット貼り付け] このデザインを実装して。結果のスクリーンショットを撮って元と比較し、差分を列挙して修正して」 |
| 症状ではなく根本原因に対処 | 「ビルドが失敗してる」 | 「ビルドがこのエラーで失敗: [エラー貼り付け]。修正してビルドが成功することを確認して。エラーを抑制するのではなく根本原因に対処して」 |
2. まず探索、次に計画、それからコード
Claude にいきなりコードを書かせると、間違った問題を解決してしまう可能性があります。Plan Mode（Claude Code のプロンプト入力中に Shift+Tab で切り替え）を使って、探索と実装を分離しましょう。
Plan Mode 中はファイルの読み取り・分析のみで、コードの変更は行いません。
推奨ワークフローは 4つのフェーズ です：
1. 探索（Explore） — Plan Mode で既存の実装を理解する
/src/auth を読んで、セッション管理とログインの仕組みを説明して。 環境変数でシークレットをどう管理しているかも確認して。
2. 計画（Plan） — そのまま Plan Mode で実装計画を作らせる
Google OAuth を追加したい。どのファイルを変更する必要がある？ セッションフローはどうなる？実装計画を作って。
Ctrl+G を押すと、Claude が実装に進む前に、作った計画をエディタで直接編集できます。
3. 実装（Implement） — Normal Mode に戻してコーディング
さっきの計画に沿って OAuth フローを実装して。 コールバックハンドラのテストも書いて、テストスイートを実行して失敗があれば修正して。
4. コミット（Commit） — コミットと PR 作成を依頼
説明的なコミットメッセージでコミットして、PR を作成して。
モード切り替えの詳細
Shift+Tab を押すたびに3つのモードを順番に循環します（参考: Common Workflows - Use Plan Mode）。
| モード | ステータスバー表示 | Claude の動作 |
|---|---|---|
| Normal Mode | (モード表示なし) | コードの変更が可能（デフォルト・起動直後） |
| Auto-accept Mode | ⏵⏵ accept edits on |
コードの編集を自動的に即反映する（Shift+Tab 1回目） |
| Plan Mode | ⏸ plan mode on |
ファイルの読み取り・分析のみ。コード変更は行わない（Shift+Tab 2回目） |
ただし、スコープが明確で修正が小さいタスク（タイポ修正、ログ追加、変数リネームなど）では Plan Mode は不要です。差分を一文で説明できるなら、計画はスキップしましょう。
3. プロンプトに具体的なコンテキストを与える
Claude は意図を推測できますが、心を読むことはできません。具体的なファイル名、制約、参考パターンを示すことで、修正回数を減らせます。
効果的な指示の例:
| 戦略 | Before | After |
|---|---|---|
| スコープを限定する | 「foo.py にテストを追加して」 | 「foo.py にユーザーがログアウトしている場合のエッジケースのテストを書いて。モックは避けて」 |
| ソースを指示する | 「ExecutionFactory の API はなぜこんなに奇妙？」 | 「ExecutionFactory の git 履歴を調べて、API がどう変遷してきたかまとめて」 |
| 既存パターンを参照させる | 「カレンダーウィジェットを追加して」 | 「ホームページの既存ウィジェットの実装パターンを確認して。HotDogWidget.php を参考に、月を選択でき前後にページ送りで年を選べるカレンダーウィジェットを同じパターンで実装して。既存ライブラリのみ使用」 |
| 症状を具体的に伝える | 「ログインバグを直して」 | 「セッションタイムアウト後にログインが失敗するとの報告。src/auth/ の認証フロー、特にトークンリフレッシュを確認して。問題を再現する失敗テストを書いてから修正して」 |
リッチコンテンツの活用
Claude にコンテキストを与える方法はいくつかあります：
@でファイルを参照 — コードの場所を説明する代わりに直接参照- 画像を貼り付け — スクリーンショットのコピー＆ペースト、ドラッグ＆ドロップ
- URL を渡す — ドキュメントや API リファレンス。
/permissions（セクション4で後述）で頻繁に使うドメインを許可リストに追加可能 - パイプでデータを送る —
cat error.log | claudeでファイル内容を直接送信 - Claude に自分で取得させる — Bash コマンド、MCP ツール、ファイル読み取りで Claude 自身にコンテキストを取得させる
4. 環境を設定する
いくつかのセットアップで、すべてのセッションで Claude Code の効果を大幅に向上できます。
CLAUDE.md を書く
CLAUDE.md は 毎回のセッション開始時に Claude が読み込む特別なファイル です。/init コマンドでプロジェクト構造を分析した雛形を生成でき、そこから改善していきます。
# Code style - ES modules (import/export) を使用、CommonJS (require) は不可 - 可能な場合はインポートを分割代入 # Workflow - コード変更の後は必ず型チェックを実行 - パフォーマンスのためテストスイート全体ではなく個別テストを実行
含めるべきもの / 含めないもの:
| 含める | 含めない |
|---|---|
| Claude が推測できない Bash コマンド | Claude がコードを読めばわかること |
| デフォルトと異なるコードスタイル | Claude が既に知っている言語の慣習 |
| テスト方法と好みのテストランナー | 詳細な API ドキュメント（リンクで十分） |
| リポジトリのルール（ブランチ命名、PR 規約） | 頻繁に変わる情報 |
| プロジェクト固有のアーキテクチャ決定事項 | 長い説明やチュートリアル |
| 開発環境の癖（必要な環境変数など） | ファイルごとのコードベース説明 |
| よくあるハマりポイントや非自明な挙動 | 「きれいなコードを書く」のような自明なこと |
CLAUDE.md が 長すぎると重要な指示がノイズに埋もれ、無視されてしまいます。
各行について「これを削除したら Claude がミスするか？」と問い、不要なら削除しましょう。CLAUDE.md はコードと同じように扱い、問題が起きたら見直し、定期的に剪定しましょう。
その他の実践的なアドバイス：
- CLAUDE.md は git にチェックインしてチームで共有 しましょう。時間とともに価値が蓄積されます
- 特に重要な指示には IMPORTANT や YOU MUST などの強調を加えると、遵守率が向上します
- 毎回読み込まれるため、広く適用される内容のみ書きましょう。特定の場面でしか使わないドメイン知識は Skills に分離するのが適切です
@path/to/import 構文で他のファイルをインポートすることもできます：
See @README.md for project overview and @package.json for available npm commands. # Additional Instructions - Git workflow: @docs/git-instructions.md
配置場所:
| 場所 | 用途 |
|---|---|
~/.claude/CLAUDE.md |
すべてのセッションに適用 |
./CLAUDE.md（プロジェクトルート） |
git にチェックインしてチームで共有。.gitignore したい場合は CLAUDE.local.md |
| 親ディレクトリ | モノレポで root/CLAUDE.md と root/foo/CLAUDE.md を両方読み込む |
| 子ディレクトリ | そのディレクトリのファイルを扱う際にオンデマンドで読み込み |
パーミッション設定
/permissions で安全なコマンド（npm run lint、git commit など）を許可リストに追加すると、承認の手間を減らせます。/sandbox で OS レベルの隔離を有効にすることもできます。
CLI ツール
gh、aws、gcloud、sentry-cli など外部サービス用の CLI をインストールしておくと、Claude がコンテキストを効率よく使って外部サービスと連携できます。
Claude が知らない CLI ツールも、'foo-cli-tool --help' を使って foo ツールについて学んで、それを使って A, B, C を解決して のようなプロンプトで学習させられます。
MCP サーバー
claude mcp add で Notion、Figma、データベースなどの外部ツールを接続できます。イシュートラッカーからの機能実装、DB クエリ、モニタリングデータの分析、Figma デザインの統合などが可能になります。
Hooks
CLAUDE.md の指示は助言的ですが、Hooks は確実に実行される決定論的な処理です。Claude のワークフローの特定のタイミングでスクリプトを自動実行します。
Claude に Hooks を作らせることもできます： - 「ファイル編集のたびに eslint を実行する Hook を書いて」 - 「migrations フォルダへの書き込みをブロックする Hook を書いて」
/hooks で対話的に設定するか、.claude/settings.json を直接編集します。
Skills
.claude/skills/ に SKILL.md ファイルを作成して、プロジェクト・チーム・ドメイン固有の知識を追加できます。関連する場面で自動適用されるか、/skill-name で直接呼び出せます。
# .claude/skills/api-conventions/SKILL.md --- name: api-conventions description: REST API design conventions for our services --- # API Conventions - Use kebab-case for URL paths - Use camelCase for JSON properties - Always include pagination for list endpoints
副作用のあるワークフローには disable-model-invocation: true を設定し、手動でのみ実行するようにできます。
Subagents
.claude/agents/ に専門のアシスタントを定義して、独立したコンテキストでタスクを委任できます。大量のファイルを読む必要があるタスクや、専門的なフォーカスが必要なタスクに有効です。
# .claude/agents/security-reviewer.md --- 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
「サブエージェントを使ってこのコードのセキュリティ問題をレビューして」のように明示的に指示します。
Plugins
/plugin でマーケットプレイスからインストールできます。Skills、Hooks、Subagents、MCP サーバーを1つのパッケージにまとめたものです。型付き言語を使っている場合は、コードインテリジェンスプラグインをインストールすると、正確なシンボルナビゲーションと編集後の自動エラー検出が得られます。
5. 効果的にコミュニケーションする
📖 原文: Communicate effectively
コードベースについて質問する
新しいコードベースへのオンボーディングでは、シニアエンジニアに聞くのと同じ感覚で質問できます：
- 「ロギングはどう動いている？」
- 「新しい API エンドポイントはどう作る？」
- 「foo.rs の134行目の
async move { ... }は何をしている？」 - 「
CustomerOnboardingFlowImplはどんなエッジケースを処理している？」 - 「このコードが333行目で
foo()ではなくbar()を呼んでいるのはなぜ？」
特別なプロンプトのテクニックは不要で、直接質問するだけで OK です。オンボーディングの時間を短縮し、他のエンジニアへの負荷を減らせます。
Claude にインタビューさせる
大きな機能を実装する際は、まず Claude にインタビューしてもらうアプローチが有効です：
[機能の簡単な説明]を作りたい。AskUserQuestion ツールを使って詳しくインタビューして。 技術的な実装、UI/UX、エッジケース、懸念事項、トレードオフについて聞いて。 自明な質問は避けて、自分が考えていなかった難しい部分を掘り下げて。 全てカバーしたら、完全な仕様書を SPEC.md に書いて。
仕様が完成したら、新しいセッション で実装を開始します。クリーンなコンテキストで実装に集中できます。
6. セッションを管理する
📖 原文: Manage your session
早めに軌道修正する
Claude が間違った方向に進んでいると気づいたら、すぐに修正しましょう：
Esc— 実行中の操作を停止（コンテキストは保持）Escを2回押す または/rewind— チェックポイントに巻き戻し「それを元に戻して」— 変更を取り消し/clear— 関係ないタスク間でコンテキストをリセット
同じセッションで2回以上修正しても直らない場合、コンテキストが失敗したアプローチで汚染されています。/clear して、学んだことを反映したより良いプロンプトで再開しましょう。
コンテキストを積極的に管理する
長いセッションでは、コンテキストウィンドウが無関係な会話やファイル内容で埋まり、パフォーマンスが低下することがあります。Claude Code はコンテキスト上限に近づくと自動的にcompact（要約）を行いますが、能動的に管理することも重要です。
/clear— 異なるタスク間で頻繁に使い、コンテキストを完全にリセット/compact <指示>— 例:/compact API の変更に集中して。重要な情報を残しつつ圧縮Escを2回押す または/rewind→ メッセージを選択して「ここから要約」で部分的に圧縮。それ以前のコンテキストはそのまま保持- CLAUDE.md に
"compact時は、変更したファイルの一覧とテストコマンドを必ず保持すること"のように指示を書くと、要約時に重要な情報が失われるのを防げる
サブエージェントで調査する
コンテキストは最も重要なリソースです。調査のために大量のファイルを読むと、メインのコンテキストが消費されます。サブエージェントは別のコンテキストウィンドウで動作し、結果の要約だけを返します：
サブエージェントを使って、認証システムがトークンリフレッシュをどう処理しているか、 また再利用できる既存の OAuth ユーティリティがあるかを調査して。
実装後の検証にも使えます：
サブエージェントを使って、このコードのエッジケースをレビューして。
チェックポイントで巻き戻す
Claude が行うすべてのアクションはチェックポイントを作成します。Esc を2回押すか /rewind で、会話のみ・コードのみ・両方のいずれかを任意の時点に復元できます。
慎重に計画を立てなくても、リスクのある変更を気軽に試せます。うまくいかなければ巻き戻して別のアプローチを試しましょう。
チェックポイントはセッションをまたいで持続するので、ターミナルを閉じても後から巻き戻せます。
ただし、チェックポイントが追跡するのは Claude による変更のみ です。外部プロセスの変更は含まれないため、git の代替にはなりません。
会話を再開する
claude --continue # 最新の会話を再開 claude --resume # 最近の会話から選択
/rename でセッションに説明的な名前（"oauth-migration"、"debugging-memory-leak" など）をつけると、後から見つけやすくなります。セッションをブランチのように扱い、異なる作業に別々の永続的コンテキストを持たせましょう。
なお、この /rename 機能は、非公式のチェンジログまとめによると v2.0.64（2025年12月10日） から追加されたものです。以前紹介した記事では「セッションに名前をつけられない」という課題を挙げていましたが、現在は公式に対応されています。
7. 自動化とスケール
📖 原文: Automate and scale
一人で Claude を使いこなせるようになったら、並列セッションやヘッドレスモードで出力を倍増できます。
ヘッドレスモード
claude -p "プロンプト" で、対話セッションなしで Claude を実行できます。CI パイプライン、pre-commit hook、スクリプトなどへの組み込みに使います。
出力形式（プレーンテキスト、JSON、ストリーミング JSON）を選べるので、結果をプログラムで処理できます。
# 単発のクエリ claude -p "このプロジェクトが何をするか説明して" # スクリプト向けの構造化出力 claude -p "すべての API エンドポイントを列挙して" --output-format json # リアルタイム処理向けのストリーミング claude -p "このログファイルを分析して" --output-format stream-json
複数セッションの並列実行
並列セッションを実行する主な方法は3つあります：
- Claude Desktop — 複数のローカルセッションをビジュアルに管理。各セッションは独立した worktree を持つ
- Claude Code on the web — クラウド上の隔離された VM で実行
- Agent teams — 共有タスクとメッセージングによる複数セッションの自動連携
並列化だけでなく、品質向上にも活用できます。新しいコンテキストでレビューすると、自分が書いたコードへのバイアスがかかりません。
Writer/Reviewer パターンの例:
| セッション A（Writer） | セッション B（Reviewer） |
|---|---|
API エンドポイントにレートリミッターを実装して |
|
@src/middleware/rateLimiter.ts のレートリミッター実装をレビューして。エッジケース、競合状態、既存ミドルウェアパターンとの一貫性を確認して |
|
レビューのフィードバック: [セッション B の出力]。この指摘に対応して |
テストでも同様に、一方の Claude にテストを書かせ、もう一方にそのテストを通すコードを書かせることができます。
ファイル横断のバッチ処理
大規模なマイグレーションや分析では、タスクを多数の並列 Claude に分散できます：
- タスクリストを生成 — Claude にマイグレーション対象のファイルを列挙させる
- ループで処理するスクリプトを書く：
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
- 数ファイルでテストしてからスケール — 最初の2〜3ファイルでプロンプトを改善し、全体に適用
--allowedTools フラグで Claude ができることを制限します。無人実行時に重要です。
既存のパイプラインへの統合も可能です：
claude -p "<プロンプト>" --output-format json | your_command
Safe Autonomous Mode
claude --dangerously-skip-permissions ですべてのパーミッションチェックをバイパスし、中断なしで作業させることもできます。lint エラーの修正やボイラープレート生成などに便利です。
⚠️ 注意: 任意のコマンド実行を許可するため、データ損失、システム破損、プロンプトインジェクション攻撃によるデータ流出のリスクがあります。リスクを最小化するため、インターネットアクセスのないコンテナ内で使用してください。
/sandbox を使えば、すべてのチェックをバイパスするのではなく、事前に境界を定義して同様の自律性を安全に得られます。
8. よくある失敗パターンを避ける
| パターン | 問題 | 対処法 |
|---|---|---|
| キッチンシンク・セッション | 1つのセッションで無関係なタスクを混在させ、コンテキストが無関係な情報で埋まる | /clear でタスク間をリセット |
| 何度も修正を繰り返す | 修正を重ねるほど、失敗したアプローチでコンテキストが汚染される | 2回失敗したら /clear して、学びを反映した新しいプロンプトで再開 |
| CLAUDE.md の詰め込みすぎ | 長すぎると重要なルールがノイズに埋もれ、Claude が半分を無視する | 定期的に剪定。Claude が既に正しくやっていることは削除 |
| 信頼して検証しない | もっともらしい実装がエッジケースを見逃している | 必ず検証手段（テスト、スクリプト、スクリーンショット）を用意 |
| 無限の探索 | スコープを絞らず「調査して」と依頼し、Claude が大量のファイルを読む | 調査範囲を限定するか、サブエージェントに委任 |
9. 直感を磨く
📖 原文: Develop your intuition
このガイドのパターンは出発点であり、絶対的なルールではありません。あらゆる状況に最適とは限らないのです。
例えば、1つの複雑な問題に深く取り組んでいるときは、コンテキストを 蓄積したままにすべき 場合もあります。探索的なタスクでは、計画を スキップして Claude に任せた方がよいこともあります。Claude がどう解釈するか見たいときは、曖昧なプロンプトが 正解 なこともあります。
Claude の出力が良かったときは何をしたか（プロンプトの構造、提供したコンテキスト、使ったモード）に注目し、苦戦したときはなぜかを考えましょう。コンテキストがノイジーだったか？プロンプトが曖昧だったか？タスクが一度で大きすぎたか？
使い続けるうちに、いつ具体的にすべきか、いつオープンにすべきか、いつ計画しいつ探索すべきか、いつコンテキストをクリアしいつ蓄積すべきかの 直感 が養われていきます。
自分の実践を振り返って
9つのプラクティスを自分の普段の使い方と照らし合わせてみました。
できていたこと
| # | プラクティス | 振り返り |
|---|---|---|
| 1 | 検証させる | テストの実行や結果の確認を指示に含めるようにしていた。ベストプラクティスとして明文化されているのを見て、やり方が間違っていなかったと確認できた |
| 6 | セッション管理 | /clear はコンテキストが多くなった時によく使っていた。ただし作業中に自動compactが走って戸惑うこともあり、コンテキスト管理の難しさは実感していた |
部分的にできていたこと
| # | プラクティス | 振り返り |
|---|---|---|
| 3 | 具体的なコンテキスト | うまくいかない時に指示を具体的にすることで改善してきた。ただ「事後対応」であり、最初から意識的にコンテキストを与える習慣はなかった |
| 5 | コミュニケーション | 「これはどう動いている？」「なぜこの構成になっている？」といった質問は日常的にしていた。インタビュー手法は未経験だが、結果的にコードベースへの質問という形で部分的に実践できていた |
| 8 | 失敗パターン | /clear の習慣はあったが、つい長いセッションになることも。「調査して」で大量のファイルを読ませることもあったが、プロンプト改善で対処できるようになった。エッジケースの見逃しは、セクション1の「最初から検証手段を与える」を意識すれば減らせそう |
できていなかった / 知らなかったこと
| # | プラクティス | 振り返り |
|---|---|---|
| 2 | 探索→計画→コード | Plan Mode の存在を知らなかった。探索と実装を分離する考え方は、特に大きな変更で効果を発揮しそう |
| 4 | 環境設定 | CLAUDE.md は社内で過去に整備されたものを使っていただけだった。Skills や Hooks も含め、この記事を書いたのを機に自分でもきちんと整理したい |
| 7 | 自動化とスケール | ヘッドレスモードや並列セッションなど、全体的に利用したことがなかった。まずはヘッドレスモードの単発クエリから試してみたい |
/rename でセッションに名前をつけられるようになったことも、この記事を書くまで知りませんでした。以前紹介した記事では「セッションに名前をつけられない」という課題を挙げていたので、地味ですが嬉しい改善です。
今後取り組みたいこと
振り返りを踏まえ、特に以下を意識して取り組んでいきたいと考えています。
- Plan Mode の活用 — 大きな変更やスコープが不明確なタスクでは、いきなりコードに入らず探索→計画→実装の流れを試す
- CLAUDE.md の整備 — 社内で整備されたものを使うだけでなく、自分のプロジェクトに合わせて Skills や Hooks も含めて整理する
- 最初からコンテキストを意識的に与える — うまくいかない時の「事後対応」ではなく、最初の指示から具体的なファイル名・制約・参考パターンを含める
- コンテキスト管理の徹底 —
/clearや/compactをこまめに使い、コンテキストウィンドウを常に意識する。自動compactに頼るのではなく能動的に管理する
ベストプラクティスを実践してみた
この記事を書く過程で、9つのプラクティスを一つひとつ読み込んでいくうちに、自分でも試してみたくなりました。そこで、学んだ内容を活かして カスタムエージェントの作成（セクション4: Subagents）と CLAUDE.md によるワークフロー制御（セクション4: CLAUDE.md）を実践し、この記事自体のレビューに使ってみました。
記事レビューにサブエージェントを使う理由
この記事は Claude Code との会話の中で書いています。メインの会話には執筆過程のやりとり（方針の相談、修正の往復、調査結果など）がすべて蓄積されています。
この状態で「レビューして」と頼んでも、Claude は執筆の経緯を知った上で記事を見ることになり、客観的な評価が難しくなります。
サブエージェントはメインの会話とは 独立したコンテキスト で起動するため、記事の完成品だけを渡してレビューさせることができます。執筆の経緯を知らない「別の目」でチェックできることを狙い、サブエージェントを使うことにしました。
また、レビュー結果（長文の指摘リスト）がメインのコンテキストを圧迫しないという実用的なメリットもあります。
準備1: カスタムエージェントの作成
セクション4で紹介した Subagents の仕組みを使い、記事レビュー専用のカスタムエージェントを ~/.claude/agents/article-reviewer.md に作成しました。
--- name: article-reviewer description: 技術記事のレビュースペシャリスト。正確性、読みやすさ、構成の観点でレビューする。 tools: ["Read", "Grep", "Glob", "WebFetch"] model: opus --- あなたは技術ブログ記事のレビューアです。 ## レビュー観点 1. **正確性**: 技術的な記述が正確か、公式ドキュメントと矛盾がないか 2. **読みやすさ**: 説明が明確で、論理の飛躍がないか 3. **構成**: セクション間の流れが自然か、冗長な部分がないか 4. **一貫性**: 文体、用語の統一がとれているか 5. **過不足**: 重要な情報の欠落、不要に詳細な部分がないか ## 出力フォーマット フィードバックを優先度順に整理する: - **WARNING**（要確認）: 正確性に疑問がある箇所 - **提案**: 改善候補 各指摘には該当箇所の行番号と具体的な修正案を含める。
ポイントは以下の通りです:
- tools:
WebFetchを含めることで、公式ドキュメントを直接参照して正確性を検証できる - model:
opusを指定し、高性能なモデルでレビューさせる - レビュー観点と出力フォーマット: エージェント定義に含めることで、レビューのたびに観点を指定し直す必要がない
準備2: CLAUDE.md にワークフロールールを追加
レビュー結果への対応で重要なのは、AI の指摘をそのまま反映しない ことです。セクション1で「検証させる」ことの重要性を紹介しましたが、サブエージェントのレビュー結果も同様に、人間が検証して判断する必要があります。
このワークフローを徹底するため、~/.claude/CLAUDE.md（グローバル設定）に以下のルールを追加しました:
## サブエージェント利用時のワークフロー サブエージェント（Task ツール）の結果を受け取った場合、以下のフローを厳守すること: 1. サブエージェントの結果をそのままユーザーに提示する 2. ユーザーの判断を待つ 3. ユーザーが承認した項目のみ修正を実施する YOU MUST NOT: - サブエージェントの結果をもとに勝手に修正を進めること - 指摘への対応（適用/スキップ）を自分で判断すること
セクション4で紹介した通り、特に重要な指示には YOU MUST NOT のような強調を加えています。実際、このルールを追加する前は Claude がレビュー結果を受け取った直後に自分で修正を進めてしまい、全件リバートする羽目になりました。CLAUDE.md にルールとして明記したことで、この問題は解消されました。
レビューの実行
記事の全セクションが書き終わった段階で、以下のように依頼しました:
作成したエージェントを用いてこの記事をレビューしてください。
エージェント定義にレビュー観点と出力フォーマットを含めているため、依頼時に細かい指示を繰り返す必要はありません。
Claude Code はこの依頼をもとに、内部で Task ツールを使ってサブエージェントを起動しました。その際、Claude Code が自動的に生成してサブエージェントに渡したプロンプトは以下の通りです:
あなたは技術ブログ記事のレビューアです。 ## レビュー観点 1. **正確性**: 技術的な記述が正確か、公式ドキュメントと矛盾がないか 2. **読みやすさ**: 説明が明確で、論理の飛躍がないか 3. **構成**: セクション間の流れが自然か、冗長な部分がないか 4. **一貫性**: 文体、用語の統一がとれているか 5. **過不足**: 重要な情報の欠落、不要に詳細な部分がないか ## 出力フォーマット フィードバックを優先度順に整理する: - **WARNING**（要確認）: 正確性に疑問がある箇所 - **提案**: 改善候補 各指摘には該当箇所の行番号と具体的な修正案を含める。 ## レビュー対象 以下のファイルをレビューしてください: /path/to/claude-code-best-practices.md これは ENECHANGE 公式テックブログ向けの技術記事で、Claude Code 公式ドキュメントの 「Best Practices」(https://code.claude.com/docs/en/best-practices) を 日本語で紹介・解説するものです。 公式ドキュメントの内容と照合して正確性を確認し、レビュー結果を出力してください。
エージェント定義の内容（レビュー観点・出力フォーマット）がそのままプロンプトに組み込まれ、さらにレビュー対象のファイルパスや記事の背景情報が自動的に補完されていることが読み取れます。
レビュー結果
サブエージェントは WARNING 5件、提案 14件 を返しました。以下はその一部です。
WARNING の例:
/renameのバージョン情報の出典が非公式サイト（claudelog.com）です。「非公式のチェンジログまとめによると」と明記するか、公式リリースノートへのリンクに差し替えることを検討してください。
提案の例:
公式ドキュメントでは冒頭で「すべてのベストプラクティスの根底にある制約」としてコンテキストウィンドウの管理を挙げています。記事の「はじめに」にもこの大原則を追加すると、記事全体の文脈がより伝わりやすくなります。
レビューアは各指摘に優先度（高/低）も付けており、対応の判断材料になりました。
対応プロセス
CLAUDE.md のルールに従い、Claude はレビュー結果をそのまま提示し、対応判断を待ちました。各指摘を確認し、以下のように対応しました:
| 指摘 | 内容 | 判断 | 理由 |
|---|---|---|---|
| W-3 | 出典が非公式 | ✅ 適用 | 読者の混乱を防ぐため |
| P-13 | コンテキスト管理の大原則を冒頭に | ✅ 適用 | 公式が最重要とする概念の欠落 |
| P-6 | パーミッション設定の背景説明追加 | ❌ スキップ | 原文と齟齬なし、簡潔さ優先 |
| 他16件 | 各種改善提案 | ❌ スキップ | 問題なし、または記事の方針と合わない |
19件中2件のみ適用という結果でした。
感想
この実践を通じて感じたことが3点あります。
1. カスタムエージェントで観点を標準化できる
エージェント定義にレビュー観点と出力フォーマットを含めておくことで、毎回のレビュー依頼が簡潔になります。同じ観点で繰り返しレビューしたい場合に特に有効です。
2. CLAUDE.md でワークフローを制御できる
「レビュー結果を勝手に適用しない」というルールを CLAUDE.md に書くことで、AI の振る舞いを制御できました。ルール追加前に実際に問題が起きたため、この効果は実感を持って確認できています。
3. 人間が最終判断するワークフローが実用的
19件の指摘のうち、実際に記事の改善に寄与したのは2件でした。残りはレビューア自身が「問題なし」と判断していたり、記事の方針と合わなかったりしたものです。AI のレビューは「見落としを拾う網」として有用ですが、最終的な判断は人間が行う必要があります。
おわりに
コンテキストウィンドウの管理が重要であることは知っていましたが、公式ドキュメントをまとめてみて、それが全体を貫く最も重要な原則であることをあらためて実感しました。知ってはいたものの、普段の業務できちんと意識できていたかというと、正直なところ不十分だったと思います。
ここで学んだベストプラクティスをもとに、日々の使い方をより改善し、業務に活かしていきたいと思います。
参考リンク
- Best Practices for Claude Code — 本記事の元となった公式ドキュメント
- Common workflows — デバッグ、テスト、PR 作成などのステップバイステップガイド
