中小DXラボ のツール

Claude Code ベストプラクティス:公式ドキュメントの要点を情シス向けに整理

公開: ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

結論

  • Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)の公式ベストプラクティスの多くは、コンテキストウィンドウが急速に埋まり、埋まるほど性能が落ちるという1つの制約が土台です。
  • 最初に整えるのは、テストなど Claude が自分で実行できる確認手段、短く保った CLAUDE.md、権限の事前承認です。
  • 無関係な作業の間は /clear を使い、同じ問題で2回を超えて直せなければ、具体的なプロンプトで新しく始め直します。

土台の制約と、確認手段を渡すこと

公式ドキュメントによると、Claude Code はファイルを読み、コマンドを実行し、変更を加え、自律的に問題へ取り組めるエージェント型の環境です。その分、理解しておくべき制約があります。

中心はコンテキストウィンドウ(会話全体を保持する領域)です。メッセージ、読み込んだファイル、コマンド出力のすべてが入り、1回の調査で数万トークンを消費することもあります。埋まるほど、以前の指示を「忘れる」ようになったり、ミスが増えたりします。

最初の勧めは、テストやビルドなど、Claude が自分で実行できる確認手段を渡すことです。ないと「できたように見える」しか手がかりがなく、利用者が確認役になります。確認の強さは次のように選べます。

  • 1回のプロンプト内で、確認の実行と修正の繰り返しまで頼みます。
  • セッション全体では /goal 条件にします。別の評価役がターンごとに再確認し、Claude が停滞すると、目標を残したまま実行が止まることがあります。
  • 決定的な関門としては Stop フックを使います。確認をスクリプトとして実行し、通るまでターンの終了をブロックします。
  • 第二の目として、検証用サブエージェントなどに結果を反証させます。

成功を宣言させるより、テスト出力や実行結果などの証拠を出させるほうが確認は速く、見ていなかったセッションにも使えるとされています。

出典: Best practices for Claude Code

探索、計画、実装の順に進め、指示は具体的にする

いきなりコードを書かせると、違う問題を解くことがあります。そこでプランモードで調査と実装を分けます。Shift+Tab でステータスバーに ⏸ plan mode on と出るまで切り替えるか、claude --permission-mode plan でセッションを始めます。

  1. 探索:ファイルを読み質問に答えさせます。変更はしません。
  2. 計画:実装計画を作らせます。Ctrl+G でエディタ上で直接編集できます。
  3. 実装:プランモードを抜け、計画に照らして検証しながらコードを書かせます。
  4. コミット:説明的なメッセージでコミットし、PR を作らせます。

ただし、タイポ修正やログ1行の追加のように範囲が明確で小さい作業は、直接頼みます。差分を1文で説明できるなら、プランは省きます。

指示は具体的に

公式ドキュメントでは、対象ファイル、制約、手本にする既存パターンを示すよう勧めています。不具合なら、症状、疑わしい場所、「直った」状態を伝えます。

  • @ でファイルを参照すると、Claude は回答前にそのファイルを読みます。
  • 画像は貼り付けやドラッグ&ドロップで渡せます。
  • cat error.log | claude -p "explain this error" のようにデータをパイプで渡せます。

探索中で軌道修正できるなら、曖昧なプロンプトが役立つこともあります。

出典: Best practices for Claude Code

環境設定:CLAUDE.md、権限、フック

CLAUDE.md

CLAUDE.md は Claude が毎回の会話の開始時に読む特別なファイルです。/init で雛形を作り、育てていきます。形式の決まりはなく、短く読みやすく保ちます。公式ドキュメントの例です。

# 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

毎回読まれるため、広く当てはまる内容に絞り、時々しか要らない知識は skills(必要なときだけ読み込まれる知識や手順)に回します。各行について「これを消すと Claude がミスするか」と問い、そうでなければ削ります。長すぎると肝心の指示が埋もれます。コードを読めば分かること、頻繁に変わる情報、API ドキュメントの全文は入れません。git にチェックインしてチームで育てます。

権限

Manual モードは確認が多く、承認が惰性になりがちです。/permissions で信頼するツールを事前承認し、/sandbox でサンドボックス内のコマンドを確認なしで実行させられます。

