CLAUDE.md 约定
CLAUDE.md 文件是 Claude Code 在项目中启动会话时自动读取的指令文件。它相当于 AI 的入门手册：告诉 AI 你使用的技术栈、代码的组织方式、要遵循的约定，以及如何连接 Almirant 等外部工具。
配置完善的 CLAUDE.md 决定了 AI 是生成通用代码，还是遵循你团队的架构、模式和约定。
文件放置位置
将 CLAUDE.md 放在仓库根目录：
your-project/
CLAUDE.md # <-- 此处
.claude/
skills/
settings.json
src/
package.json
Claude Code 会在打开项目时自动查找此文件，无需额外配置。
如果你使用 monorepo，可以在根目录放置一个 CLAUDE.md，并在子目录中添加其他文件。Claude Code 会将它们全部合并。
使用 Almirant 时应包含的内容
1. MCP 配置
最重要的是让 Claude Code 知道如何连接到 Almirant。请包含 MCP 服务器的 URL 和 API key 配置。
## MCP - Almirant
此项目已连接到 Almirant 进行任务管理。
在 `.claude/settings.json` 或 `.mcp.json` 中配置：
\```json
{
"mcpServers": {
"almirant": {
"type": "http",
"url": "http://localhost:3001/mcp?projectId=<your-project-uuid>",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
}
}
\```
使用 MCP 工具读取和更新工作项、看板及冲刺。
可以说明 MCP 配置的位置，但绝不要将 API key 直接写入 CLAUDE.md。请使用 .claude/settings.json（应添加到 .gitignore）或环境变量。
2. 项目描述
说明项目的基本情况以及所使用的技术。
## 项目描述
B2B 电子商务 Web 应用，使用以下技术构建：
- **前端**：Next.js 15 + React 19 + TypeScript + Tailwind CSS
- **后端**：Bun + Elysia + Drizzle ORM
- **数据库**：PostgreSQL 16
- **认证**：Better-Auth 与 Google OAuth
- **测试**：Vitest + Playwright
3. 仓库结构
说明代码的组织方式，以便 AI 能高效导航。
## 结构
\```
src/
domains/ # 领域模块（DDD）
users/
domain/ # 类型和接口
application/ # Hooks 和用例
presentation/ # 组件和容器
orders/
products/
components/ui/ # 共享组件（shadcn/ui）
lib/ # 工具函数、API client、认证
\```
4. 代码约定
定义 Claude Code 生成代码时应遵循的规则。
## 约定
- **文件**：kebab-case（`user-service.ts`、`order-form.tsx`）
- **组件**：PascalCase（`UserProfile`、`OrderList`）
- **Hooks**：使用带 `use` 前缀的 camelCase（`useUserProfile`、`useOrderList`）
- **不使用类**：采用函数式编程，使用纯函数、自定义 Hooks 和函数式对象
- **类型**：放在 `domain/types.ts`，不要放在 `.tsx` 组件内
- **`.tsx` 组件**：仅负责展示，不使用 useState、useEffect 或业务逻辑
- **逻辑**：放在 `application/hooks/` 内的自定义 Hooks 中
5. 项目命令
包含 Claude Code 可能需要执行的命令。
## 命令
\```bash
bun run dev # 开发服务器
bun run build # 生产构建
bun run lint # Linter
bun run test # 测试
bun run type-check # 类型检查
bun run db:generate # 生成迁移
bun run db:migrate # 应用迁移
\```
6. 代码模式
记录希望 AI 复用的具体模式。
## 模式
### 使用 React Query 的 API 调用
所有 API 调用都使用带有结构化 query key 的 React Query：
\```typescript
export const userKeys = {
all: ['users'] as const,
list: (filters: UserFilters) => [...userKeys.all, 'list', filters] as const,
detail: (id: string) => [...userKeys.all, 'detail', id] as const,
};
export const useUsers = (filters: UserFilters) => {
return useQuery({
queryKey: userKeys.list(filters),
queryFn: () => usersApi.getAll(filters),
});
};
\```
### 带失效处理的 Mutations
\```typescript
export const useCreateUser = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: usersApi.create,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: userKeys.all });
},
});
};
\```
7. 项目专属规则
包含 AI 必须遵守的限制或业务规则。
## 规则
- **绝不**直接执行 SQL。使用 Drizzle ORM + migrations
- **绝不**提交 `.env` 文件或凭据
- **绝不**修改 `migrations/meta/` 中的文件
- 工作项没有 `status` 列，状态由看板列派生
- 工作项使用 `archived_at`（timestamp）而非布尔值来归档
- 认证使用 `better-auth.session_token` cookie
完整示例
# CLAUDE.md
## 项目
B2B 工业产品分销电子商务。
**Stack**: Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + Elysia + Drizzle ORM + PostgreSQL 16
## MCP - Almirant
通过 MCP 进行任务管理。配置位于 `.mcp.json`。
实现前使用 MCP 工具读取工作项，并在完成后
更新状态。
## 结构
\```
src/
domains/ # DDD 模块
catalog/ # 产品和分类
orders/ # 订单和开票
customers/ # B2B 客户
components/ui/ # shadcn/ui
lib/ # API client、认证、工具函数
\```
## 约定
- 文件使用 kebab-case
- 组件：仅负责展示（`.tsx` 中不使用 Hooks）
- 逻辑：自定义 Hooks 放在 `application/hooks/`
- 类型：放在 `domain/types.ts`
- 不使用类：仅使用函数、Hooks 和接口
## 命令
\```bash
bun run dev # 开发服务器（端口 3000）
bun run build # 生产构建
bun run lint # ESLint
bun run test # Vitest
bun run db:generate # 生成迁移
bun run db:migrate # 应用迁移
\```
## 模式
### React Query
按领域组织结构化 query key。
Mutations 会在 onSuccess 中使相关 query 失效。
### API Client
模块位于 `lib/api/client.ts`：
- catalogApi.getProducts(filters)
- ordersApi.create(data)
- customersApi.getById(id)
## 规则
- 绝不使用直接 SQL，始终使用 Drizzle + migrations
- 绝不提交 `.env`
- 订单确认前必须验证库存
- 价格在服务端计算，绝不信任前端
高级建议
按受众划分
如果团队中有不同角色（前端、后端、DevOps），可以使用标题明确的章节，让每个 skill 或工作流知道在哪里查找相关信息。
保持更新
将 CLAUDE.md 视为活文档。更改模式、约定或项目结构时，请更新此文件。过时的指令可能导致 AI 生成不一致的代码。
不要记录显而易见的内容
无需记录 React 或 TypeScript 的工作原理。专注于你的项目特有内容：内部约定、自定义模式和业务限制。
与团队一起验证
与 skills 一样，CLAUDE.md 也由 Git 进行版本管理。发生重大变更时，请在 code review 中审查它，以确保整个团队保持一致。
绝不要将凭据、API keys、tokens 或生产环境 URL 直接写入 CLAUDE.md。此文件由 Git 进行版本管理，并且对整个团队可见。请使用环境变量或 .gitignore 中的配置文件。