MENU
  1. ホーム
  2. Claude Code
  3. Claude CodeのCLAUDE.md設計 — チーム開発ルールを統一する仕組み

Claude CodeのCLAUDE.md設計 — チーム開発ルールを統一する仕組み

Claude Code
Claude CodeのCLAUDE.md設計 — チーム開発ルールを統一する仕組み | mohablog

Claude Codeをチームで導入したとき、最初にぶつかったのが「人によって生成されるコードが全然違う」という問題でした。あるメンバーはテストも型ヒントもきっちり書かせるのに、別のメンバーはそこを省略する。命名規則もバラバラ。プルリクエストのレビューで毎回同じ指摘を繰り返すことになり、これではClaude Codeを導入した意味が半減してしまいます。

この問題を根本から解決するのがCLAUDE.mdという設定ファイルです。この記事では、CLAUDE.mdの仕組みと設計方法、チーム開発で効果を出すためのベストプラクティスを具体例付きで解説します。

目次

CLAUDE.mdとは何か

Claude Codeの動作を決める設定ファイル

CLAUDE.mdは、Claude Codeがプロジェクトのコンテキストを理解するための設定ファイルです。プロジェクトのルートディレクトリに配置しておくと、Claude Codeが起動時に自動で読み込み、以降のすべての操作にルールが反映されます。

公式ドキュメントによると、CLAUDE.mdには以下のような内容を記述できます。

  • コーディングスタイルや命名規則
  • 使用するフレームワークやライブラリの指定
  • テスト方針やCI/CDとの連携ルール
  • 禁止操作（破壊的コマンドの制限など）
  • プロジェクト固有の用語やドメイン知識

イメージとしては、.editorconfigがエディタの振る舞いを統一するように、CLAUDE.mdはClaude Codeの振る舞いを統一する役割を担います。

配置場所と読み込みの優先順位

CLAUDE.mdは複数の場所に配置でき、それぞれスコープが異なります。

配置場所スコープ用途
~/.claude/CLAUDE.mdユーザー全体個人の好み（応答言語、文体など）
プロジェクトルート/CLAUDE.mdプロジェクト全体チーム共通のルール
サブディレクトリ/CLAUDE.md特定ディレクトリモジュール固有のルール

Claude Codeはこれらを階層的にマージして読み込みます。チームで共有するルールはプロジェクトルートのCLAUDE.mdに書くのが基本です。個人設定（応答言語の好みなど）はホームディレクトリの方に書けば、プロジェクトルールと分離できます。

CLAUDE.mdがないとどうなるか

ありがちな失敗パターン

CLAUDE.mdを用意せずにチームでClaude Codeを使うと、以下のような問題が起きがちです。

# メンバーAが生成させたコード
def getUserData(userId):
    result = db.query(f"SELECT * FROM users WHERE id = {userId}")
    return result

# メンバーBが生成させたコード
def get_user_data(user_id: int) -> dict[str, Any]:
    stmt = select(User).where(User.id == user_id)
    return session.execute(stmt).scalar_one()

同じプロジェクトなのに:
- 命名規則: camelCase vs snake_case
- 型ヒント: なし vs あり
- SQLの書き方: 文字列結合（SQLインジェクションリスクあり） vs ORM
すべてが異なっている

Claude Codeは指示がなければ「それっぽいコード」を生成します。メンバーそれぞれの質問の仕方や好みに引きずられるため、チーム全体でスタイルが統一されません。

レビューコストの増大

スタイルの不統一はレビューコストに直結します。本来ロジックの正しさに集中すべきレビューで、「ここはsnake_caseにしてください」「型ヒントを付けてください」といった形式的な指摘が大量に発生する。こうした指摘はCLAUDE.mdでルールを定義しておけば最初から統一されたコードが生成されるため、本来は発生しなくて済むコストです。

CLAUDE.mdの基本構成と書き方

最小構成で始める

最初から完璧なCLAUDE.mdを書こうとすると挫折します。まずは最小構成から始めるのがおすすめです。

# プロジェクト概要

PythonのFastAPIで構築されたREST APIサーバー。
データベースはPostgreSQL、ORMはSQLAlchemy 2.0を使用。

# コーディングスタイル

- 命名規則はsnake_caseを使用する
- すべての関数に型ヒントを付ける
- docstringはGoogle Styleで記述する

