CLAUDE.md 使用ガイド

CLAUDE.mdは Claude Code において最も重要な設定ファイルであり、Claude にプロジェクトレベルの永続的な指示を伝えるために使用されます。Claude Code セッションを起動するたびに、このファイルの内容が自動的に読み込まれ、システムレベルのコンテキストとしてすべての会話に組み込まれます。

わかりやすく言うと、CLAUDE.mdこれは、プロジェクト内で Claude に渡す「仕事マニュアル」のようなものです。このプロジェクトが何なのか、どのような規約に従うのか、どのような注意点があるのかを Claude に伝え、毎回の会話で改めて説明し直すことなく、毎回プロジェクトの要件に沿った方法で作業できるようにします。

CLAUDE.md の役割

[CLAUDE.md] がない場合、CLAUDE.mdClaude は毎回ゼロからプロジェクトを理解する必要があり、どのパッケージマネージャーを使うのか、コードスタイルは何か、テストの実行方法、どのファイルを変更してはいけないのかを、何度も伝えなければなりません。[CLAUDE.md] があれば、CLAUDE.mdこれらの情報は一度書くだけで、Claude は毎回それを守ってくれます。

具体的には、CLAUDE.md以下のことを実現できます：

• チームの行動を統一する：ファイルを git にコミットすれば、すべてのチームメンバーが Claude Code を使用する際に同じ規約を守ることができます
• 重複したコミュニケーションを減らす：プロジェクトの約束事、アーキテクチャのルール、禁止事項を一度書くだけで、永続的に有効になります
• エラー発生の確率を下げる：Claude にどの操作にリスクがあるかを明確に伝え、誤った判断を避けさせます
• AI の理解を加速する：Claude が重要なファイルを素早く見つけ、プロジェクト構造を理解するのを助け、不要なファイル探索を減らします

ファイルの配置場所

Claude Code は複数の場所から [CLAUDE.md] を読み込みますCLAUDE.md。場所によってファイルの適用範囲が異なります：

複数の場所に存在する場合、CLAUDE.mdClaude Code はそれらをすべて読み込んでマージします。優先順位は高いものから低いものの順に次のとおりです：

プロジェクトローカル → プロジェクトルートディレクトリ → サブディレクトリ → グローバルユーザーレベル

プロジェクトルートディレクトリの [CLAUDE.md]CLAUDE.mdは git にコミットして、チーム全体で同じ AI 作業規約を共有することをお勧めします。

個人的な好み（例：セミコロンを付けたくない）は [CLAUDE.md] に.claude/CLAUDE.md入れて、[.gitignore] にも追加すれば、.gitignore他の人に影響を与えません。

CLAUDE.md をすばやく作成する

最も簡単な方法は、Claude Code に初期バージョンを自動生成させることです。プロジェクトディレクトリで Claude Code を起動した後、以下を実行します：

/init

Claude Code は、プロジェクトの構造、コードスタイル、既存の設定ファイル（例：package.json、pyproject.toml、.eslintrcなど）を分析し、プロジェクトの実情に合った [CLAUDE.md] を自動生成します。CLAUDE.mdその後、これを基に補足や調整を行うことができます。

プロジェクトディレクトリに手動で作成することもできます：

touch CLAUDE.md

ファイル内容の構成

CLAUDE.mdは通常の Markdown ファイルであり、強制的なフォーマット要件はありませんが、適切な構造は Claude が重要な情報をより早く見つけるのに役立ちます。以下は推奨される内容構成です：

# 项目名称

一句话说明这个项目是什么，方便 Claude 快速定位项目性质。

## 技术栈
- 语言：Python 3.11
- 框架：FastAPI 0.110
- 数据库：PostgreSQL 15 + SQLAlchemy ORM
- 测试：pytest

## 常用命令

### 开发
```bash
uv run uvicorn main:app --reload   # 启动开发服务器
uv run pytest                       # 运行所有测试
uv run pytest -k "test_auth"        # 运行指定测试
```

