CLAUDE.mdの書き方: Claude Codeが迷わない実践テンプレート

レビューのたびに同じ修正を頼み、テストコマンドも毎回説明しているのに、Claude Codeが別のファイルを触って手戻りになる。そんな制作会社やSaaSチームでは、原因がプロンプトではなく CLAUDE.md の書き方にあるかもしれません。

長い社内Wikiを貼れば賢くなるわけではありません。必要なのは、作業前に読むべき短い判断基準と、変更後に実行するコマンドです。この記事では、初心者が今日1ファイルから始められる形に絞ります。

この記事の要点

CLAUDE.md ファイルに残すのは、毎回使うコマンド、編集してよい範囲、レビューの合格条件です。次の5点を先に押さえてください。

• CLAUDE.mdはClaude Codeへの継続的な指示であり、アクセス制御ではない。
• 共有ルールはリポジトリ直下、個人用メモは CLAUDE.local.md、特定パスのルールは .claude/rules/ に分ける。
• 目安は200行未満。背景説明より、ファイル名、コマンド、合否条件を残す。
• セキュリティ上の禁止は、文章だけでなくpermissionsやhooksでも止める。
• 更新後は、実際の作業と検査コードで「守られる指示か」を確認する。

最初から完璧な文書を作る必要はありません。まず、直近3回のレビューで繰り返した指摘を並べ、その中から今後も使うものだけを残します。

Claude Codeに任せる範囲と人が判断する範囲

CLAUDE.md と権限設定を同じものとして扱うと、事故を防げません。Claude Codeに任せるのは、既存コードの調査、決められた範囲の修正、テスト実行、差分の要約です。仕様変更や公開判断は人が持ちます。

判断	Claude Codeに任せる	人が判断する
調査	関連ファイル、既存パターン、テストの探索	調査対象に個人情報や契約情報を含めるか
実装	指定範囲のコードとテストの変更	料金、権限、法務、顧客向け仕様の変更
検証	lint、型検査、単体テスト、build	受け入れ基準を満たすか、公開してよいか
記録	変更ファイルと未解決リスクの報告	CLAUDE.mdに恒久ルールを追加するか

CLAUDE.mdは「この順で確認してほしい」という案内です。git push --force や本番DB更新を本当に止めたい場合は、settings.json のpermissionsや PreToolUse hookを使います。詳しい分離はClaude Codeの権限設定ガイドでも確認できます。

読み込まれる場所を先に決める

リポジトリのどこにファイルを置くかで、指示が届く範囲が変わります。プロジェクト直下の CLAUDE.md はチーム共通、~/.claude/CLAUDE.md は自分の全プロジェクト共通、CLAUDE.local.md はその作業環境だけのメモに向きます。

repo/
  CLAUDE.md                  # チーム共通の短いルール
  CLAUDE.local.md            # 個人用。gitignoreに追加
  .claude/
    rules/
      api.md                 # APIファイルだけに必要なルール
  packages/
    admin/
      CLAUDE.md              # admin配下を読むときに追加される指示

起動時には現在地と親ディレクトリの指示が読み込まれます。子ディレクトリのCLAUDE.mdは、その配下のファイルをClaude Codeが読んだときに追加されます。大規模リポジトリで全部をルートへ詰め込まず、影響するコードの近くに置く理由はここにあります。

@docs/project-map.md のようなimportは整理には役立ちますが、読み込む情報量の節約にはなりません。長い議事録をimportするより、必要になったときに読むファイルとして名前だけ示します。WindowsではClaude Codeが直接読むのはCLAUDE.mdなので、AGENTS.mdと共用したい場合は @AGENTS.md と明示する方法が確実です。

最初のCLAUDE.mdはこの形でよい

コマンドと変更ルールを1画面で読める程度にまとめます。下のテンプレートでは、抽象的な「きれいなコードを書く」を避け、どのファイルを触り、何を実行し、何を報告するかまで書いています。

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

チームが日本語で運用しているなら日本語で構いません。言語よりも「確認可能か」を見ます。「適切にテストする」ではなく npm test、「既存設計を守る」ではなく「APIレスポンスは src/lib/api-response.ts を使う」と書くほうが判断がそろいます。

3つのUse case

レビュー差分、問い合わせフォーム、公開前チェックの3場面で、何を入力し、何を受け取り、どこを人が見るかを分けます。CLAUDE.mdへ追加する前に、小さな作業で再現するかを確かめます。

Use case 1: 制作会社のレビュー指摘を減らす

制作会社では、案件ごとにCSS命名や画像サイズが違い、レビューのたびに同じ差し戻しが起きます。共通ルールではなく、対象リポジトリで毎回守る3〜5項目だけを残します。

入力: 直近3件のレビューコメント、対象ファイル、既存のlintとbuildコマンド。

出力: 使用した既存コンポーネント、変更したページ、実行した検査、未確認のブラウザ条件を含む差分報告。

人の確認: デザインの意図、写真の権利、CTA文言、スマホでの最終表示。レビュー戻り回数を導入前後の10件で数えると、ルールを残す価値を判断できます。

Use case 2: SaaSの問い合わせフォームを安全に直す

