Claude Codeフォルダ構成の完全ガイド｜CLAUDE.mdで開発効率を上げる5つの設計術

🌐 Read this article in English

Claude Codeの公式情報はAnthropic公式ドキュメントを参照。MCPの仕様はModel Context Protocol公式サイトで確認できる。

Claude Codeを本格的に使い込むなら、プロジェクト構成（project structure）の設計が成功の鍵を握る。適当にファイルを配置するとすぐにカオスになり、AIが正しいファイルを参照できなくなる。

この記事では、自分が実際に運用しているClaude Codeのフォルダ構成と、AIへの指示書である「CLAUDE.md」の書き方を詳しく紹介する。さらに、設計で失敗しがちなポイントとその解決策も共有する。

Claude Code project structureの全体像

自分のリポジトリは以下のような構造になっている：

project-root/
├── .claude/
│   ├── CLAUDE.md          # グローバル設定（最重要）
│   ├── settings.local.json # ローカル設定
│   ├── skills/            # カスタムスキル
│   ├── scheduled-tasks/   # 定期実行タスク
│   ├── scripts/           # ヘルパースクリプト
│   ├── mcp-servers/       # 自作MCPサーバー
│   └── projects/          # プロジェクト別メモリ
├── scripts/               # 独立ツール群
├── the-stash/             # 家計管理アプリ
├── .mcp.json              # MCP接続設定
└── .gitignore

ポイントは.claude/ 配下にClaude Code関連のファイルを全部まとめること。このディレクトリはClaude Codeが自動で認識するため、ここに設定やスキルを置けば明示的に指定しなくても読み込んでくれる。

CLAUDE.md — AIへの永続的な指示書

CLAUDE.mdは、Claude Codeが毎回の会話開始時に自動で読み込む設定ファイルだ。いわばAIへの永続的な指示書であり、ここに書いた内容がすべての会話に適用される。

したがって、プロジェクト固有のルールや開発方針を書いておけば、毎回同じ説明を繰り返す必要がなくなる。以下に、自分が実際にCLAUDE.mdに記述しているセクションを紹介する。

Windows デスクトップ自動化のルール

## Windows Desktop Automation
1. App起動 → 2. スクリーンショット → 3. 座標確認 → 4. クリック/入力

Windows MCPでデスクトップ操作する際のフローを明記している。この手順を省略すると、Claude Codeが毎回異なるアプローチを試み、操作が不安定になる。つまり、操作フローの標準化がClaude Code project structureの安定性に直結する。

ブラウザ自動化のMCP使い分け

## Browser Automation
- ローカル: k-chrome MCP（自作・既存プロファイル使用）
- フォールバック: Windows MCP（スクリーンショット→座標クリック）

ブラウザ操作用のMCPが複数ある場合、どれを優先するかを定義しておく必要がある。一方で、この指定がないと、Claude Codeはランダムにツールを選んでしまい、操作結果が不安定になる。

セキュリティルール

## Security Rules
- パスワードは絶対に入力しない（ユーザーが手動で行う）
- 金融アカウントは読み取り専用

AIに勝手にパスワードを入力させないルールは必須だ。特に、ブラウザ自動化やデスクトップ操作を行う場合、認証画面に遭遇する機会が多い。このルールをCLAUDE.mdに書いておくことで、Claude Codeは認証画面を検出した時点で自動的にユーザーの手動入力を待つようになる。

パフォーマンスルール — トークン節約の秘訣

## Performance Rules
- 3回以上のGrep/Globが予想される調査はサブエージェントに委任
- 100行超のファイルは部分読み
- 同じファイルを2回読まない

Claude Codeはトークンを消費するため、無駄遣いを防ぐルールを設定している。その結果、体感で2倍ほど長い会話が可能になった。たとえば、大きなファイルを毎回全行読むのではなく、必要な部分だけ読む指示を入れるだけで大幅に効率化できる。

skills/ — カスタムスキルの配置

カスタムスキルは.claude/skills/配下にフォルダ単位で配置する。各フォルダにはSKILL.mdというMarkdownファイルを1つ置くだけで、Claude Codeが自動的にスキルとして認識する。

.claude/skills/
├── amazon-purchase/SKILL.md   # Amazon購入
├── line-message/SKILL.md      # LINE送信
├── restaurant/SKILL.md        # レストラン予約
├── travel-booking/SKILL.md    # 旅行予約
└── monthly-invoice/SKILL.md       # 請求書作成

このClaude Code project structureのおかげで、スキルの追加・削除が簡単だ。新しいスキルを追加したい場合は、フォルダを作ってSKILL.mdを書くだけで良い。詳しくはスキル編で解説する。

scheduled-tasks/ — 定期実行タスク

cronライクな定期実行タスクもスキルと同じフォルダ構造で管理する。

.claude/scheduled-tasks/
├── monthly-invoice/SKILL.md   # 月次請求書
├── claude-update-digest/SKILL.md  # 更新情報ダイジェスト
└── the-stash-daily/SKILL.md       # 家計データ日次同期

スキルと同じSKILL.md形式なので、学習コストがほぼゼロだ。こちらもスケジュール実行編で詳しく説明する。

scripts/ — 汎用スクリプト

Claude Code専用ではない汎用スクリプトはscripts/配下に配置している。

scripts/
├── daily-brief/      # 日次ダイジェスト生成
├── remote-control/   # リモート操作ランチャー
├── shared/           # 共有ユーティリティ（メール送信等）
└── cleanup-mcp/      # MCP掃除スクリプト

ここには純粋なPythonスクリプトを置いている。Claude Codeからも呼び出せるし、単独でも実行できる汎用ツールだ。

フォルダ設計で意識すべき5つのコツ

• 1フォルダ1機能 — スキルもタスクもスクリプトも、責務ごとにフォルダを分離する
• CLAUDE.mdは簡潔に — 長すぎるとトークンの無駄になる。ルールと方針だけを端的に書く
• .gitignoreを忘れずに — キャッシュファイル、一時ファイル、認証情報は必ず除外する
• 命名規則を統一 — ケバブケース（例: amazon-purchase）で全ディレクトリを統一
• ドキュメントは近くに置く — 関連するドキュメントは同じフォルダに配置し、探しやすくする

これらのルールを守ることで、Claude Codeのproject structureは長期的にメンテナンスしやすくなる。結果として、AIとの協業がスムーズに進むようになる。

# Claude Code User Instructions

## User Constants
- Email: your-email@example.com

## Language & Style
- 言語: Python優先
- 新規スクリプトは scripts/<名前>/ 配下に配置
- 一時ファイルは作業完了後に削除

## Browser Automation
- Primary: k-chrome MCP
- Fallback: Windows MCP (screenshot + click)

## Security Rules
- Never enter passwords (user does it manually)
- Financial accounts are read-only

## Performance Rules
- 3回以上の調査はサブエージェントに委任
- 100行超のファイルは部分読み
- 同じファイルを2回読まない

次回予告

次回はMCPサーバー編。Claude Codeの機能を拡張する「MCP（Model Context Protocol）」サーバーの仕組みと、自作したMCPサーバーの具体的な実装を紹介する。