### 代码检查
```bash
uv run ruff check .                 # 代码检查
uv run ruff format .                # 代码格式化
```

## 项目结构
- `src/api/` — API 路由和请求处理
- `src/models/` — 数据库模型定义
- `src/services/` — 业务逻辑层
- `tests/` — 测试文件，与 src/ 目录结构镜像对应

## 编码规范
- 使用 `uv` 管理依赖，不使用 pip 直接安装
- 所有函数必须有类型注解
- 字符串一律使用双引号
- 新增 API 路由必须同步添加测试

## 注意事项
- 不要修改 `migrations/` 目录下的已有文件，只能新增迁移文件
- `config/secrets.py` 包含敏感配置，禁止输出其内容到日志或终端
- 数据库操作必须通过 Service 层，不要在路由层直接操作 ORM

コア内容モジュールの詳細解説

1、よく使うコマンド

これは [CLAUDE.md] の中でCLAUDE.md 中最も頻繁に参照される部分です。Claude はテスト、ビルド、コードチェックなどのタスクを実行する際、ここで定義されたコマンドを優先的に探すため、推測や誤ったコマンドの使用を避けることができます：

## 常用命令

### 安装依赖
```bash
npm ci                    # 安装依赖（CI 环境使用，严格按 lock 文件安装）
```

### 开发
```bash
npm run dev               # 启动开发服务器（端口 3000）
npm run build             # 构建生产版本
npm run preview           # 预览生产构建
```

### 测试
```bash
npm test                  # 运行所有测试
npm test -- --watch       # 监听模式
npm test -- --coverage    # 生成覆盖率报告
```

### 代码质量
```bash
npm run lint              # ESLint 检查
npm run lint:fix          # 自动修复可修复的问题
npm run typecheck         # TypeScript 类型检查
```

2、プロジェクト構造の説明

Claude がファイルを素早く特定するのを助け、不要なディレクトリスキャンを減らします。特に大規模プロジェクトで効果が顕著です：

## 项目结构

```
src/
├── app/                  # Next.js App Router 页面
│   ├── (auth)/           # 需要登录才能访问的页面组
│   └── api/              # API 路由
├── components/           # 可复用 UI 组件
│   ├── ui/               # 基础 UI 组件（Button、Input 等）
│   └── features/         # 业务组件（按功能模块组织）
├── lib/                  # 工具函数和配置
│   ├── db/               # 数据库客户端和查询
│   └── auth/             # 认证相关逻辑
└── types/                # TypeScript 类型定义
```

关键文件：
- `src/lib/db/client.ts` — 数据库连接配置
- `src/middleware.ts` — 认证中间件，处理路由保护
- `env.example` — 所有必要的环境变量示例

3、コーディング規約

Claude にプロジェクトのコードスタイルと約束事を伝え、生成されるコードが既存のコードベースのスタイルと一致することを保証します：

## 编码规范

### 通用
- 文件名使用 kebab-case（如 `user-profile.ts`），类名使用 PascalCase
- 优先使用具名导出（named export），避免默认导出（default export）
- 异步函数一律使用 async/await，禁止使用 .then() 链式调用

### 组件规范
- 组件文件与其测试文件放在同一目录（如 `Button.tsx` 和 `Button.test.tsx`）
- Props 类型使用 interface 定义，命名格式为 `${组件名}Props`
- 不要将业务逻辑写在组件中，提取为自定义 Hook 或 Service

### 错误处理
- API 路由使用统一的错误响应格式：`{ error: string, code: string }`
- 客户端错误通过 Error Boundary 捕获，不要在每个组件里单独 try/catch

4、アーキテクチャの制約と禁止事項

これは、Claude が「賢いが誤った」判断をするのを防ぐための重要な部分です。あなたが知っているが Claude が知らない特別な状況については、明確に書き出す必要があります：

## 架构约束