フォーム修正では、見た目だけ直ってバリデーションや通知メールが抜ける失敗が起きます。変更時に一緒に確認するファイルとテストをCLAUDE.mdへ書きます。

入力: フォーム本体、入力スキーマ、APIハンドラー、通知テンプレート、既存テスト。

出力: 正常系と不正入力のテスト、エラーメッセージ、変更した設定の一覧。個人情報をログへ出さないことも報告対象にします。

人の確認: 収集する個人情報の妥当性、保存期間、メール送信先、本番反映。指標は問い合わせ率だけでなく、送信失敗件数と対応時間も並べます。

Use case 3: コンテンツサイトの公開漏れを防ぐ

記事ページでは、本文が正しくてもdescription、内部リンク、画像、モバイル表示が抜けると流入や広告収益に響きます。公開条件を短いチェックリストとして共有します。

入力: MDXファイル、frontmatter定義、内部リンク一覧、buildコマンド、対象URL。

出力: descriptionの文字数、リンク切れ、コードブロック、build結果、確認したURLの一覧。

人の確認: 内容の正確さ、検索意図、広告と本文の読みやすさ、公開可否。PVだけでなく、検索クリック、読了に近い滞在、CTAクリックを週単位で見ます。

動く確認コードでCLAUDE.mdを検査する

ファイルが長くなりすぎていないか、必須見出しがあるか、秘密情報らしい文字列が入っていないかをNode.jsで確認します。次を check-claude-md.mjs として保存し、Node.js 20以降で実行してください。

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

実行コマンドは1つです。CIにも同じコマンドを置けば、秘密情報の混入や必須項目の削除をレビュー前に検出できます。

node check-claude-md.mjs CLAUDE.md
# 日本語のH2見出しを使う場合
node check-claude-md.mjs CLAUDE.md "コマンド|変更ルール|レビューチェック"

この検査は秘密情報の全種類を保証するものではありません。GitHubのsecret scanningや専用スキャナーと併用し、検出した値は履歴からの除去と失効まで行います。

Pitfall: 長文化・曖昧な指示・権限の混同

差分が増えるたびにルールを足すと、ファイルはすぐ読みにくくなります。原因は、発生理由を確かめずにレビューコメントをすべて恒久ルールへ変えることです。直し方は、同じ失敗が2回起きた項目だけを候補にし、古いコマンドを消してから加えます。

「品質を高く」「既存の設計に合わせる」のような曖昧な文章も判断を助けません。原因は合格条件が見えないことです。修正は、対象パス、実行コマンド、期待する終了コード、確認する画面幅まで書くことです。

最も危険なのは「本番DBを触らない」と書けば防げると思うことです。CLAUDE.mdは指示であり、防壁ではありません。対策としてpermissionsで危険なコマンドをdenyし、必要ならPreToolUse hookで終了コード2を返して止めます。文章には禁止理由と代替手順だけを残します。

もう一つの落とし穴は、READMEや議事録を大量にimportしてコンテキストを圧迫することです。原因は「別ファイルなら軽い」という誤解です。importsも起動時に読み込まれるため、常時必要な判断だけ残し、詳細は必要時に読むURLやパスとして示します。

よくある質問

Q. CLAUDE.mdは何行までですか？

厳密な上限ではありませんが、公式ドキュメントは200行未満を目安にしています。まず100行前後で始め、似た指示を統合します。パッケージ固有の内容は配下のCLAUDE.mdか .claude/rules/ へ移します。

Q. /compact の後も指示は残りますか？

ルートのCLAUDE.mdは圧縮後に再度コンテキストへ入ります。子ディレクトリやパス限定ルールは、該当ファイルを読んだときに読み込まれます。圧縮前の会話だけに頼らず、継続して必要な判断をファイルへ残します。

Q. Auto memoryとの違いは何ですか？

CLAUDE.mdは人が管理して共有する指示です。Auto memoryはClaude Codeがローカルに保存する学習メモです。チーム全員が守るコマンドや境界はCLAUDE.md、調査中に得た個人的な発見はAuto memoryと分けます。

Q. 最初は何を書けばよいですか？

インストール、テスト、buildの3コマンド、触ってはいけない領域、完了時の報告項目から始めます。実際の1タスクで不足した指示だけを次に足してください。

教材で自社用テンプレートを作る

CLAUDE.mdの構成を決めても、権限、テスト、引き継ぎまで別々に考えると運用が止まりやすくなります。自社リポジトリへ貼るチェックリストと演習をまとめて確認したい方は、ClaudeCodeLabの教材一覧から目的に合うものを選べます。

実際に試した結果

2026年7月22日に、この記事の check-claude-md.mjs を一時ファイルで実行しました。必須見出しを含む10行のサンプルでは終了コード0と合格メッセージを確認し、見出しを1つ削ってテスト用トークンを入れたサンプルでは終了コード1と3件の指摘を確認しました。

あわせて、コードの構文、記事内の公式URL、内部リンク、frontmatter、最後の見出し、主CTAが1つであることを確認しました。まず自分の CLAUDE.md に検査コードを実行し、出た指摘を直すところから始めてください。仕様の根拠はClaude Code公式のmemory、context window、settings、hooksを確認しています。