Blog

はじめに

Claude Codeを使いこなすための隠れた鍵がCLAUDE.mdです。
このファイルはプロジェクトのルートディレクトリに置くことで、Claude Codeにプロジェクト固有の知識、規約、設定を教えることができます。
適切なCLAUDE.mdが存在することで、Claude Codeはプロジェクトの「通」として振る舞い、チームの文化に合わせた提案や実装を行うようになります。
この記事では、CLAUDE.mdの書き方から高度な活用法まで詳しく解説します。

 

CLAUDE.mdとは何か

CLAUDE.mdは、Claude Codeのための「プロジェクト取扱説明書」です。
セッションをまたいで持続するコンテキストを提供し、毎回同じ説明を繰り返す必要をなくします。

通常のMarkdownファイルで、Claude Codeが新しいセッションを開始するたびに自動的に読み込まれます。
ここに書いた情報は、そのセッション中のすべての対話で考慮されます。
 

/init コマンドで自動生成する

CLAUDE.mdを一から書く必要はありません。
/initコマンドを使えば、Claude Codeが自動的にプロジェクトを分析して
CLAUDE.mdを生成します：

 /init 

生成されたCLAUDE.mdを基に、プロジェクト固有の情報を追加していきます。
 

CLAUDE.mdの基本構造

よく整備されたCLAUDE.mdの構造例：

 # プロジェクト概要 
## このプロジェクトについて 
このプロジェクトは[会社名]の[サービス名]のバックエンドAPIです。 
Node.js + TypeScript + PostgreSQLで構築されており、 
月間アクティブユーザー数50万人のeコマースプラットフォームを支えています。 

## 技術スタック 
- **Runtime**: Node.js 20 LTS 
- **Language**: TypeScript 5.x（strict mode必須） 
- **Framework**: Fastify 4.x 
- **Database**: PostgreSQL 15 + Prisma ORM 
- **Cache**: Redis 7 
- **Testing**: Jest + Supertest 
- **CI/CD**: GitHub Actions → AWS ECS 

## アーキテクチャ 
src/ 
├── modules/ # ドメインモジュール（認証、商品、注文など） 
├── shared/ # 共通ユーティリティ 
├── infrastructure/ # DB接続、外部API連携 
└── middleware/ # 認証、バリデーション等 

## コーディング規約 
### TypeScript 
- `any`型は絶対に使用しない 
- 全ての公開APIに型定義が必要 
- `interface`を`type`より優先する 

### エラーハンドリング 
- カスタムエラークラスを使用する（`src/shared/errors.ts`参照） 
- 全ての非同期処理はtry-catchで囲む 
- ユーザーに見せるエラーメッセージは`errors/messages.ts`から 

### データベース 
- 直接のSQLクエリは禁止。必ずPrismaを使用する 
- トランザクションが必要な場合は`prisma.$transaction()` 
- N+1問題を避けるためincludeを適切に使用する 

## テスト要件 
- 単体テストのカバレッジは80%以上 
- 全APIエンドポイントに統合テストが必要 
- `npm test`で全テストが通ること 

## 環境変数 
機密情報は絶対にコミットしない。 
`.env.example`を参照して`.env`を作成すること。 
本番環境の環境変数はAWS Parameter Storeで管理。 

## MCP設定 
このプロジェクトでは以下のMCPサーバーを使用： 
- **github**: PR作成、Issueの管理に使用 
- **aws**: ECSへのデプロイ確認に使用 

## デプロイフロー 
1. `develop`ブランチで開発 
2. PRを作成してコードレビュー 
3. CIが全通過でmainにマージ 
4. 自動でstaging環境にデプロイ 
5. 手動承認でproduction環境にデプロイ 

 

プロジェクト固有の知識を追加する

CLAUDE.mdに追加すると特に効果的な情報：

よくあるパターンと解決策

 
## Known Patterns 
### 認証が必要なエンドポイントの実装 
新しい認証が必要なエンドポイントを追加する際は、必ず 
`src/middleware/auth.ts`の`requireAuth`ミドルウェアを使用すること： 