- 所有数据库查询必须通过 `src/lib/db/queries/` 中的函数执行，不要在路由或组件中直接写 SQL
- 状态管理使用 Zustand，不要引入 Redux 或其他状态管理库
- 样式使用 Tailwind CSS utility class，不要新增 CSS 文件或使用 CSS Modules

## 注意事项（重要）

- `legacy/` 目录下的代码是遗留代码，**禁止修改**，只能读取
- `.env.local` 和 `.env.production` 包含真实密钥，**禁止输出文件内容**
- `prisma/migrations/` 中已有的迁移文件**禁止修改**，数据库变更只能新增迁移
- 修改 `src/middleware.ts` 前必须先告知我，该文件影响所有路由的认证逻辑

5、開発環境の説明

Claude がプロジェクトの実行環境を理解するのを助け、環境の違いによるコマンド実行の失敗を防ぎます：

## 开发环境

- Node.js：需要 v20 或以上版本（通过 `.nvmrc` 指定）
- 包管理器：pnpm（禁止使用 npm 或 yarn 安装依赖）
- 本地数据库：Docker Compose 启动（`docker compose up -d`）
- 端口：前端 3000，API 3001，数据库 5432

### 环境变量
参考 `.env.example` 文件配置本地环境变量，复制为 `.env.local` 后填入实际值。
必填项：`DATABASE_URL`、`NEXTAUTH_SECRET`、`NEXTAUTH_URL`

マルチモジュールリポジトリ（Monorepo）の設定方法

Monorepo では、リポジトリのルートディレクトリにグローバルな [CLAUDE.md] を1つ置き、CLAUDE.md各サブパッケージのディレクトリには、それぞれの [CLAUDE.md] を置くことができます。CLAUDE.mdClaude がサブパッケージのファイルを開くと、ルートディレクトリとそのサブパッケージディレクトリにある2つのファイルが同時に読み込まれます：

my-monorepo/
├── CLAUDE.md                  ← 全局规范：共用命令、整体架构、通用约定
├── packages/
│   ├── web/
│   │   └── CLAUDE.md          ← 前端专属：React 规范、样式约定、构建流程
│   ├── api/
│   │   └── CLAUDE.md          ← 后端专属：API 设计规范、数据库约定
│   └── shared/
│       └── CLAUDE.md          ← 共享包：导出规则、版本管理约定
└── tools/
    └── CLAUDE.md              ← 工具脚本：特殊说明和使用限制

<!-- 根目录 CLAUDE.md（全局规范） -->
# My Monorepo

使用 pnpm workspace 管理的前后端一体化项目。

## 全局命令
```bash
pnpm install          # 安装所有包的依赖
pnpm -r build         # 构建所有包
pnpm -r test          # 运行所有包的测试
pnpm --filter web dev # 只启动 web 包的开发服务器
```

## 包之间的依赖关系
- `web` 和 `api` 都依赖 `shared`
- 禁止 `shared` 依赖 `web` 或 `api`（防止循环依赖）
- 跨包引用使用包名（如 `@my-app/shared`），不要使用相对路径

@構文で外部ファイルを参照する

プロジェクトにすでに規約ドキュメント（API 設計規約、データベース設計ドキュメントなど）がある場合、内容を [CLAUDE.md] にコピーする必要はなく、CLAUDE.md直接@ファイルパスで参照するだけで済みます。

Claude が [CLAUDE.md] を読み取るとき、CLAUDE.md参照されたファイルの内容が自動的に読み込まれます：

## 规范文档

详细的 API 设计规范请参考：
@docs/api-design-guide.md

数据库设计约定：
@docs/database-conventions.md

组件库使用说明：
@docs/component-guidelines.md

参照するファイルパスは、CLAUDE.md[CLAUDE.md] が置かれているディレクトリを基準とした相対パスです。参照するファイルの内容はコンテキストウィンドウを占有するため、大きすぎるファイルの参照は避けてください（単一の参照ファイルは500行以内を推奨します）。

グローバル CLAUDE.md の使用に関する提案