# テスト

- テストフレームワークはpytestを使用する
- 新しい関数を追加したら、対応するテストも必ず書く

この最小構成だけでも、Claude Codeの生成結果は大きく変わります。
命名規則、型ヒント、テスト方針の3つが揃えば
チーム内のコード品質はかなり安定します。

調べてみたところ、CLAUDE.mdのファイルサイズに明確な上限はありませんが、長すぎるとClaude Codeのコンテキストウィンドウを圧迫します。500行以内を目安にするのが現実的です。

セクション設計のポイント

CLAUDE.mdはMarkdown形式で書きます。効果的なセクション構成は以下のとおりです。

  • プロジェクト概要: 技術スタック、アーキテクチャの概要を簡潔に
  • コーディングスタイル: 命名規則、フォーマット、インポート順序
  • テスト方針: フレームワーク、カバレッジ基準、モックの方針
  • 禁止事項: やってはいけないことを明確に
  • コマンド: ビルド、テスト、デプロイのコマンド

ここで重要なのが、「なぜそのルールなのか」を書かないことです。CLAUDE.mdは人間向けのドキュメントではなく、Claude Code向けの指示書です。理由を長々と書くとコンテキストを無駄に消費するため、ルールだけを端的に記述しましょう。理由を残したい場合はADR（Architecture Decision Record）やREADMEに分離するのがベターです。

チーム開発で効果が出るCLAUDE.mdの設計例

コーディング規約の統一

以下は、Pythonプロジェクト向けのCLAUDE.md設計例です。

# コーディングスタイル

- 命名規則: snake_case（クラス名のみPascalCase）
- 型ヒント: すべての関数の引数と戻り値に必須
- インポート順序: 標準ライブラリ → サードパーティ → ローカル
- 文字列: f-stringを使用する（.formatは使わない）
- エラーハンドリング: 裸のexceptは禁止。具体的な例外クラスを指定する

# 禁止事項

- printデバッグは使わない。loggingモジュールを使用する
- グローバル変数は使用しない
- SQLを文字列結合で組み立てない（SQLインジェクション防止）
- requirements.txtを直接編集しない。pyproject.tomlで管理する

上記ルールを設定した場合のClaude Code出力例:

import logging
from datetime import datetime

from fastapi import HTTPException
from sqlalchemy import select

from app.models import User

logger = logging.getLogger(__name__)

def get_active_users(since: datetime) -> list[User]:
    stmt = select(User).where(
        User.last_login >= since,
        User.is_active == True
    )
    return list(session.execute(stmt).scalars())

CLAUDE.mdにルールを書いておくだけで、インポート順序、型ヒント、ロガーの使用がすべて統一されたコードが生成されます。メンバーごとにプロンプトで指示する必要はありません。

テスト方針とCIの連携設定

テストに関するルールも重要です。「どこまでテストを書くか」の基準をCLAUDE.mdで明確にしておくと、テスト不足やテスト過剰を防げます。

# テスト

- フレームワーク: pytest
- テストファイルの配置: tests/ ディレクトリにミラー構造で配置
- モック: unittest.mockを使用。外部APIコールは必ずモックする
- データベーステスト: テスト用のSQLiteを使用（本番はPostgreSQL）
- カバレッジ: 新規コードは80%以上を目標とする

# コマンド

- テスト実行: pytest tests/ -v
- カバレッジ確認: pytest --cov=src tests/
- 型チェック: mypy src/
- リント: ruff check src/

コマンドセクションの効果:
Claude Codeに「テストを実行して」と指示すると
→ pytest tests/ -v が実行される（正しいコマンドを覚えてくれる）

コマンドセクションがないと
→ python -m pytest や pytest --verbose など、
  毎回微妙に異なるコマンドが使われる

禁止操作を明記する

Claude Codeは強力なツールですが、チーム開発では意図しない操作のリスクもあります。禁止事項を明確に定義しておきましょう。

# 禁止事項

- git push --forceは絶対に使わない
- mainブランチに直接コミットしない
- .envファイルや認証情報を含むファイルをコミットしない
- 明示的な指示なしにデータベースのテーブルをDROPしない
- node_modulesや.venvをコミットしない

