Guía de uso de CLAUDE.md

CLAUDE.mdEs el archivo de configuración más importante en Claude Code, utilizado para transmitir instrucciones persistentes a nivel de proyecto a Claude. Cada vez que se inicia una sesión de Claude Code, este lee y carga automáticamente el contenido de este archivo, integrándolo en cada conversación como contexto a nivel de sistema.

En términos sencillos,CLAUDE.mdes un manual de trabajo que le escribes a Claude en el proyecto: le indicas qué es este proyecto, qué normas seguir y qué precauciones hay, para que cada vez pueda trabajar de acuerdo con los requisitos del proyecto, en lugar de tener que volver a explicarlo en cada conversación.

La función de CLAUDE.md

SinCLAUDE.mdCLAUDE.md, Claude entiende tu proyecto desde cero cada vez; tienes que repetirle: qué gestor de paquetes usar, cuál es el estilo de código, cómo ejecutar las pruebas, qué archivos no tocar... ConCLAUDE.mdCLAUDE.md, esta información solo se escribe una vez y Claude la cumplirá cada vez.

En concreto,CLAUDE.mdCLAUDE.md puede ayudarte a lograr lo siguiente:

• Unificar el comportamiento del equipo: envía el archivo a git y todos los miembros del equipo seguirán las mismas normas al usar Claude Code.
• Reducir la comunicación repetitiva: las convenciones del proyecto, las reglas de arquitectura y los asuntos prohibidos se escriben una sola vez y tienen efecto permanente.
• Reducir la probabilidad de errores: indícale claramente a Claude qué operaciones son arriesgadas para evitar que tome decisiones incorrectas.
• Acelerar la comprensión de la IA: ayuda a Claude a localizar rápidamente archivos clave y comprender la estructura del proyecto, reduciendo exploraciones innecesarias de archivos.

Ubicación del archivo

Claude Code cargará CLAUDE.md desde varias ubicacionesCLAUDE.md: los archivos en diferentes ubicaciones tienen distintos alcances:

Cuando existen múltiples ubicacionesCLAUDE.mdcon CLAUDE.md, Claude Code lascargará y fusionará todas. La prioridad, de mayor a menor, es:

Local del proyecto → Directorio raíz del proyecto → Subdirectorio → Nivel de usuario global

La del directorio raíz del proyectoCLAUDE.mdSe recomienda enviarla a git para que todo el equipo comparta el mismo conjunto de normas de trabajo con IA.

Las preferencias personales (como no gustar los puntos y comas) se colocan en.claude/CLAUDE.mdCLAUDE.md local y se añaden a.gitignore.gitignore, sin afectar a los demás.

Crear CLAUDE.md rápidamente

La forma más sencilla es dejar que Claude Code genere automáticamente la versión inicial. Después de iniciar Claude Code en el directorio del proyecto, ejecuta:

/init

Claude Code analizará la estructura de tu proyecto, el estilo de código y los archivos de configuración existentes (comopackage.json、pyproject.toml、.eslintrcpackage.json, etc.) y generará automáticamente un CLAUDE.md acorde con la situación real del proyecto,CLAUDE.mdy luego puedes complementarlo y ajustarlo sobre esa base.

También puedes crearlo manualmente en el directorio del proyecto:

touch CLAUDE.md

Estructura del contenido del archivo

CLAUDE.mdCLAUDE.md es un archivo Markdown normal, sin requisitos de formato obligatorios, pero una buena estructura ayuda a Claude a encontrar información clave más rápido. A continuación se muestra la estructura de contenido recomendada:

# 项目名称

一句话说明这个项目是什么，方便 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

Explicación detallada de los módulos de contenido principales

1. Comandos comunes

Esta esCLAUDE.mdMediola parte más consultada con frecuencia. Al ejecutar tareas como pruebas, compilación o revisión de código, Claude buscará primero los comandos definidos aquí para evitar adivinar o usar comandos incorrectos:

## 常用命令

### 安装依赖
```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. Descripción de la estructura del proyecto

Ayuda a Claude a localizar archivos rápidamente y reduce escaneos innecesarios de directorios, especialmente efectivo en proyectos grandes:

## 项目结构

```
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. Normas de codificación

Informa a Claude sobre el estilo de código y las convenciones del proyecto, asegurando que el código generado sea coherente con la base de código existente:

## 编码规范

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

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

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

4. Restricciones de arquitectura y asuntos prohibidos

Esta es la parte clave para evitar que Claude tome decisiones "inteligentes pero incorrectas". Las situaciones especiales que tú conoces pero Claude desconoce deben escribirse explícitamente:

## 架构约束

