ankuro.dev
← ブログ一覧に戻る
【Claude Code中級編 #1】CLAUDE.mdを育てる——チームで使える指示書の作り方
2026-03-20#Claude Code#AI#CLAUDE.md

【Claude Code中級編 #1】CLAUDE.mdを育てる——チームで使える指示書の作り方

Claude Code基本操作シリーズでCLAUDE.mdの書き方は触れた。ファイルを作って、プロジェクトの概要やルールを書けば動く——それは間違いない。

ただ、「とりあえず書いた」CLAUDE.mdはすぐ限界が来る。チームに共有したとき機能しない、Claudeが思った通りに動かない、そのうち誰も更新しなくなる。

この記事では、個人用CLAUDE.mdをチームで長く使える指示書に育てる方法を整理する。

個人用CLAUDE.mdの限界

自分だけが使う前提で書いたCLAUDE.mdには、こんな問題が起きやすい。

① 暗黙の前提が多すぎる

自分には当然のことでも、他のメンバーには分からない前提が書かれていない。例えば「テストはvitest」と書いてあっても、ファイルの置き場所や命名規則が省略されていると、新しいメンバーが使ったときにClaudeが誤った実装をする。

② NG事項が書かれていない

「やってほしいこと」だけ書いて「やってほしくないこと」を書き忘れるパターン。Claudeは指示がなければ合理的と判断した方法を選ぶ。チームのコーディング規約と食い違う実装が出てくる原因になる。

③ メンテナンスされない

最初に書いたまま更新されない。プロジェクトが変化しているのにCLAUDE.mdが古いままで、内容が実態と乖離していく。

CLAUDE.mdのセクション設計

チームで機能するCLAUDE.mdには、以下の5つのカテゴリを揃えると安定する。

1. プロジェクト概要

何を作っているか、どんな構成かを簡潔に。Claudeが全体像を把握するための文脈として機能する。

## プロジェクト概要
Next.js App Router + TypeScriptで構築したブログサイト。
コンテンツはMarkdown（gray-matter）で管理し、Vercelにデプロイしている。

2. 技術スタック・環境

使っているライブラリ・フレームワーク・ランタイムを明記する。特に「なぜそれを使っているか」を添えると、Claudeが代替手段を勝手に選ばなくなる。

## 技術スタック
- フレームワーク: Next.js 14（App Router）
- 言語: TypeScript
- テスト: vitest（Jestに似た構文。テストファイルは __tests__ ディレクトリに置く）
- スタイリング: Tailwind CSS（CSS Modulesは使わない）

3. NG行動・制約

これが最も重要なセクション。Claudeが「合理的」と判断しても、チームの方針として避けたいことを明示する。

## やらないこと
- `any` 型を使わない。型が不明な場合は `unknown` を使う
- コメントを日本語で書かない（英語で統一）
- `console.log` をコミットに含めない
- ライブラリを勝手に追加しない。追加が必要な場合は提案してから待つ

4. よく使うコマンド

開発でよく使うコマンドをまとめておくと、Claudeが正確なコマンドを実行できる。

## コマンド
- 開発サーバー起動: `npm run dev`
- ビルド確認: `npm run build`
- テスト実行: `npm run test`
- 型チェック: `npm run type-check`

5. 外部リソース・参照先

ドキュメントのURL・設計書の場所・関連リポジトリなどを書いておく。Claudeがより正確な文脈でコードを生成できるようになる。

## 参照先
- デザインドキュメント: `design_document/` ディレクトリ
- API仕様: `docs/api.md`

良いCLAUDE.mdと悪いCLAUDE.mdの比較

悪い例

- TypeScriptで書いてください
- テストも書いてください
- きれいなコードにしてください
- コメントを書いてください

「〜してください」の羅列は曖昧すぎる。「きれいなコード」の定義はClaudeに委ねられるし、「コメント」が日本語か英語かも分からない。

良い例

## コーディング規約
- TypeScript strict モードで書く（`any` 禁止）
- 関数は最大50行。それ以上になりそうなら分割を提案する
- コメントは英語で書く。コメントで「何をしているか」は書かない。「なぜそうしているか」だけ書く
- vitest でユニットテストを書く。ファイル名は `*.test.ts`、`__tests__/` に置く

