Claude.md 编写指南

claude.md（或 CLAUDE.md）是 Claude Code 特有的项目上下文文件。将它放在项目根目录，Claude 会在每次对话时自动读取，从而获得关于你项目的持久化记忆。

与通用 AI 助手不同，有了 claude.md 后：

• 不需要每次解释项目使用的框架
• 不需要重复说明代码规范
• 不需要介绍项目目录结构
• Claude 从一开始就知道"正确的方式"

对比：有 vs 没有 claude.md

你：帮我写个登录功能

Claude：好的，我用 Express +
Session 来实现...

你：等等，我们项目用 Fastify +
JWT，不是 Express

Claude：抱歉，我重写...
（反复调整）

你：帮我写个登录功能

Claude：好的，根据项目规范，
使用 Fastify + JWT + Prisma，
按 src/modules/ 目录结构，
包含单元测试...

（一次到位）

一个完整的 claude.md 通常包含以下几个部分：

推荐顺序

1. 项目概述 — 让 AI 快速理解项目定位
2. 技术栈 — 明确使用的工具和版本
3. 开发规范 — 定义好代码的标准
4. 项目结构 — 说明组织方式
5. 其他补充 — 根据项目特点添加

1. 简洁但完整

2. 重"为什么"，轻"是什么"

不要只列文件名（Claude 能看到文件树），要解释：

• 为什么选择这种架构
• 业务逻辑有什么约束
• 有哪些约定俗成的做法

3. 使用清晰的结构化格式

• 使用 Markdown 标题分层
• 关键信息用列表或表格呈现
• 代码示例要简短、有代表性

4. 保持更新

5. 避免的内容

以下是通用模板，可根据项目类型选择：

Web 项目模板

# 项目概述
[项目名称] 是一个 [类型，如：电商平台/SaaS 工具]，
面向 [目标用户]，核心功能是 [一句话描述]。

## 技术栈
- **前端**: Next.js 14 + TypeScript + Tailwind CSS
- **后端**: Node.js + Express + tRPC
- **数据库**: PostgreSQL + Prisma ORM
- **部署**: Vercel (前端) + Railway (后端)

## 项目结构
```
src/
  components/     # React 组件（按功能模块分）
  hooks/          # 自定义 Hooks
  lib/            # 工具函数、配置
  pages/          # Next.js 页面路由
  server/         # tRPC 路由和逻辑
  styles/         # 全局样式
  types/          # TypeScript 类型定义
```

## 开发规范

### 代码风格
- 使用 TypeScript，严格模式开启
- 组件使用函数式 + Hooks
- 异步操作使用 async/await，不用回调
- 错误处理：使用自定义 Error 类，统一在 API 层处理

### 命名规范
- 组件：PascalCase（如：UserProfile.tsx）
- 函数/变量：camelCase（如：fetchUserData）
- 常量：UPPER_SNAKE_CASE
- 文件：与默认导出同名

### Git 规范
- 分支：feature/xxx, bugfix/xxx, hotfix/xxx
- 提交格式：`type: description`（如：feat: add login）
- 类型：feat, fix, docs, style, refactor, test, chore

## 常用命令
```bash
# 开发
npm run dev          # 启动开发服务器

# 构建
npm run build        # 生产构建

# 测试
npm run test         # 运行测试
npm run test:watch   # 监听模式

# 数据库
npx prisma migrate dev   # 运行迁移
npx prisma generate      # 生成客户端
```

## 重要约定
- 所有 API 调用必须通过 tRPC，不直接 fetch
- 表单验证使用 Zod，前后端共用 schema
- 图片必须使用 Next.js Image 组件
- 颜色值必须使用 Tailwind 预设，不手写 CSS

Python 项目模板

# 项目概述
[项目名称] 是一个 Python [类型，如：数据分析工具/CLI 应用]

## 技术栈
- **语言**: Python 3.11+
- **框架**: FastAPI / Django / Flask
- **数据库**: PostgreSQL / MongoDB
- **测试**: pytest
- **依赖**: Poetry / pipenv

## 项目结构
```
project/
  src/              # 源代码
  tests/            # 测试文件
  docs/             # 文档
  scripts/          # 脚本工具
  pyproject.toml    # 项目配置
```

## 开发规范

### 代码风格
- 遵循 PEP 8
- 使用 Black 格式化（行宽 88）
- 使用 isort 排序导入
- 类型注解：全部函数必须加类型提示

### 命名规范
- 类：PascalCase
- 函数/变量：snake_case
- 常量：UPPER_SNAKE_CASE
- 私有：_leading_underscore

## 常用命令
```bash
# 环境
poetry install       # 安装依赖
poetry shell         # 进入虚拟环境

# 开发
python -m src.main   # 运行应用

# 代码质量
black src tests      # 格式化
isort src tests      # 排序导入
mypy src             # 类型检查

# 测试
pytest               # 运行测试
pytest --cov=src     # 带覆盖率
```

## 架构说明
- 使用 Repository 模式处理数据访问
- 业务逻辑放在 Service 层
- API 层只处理请求/响应转换

案例 1：微服务架构项目

## 服务边界
项目包含以下微服务，每个服务独立仓库：
- `api-gateway`: 统一入口，路由分发，认证
- `user-service`: 用户管理，JWT 签发
- `order-service`: 订单处理，状态机管理
- `payment-service`: 支付对接，幂等性处理

## 服务间通信
- 同步：gRPC（内部服务调用）
- 异步：RabbitMQ（事件驱动）
- 避免循环依赖，使用事件解耦

## 共享规范
- 所有服务统一使用 protobuf 定义 API
- 错误码统一格式：{code, message, details}
- 日志格式统一，包含 trace_id

案例 2：开源库/工具项目

## 项目定位
这是一个 [功能描述] 的 TypeScript 库，
追求零依赖、轻量级、TypeScript 原生支持。

## 兼容性要求
- Node.js >= 16
- 浏览器：ES2018+
- 包体积：< 5KB gzipped

## API 设计原则
- 链式调用优先
- 支持 tree-shaking
- 提供 ESM 和 CJS 两种格式
- 零运行时依赖

## 发布流程
1. 更新 CHANGELOG.md
2. 版本号遵循 SemVer
3. npm run build 生成产物
4. npm publish --access public

案例 3：AI 应用项目

## AI 集成规范
- 使用 OpenAI API，gpt-4o 模型
- 所有 Prompt 放在 prompts/ 目录，按功能分文件
- 必须实现流式响应（SSE）
- 实现 token 使用量追踪和限制

## Prompt 管理
- 使用 LangChain / 自研模板系统
- Prompt 版本化，A/B 测试时切换
- 敏感内容过滤：调用内容审核 API

## 数据处理
- 用户数据脱敏存储
- 对话历史保存最近 10 轮
- 长文本分块处理，避免超限

写好 claude.md 的关键在于：提供 Claude 无法从代码中直接推断出的上下文。

• 项目定位和核心价值
• 技术选型和版本信息
• 代码规范和命名约定
• 架构决策和理由
• 常见陷阱和注意事项
• 团队特有的工作方式