- 所有数据库查询必须通过 `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. Descripción del entorno de desarrollo

Ayuda a Claude a comprender el entorno de ejecución del proyecto, evitando fallos en la ejecución de comandos debido a diferencias de entorno:

## 开发环境

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

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

Configuración para repositorios multimódulo (Monorepo)

En un Monorepo, puedes poner un CLAUDE.md global en la raíz del repositorioCLAUDE.mdy en cada subpaquete colocar su propio CLAUDE.md.CLAUDE.mdCuando Claude abre un archivo de un subpaquete, cargará simultáneamente los dos archivos: el de la raíz y el del directorio del subpaquete:

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` o  `api`（防止循环依赖）
- 跨包引用使用包名（如 `@my-app/shared`），不要使用相对路径

Usar la sintaxis @ para hacer referencia a archivos externos

Cuando el proyecto ya tiene documentos de normas (como especificaciones de diseño de API, documentos de diseño de base de datos, etc.), no es necesario copiar el contenido enCLAUDE.mdCLAUDE.md; simplemente usa@ruta-del-archivopara hacer la referencia.

Claude, al leerCLAUDE.mdCLAUDE.md, cargará automáticamente el contenido de los archivos referenciados:

## 规范文档

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

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

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

La ruta del archivo referenciado es relativa al directorio donde se encuentraCLAUDE.mdCLAUDE.md. El contenido de los archivos referenciados ocupa la ventana de contexto; evita referenciar archivos demasiado grandes (se recomienda que cada archivo referenciado no supere las 500 líneas).

Sugerencias para el uso de CLAUDE.md global

El CLAUDE.md a nivel de usuario~/.claude/CLAUDE.mdes adecuado para almacenar preferencias y hábitos personales comunes entre proyectos; estos contenidos son efectivos en todos los proyectos:

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

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

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

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

Sugerencias para el mantenimiento de CLAUDE.md

1. Mantener la concisión

CLAUDE.mdEl contenido de CLAUDE.md ocupa la ventana de contexto en cada sesión. Un contenido excesivo comprimirá el espacio de contexto realmente disponible para Claude, reduciendo la eficiencia. Se recomienda seguir los siguientes principios:

• Escribe cada regla solo una vez; no repitas el mismo significado
• No incluyas información de fondo no relacionada con el código (como presentaciones de la empresa o planificación de productos)
• La información que puede transmitirse mediante el propio código (como la configuración de eslint que ya define el estilo de código) no necesita declararse enCLAUDE.mdCLAUDE.md repetidamente.
• Se recomienda mantener el total en menos de 500 caracteres; si supera los 1000, es necesario considerar simplificarlo.

2. Actualización continua

Con la evolución del proyecto,CLAUDE.mdCLAUDE.md también debe actualizarse. Las siguientes situaciones deberían provocar una actualización:

• Cambio de gestor de paquetes o herramienta de compilación
• Adición o eliminación de bibliotecas de dependencias importantes
• Adopción de nuevas convenciones de codificación
• Descubrir que Claude comete repetidamente el mismo tipo de error (indica que es necesario añadir una aclaración enCLAUDE.mdCLAUDE.md)
• Algún archivo o módulo se vuelve no modificable al azar (añádalo a las notas de precaución)

3. Usar lenguaje imperativo

Cuanto más claras sean las instrucciones, mayor será la probabilidad de que Claude las cumpla. Evita descripciones vagas y usa órdenes directas:

Ejemplo completo

A continuación se muestra un CLAUDE.md completo de un proyecto full-stack Node.js + TypeScriptCLAUDE.mdque puede servir como plantilla de referencia para tu proyecto:

Preguntas frecuentes

P: ¿Qué hacer si Claude no sigue las reglas en CLAUDE.md?

Primero verifica si la redacción de la regla es lo suficientemente clara (consulta la sugerencia anterior sobre "usar lenguaje imperativo"). Si la redacción ya es clara pero aún así no la sigue, puedes enfatizarla nuevamente en la conversación específica, o colocar la regla en una posición más adelantada del archivo: Claude presta más atención al contenido de la primera mitad del archivo.

P: ¿Es mejor que CLAUDE.md sea más largo?

No. Demasiado contenido tiene dos efectos secundarios: primero, ocupa la ventana de contexto, reduciendo el espacio de Claude para procesar tareas reales; segundo, las reglas importantes se pierden entre mucho texto y son menos propensas a cumplirse. Se recomienda revisar periódicamente y eliminar las entradas que ya no sean aplicables o tengan poco valor.

P: ¿Cuándo se carga el CLAUDE.md de un subdirectorio?

Cuando Claude abre o edita un archivo en ese subdirectorio, elCLAUDE.mdCLAUDE.md de ese subdirectorio se carga automáticamente. No necesitas decirle manualmente a Claude que lo lea; todo el proceso es automático.

P: ¿Se puede hacer referencia a otro CLAUDE.md dentro de un CLAUDE.md?

No se puede hacer referencia directa, pero puedes usar la sintaxis@ruta de archivopara hacer referencia al contenido de cualquier archivo Markdown. Si hay estándares compartidos entre módulos, se recomienda extraerlos a un documento independiente y luego en cadaCLAUDE.mduno usar@para referenciarlo.