【Claude Code】CLAUDE.mdとフォルダ構成でClaude Codeの自律性を引き出す

データ事業本部の川中子（かわなご）です。

突然ですが、みなさんはどのような環境でClaude Codeを動かしていますか？
Claude Codeを動かすための環境について考えたことはありますか？

私は日頃Claude Codeを使う中で、使い勝手の不便を解決しながら、
Claude Codeを動かしやすい環境を少しずつ整理してきました。

特に複数のリポジトリや大量のドキュメントが関わるタスクでは、
Claude Codeを実行する環境が作業効率に大きく影響します。

今回は私なりのClaude Codeの実行環境の工夫をまとめてみました。

私のバッドプラクティス

今までClaude Codeを利用する際は基本的に、個別のリポジトリや、
タスクごとに作成したフォルダでClaude Codeを起動していました。

cd ~/project/repositories/repo-a
claude

ただこの方法ではプロジェクト内の資材を横断するような作業が難しく、
特に以下のような場面で課題を感じていました。

他リポジトリとの整合性チェック

複数のリポジトリが存在するプロジェクトにおいては、
リポジトリ間での整合性を保つ必要がある場面が頻繁にあると思います。

私はリポジトリ単位でClaude Codeを起動してしまっていたため、
他リポジトリとの整合性チェックなどを行なう場合は、
都度、直接フォルダパスを指定する形で作業を指示していました。

都度ユーザーから明示的に指示することで作業自体は可能ですが、
Claude Code自身に自律的に探索させることは不可能なので不便でした。

関連ドキュメントの特定

資材の更新が発生した際には、関連ドキュメントの修正も必要になります。

普段の業務では、設計書などのドキュメントはBacklogで管理することが多く、
資材修正の影響があるドキュメントを特定すること自体がとても手間でした。

膨大なドキュメントをローカルに同期して保存もしていましたが、
都度Claude Codeに探させるにはトークンの消費量が多くなってしまい、
また自分自身で探すにも、影響箇所を正確に把握するのは難しい状況でした。

フォルダ構成の整理

前述のような課題を踏まえ、今は以下のようなフォルダ構成になりました。

project/
├── CLAUDE.md              # ★プロジェクト全体のコンテキスト
├── .claude/               # Claude Code設定
│   ├── settings.local.json
│   └── skills/
├── documents/             # ドキュメント群
│   ├── document-index.md  # ★ドキュメントインデックス
│   ├── document-a.md
│   ├── document-b.md
│   └── ...
├── repositories/          # Gitリポジトリ群
│   ├── repo-a/
│   │   ├── CLAUDE.md
│   │   └── ...
│   ├── repo-b/
│   │   ├── CLAUDE.md
│   │   └── ...
│   └── ...
├── tasks/                 # タスク単位の作業フォルダ
│   ├── done_tasks/        # 完了済みタスク
│   ├── TASK-a/
│   ├── TASK-b/
│   └── ...
└── others/                # その他

ドキュメント、リポジトリ、タスク用のフォルダを作って資材をまとめ、
プロジェクトのルートにCLAUDE.mdを配置しています。

関連する情報をプロジェクトフォルダ配下に整理し、
基本的にはプロジェクトルートでClaude Codeを起動することで、
スムーズにプロジェクト内の情報にアクセスしやすくなっています。

ただClaude Code自身が自律的に探索できるようにするには、
フォルダ構造や起動場所だけでは十分ではありません。

ポイントはプロジェクト資材全体の見取り図を作ることです。

Claude Codeに見取り図を渡す

CLAUDE.mdの運用方法

プロジェクトルートのCLAUDE.mdには、配下資材の概要を記載しておきます。
Claude Codeは起動時にこのCLAUDE.mdを読み込むことで、
必要に応じて関連する資材を自律的に探しに行けるようになります。

以下はプロジェクトルートのCLAUDE.mdの記載例です。
下記以外にはプロジェクトの概要やルール、テスト手順などを記載しています。

## ディレクトリ構成

| ディレクトリ | 説明 |
|-------------|------|
| `repositories/` | Gitリポジトリ群 |
| `documents/` | プロジェクトドキュメント。`document-index.md`にキーワードタグ付きのインデックスがある |
| `tasks/` | タスク単位の作業ディレクトリ。完了後は`done_tasks/`に移動する |