具体的な制約と理由がセットになっていると、Claudeは迷わずに従える。

育て方のサイクル

CLAUDE.mdは最初から完璧にならなくていい。以下のサイクルで育てていくのが現実的。

Claudeが思った通りに動かない
  ↓
なぜそうなったかを考える
  ↓
CLAUDE.mdに追記・修正する
  ↓
次回から期待通りに動く

追記のタイミングの目安

  • Claudeが同じ間違いを2回した → NGルールとして追記
  • 「いつもこう指示してる」と気づいた → CLAUDE.mdに書いて省略できるようにする
  • 新しいライブラリを導入した → 技術スタックセクションを更新する

Gitでバージョン管理しているなら、CLAUDE.mdの変更履歴がそのままチームの「Claudeへの学習記録」になる。コミットメッセージに変更の理由を書いておくと、なぜそのルールが生まれたか後から分かる。

階層構造の活用

プロジェクトが大きくなると、ルートのCLAUDE.mdだけでは管理しきれなくなる。Claude Codeは起動したディレクトリからルートに向かって階層をたどり、見つかったCLAUDE.mdをすべて読み込む仕組みになっている。

これを使うと、全体ルールと部分ルールを分離できる。

my-project/
├── CLAUDE.md           ← 全体共通のルール
├── frontend/
│   └── CLAUDE.md      ← フロント固有のルール（React・CSS等）
└── backend/
    └── CLAUDE.md      ← バックエンド固有のルール（Python・DB等）

ルートCLAUDE.md（全体共通）

## プロジェクト概要
フロントエンド（Next.js）とバックエンド（FastAPI）で構成されるWebアプリ。

## 共通ルール
- コミットメッセージはConventional Commits形式
- ブランチ名は `feature/xxx` または `fix/xxx`

frontend/CLAUDE.md（フロント固有）

## フロントエンド固有ルール
- コンポーネントはすべて `components/` に置く
- APIクライアントは `lib/api.ts` を経由する（直接fetchしない）
- スタイリングはTailwind CSSのみ。インラインスタイルは使わない

フロントエンドディレクトリで起動したClaude Codeには、全体ルール + フロント固有ルールの両方が読み込まれる。バックエンドで作業するときにフロントのルールが混入することもない。

チームへの展開

CLAUDE.mdをチームに展開するときに意識するポイント。

Gitでコミットする

CLAUDE.mdはプロジェクトスコープのファイルとしてGitにコミットする。チーム全員が同じ指示書を使える状態にする。

git add CLAUDE.md
git commit -m "docs: add CLAUDE.md for project context"

settings.jsonとの使い分け

CLAUDE.mdに書くのはコンテンツ・ルール系の指示。MCPサーバーやツールの許可設定は.claude/settings.json（projectスコープ）に書く。混在させると管理が煩雑になる。

何を書くか 場所
プロジェクトの概要・ルール・制約 CLAUDE.md
MCPサーバー設定・ツール権限 .claude/settings.json
個人の好み・APIキー .claude/settings.local.json（Gitignore）

レビュープロセスへの組み込み

CLAUDE.mdの変更もコードレビューの対象にする。「このルールを追加した理由」を明確にしてからマージする運用にすると、形骸化を防げる。

まとめ

  • 個人用CLAUDE.mdをチーム展開するには5セクション（概要・技術スタック・NG行動・コマンド・参照先）を揃える
  • 「〜してください」の羅列より、具体的な制約と理由のセットが効く
  • 「Claudeが迷ったらCLAUDE.mdに追記する」サイクルで育てていく
  • 大規模プロジェクトは階層構造で全体ルールと部分ルールを分離する
  • MCPサーバー設定・権限はsettings.jsonに分けて管理する

← 基本操作 #8：MCPサーバーの設定と活用 ｜ 中級編 #2：Hooksとは何か——Claude Codeの動作に割り込む →

← ブログ一覧に戻る