CLAUDE.mdの書き方完全ガイド：初心者でも失敗しない実務テンプレート

CLAUDE.mdは、Claude Codeに毎回同じ説明をしなくてよくするための「プロジェクトの説明書」です。ただし、何でも詰め込めば賢くなるわけではありません。

むしろ長すぎるCLAUDE.mdはコンテキストを圧迫し、重要な指示ほど守られにくくなります。公式ドキュメントでも、CLAUDE.mdは強制設定ではなく、セッション開始時に読まれる指示として扱われます。

この記事では、初心者でもそのまま使えるテンプレート、チームでの更新ルール、やってはいけない書き方、Obsidianや教材導線まで、実務で使える形に絞って整理します。

最初に理解する：CLAUDE.mdは強制設定ではない

公式仕様でまず押さえるべき点は、CLAUDE.md、Auto memory、settings、hooksを混同しないことです。CLAUDE.mdはClaudeに「こう振る舞ってほしい」と伝える文脈です。権限を本当に止めたい場合はsettingsやhooks、権限ルールを使います。

仕組み	役割	向いている内容
CLAUDE.md	人が書く永続指示	規約、構成、検証コマンド
Auto memory	Claudeが保存するローカル学習	デバッグ知見、好み、繰り返す発見
settings / permissions	クライアント設定と許可ルール	許可、拒否、追加ディレクトリ
hooks	固定タイミングで実行するコマンド	危険操作の停止、検証、自動整形

読み込み場所と優先順位を実務で考える

Claude Codeは起動した作業ディレクトリから親方向のCLAUDE.mdとCLAUDE.local.mdを読み、サブディレクトリのCLAUDE.mdはその場所のファイルを読んだときに追加されます。プロジェクト全員で共有する内容はリポジトリ直下、個人メモはCLAUDE.local.mdに分けるのが基本です。

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

常時メモリに置くもの、置かないもの

常時メモリに置くべきなのは、毎セッションで役立つ短い事実です。ビルドコマンド、テストコマンド、アーキテクチャの境界、命名規則、禁止事項、レビュー前チェックは向いています。逆に、長い設計議論、過去のログ、タスク固有の手順、秘密情報、古い意思決定の全部入りは向きません。

• 置く: ビルド、テスト、lint、型チェック、デプロイ前確認。
• 置く: 変更してよい境界、触ってはいけない境界、命名規則。
• 置かない: 秘密情報、長い議事録、過去ログ、今回だけの指示。
• 置かない: 公式docsの全文コピー。必要なURLと判断基準だけで十分。

コピペできるCLAUDE.mdテンプレート

以下はNext.jsやAPI開発の現場でそのまま試せるテンプレートです。重要なのは、Claudeが実行できるコマンド、守るべき境界、触ってはいけないものを短く書くことです。

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

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

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

importsと.claude/rules/の使い分け

CLAUDE.mdが大きくなったら、まず削るか、.claude/rules/でパスごとのルールに分けます。@docs/file.mdのimportは整理には便利ですが、読み込まれればコンテキストを消費します。トークン節約の手段ではない点に注意してください。

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

実例3つ：いつ効くのか

1. 新規参加者のオンボーディングでは、セットアップ手順よりも「どこに何があるか」「変更後に何を確認するか」を書くと効果が出ます。
2. バグ修正では、再現手順、ログの場所、テストの走らせ方を短く書くと、Claude Codeが余計な探索にコンテキストを使わずに済みます。
3. 記事制作やObsidian連携では、語調、内部リンク、公開前チェック、画像要件をCLAUDE.mdに置き、長いネタ帳はObsidian側に置くと運用が安定します。

失敗例と落とし穴

