Claude Codeを使い込んでいくと、ある壁にぶつかる。プロジェクトが大きくなるほど、毎回同じ指示を繰り返す羽目になるのだ。コーディング規約、テストの実行方法、避けてほしいパターン。セッションのたびに伝え直すのは時間の無駄で、ミスの温床にもなる。
こうした問題への答えとして、海外のエンジニアコミュニティで注目されているのがClaude Codeのプロジェクト構造設計というアプローチだ。単発のプロンプトに頼るのをやめ、ソフトウェアエンジニアリングと同じ発想で仕組みを整える。
CLAUDE.mdをプロジェクトメモリとして設計する
CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むファイルだ。ここに書いた内容が、すべてのやり取りの前提になる。
ただのメモ帳として使っている人が多いが、それではもったいない。コーディング規約、アーキテクチャの制約、やってはいけないこと。これらをCLAUDE.mdに一元化すると、セッションごとの指示の繰り返しがなくなる。
具体的には、こういう内容を入れる。
## プロジェクト概要
Tech Stack: Next.js 14, TypeScript, Prisma
DB: PostgreSQL（Supabase）
## 開発コマンド
npm run dev # 開発サーバー起動
npm run test # Vitest実行
npm run lint # ESLint + Prettier
## コーディング規約
- コンポーネントは関数コンポーネント + TypeScript strict
- API routeではzodでバリデーション必須
- main直pushは禁止。必ずブランチを切ってPRを作る
## やってはいけないこと
- anyの使用
- console.logの残存
- テストなしのマージここで注意したいのが文量だ。Claudeが確実に従えるのは150〜200行程度の指示で、システムプロンプトが約50行を消費するため、実質100〜150行が上限になる。詰め込みすぎると、ランダムに無視される行が出てくる。
さらにCLAUDE.mdは階層構造に対応している。~/.claude/CLAUDE.mdにはユーザー全体の設定、プロジェクトルートの./CLAUDE.mdにはチーム共通の規約、各ディレクトリにはパッケージ固有のルールを置く。モノレポ構成でも、各パッケージに適切な文脈を渡せる。
何を書くべきか、書かなくていいか
CLAUDE.mdに何でも書けばいいわけではない。コンテキストウィンドウには上限があり、読ませる内容が増えるほど各指示の重みが薄まる。判断基準として使えるのが「この行を消したらClaudeがミスするか？」というリトマス試験だ。答えがYesならば書く価値がある。Noならば不要だ。
書くべき内容
- ビルドコマンドやテストの実行方法（プロジェクトごとに異なるため）
- プロジェクト固有のコード規約（チームで決めたルールであり、標準から外れているもの）
- 環境の癖（特定のライブラリの制約、外部APIの挙動など）
- アーキテクチャ上の判断（なぜこの設計を選んだかの背景）
書かなくていい内容
- Claudeがコードを読めば分かること（ファイル構造、変数名の意味など）
- 言語・フレームワークの標準的な慣習（TypeScriptの型付け、Reactのhooks規則など）
- 頻繁に変わる情報（バージョン番号、一時的なTODOなど）
「プロジェクト固有かどうか」という軸で判断すると迷いにくい。
出典: alexop.dev
Skills — 繰り返す作業を機能として定義する
Claude Codeにはskillsという仕組みがある。.claude/skills/にSKILL.mdファイルを置くと、タスクの文脈に応じて自動的にロードされる。
コードレビュー、リファクタリング、テスト生成。こうした繰り返しの作業を、毎回アドホックにプロンプトで指示するのではなく、再利用可能なワークフローとして定義する。プロンプトではなく機能として持たせるという発想だ。
たとえばコードレビュー用のスキルなら、こう書く。
---
name: code-review
description: PRのコードレビューを実行する
---
以下の観点でコードをレビューしてください。
1. 型安全性（any, as の使用箇所）
2. エラーハンドリングの網羅性
3. テストカバレッジの十分性
4. パフォーマンス上の懸念
5. セキュリティリスク（インジェクション、XSS）
問題を見つけたら、修正案をコードブロックで提示すること。スキルのディレクトリ構造はシンプルだ。.claude/skills/以下にスキル名のフォルダを作り、SKILL.mdを置くだけでよい。
.claude/skills/
├── code-review/
│ └── SKILL.md
├── test-gen/
│ └── SKILL.md
└── refactor/
└── SKILL.mdスキルが増えても整理しやすく、チームメンバーが「どんなスキルが使えるか」を把握しやすい構造になる。
Slash Commandsとの違いも押さえておきたい。コマンドは/reviewのようにユーザーが明示的に呼び出す。一方スキルは、タスクの文脈からClaude側が判断して読み込む。どちらが合うかはユースケース次第だが、定型的なワークフローほどスキル化の恩恵が出やすい。
Hooks — 出力の品質を仕組みで担保する
HooksはClaude Codeのライフサイクルイベントに紐づけてシェルスクリプトを自動実行する仕組みだ。CLAUDE.mdのルールが依頼ベースなら、Hooksは強制に相当する。
ファイル編集後の自動lint、保護ファイルへの書き込みブロック、特定フォーマットへの変換。手動で毎回直していた整形作業を自動化できる。
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": "npx eslint --fix $CLAUDE_FILE_PATH"
}]
}]
}
}この設定では、Claudeがファイルを編集するたびにESLintが自動で走る。lint違反が残ったままコミットされる心配がなくなる。
使えるイベントはPreToolUse、PostToolUse、UserPromptSubmit、SubagentStopなど。実行モードもシェルコマンドとLLM判断の2種類から選べる。
出典: alexop.dev
.claudeignoreとコンテキスト管理
Claude Codeはデフォルトでプロジェクト全体を走査しようとするが、それがかえってコンテキストを汚染することがある。node_modules/やdist/のようなファイルをClaudeに読ませても意味がない。.claudeignoreファイルでこれらを除外することで、入力トークンを40%以上節約できるケースもある。
# .claudeignore
node_modules/
dist/
build/
*.min.js
coverage/.gitignoreと同じ記法で書けるため、既存の設定を流用しやすい。
コンテキスト管理には/clearと/compactも活用したい。/clearはセッション間で会話履歴をリセットし、無関係な文脈が引き継がれるのを防ぐ。/compactはコンテキストを要約して圧縮することで、長時間のセッションでもウィンドウ消費を抑える。
さらに根本的なアプローチとして、サブエージェントによるコンテキスト分離がある。調査タスクを独立したエージェントウィンドウに委任し、結果だけを受け取る形にすると、メインセッションのコンテキストが調査ログで埋まらない。複雑な調査を並行して走らせつつ、メインの会話を軽く保つことができる。
関心の分離 — ソフトウェア設計と同じ原則
ここまで紹介した3つの仕組みは、結局ソフトウェアエンジニアリングの基本原則に行き着く。
| レイヤー | 仕組み | 性質 | 実行タイミング |
|---|---|---|---|
| 設定 | CLAUDE.md | 助言的（advisory） | セッション開始時 |
| 機能 | Skills | 文脈駆動（contextual） | タスク検出時 |
| 実行 | Hooks | 強制的（mandatory） | イベント発火時 |
CLAUDE.mdはClaudeへの「お願い」だ。書かれていれば従うが、忘れられることもある。Skillsはタスクの内容から自動判断して読み込まれる。HooksはClaudeの意思に関係なく、イベントが発火したら必ず実行される。この3つの性質の違いを理解しておくと、どの仕組みを使うべきか判断しやすくなる。
これにサブエージェントを組み合わせると、セキュリティ監査、テスト実行、コードレビューといった専門タスクを並列で委任できる。各エージェントは独立したコンテキストウィンドウで動くため、メインの会話が汚染されない。
EastCloudでも、自社プロダクトの開発にClaude Codeを日常的に使っている。CLAUDE.mdでプロジェクトメモリを持ち、スキルでワークフローを定義し、フックで品質を担保する。この三層構造を導入してから、セッションごとの指示の重複が目に見えて減った。また、新しいメンバーがCLAUDE.mdを読むだけでプロジェクトの制約を把握できるため、属人化の防止にもつながっている。
プロンプトの書き方を磨くだけでは、いずれ限界が来る。AIエージェントによる開発が広がるなか、次に必要なのは仕組みを整えるフェーズだ。
