CLAUDE.md ファイル設定ガイド

CLAUDE.mdファイルを通じてプロジェクトの規約と制約を定義し、Claude Codeがプロジェクト要件をより良く理解し遵守できるようにする。

CLAUDE.mdとは

CLAUDE.mdはClaude Codeのプロジェクト設定ファイルで、各会話開始時に自動的にロードされ、システムプロンプトの一部として機能します。このファイルを適切に設定することで:

  • プロジェクト固有のコーディング規約を定義
  • 技術スタックとフレームワークの制約を設定
  • コード品質基準を制定
  • 開発ワークフローを規範化
  • アーキテクチャ決定を記録

コア設定テンプレート

基本テンプレート構造

# プロジェクト名

## プロジェクト概要

[プロジェクトの目的、コア機能、ターゲットユーザーを簡潔に説明]

## 技術スタック

- フロントエンド:[フレームワークと主要ライブラリ]
- バックエンド:[言語とフレームワーク]
- データベース:[データベースタイプ]
- デプロイ:[デプロイプラットフォーム]

## プロジェクト構造

\```
project/
├── src/ # ソースコード
├── tests/ # テストファイル
├── docs/ # ドキュメント
└── scripts/ # スクリプトファイル
\```

## 開発規約

[プロジェクト固有のコーディング規約]

## 注意事項

[プロジェクト固有の注意事項と制限]

完全な設定例

# CLAUDE.md - プロジェクト設定ファイル

## 通用ルール(すべてのプロジェクトで遵守必須)

### コミュニケーション言語

- 常に日本語で思考し対話する
- コードコメントは英語、ドキュメントは日本語

### ドキュメント管理

- 正式なドキュメントは `docs/` ディレクトリに記載
- 議論内容は `discuss/` ディレクトリに記載
- READMEは簡潔に、詳細ドキュメントは独立して保存

## コードアーキテクチャ規約

### ファイルサイズ制限

- Python/JavaScript/TypeScript:各ファイル300行以内
- Java/Go/Rust:各ファイル400行以内
- 各フォルダのファイル数は8個以内
- 制限を超える場合はリファクタリングまたは分割

### コード品質指標

以下のコードの悪臭を避ける:

1. **硬直性**:システムが変更困難
2. **冗長性**:重複コードが多すぎる
3. **循環依存**:モジュール間の相互依存
4. **脆弱性**:変更が連鎖的な問題を引き起こす
5. **不明瞭性**:コードの意図が不明確
6. **データの塊**:データ項目が常に一緒に出現
7. **過剰設計**:不必要な複雑性

## 技術スタック制約

### フロントエンド技術スタック

- React 19+(18以下のバージョンは使用しない)
- Next.js 15.4+(14以下のバージョンは使用しない)
- Tailwind CSS v4(v3は使用しない)
- TypeScript優先、JavaScriptは避ける
- CommonJS禁止、ES Modulesのみ使用

### バックエンド技術スタック

- Node.js 18+
- TypeScriptを使用
- Express/FastifyをWebフレームワークとして使用
- PrismaをORMとして使用

### Pythonプロジェクト

- uvで依存関係を管理(pip/poetry/condaは使用しない)
- 仮想環境ディレクトリ名:`.venv`
- 強い型定義、dictの使用を避ける
- プロジェクトルートディレクトリは簡潔に保つ

## 開発ワークフロー

### スクリプト管理

- すべてのスクリプトは `scripts/` ディレクトリに配置
- `.sh` スクリプトで起動停止操作を行う
- npm/pnpm/pythonコマンドを直接使用しない
- スクリプトの失敗は即座に修正する

### ログ管理

- 設定ファイルでログ出力を設定
- `logs/` ディレクトリに統一出力
- タイムスタンプとログレベルを含める
- エラーログは別途保存

### テスト要件

- 単体テストカバレッジ > 80%
- 重要機能には統合テストが必須
- テストファイルは `tests/` ディレクトリに配置
- CI/CDで自動テストを実行

## 命名規約

### ファイル命名

- コンポーネント:PascalCase(例:UserProfile.tsx)
- ユーティリティ関数:camelCase(例:formatDate.ts)
- 定数ファイル:UPPER_SNAKE_CASE(例:API_CONSTANTS.ts)
- スタイルファイル:kebab-case(例:user-profile.css)

### 変数命名

- 変数/関数:camelCase
- 定数:UPPER_SNAKE_CASE
- クラス/インターフェース:PascalCase
- プライベートプロパティ:\_camelCase

## Gitワークフロー

### ブランチ戦略

- main:本番環境コード
- develop:開発環境コード
- feature/\*:機能ブランチ
- hotfix/\*:緊急修正ブランチ

### コミット規約

- feat: 新機能
- fix: 問題修正
- docs: ドキュメント更新
- style: コードフォーマット調整
- refactor: コードリファクタリング
- test: テスト関連
- chore: ビルド/ツール変更

## API設計規約

### RESTful原則

- GET:リソース取得
- POST:リソース作成
- PUT:リソース更新(全体)
- PATCH:リソース更新(部分)
- DELETE:リソース削除

### レスポンス形式

\```json
{
"success": true,
"data": {},
"message": "操作成功",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### エラー処理

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "エラー説明",
"details": {}
}
}
\```

## セキュリティ規約

### 機密情報

- コード内でキーをハードコーディングしない
- 環境変数で設定を管理
- `.env` ファイルはGitにコミットしない
- 依存パッケージを定期的に更新

### データ検証

- フロントエンドとバックエンドの両方でデータ検証
- schemaバリデーションライブラリ(例:zod)を使用
- SQLクエリはパラメータ化を使用
- XSSおよびCSRF攻撃を防ぐ

## パフォーマンス最適化

### フロントエンド最適化

- 画像の遅延読み込み
- コード分割
- キャッシュ戦略
- 仮想スクロール(大規模リスト)

### バックエンド最適化

- データベースクエリ最適化
- キャッシュ使用(Redis)
- APIレスポンス圧縮
- 並行制御

## デプロイ設定

### 環境変数

- development:開発環境
- staging:テスト環境
- production:本番環境

### コンテナ化

- Dockerでデプロイ
- マルチステージビルドでイメージサイズを最適化
- docker-composeでサービスを編成

## 監視とログ

### 監視指標

- APIレスポンス時間
- エラー率
- リソース使用率
- ユーザー行動分析

### ログレベル

- ERROR:エラー情報
- WARN:警告情報
- INFO:一般情報
- DEBUG:デバッグ情報

## 特別注意事項

⚠️ **重要な注意**:

1. コード問題を発見したら即座に指摘
2. 不明な場合は積極的にユーザーに質問
3. コードの整潔性と保守性を維持
4. プロジェクトの既定規約を遵守

プロジェクトタイプ専用テンプレート

React/Next.jsプロジェクト

## React/Next.jsプロジェクト規約

### コンポーネント規約

- 関数コンポーネント + Hooksを使用
- コンポーネントファイルはコンポーネントと同名
- 1ファイル1コンポーネント
- PropsはTypeScriptインターフェースで定義

### 状態管理

- シンプルな状態:useState
- 複雑な状態:useReducer
- グローバル状態:Context API / Zustand
- サーバー状態:TanStack Query

### スタイル方案

- Tailwind CSS v4を主に使用
- CSS Modulesを補助として使用
- インラインスタイルは避ける
- レスポンシブデザイン優先

### パフォーマンス最適化

- React.memoで不要な再レンダリングを回避
- useMemo/useCallbackで計算を最適化
- 動的インポートでコード分割を実現
- 画像はnext/imageコンポーネントを使用

Pythonプロジェクト

## Pythonプロジェクト規約

### プロジェクト構造

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### 依存関係管理

- uvですべての依存関係を管理
- pyproject.tomlでプロジェクト設定を定義
- requirements.txtは本番デプロイ用
- requirements-dev.txtは開発依存用

### 型アノテーション

- すべての関数に型アノテーションが必須
- dataclassでデータ構造を定義
- mypyで型チェック
- Any型の使用を避ける

### 非同期プログラミング

- async/awaitを優先使用
- asyncioで並行処理を管理
- データベース操作は非同期ドライバを使用
- HTTPリクエストはhttpxを使用

マイクロサービスプロジェクト

## マイクロサービスアーキテクチャ規約

### サービス分割

- ビジネス領域でサービスを分割
- 各サービスは独立してデプロイ
- サービス間はAPIで通信
- 共有コードはパッケージ管理

### APIゲートウェイ

- 統一エントリポイント管理
- 認証認可
- レート制限とサーキットブレーカー
- リクエストルーティング

### サービス通信

- HTTP/REST:同期呼び出し
- メッセージキュー:非同期通信
- gRPC:高性能シナリオ
- WebSocket:リアルタイム通信

### データ管理

- 各サービスに独立したデータベース
- クロスサービストランザクションを避ける
- イベント駆動で一貫性を保つ
- 冪等性操作を実装

使用上のアドバイス

初期設定

/init コマンドで基本設定を自動生成:

> /init

Claude Codeがプロジェクト構造を分析し、初期の CLAUDE.md ファイルを生成します。

継続的な更新

プロジェクトの発展に伴い、設定ファイルを継続的に更新:

アーキテクチャ決定を記録

重要な技術決定をすべて記録

技術スタックを更新

技術スタックの変更を即座に更新

規約を完善

問題を発見したら即座に規約を補充

ワークフローを最適化

実践に基づいて開発プロセスを最適化

チーム協力

チームメンバー全員が設定を理解し遵守することを確保:

  • 新メンバー入社時はまず CLAUDE.md を読む
  • 定期的に設定をレビューし更新
  • 設定変更は全員に通知
  • 設定の実用性を保つ

ベストプラクティス

DO - 推奨される実践

✅ 簡潔明確を保つ

  • ルールが明確で理解しやすい
  • 過度な設定を避ける
  • 重要な制約を強調

✅ プロジェクトと同期

  • 設定は実際の状況を反映
  • 古い内容を即座に更新
  • 適用されなくなったルールを削除

✅ 実効性を重視

  • ルールは効率向上に役立つ
  • 形式主義を避ける
  • フィードバックに基づいて継続的に改善

DON'T - 避けるべき実践

❌ 過度な制約

  • 厳しすぎるルールを制定しない
  • 開発に柔軟な余地を残す
  • イノベーションを抑制しない

❌ 現実離れ

  • 他プロジェクトの設定を盲目的にコピーしない
  • ルールはチームの能力に適合させる
  • プロジェクトの実際のニーズを考慮

❌ メンテナンス軽視

  • 一度設定して永久に更新しない
  • 設定の有効性を定期的に審査
  • 無用な設定を即座にクリーンアップ

💡 ヒント:CLAUDE.mdはプロジェクトの"憲法"であり、Claude Codeのプロジェクトでの行動規範を定義します。適切な設定により開発効率とコード品質を大幅に向上させることができますが、過度な設定による負担は避けるべきです。常に覚えておいてください:設定は開発のためにあり、開発が設定のためにあるのではありません。

AIとともに、無限のイノベーションと尽きることのない機会をもたらします。
概要
機能
ドキュメント
料金プラン
お問い合わせ