公式ドキュメントを調べてみると、CLAUDE.mdの禁止事項はClaude Codeの行動を制約する「ソフトガード」として機能します。より強固な制御が必要な場合は、settings.jsonのdeny設定と組み合わせるのが効果的です。

CLAUDE.mdの階層構造を活用する

グローバル設定とプロジェクト設定の分離

CLAUDE.mdは複数の階層に配置できるため、個人の好みとチームのルールを分離して管理できます。

~/.claude/CLAUDE.md          <- 個人設定（応答言語、好みのスタイル）
project-root/
+-- CLAUDE.md                 <- プロジェクト共通ルール（Git管理対象）
+-- backend/
|   +-- CLAUDE.md             <- バックエンド固有のルール
+-- frontend/
|   +-- CLAUDE.md             <- フロントエンド固有のルール
+-- infra/
    +-- CLAUDE.md             <- インフラ固有のルール

グローバル設定（~/.claude/CLAUDE.md）にはGit管理の対象外となる個人の設定を書きます。

# ~/.claude/CLAUDE.md の例

# 応答言語
- すべての説明と回答は日本語で提供する
- コードコメントも日本語で記述する

# コミット
- 明示的に依頼されない限りgit commitは行わない

モノレポでの活用パターン

バックエンド（Go）とフロントエンド（TypeScript）で技術スタックが異なるモノレポ構成では、サブディレクトリごとにCLAUDE.mdを分けるのが効果的です。

# backend/CLAUDE.md

## 技術スタック
- 言語: Go 1.22
- フレームワーク: Echo v4
- ORM: GORM
- テスト: go test + testify

## コーディングスタイル
- エラーは必ず呼び出し元に返す（panicは使わない）
- インターフェースはコンシューマ側で定義する
- 構造体のフィールドにはjsonタグを必ず付ける

# frontend/CLAUDE.md

## 技術スタック
- 言語: TypeScript 5.4
- フレームワーク: Next.js 14 (App Router)
- スタイリング: Tailwind CSS
- テスト: Vitest + Testing Library

## コーディングスタイル
- コンポーネントは関数コンポーネントで記述する
- 状態管理はReact Server Componentsを優先する
- anyは使用禁止。unknownを使う

このように分離しておくと、バックエンドのディレクトリで作業するときはGoのルール、フロントエンドで作業するときはTypeScriptのルールが自動的に適用されます。ルートのCLAUDE.mdにはプロジェクト全体に適用される共通ルール（コミットメッセージのフォーマットなど）だけを書きます。

チームでCLAUDE.mdを運用するポイント

CLAUDE.mdをGitで管理してレビュー対象にする

CLAUDE.mdはプロジェクトのコードと同じく、Gitでバージョン管理してプルリクエストのレビュー対象にするのが鉄則です。

git add CLAUDE.md
git commit -m "CLAUDE.md: テストカバレッジ基準を80%に設定"
git push origin feature/update-claude-md

プルリクエストのタイトル例:
「CLAUDE.md: テストカバレッジ基準を追加」
「CLAUDE.md: SQLAlchemy 2.0スタイルに移行する旨を追記」
「CLAUDE.md: ruffのルール設定を追加」

.editorconfigや.eslintrcの変更と同じ感覚で、チームの合意のもとにルールを更新していくのが理想です。

段階的に育てるアプローチ

最初から網羅的なCLAUDE.mdを書こうとすると、メンテナンスが大変になります。以下のステップで育てるのがおすすめです。

  • ステップ1: プロジェクト概要と技術スタックだけを書く（5分で完了）
  • ステップ2: コードレビューで繰り返し指摘されるポイントをルールとして追加する
  • ステップ3: チームでふりかえりを行い、ルールの過不足を見直す
  • ステップ4: settings.jsonのHooks設定と連携させて自動チェックを組み込む

特にステップ2が重要です。レビューで「ここはこう書いてほしい」と毎回指摘しているポイントは、CLAUDE.mdに書くべきルールの候補。指摘をルール化することで、レビュー負荷が徐々に下がっていきます。

アンチパターン集

CLAUDE.md運用でよく見かける失敗パターンも紹介します。

# アンチパターン: ルールの理由を長々と書く

## コーディングスタイル
- snake_caseを使用する
  理由: PEP 8ではsnake_caseが推奨されており、
  Python公式のスタイルガイドに準拠することで
  サードパーティライブラリとの一貫性が保たれ...
  （この説明だけで100文字以上消費してしまう）

