2026-03-26
Claude Code CLAUDE.mdの書き方 — AIへの業務マニュアル設計
CLAUDE.mdはClaude Codeへの業務マニュアル。ゴール・フォルダ構成・スキル一覧・禁止操作の4要素で、AIが毎セッション即戦力になる設計方法を解説。
3行で分かるこの記事
CLAUDE.mdはリポジトリのルートに置く「AIへの業務マニュアル」。ゴール・フォルダ構成・スキル一覧・禁止操作の4要素を書くだけで、Claude Codeが毎セッション即戦力になる。実際に136案件で使っている設計パターンを公開する。
CLAUDE.mdとは何か
Claude Codeはセッションが切れると全部忘れる。
136案件を回していると、1日に5〜10回セッションが切り替わる。そのたびに「この案件の状況は...」「このリポジトリでは...」と教え直すと、スイッチングコストだけで1日の時間が消える。
CLAUDE.mdは、この問題を解決するファイル。リポジトリのルートに置くと、Claude Codeが起動時に自動で読み込む。
~/dev/
├── CLAUDE.md ← ここに置く（全リポジトリ共通）
└── projects/
└── 051_A社/
└── 06_開発/
└── aipos/
└── CLAUDE.md ← プロジェクト固有も置ける
人間の新人マニュアルと同じ構造。 ただし人間は1回覚えれば忘れないが、AIは毎回読む必要がある。
最小構成: この4つだけ書く
CLAUDE.mdに書くべきは4つだけ。
1. ゴール
## ゴール
1人で、エージェント（Claude Code）を使いつつ、開発工程を回せるようになる
1行でいい。「このリポジトリで何をするか」が分かればいい。ゴールがないとCCは方向性を見失う。
2. フォルダ構成
## フォルダ構成
| パス | 説明 |
|------|------|
| `README.md` | ダッシュボード（人間用） |
| `CLAUDE.md` | このファイル（AI用） |
| `.claude/skills/` | スキル定義 |
| `projects/` | 案件群（.gitignore） |
CCは「どこに何があるか」を知らないと、関係ないファイルを読みに行って時間を浪費する。テーブル形式が見やすい。
3. スキル一覧
## スキル一覧
| スキル | やること |
|--------|----------|
| `/dev-init` | 案件フォルダ作成 |
| `/dev-minutes` | 文字起こし→議事録 |
| `/dev-followup` | フォローメール生成 |
使えるスキルと、その入出力を明示する。CCは一覧があると「この場面ではこのスキルを使えばいい」と判断できるようになる。
4. 禁止操作
## 禁止操作
- `rm -rf` / `git push --force` / `git reset --hard` / `sudo`
- プロジェクトルートに画像ファイルを保存しない
やってはいけないことを明示する。 これがないと、CCが善意で rm -rf したり、git push --force で履歴を壊したりする。
実践: 136案件で使っているCLAUDE.md
実際の構成はこう。最小構成の4つに加えて、運用で必要になったものを足している。
CLAUDE.md の全体構造
├── ゴール ← 1行
├── フォルダ構成 ← テーブル
├── スキル一覧 ← テーブル（40スキル分）
├── Skill vs Agent ← スキルとサブエージェントの違い
├── 案件フォルダ構成 ← 案件ごとのテンプレ
├── 詳細ドキュメント参照先 ← 外部ファイルへのポインタ
├── クイックリファレンス ← コマンド集
├── 禁止操作 ← 絶対にやってはいけないこと
├── 環境変数 ← 必要なキー一覧
├── GitHub運用ルール ← private必須、等
├── ポート割当ルール ← 案件番号ベース
├── 心得 ← 判断の指針
└── アクティブプロジェクト文脈 ← 今動いてる案件の概要
全部入りにしない
CLAUDE.mdが長すぎるとCCのコンテキストを圧迫する。コツは:
- 概要だけCLAUDE.mdに書く
- 詳細は別ファイルに分けて参照させる
## 詳細ドキュメント
| 参照先 | 内容 |
|--------|------|
| `.claude/config/guides/workflow.md` | 開発フロー |
| `.claude/config/guides/coding-rules.md` | コーディング規約 |
| `.claude/config/stacks/` | 技術スタック定義 |
CCは必要なときだけ参照ファイルを読みに行く。全部CLAUDE.mdに詰め込む必要はない。
スキル定義の書き方
スキルはCLAUDE.mdに一覧を書き、詳細は .claude/skills/{name}/SKILL.md に分離する。
CLAUDE.mdに書くこと（一覧）
| `/dev-minutes` | 文字起こし→議事録（VAT分析） |
1行で何をするか分かればいい。
SKILL.mdに書くこと（詳細）
---
description: 文字起こしから議事録を生成する
model: claude-opus-4-5-20251101
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
---
## 入力
- `01_文字起こし/` 配下のテキストファイル
## 出力
- `02_議事録/YYYY-MM-DD_会議名.md`
## 手順
1. 文字起こしファイルを読む
2. VAT分析で構造化する
3. 温度判定（A/B/C）を付ける
4. 議事録ファイルを出力する
入力・出力・手順の3点セット。 料理のレシピと同じ構造。
よくあるミス5つ
1. ゴールを書かない
CCが「何のためにこのリポジトリがあるか」を理解できない。コードレビューを頼んだのにリファクタリングを始める、といった暴走の原因になる。
2. フォルダ構成を書かない
CCが最初に find や ls で探索を始める。100ファイル以上あるリポジトリだと、それだけで30秒〜1分を浪費する。
3. 禁止操作を書かない
CCは善意でクリーンアップする。git push --force で履歴を消す。rm -rf node_modules でキャッシュを消す。「やってはいけない」を明示しないと、AIは最適と判断した操作を実行する。
4. CLAUDE.mdに全部詰め込む
500行超えるとコンテキストを圧迫する。概要をCLAUDE.md、詳細を別ファイルに分離する。
5. 更新しない
CLAUDE.mdが古いと、存在しないスキルを呼んだり、古いフォルダ構造を前提に動いたりする。案件構成やスキルが変わったら更新する。最終更新日を書いておくと、鮮度が分かる。
階層構造で管理する
プロジェクトが複数ある場合、CLAUDE.mdを階層的に配置する。
~/dev/
├── CLAUDE.md ← 全リポジトリ共通（スキル一覧、禁止操作、心得）
└── projects/
├── 051_A社/
│ └── 06_開発/
│ └── aipos/
│ └── CLAUDE.md ← プロジェクト固有（技術スタック、API、デプロイ先）
└── 072_B社/
└── 06_開発/
└── capaplanner/
└── CLAUDE.md ← プロジェクト固有
Claude Codeは起動時に、カレントディレクトリから上に向かってCLAUDE.mdを探す。プロジェクト固有 → 全体共通の順で読み込まれる。
心得セクションの設計
CLAUDE.mdの中で一番効くのが「心得」。
## 心得
- 雑な指示は雑な事故を呼ぶ
- 承認ゲートをスキップしない
- 集計値が合っていても詳細データは元データと照合する
→ AIが「加工・集約」を挟んだ数値はハルシネーションしやすい
心得はルールではなく判断の指針。「こうしろ」ではなく「こう考えろ」を書く。
実際にあった事故から生まれた心得:
- 「集計値が合っていても詳細を確認」→ AIが商品レベルで粗利率を+5pt水増しした実績から
- 「承認ゲートをスキップしない」→ CCが勝手にデプロイした事故から
心得は事故の教訓集。 先に書くのではなく、痛い目を見てから追加していく。
テンプレート
最小構成のテンプレートを置いておく。コピーして使える。
# プロジェクト名 CLAUDE.md
## ゴール
（1行でこのリポジトリの目的を書く）
## フォルダ構成
| パス | 説明 |
|------|------|
| `src/` | ソースコード |
| `docs/` | ドキュメント |
| `tests/` | テスト |
## スキル一覧
| スキル | やること |
|--------|----------|
| （使うスキルを列挙） | |
## コマンド
```bash
# テスト
npm test
# 開発サーバー
npm run dev
禁止操作
rm -rf/git push --force/sudo- （プロジェクト固有の禁止事項）
環境変数
| 変数名 | 用途 |
|--------|------|
| DATABASE_URL | DB接続 |
最終更新: YYYY-MM-DD
---
## FAQ
### Q. CLAUDE.mdとREADME.mdの違いは？
READMEは人間向け、CLAUDE.mdはAI向け。READMEにはプロジェクトの概要・セットアップ手順を書く。CLAUDE.mdにはAIが作業するために必要な情報（スキル一覧・禁止操作・フォルダ構成）を書く。
### Q. .claude/ ディレクトリは何？
Claude Codeの設定ディレクトリ。スキル定義（`.claude/skills/`）、サブエージェント（`.claude/agents/`）、設定（`.claude/config/`）を格納する。CLAUDE.mdはこのディレクトリの「目次」として機能する。
### Q. チーム開発でも使える？
使える。CLAUDE.mdをリポジトリにコミットすれば、チーム全員が同じAI設定で作業できる。個人設定は `.claude/settings.local.json` に分離する。
### Q. どのくらいの頻度で更新すべき？
スキルの追加・削除、フォルダ構成の変更、重大な事故があったとき。目安は月1〜2回。最終更新日を書いておくと鮮度を判断しやすい。
---
## 次に読む記事
- [AI駆動開発 完全ガイド](/articles/ai-driven-development-guide) — 全体像に戻る
- [40スキル作って毎日使うのは5つだけだった](/articles/five-skills-daily) — スキルの詳細
- [AI受託開発 1人で回す案件管理術](/articles/solo-ai-project-management) — フォルダ構造の実践