ユーザーレベルの~/.claude/CLAUDE.md[CLAUDE.md] は、プロジェクト横断的に共通する個人的な好みや習慣を保存するのに適しています。これらの内容はすべてのプロジェクトに適用されます：

<!-- 文件路径：~/.claude/CLAUDE.md -->
# 个人全局配置

## 回答偏好
- 回复使用中文
- 代码修改前先简要说明修改思路，不要直接给出代码
- 遇到有多种实现方案时，列出选项让我选择，而不是直接选一种

## 通用约定
- 提交信息使用英文，格式：`type(scope): description`
- 新文件开头不加版权注释
- 优先使用原生 API，避免引入不必要的依赖

## 安全习惯
- 修改认证相关代码前主动提示我注意安全影响
- 不要在代码注释或日志中输出任何密钥或 token

CLAUDE.md のメンテナンスに関する提案

1、簡潔に保つ

CLAUDE.md[CLAUDE.md] の内容は毎回のセッションでコンテキストウィンドウを占有します。内容が多すぎると、Claude が実際に利用できるコンテキスト空間が圧縮され、逆に効率が低下します。次の原則に従うことをお勧めします：

• 各ルールは一度だけ書き、同じ意味を繰り返し表現しない
• コードと無関係な背景情報（会社紹介、製品計画など）は書き込まない
• コード自体で伝えられる情報（eslint 設定がすでにコードスタイルを定義している場合など）は、CLAUDE.md[CLAUDE.md] で重複して宣言する必要はありません。
• 総文字数は500字以内に収めることを推奨します。1000字を超える場合は簡素化を検討する必要があります。

2、継続的に更新する

プロジェクトの進化に伴い、CLAUDE.md[CLAUDE.md] も同期して更新する必要があります。以下のタイミングで更新すべきです：

• パッケージマネージャーやビルドツールを変更した
• 重要な依存ライブラリを追加または削除した
• 新しいコーディング規約を制定した
• Claude が同じ種類のエラーを繰り返していることに気づいた（[CLAUDE.md] にCLAUDE.md補足説明を追加する必要があることを示しています）
• 特定のファイルやモジュールが簡単に変更できなくなった（注意事項に追加する）

3、命令形の言語を使う

指示が明確であればあるほど、Claude が従う確率が高くなります。曖昧な説明を避け、直接的な命令を使用してください：

完全な例

以下は Node.js + TypeScript フルスタックプロジェクトのCLAUDE.md[CLAUDE.md] の完全な例です。あなたのプロジェクトの参考テンプレートとして使用できます：

よくある質問

Q：CLAUDE.md のルールを Claude が守らない場合はどうすればいいですか？

まず、ルールの表現が十分に明確かを確認してください（上記の「命令形を使う」という提案を参照）。表現が明確なのに守らない場合は、個別の会話で再度強調するか、そのルールをファイルの前方に移動してください——Claude はファイル前半部分の内容に注意を払いやすいです。

Q：CLAUDE.md は長いほど良いですか？

いいえ。内容が多すぎると 2 つの副作用があります。1 つはコンテキストウィンドウを占有し、Claude が実際のタスクを処理するスペースを圧迫すること。もう 1 つは重要なルールが大量の文章に埋もれて、かえって守られにくくなることです。定期的に見直し、適用されなくなった項目や価値の低い項目を削除することをお勧めします。

Q：サブディレクトリの CLAUDE.md はいつロードされますか？

Claude がそのサブディレクトリ内のファイルを開いたり編集したりすると、そのサブディレクトリのCLAUDE.mdが自動的にロードされます。Claude に手動で読み取るよう指示する必要はなく、プロセス全体が自動です。

Q：CLAUDE.md 内で別の CLAUDE.md を参照できますか？

直接参照はできませんが、@ファイルパス構文を使用して任意の Markdown ファイルの内容を参照できます。モジュール間で共有する規約がある場合は、独立したドキュメントファイルに抽出し、それぞれのCLAUDE.mdで@参照することをお勧めします。