1. 失敗例1: 全READMEや議事録をimportしてしまい、毎回巨大な文脈を読み込む。解決策は、常時必要な5行だけをCLAUDE.mdに残し、詳細は必要時に読ませることです。
2. 失敗例2: 「きれいに書く」「いい感じに直す」のような曖昧な指示だけを書く。解決策は、npm run lint、src/api/**、default export禁止のように検証可能な形にすることです。
3. 失敗例3: セキュリティ上の禁止をCLAUDE.mdだけに書く。Claudeが従うとは限らないため、危険コマンドはpermissionsやPreToolUse hookで止めます。

チームでの更新ルール

運用では、CLAUDE.mdを「作って終わり」にしないことが重要です。Claude Codeが同じミスを2回したとき、レビューで毎回同じ指摘が出たとき、新しいテストコマンドが増えたときだけ更新します。

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

実務でCLAUDE.mdを設計する手順

最初から完璧なCLAUDE.mdを書こうとしないほうがうまくいきます。まずは既存プロジェクトでClaude Codeに小さな修正を頼み、どこで迷ったか、どのファイルを余計に読んだか、どの検証を忘れたかを観察します。その結果だけを短いルールにします。

たとえば、毎回 src/config.ts を見ずに環境変数を直接読みに行くなら「環境変数は src/config.ts 経由で参照する」と書きます。テストを毎回広く回して時間が溶けるなら「API変更時はまず該当specだけ実行し、最後に全体テスト」と書きます。観察から生まれたルールは守られやすく、机上の理想論より価値があります。

チーム運用では、CLAUDE.mdのPRに専用レビュー観点を置きます。新しいルールが既存ルールと矛盾しないか、実行可能なコマンドになっているか、個人の好みをチーム標準にしていないかを見ます。ここを雑にすると、数週間後にClaude Codeも人間も迷う設定ファイルになります。

もう一つ大事なのは、CLAUDE.mdを万能の引き継ぎ資料にしないことです。設計の背景や長い調査は別ドキュメントに置き、CLAUDE.mdには「次にどう動くべきか」だけを残します。Claude Codeは毎回そのファイルを読みます。毎回読む価値がない文章は、どれだけ正しくても常時メモリには向きません。

目安として、初期版は100行以内、育っても200行以内を目標にすると扱いやすいです。200行を超えたら、削る、rulesに分ける、docsに逃がす、skill化する、の順番で整理します。この整理そのものが、チームの開発手順を見直す良い機会になります。

実務で効くCLAUDE.mdは、読ませたい知識の量ではなく、減らせる確認往復の数で評価します。毎回「どのテストを回すべきですか」と聞かれるならコマンドを足す。毎回「このディレクトリは触っていいですか」と迷うなら境界を書く。逆に、誰も参照しない歴史説明は消します。改善は足し算より引き算のほうが効きます。

最後に、CLAUDE.mdは人間にも読まれる前提で書きます。Claude専用の呪文にせず、新しく入った人が読んでもプロジェクトの作法が分かる文章にします。AI向け設定と人間向けオンボーディングを兼ねられると、更新する理由が増え、ファイルが放置されにくくなります。

その意味では、CLAUDE.mdは小さな運用資産です。記事サイトなら公開前チェック、研修ビジネスなら問い合わせ導線、SaaS開発なら障害時の切り戻し手順まで、毎回の判断を安定させる短いルールだけを残します。

最初の1週間は、Claude Codeへの注意書きをチャットに書いたら、そのうち再利用しそうな一文だけをCLAUDE.md候補にします。週末に候補をまとめて見直し、本当に毎回必要なものだけ残すと、自然に強いファイルになります。

次に読むものと導線

知識ワークフローまで伸ばすなら、関連記事のClaude CodeとObsidian連携、日々の使い方はClaude Code生産性Tips、安全運用はClaude Code権限設定ガイドを合わせて読むとつながります。チーム導入や教材化は教材と相談ページから相談できます。

この記事で確認したこと

この記事では、公式のmemory、context window、settings、commandsページを確認し、CLAUDE.mdを強制設定として扱わない構成に直しました。テンプレートは実際のリポジトリでコピペしやすい粒度にし、秘密情報を入れない前提で整理しています。 Official references: memory, context window, settings, and commands.