## リポジトリ

| リポジトリ | 説明 |
|-----------|------|
| `repo-a/` | アプリケーションコード。Python + FastAPI |
| `repo-b/` | Terraformによるインフラ定義。AWSのリソースを管理 |

なお子フォルダに配置したCLAUDE.mdは起動時には読み込まれず、
Claude Codeがそのフォルダ内の資材を利用する際に初めて読み込まれます。

https://docs.anthropic.com/en/docs/claude-code/memory

ドキュメントインデックスの作成

プロジェクトのドキュメントが数十〜数百ファイルに及ぶ場合、
セッションごとにClaude Codeに全て探索させてしまうと、
コンテキストウィンドウを大きく消費してしまいます。

ドキュメントはただローカルに保存してあるだけでは活用が難しいため、
CLAUDE.mdと同じ考え方でドキュメントのインデックスを作成しています。

Claude Codeはまずこのドキュメントのインデックスファイルを読み込み、
キーワードから必要なドキュメントを自律的に特定できるようになります。

以下はdocument-index.mdの記載例です。

# ドキュメントインデックス

機能改修時に修正対象のドキュメントを特定するためのインデックス。
各ドキュメントに関連するキーワードをタグとして付与している。

## 環境定義

| ドキュメント | 概要 | タグ |
|-------------|------|------|
| `010-環境定義/011-システム構成.md` | データ基盤の全体システム構成図と接続設計 | `システム構成`, `AWS`, `VPC`, `S3` |
| `010-環境定義/012-環境定義.md` | 開発・本番環境の定義とAWSアカウント情報の整理 | `環境定義`, `開発環境`, `本番環境`, `S3`, `RDS` |

## 開発標準

| ドキュメント | 概要 | タグ |
|-------------|------|------|
| `030-開発標準/031-命名規則.md` | AWSサービスリソースの命名規則 | `命名規則`, `S3`, `IAM`, `Lambda`, `Glue` |
| `030-開発標準/032-共通設計/Glueジョブ作成標準.md` | AWS Glue Sparkジョブの開発方針・設定値の標準定義 | `Glue`, `Spark`, `ETL`, `Iceberg` |

処理の流れとしては以下のようなイメージです。

• 指示：
  • 「Glueジョブの設定を修正したので、影響のあるドキュメントを修正して」
• 処理の流れ
  1. CLAUDE.mdのディレクトリ構成からdocuments/配下にドキュメントがあることを認識
  2. document-index.mdを読み込み、Glueタグのあるドキュメントを特定
  3. 030-開発標準/032-共通設計/Glueジョブ作成標準.mdだけを読み込んで修正

都度ゼロから関連するドキュメントを網羅的に探索しなくても、
インデックスを経由してコンテキストの消費を大幅に抑えられます。

なおdocument-index.md自体もClaude Codeで作成しています。
定期的にbacklog-exporterでドキュメントを更新して、
そのタイミングでインデックスファイルも更新をかけています。

さいごに

Claude Codeを複数リポジトリ・大量ドキュメントのプロジェクトで
効果的に活用するためのフォルダ構成について紹介しました。

• CLAUDE.mdに配下資材の概要を記載する
• ドキュメントのインデックス(document-index.md)を作る

CLAUDE.mdもdocument-index.mdもやっていることは同じです。
プロジェクトルートを起点にClaude Codeが自律的に動けるように、
資材の見取り図を情報として用意しておくということです。

フォルダ構成はプロジェクトによって最適解が変わりますが、
根本的な考え方はどのプロジェクトでも同じになると考えています。

この環境が整ってからは、明示的に情報を与えなくても、
自律的に関連するドキュメントや資材を適宜確認して、
スムーズにタスクを進めてくれるようになりました。

今後も定期的に環境やCLAUDE.mdをブラッシュアップして、
Claude Codeの力を最大限引き出す環境を維持していきたいと思います。

今回の内容はClaude Codeを使う上で当たり前のことですが、
大切な基本のキとして誰かの参考になれば幸いです。

最後まで記事をご覧いただきありがとうございました。