// 正しい実装例 
router.get('/protected', requireAuth, async (req, reply) => {
 // ここではrep.user が確実に存在する }); 

### ページネーションの実装 
全一覧系APIはページネーションを実装すること。 
`src/shared/pagination.ts`のヘルパーを使用する。 

 

避けるべきパターン

 
## Anti-Patterns（やってはいけないこと） 
- `res.json(data)` ではなく `reply.send(data)` を使う（Fastifyの規約） 
- `require()` は使わない。ESM importを使用すること 
- `process.env.XXX` を直接使わない。`src/config.ts`経由でアクセスすること 

 

チームのコンテキストを含める

CLAUDE.mdにはチームの文化や意思決定の背景も含めると効果的です：

 
## チームについて 
### レビュープロセス 
- PRには必ず2名以上のレビュアーをアサイン 
- 重要なビジネスロジックの変更はバックエンドリードに必ずレビュー依頼 

### 意思決定の記録 
重要な技術的意思決定は`docs/ADR/`ディレクトリにArchitecture Decision 
 Record（ADR）として記録している。 
新しいアーキテクチャの変更を提案する場合、まずADRを作成すること。 

### 既知の技術的負債 
- `src/modules/legacy/` は古いコードが残っており、変更に注意が必要 
- Payment処理は後でリファクタリング予定。現在は`payment-service`への委任で対応 

 

CLAUDE.mdの階層構造

CLAUDE.mdはプロジェクトルートだけでなく、サブディレクトリにも設置できます。
それぞれのディレクトリで作業する際、最も近いCLAUDE.mdが優先されます：

 
project/ 
├── CLAUDE.md # プロジェクト全体の設定 
├── backend/ 
│ └── CLAUDE.md # バックエンド固有の設定 
└── frontend/
 └── CLAUDE.md # フロントエンド固有の設定 

これにより、チームごとに異なる規約を持つモノレポでも、適切な設定が適用されます。
 

ルーティンの定義

CLAUDE.mdにルーティンを定義して、自動実行タスクを設定できます：

 
## Routines 
### Pre-commit Check Triggered: Before each commit Actions: 
- Run TypeScript type check 
- Run linter 
- Run affected tests 

### Weekly Maintenance (Every Monday 9:00 AM) 
- Check for security vulnerabilities in dependencies 
- Update CHANGELOG.md with recent changes 
- Generate weekly metrics report 

 

動的なCLAUDE.mdの更新

CLAUDE.mdは静的なファイルである必要はありません。
Claude Codeに更新を依頼できます：

 このプロジェクトで新しいパターンを発見しました。 
CLAUDE.mdの「Known Patterns」セクションに追記してください： 
[新しいパターンの説明] 

プロジェクトが進化するにつれて、CLAUDE.mdも更新していくことで、常に最新のプロジェクト状況を反映できます。
 

チームでのCLAUDE.md管理

CLAUDE.mdはGitで管理することが推奨されます。
チームメンバーが更新した場合、PRを通じてレビューされ、全員に共有されます。

CLAUDE.mdの変更PRは、通常のコードPRと同様に重要視しましょう。このファイルの品質が、Claude Codeの効果を左右します。
 

CLAUDE.mdのベストプラクティス

Do（やること）：

• プロジェクト固有の命名規則と規約を記述する
• よく使うコマンドとその意図を書く
• アーキテクチャの概要図または説明を含める
• 既知の落とし穴と回避策を記録する
• 外部依存関係と設定方法を説明する

 
Don't（やらないこと）：

• 機密情報（パスワード、APIキー）を含めない
• 古くなった情報を放置しない
• あまりに長くなりすぎないよう適宜整理する

 

まとめ

CLAUDE.mdは、Claude Codeをあなたのプロジェクトの専門家に変えるための重要なファイルです。
プロジェクトの技術スタック、コーディング規約、チームの文化、既知の問題など、プロジェクト固有の知識を蓄積することで、Claude Codeの提案や実装の品質が格段に向上します。

/initコマンドで基本を自動生成し、プロジェクトの進化とともに継続的に更新していく。
CLAUDE.mdを丁寧に管理することが、Claude Codeの効果を最大化する近道です。

 

ご利用にあたってのお願い

本記事は執筆時点の情報をもとにしており、仕様変更により内容が古くなっている場合があります。
最新情報はAnthropic公式ドキュメントでご確認ください。
記事内のコマンドやコードの実行はご自身の責任で行ってください。
AIの出力は必ずレビュー・検証した上でご利用ください。
とくにAPIキーや機密情報の取り扱い、セキュリティ設定の変更には十分ご注意ください。