# 改善版: ルールだけを端的に書く

## コーディングスタイル
- 命名規則: snake_case（クラス名のみPascalCase）
- PEP 8に準拠する

CLAUDE.mdはClaude Codeへの指示書であり、人間向けのドキュメントではありません。理由や背景を残したければ、ADR（Architecture Decision Record）に書いてCLAUDE.mdからは参照だけするのが良い方法です。

settings.jsonとの連携で安全性を高める

permissionsで実行制御を補完する

CLAUDE.mdはClaude Codeへの「ガイドライン」ですが、settings.jsonのpermissionsは「ハードブロック」です。両者を組み合わせることで、柔軟性と安全性を両立できます。

{
  "permissions": {
    "allow": [
      "Bash(pytest *)",
      "Bash(ruff *)",
      "Bash(mypy *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(docker rm *)"
    ]
  }
}

CLAUDE.md  → 「pushする前にテストを実行してください」（ガイドライン）
settings.json → 「rm -rfは実行不可」（ハードブロック）

この二段構えで、安全性と柔軟性を両立できます。

Hooks機能との組み合わせ

settings.jsonのHooks機能を使うと、Claude Codeの特定のアクション前後にスクリプトを自動実行できます。CLAUDE.mdでルールを定義し、Hooksで自動チェックを走らせる組み合わせは非常に強力です。

{
  "hooks": {
    "PreCommit": [
      {
        "command": "ruff check --fix . && mypy src/",
        "description": "コミット前にリントと型チェックを実行"
      }
    ]
  }
}

CLAUDE.mdで「ruffとmypyを通すこと」と記述し、Hooksで実際にコミット前チェックを走らせる。ルール違反のコードがリポジトリに混入するのを自動で防げます。関連トピックとして「Claude CodeのHooks機能を活用した開発自動化」もあわせて参考になります。

まとめ

CLAUDE.mdの設計と運用について、主要なポイントを振り返ります。

  • CLAUDE.mdはClaude Codeの動作を統一する設定ファイルであり、チーム開発では必須のアーティファクト
  • 配置場所は3階層（ユーザー、プロジェクト、サブディレクトリ）あり、スコープに応じて使い分ける
  • 最小構成（概要 + コーディングスタイル + テスト方針）から始め、レビューの指摘をルール化して育てる
  • ルールだけを端的に書く。理由や背景はADRなど別ドキュメントに分離する
  • settings.jsonのpermissionsやHooksと組み合わせて、ガイドラインとハードブロックの二段構えで運用する
  • CLAUDE.mdはGitで管理してレビュー対象にする。チームの合意を得てからルールを追加する

よくある質問（FAQ）

Q. CLAUDE.mdはどのくらいの頻度で更新すべきですか?

明確な頻度の目安はありませんが、コードレビューで同じ指摘が2回以上発生したタイミングが更新のサインです。スプリントのふりかえりでCLAUDE.mdの見直しをアジェンダに入れているチームもあります。逆に、あまり頻繁に変更するとClaude Codeの出力が安定しなくなるため、週1回程度のペースに留めておくのが良いと思います。

Q. CLAUDE.mdが長くなりすぎた場合はどうすればいいですか?

500行を超えてきたら、コンテキストウィンドウの圧迫を心配すべきタイミングです。まずサブディレクトリのCLAUDE.mdに分割することを検討してください。バックエンド固有のルール、フロントエンド固有のルールをそれぞれのディレクトリに移すだけで、ルートのCLAUDE.mdはかなり軽量になります。また、使われていない古いルールの棚卸しも定期的に行うのが効果的です。

Q. 個人のCLAUDE.mdとプロジェクトのCLAUDE.mdが矛盾したらどちらが優先されますか?

Claude Codeは階層的にCLAUDE.mdを読み込みますが、プロジェクトルートのCLAUDE.mdが優先されます。個人設定で「コメントは英語で」と指定していても、プロジェクトのCLAUDE.mdに「コメントは日本語で」と書かれていれば、プロジェクトのルールが適用されます。個人のCLAUDE.mdには、プロジェクトルールと衝突しにくい設定（応答言語やコミットの確認方針など）を書いておくのがベストです。

Claude Code
AI開発 Claude Code 設計パターン
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

目次