ディレクトリツリーの一部にスポットライトが当たり、他のファイルがフェードアウトしている抽象イラスト

記事

Claude Codeに読ませる前に整えるプロジェクト構成：ディレクトリ・命名・除外設定の指針

Claude Codeに既存プロジェクトを読ませる前に、ディレクトリ設計・命名・参照ファイル選定・不要ファイルの除外をどう整えるかを公式情報に沿ってまとめます。CLAUDE.mdとパス指定ルール、`.claude/rules/`、claudeMdExcludesの使い分けまで実務目線で整理します。

結論：Claude Code向けの「読みやすい構成」は3層で考える

Claude Codeに既存プロジェクトを読ませる前に、ファイル構成を**「読ませたい層」「ときどき読ませる層」「読ませたくない層」の3つに分けて整える**と、依頼の精度が大きく変わります。

読ませたい層: ルートCLAUDE.mdから@参照する、毎セッション必須の文書とコード
ときどき読ませる層: サブディレクトリのCLAUDE.mdや.claude/rules/に置き、必要時だけロード
読ませたくない層: ビルド成果物・自動生成・古い試作で、.gitignore／claudeMdExcludes／設定で隠す

公式のHow Claude remembers your projectでは、CLAUDE.mdとサブディレクトリのCLAUDE.md、.claude/rules/がどう読み込まれるかが詳しく説明されています。本記事はその仕様をプロジェクト整理の指針に落とし込む内容です。

CLAUDE.mdそのものの書き方はCLAUDE.mdの書き方で扱っているので、本記事はディレクトリ構造・命名・参照経路にフォーカスします。

なぜ「整える」必要があるのか

Claude Codeのコンテキストは、ファイルを読むたびに消費されていきます。公式のBest Practicesも**「context window holds your entire conversation, including every message, every file Claude reads, and every command output」**と明記しており、読む必要のないファイルを読ませないことが精度に直結します。

整っていないプロジェクトでは、次のような無駄が発生します。

1つの仕様を確認するために、似た名前のファイルを5つ読む
古い試作のbackup/配下まで読みに行ってしまう
ビルド成果物のdist/を「コード」と誤認して読み始める
親ディレクトリのCLAUDE.mdに他チームのルールが混ざっていて指示がブレる

これらはプロジェクト構成側を整えれば消せる無駄なので、Claude Codeを本格運用する前にまず手当てしておきます。

ディレクトリ設計の原則

1. ルート直下を意味で割る

ルート直下は**「読めば全体像が分かる単位」**で割ります。フレームワークの慣例（src/, tests/, docs/など）は素直に踏襲した上で、内部はドメイン単位を優先するのが現実的です。

your-project/
├── CLAUDE.md            # プロジェクト指示
├── README.md            # 人間向け概要
├── package.json
├── src/
│   ├── api/             # 外部に公開するエンドポイント
│   ├── components/      # UIコンポーネント
│   ├── domain/          # ビジネスロジック（フレームワーク非依存）
│   ├── lib/             # 横断的ユーティリティ
│   └── styles/
├── tests/               # 統合テスト
├── scripts/             # ビルド・運用スクリプト
└── docs/                # 設計メモ・ADR

ポイントは**src/lib/に何でも入れない**ことです。Claudeは「lib」を見ると「共通系」と扱い、関連ファイルを巻き込みやすくなります。ドメイン固有のロジックはsrc/domain/へ、再利用前提の薄いユーティリティだけsrc/lib/へ、という分担が読み取りやすい構造です。

2. ファイル名は「責務」で書く

Claudeはファイル名から内容を推測して読むかどうかを決めることがあります。次のような命名は読み解きの精度を下げます。

避けたい命名	推奨
`utils.ts`	`format-date.ts` / `parse-yen.ts`
`helpers.ts`	`email-validator.ts`
`index.ts`に全部	公開エントリだけ`index.ts`、本体は意味のある名前
`_old.ts` / `backup.ts`	そもそも消すか`archive/`へ移してCLAUDE.mdから除外

「責務が1ファイル名に書けない」場合は、ファイル自体が大きすぎるサインなので分割を検討します。

3. テストは対称配置で

テストは実装ファイルと対称構造で置くと、Claudeが「この実装を直す→対応するテストを直す」を自動的に紐づけやすくなります。

src/services/order/create-order.ts
tests/services/order/create-order.test.ts

VitestやJestなど標準的なテストランナーで*.test.tsパターンを使っていれば、Claudeはほぼ確実にこの対応を理解します。

CLAUDE.mdとパス指定ルールの併用

公式ドキュメント記載のCLAUDE.md配置先は次のとおりです。

場所	スコープ
`./CLAUDE.md` または `./.claude/CLAUDE.md`	プロジェクト共通（チーム共有）
`./CLAUDE.local.md`	自分専用（`.gitignore`推奨）
`~/.claude/CLAUDE.md`	全プロジェクト共通の個人設定
親ディレクトリの`CLAUDE.md`	起動時に全文ロード
子ディレクトリの`CLAUDE.md`	そのサブツリーを読むときに自動ロード