公式ドキュメントによると、Claude Code v2.1.283 以降では、対話ターミナルと VS Code のセッションで auto mode(別の分類モデルが危険そうな操作だけを止める方式)が最初の権限モードです。それ以前のバージョンでは、Pro、Max、Team プランのみです。社内で配る際は、バージョンとプランを確認してください。

フックと拡張

CLAUDE.md の指示は助言ですが、フックは決定的に毎回実行されます。.claude/settings.json を編集して設定し、/hooks で確認します。繰り返し使う手順は .claude/skills/ の SKILL.md、分担先は .claude/agents/ に置けます。

出典: Best practices for Claude Code

セッション管理:早めに直し、文脈を整える

会話は保存され、巻き戻せます。

  • Esc で作業を中断します。コンテキストは保たれます。
  • Esc + Esc か /rewind で、会話やコードを以前の状態に戻せます。
  • /clear で、無関係な作業の間にコンテキストをリセットします。
  • /compact Focus on the API changes のように指示付きで圧縮もできます。

同じ問題で2回を超えて修正しているなら、失敗した試行でコンテキストが散らかっています。/clear して、学んだことを入れた具体的なプロンプトでやり直します。広い調査はサブエージェントに任せると、本編の会話を汚しません。

チェックポイントが記録するのは Claude のファイル編集ツールによる変更だけです。Bash コマンドや外部プロセスの変更は記録されず、git の代わりにはなりません。中断した作業は claude --continue で再開でき、claude --resume で一覧から選べます。

出典: Best practices for Claude Code

自動化と並列実行、避けたい失敗パターン

claude -p "prompt" で、CI やスクリプトから非対話で実行できます。

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

並列実行には worktrees(独立した git チェックアウトで編集の衝突を避ける仕組み)などがあります。Agent view は research preview、Agent teams は experimental で既定では無効です。新しい文脈でレビューさせると、書いた直後のコードへの偏りを避けられるため、書く役とレビューする役でセッションを分ける方法も紹介されています。

多数のファイルに同じ作業を回す場合は、claude -p をループで呼びます。無人で動かすときは --allowedTools で必要なツールだけを事前承認し、--permission-mode dontAsk でそれ以外を拒否します。最初の2〜3ファイルで試してから全体に広げます。

指摘を探すよう頼まれたレビュー役は、健全な作業でもたいてい何かしら報告します。すべて追うと過剰設計になるので、正しさや要件に関わる指摘だけを出させます。

公式ドキュメントが挙げる失敗パターンは、無関係な作業を混ぜたキッチンシンク型のセッション、何度も修正を重ねること、長すぎる CLAUDE.md、確認なしで出荷すること、範囲を決めない調査です。

本記事は執筆時点(2026年10月)の公式ドキュメントに基づきます。導入前に最新の公式ドキュメントで確認してください。

出典: Best practices for Claude Code

よくある質問

CLAUDE.md には何を書けばよいですか?

公式ドキュメントによると、Claude が推測できない Bash コマンド、既定と違うコードスタイル、テスト手順、ブランチ名や PR の作法、プロジェクト固有の設計判断などです。コードを読めば分かることや頻繁に変わる情報は入れません。長すぎると指示が無視されやすくなります。

出典: Best practices for Claude Code

同じ指摘を繰り返しても Claude が直せないときは?

同じ問題で2回を超えて修正したなら、文脈が失敗した試行で散らかっています。/clear して、学んだことを入れた具体的なプロンプトで始め直すと、長いセッションよりほとんどの場合で良い結果になると公式ドキュメントは述べています。

出典: Best practices for Claude Code

チェックポイントは git の代わりになりますか?

なりません。Claude のファイル編集ツールによる変更だけが対象で、Bash コマンドや外部プロセスによる変更は記録されないと公式ドキュメントに書かれています。

出典: Best practices for Claude Code

関連する無料ツール

Claude Code CLAUDE.md テンプレート生成: 用途と守ってほしいことを選ぶと、短い CLAUDE.md のひな形を出力します。最初の数行を決めるときに使えます。

参考(執筆時点)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。