Руководство по использованию CLAUDE.md

CLAUDE.mdЭто самый важный конфигурационный файл в Claude Code, используемый для передачи Claude постоянных инструкций на уровне проекта. При каждом запуске сеанса Claude Code он автоматически читает и загружает содержимое этого файла, включая его в каждый разговор в качестве контекста системного уровня.

Простыми словами,CLAUDE.mdэто рабочее руководство, которое вы пишете для Claude в проекте — рассказывая ему, что представляет собой проект, каких стандартов придерживаться и на что обращать внимание, чтобы он каждый раз мог работать в соответствии с требованиями проекта, а не чтобы ему всё заново объясняли в каждом разговоре.

Роль CLAUDE.md

БезCLAUDE.mdнего, Claude каждый раз начинает понимать ваш проект с нуля, и вам приходится повторно говорить ему: какой менеджер пакетов использовать, каков стиль кода, как запускать тесты, какие файлы не трогать... С нимCLAUDE.md, эта информация должна быть записана только один раз, и Claude будет следовать ей каждый раз.

В частности,CLAUDE.mdэто может помочь вам достичь следующего:

• Унификация поведения команды: зафиксируйте файл в git, и все члены команды следуют одним и тем же стандартам при использовании Claude Code
• Сокращение повторяющейся коммуникации: соглашения проекта, правила архитектуры и запрещённые пункты записываются только один раз и остаются действующими навсегда
• Снизьте вероятность ошибок: Чётко сообщите Claude, какие операции рискованны, чтобы предотвратить принятие неверных решений
• Ускорьте понимание ИИ: Помогите Claude быстро находить ключевые файлы и понимать структуру проекта, сокращая ненужное исследование файлов

Расположение файлов

Claude Code загружается из нескольких расположенийCLAUDE.md, и файлы в разных расположениях имеют разные области действия:

Когда в нескольких местах естьCLAUDE.md, Claude Code будетзагружать и объединять их все, с приоритетом от высокого к низкому следующим образом:

Project local → Project root directory → Subdirectory → Global user level

Корневого каталога проектаCLAUDE.mdРекомендуется коммитить в git, чтобы вся команда использовала один и тот же набор стандартов работы с ИИ.

Личные предпочтения (например, нелюбовь к точкам с запятой) следует помещать в.claude/CLAUDE.mdи добавлены в.gitignore, не влияя на других.

Быстрое создание CLAUDE.md

Самый простой способ — позволить Claude Code автоматически сгенерировать начальную версию. После запуска Claude Code в каталоге проекта выполните:

/init

Claude Code проанализирует структуру вашего проекта, стиль кода и существующие файлы конфигурации (такие какpackage.json、pyproject.toml、.eslintrcи т. д.), и автоматически сгенерирует версию, соответствующую фактическому состоянию проекта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.mdMediumнаиболее часто упоминаемаячасть. Когда 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`

Конфигурация для многомодульного репозитория (монорепозитория)

В монорепозитории можно разместить глобальный файл в корневом каталоге репозиторияCLAUDE.md, а соответствующий файл — в каждом каталоге подпакета.CLAUDE.mdКогда Claude открывает файл в подпакете, он загрузит файлы как из корневого каталога, так и из каталога подпакета:

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Вместо этого просто используйте@file pathчтобы ссылаться на них.

Когда Claude читаетCLAUDE.mdон автоматически включит содержимое указанного файла:

## 规范文档

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

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

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

Путь к указанному файлу указывается относительноCLAUDE.mdдиректории, в которой находится файл. Содержимое указанного файла будет занимать пространство контекстного окна, поэтому избегайте ссылок на слишком большие файлы (рекомендуется, чтобы один указанный файл не превышал 500 строк).

Рекомендации по использованию глобального CLAUDE.md

Пользовательский уровень~/.claude/CLAUDE.mdподходит для хранения личных предпочтений и привычек, общих для проектов; эти данные действуют для всех проектов:

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

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

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

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

Рекомендации по поддержанию CLAUDE.md

1. Будьте кратки

CLAUDE.mdСодержимое будет занимать пространство контекстного окна в каждой сессии. Слишком большой объём содержимого сократит фактическое доступное Claude пространство контекста, снижая эффективность. Рекомендуется придерживаться следующих принципов:

• Записывайте каждое правило только один раз; не повторяйте один и тот же смысл.
• Не включайте фоновую информацию, не относящуюся к коду (например, представление компании, планы по продукту).
• Информация, которую можно передать через сам код (например, конфигурация eslint уже определяет стиль кода), не должна бытьCLAUDE.mdснова объявлена в файле.
• Рекомендуется удерживать общее количество слов в пределах 500 слов; когда оно превышает 1000 слов, рассмотрите возможность упрощения.

2. Постоянно обновляйте

По мере развития проекта,CLAUDE.mdего также необходимо синхронно обновлять. Следующие случаи должны вызывать обновления:

• Изменён менеджер пакетов или инструмент сборки
• Добавлены или удалены важные библиотеки зависимостей
• Установлены новые соглашения о кодировании
• Обнаружено, что Claude повторяет один и тот же тип ошибки (это указывает на то, что нужноCLAUDE.mdдополнить в файле)
• Некоторый файл или модуль стал недоступен для изменения по желанию (добавьте его в меры предосторожности)

3. Используйте повелительное наклонение

Чем яснее инструкция, тем выше вероятность, что Claude будет её соблюдать. Избегайте расплывчатых описаний и используйте прямые команды:

Полный пример

Ниже приведёнCLAUDE.mdполный пример проекта Node.js + TypeScript с полным стеком, который может служить справочным шаблоном для вашего проекта:

Часто задаваемые вопросы

Вопрос: Что, если Claude не соблюдает правила в CLAUDE.md?

Сначала проверьте, достаточно ли чётко сформулировано правило (см. рекомендацию «используйте повелительное наклонение» выше). Если оно уже чёткое, но всё ещё не соблюдается, вы можете ещё раз подчеркнуть его в конкретном разговоре или переместить правило в более раннюю позицию в файле — Claude уделяет больше внимания содержимому в первой половине файла.

Вопрос: Более длинный CLAUDE.md лучше?

Нет. У слишком большого объёма содержимого есть два недостатка: во-первых, он занимает место в контекстном окне, уменьшая пространство, доступное Claude для выполнения реальных задач; во-вторых, важные правила теряются в большом объёме текста и с меньшей вероятностью соблюдаются. Рекомендуется периодически пересматривать и удалять записи, которые больше не применимы или имеют низкую ценность.

Вопрос: Когда загружается CLAUDE.md в подкаталоге?

Когда Claude открывает или редактирует файл в этом подкаталоге, CLAUDE.md этого подкаталогаCLAUDE.mdавтоматически загружается. Вам не нужно вручную просить Claude прочитать его; весь процесс происходит автоматически.

Вопрос: Могу ли я ссылаться на другой CLAUDE.md в CLAUDE.md?

Вы не можете ссылаться на него напрямую, но можете использовать@file pathсинтаксис для ссылки на содержимое любого файла Markdown. Если есть соглашения, общие для нескольких модулей, рекомендуется вынести их в отдельный файл документа, а затем в каждомCLAUDE.mdиспользовать@ссылаться на него.