ルートのCLAUDE.mdは200行未満を目安にし、内容が増えたら.claude/rules/へ移すのが推奨パターンです。.claude/rules/は**pathsフロントマター**で対象ファイルを限定できるため、Claudeが該当ファイルを開いたときだけそのルールを読む形にできます。

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

# API Development Rules
- 入力検証は必ずzodで行う
- レスポンスは標準のエラー形式を使う
- OpenAPIコメントを書く

ルート全体に効かせたいルール（命名、PR運用、禁止事項）はCLAUDE.mdへ、特定ディレクトリだけのルールは.claude/rules/<topic>.mdへ、と置き場所を分けると、コンテキストの肥大化を防げます。

「読ませたくない層」の作り方

Claude Codeに読ませたくないファイルは、3段の防御で隠します。

1. .gitignoreで物理的に隔離

.gitignoreに入っているファイルは、@参照や明示指定をしない限り基本的に読まれません。ビルド成果物、ログ、ローカル環境変数は確実に.gitignoreへ。

# .gitignore
dist/
build/
.next/
coverage/
.env
.env.local
*.log
.DS_Store

2. .claudeignore相当はclaudeMdExcludesで

公式設定のclaudeMdExcludesは、親ディレクトリのCLAUDE.mdを除外するためのものです。モノレポで他チームのCLAUDE.mdが効きすぎる場合に使います。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

.claude/settings.local.jsonに書けば、自分のローカルだけに効きます。チームとしては.claude/settings.jsonに、組織共通はマネージド設定で配るのが筋です。

3. CLAUDE.mdに「読まないでほしい場所」を書く

.gitignoreにもCLAUDE.md除外にも該当しない、**「Gitに入っているけど読ませたくない場所」**は、CLAUDE.mdに明示します。

## 触らない／読まないディレクトリ
- archive/ — 古い実装。参照不要。タスクで「archiveを参考に」と言われない限り読まない
- vendor/ — 外部由来の固定コード。修正・読み込みは禁止
- public/legacy/ — 旧UIアセット。新規実装では参照しない

これは強制ではなく行動指針ですが、Claudeに「読まなくていい」と明言しておくと、無駄なファイル読みを抑制できます。

参照経路を「`@`」で固定する

Claudeに毎セッション必ず読んでほしい資料は、CLAUDE.mdから@参照で固定します。公式仕様では最大5階層まで再帰的にimportできます。

## プロジェクト概要
@docs/architecture.md

## API規約
@docs/api-conventions.md

## デザイン原則
@docs/design-principles.md

ただし、@参照したファイルは起動時に全文ロードされてコンテキストを食うため、「全ての依頼で必要な内容」だけを入れるのが基本です。タスク特化の手順書は、サブディレクトリのCLAUDE.mdや.claude/rules/の方が向きます。

/initで現状を可視化する

公式は、既存プロジェクトではまず/initを走らせることを推奨しています。/initはビルドシステム・テストフレームワーク・既存の規約を解析し、CLAUDE.mdの叩き台を作ります。

claude

セッション内で次のように打つと初期生成が始まります。

/init

既にCLAUDE.mdがある場合、/initは上書きせず改善提案を行います。CLAUDE_CODE_NEW_INIT=1を有効にした上で動かすと、サブエージェントを使って多段で対話的に整える新フローも使えます。

/initの出力は鵜呑みにせず、**「200行を超えていないか」「具体的か」「自プロジェクト固有か（一般論でないか）」**の3点で見直してから採用します。

チェックリスト：Claude Code導入前の最終確認

ルート直下のディレクトリが意味で割れている（lib一辺倒になっていない）
ファイル名が責務で読める（utils.ts／helpers.tsを使っていない）
テストが実装と対称配置になっている
ルートCLAUDE.mdが200行未満で、ドメイン特有ルールは.claude/rules/へ移してある
.gitignoreが広めで、ビルド成果物と環境ファイルが入っていない
読ませたくないGit追跡ファイルはCLAUDE.mdに明記してある
archive/やbackup/の類は消すか別レポジトリへ移動されている
親ディレクトリ／モノレポの不要なCLAUDE.mdはclaudeMdExcludesで外してある
/initで叩き台を作り、人間が削って整えてある

ここまで整えてからClaude Codeに本格的なタスクを依頼すると、**「ファイル探しに無駄なターンが消えた」「指示の通りが体感で良くなった」**といった効果が出やすくなります。

次に読む

Claude Codeで最初に作るべきCLAUDE.mdの書き方 — CLAUDE.md本体の書き方と最小テンプレート
Claude Codeに大きなタスクを渡す前の分解方法 — 整えた構成の上で大きなタスクを安全に分解する手順
Claude Codeに伝わるプロンプトの基本構造 — 整えた構成を依頼文でどう参照するか

管理人

編集者 / オーナー