# CLAUDE.md — 软件开发最佳实践

> 本文件指导 Claude Code 在此项目中的行为。
> 创建日期：2026-05-04

## 核心原则

- **先理解，再动手** — 修改前先阅读相关文件，理解上下文
- **最小改动** — 只改必要的，不要动无关代码
- **保持风格一致** — 遵循项目现有代码风格
- **原子化提交** — 每次提交只做一件事

## 开发流程

### 每次修改后必须执行

```bash
git add -A && git commit -m "[AI] 简短描述做了什么"
```

提交信息格式：`[AI] 动词+名词`，例如：
- `[AI] 添加用户登录接口`
- `[AI] 修复分页参数越界`
- `[AI] 重构订单计算逻辑`

### 开发步骤

1. **需求确认** — 不清楚时先问，不要假设
2. **方案设计** — 大改动先写方案（`docs/` 目录下）
3. **小步实现** — 分步实现，每步可编译、可测试
4. **自动提交** — 每步完成后自动 git commit
5. **自检** — 运行 lint/test，确认无报错

## 代码规范

### 通用
- 变量/函数名用英文，语义清晰
- 函数不超过 50 行，超过考虑拆分
- 禁止魔法数字，用常量代替
- 错误处理必须覆盖，不要吞异常

### TypeScript / JavaScript
- 优先 `const`，需要改再用 `let`，不用 `var`
- 使用 async/await，不用回调地狱
- 接口定义在前，实现在后
- 使用 ESLint + Prettier，提交前自动格式化

### Python
- 遵循 PEP 8
- 类型注解必须（`def func(x: int) -> str:`）
- 使用 pyproject.toml 管理依赖

### Node.js
- 错误优先回调或 Promise，统一用 async/await
- 环境变量用 `.env`，不硬编码
- 日志用结构化格式（JSON）

## 测试

- 新功能必须写测试
- 修改后运行相关测试确认通过
- 测试命名：`describe('xxx', () => { it('should xxx', () => {}) })`
- 覆盖率不低于 80%

## Git 规范

- **分支命名**：`feat/xxx`、`fix/xxx`、`refactor/xxx`
- **提交前检查**：
  ```bash
  git diff --staged --name-only  # 确认变更范围
  ```
- **不要 force push** 除非明确要求
- **冲突处理**：保留双方代码 + 注释说明，让用户决定

## 文档

- 公共 API 必须有 JSDoc / docstring
- 复杂逻辑写注释解释 **为什么**，不是 **做了什么**
- 重大变更更新 `CHANGELOG.md`
- README 保持更新

## 安全

- **绝不提交密钥、Token、密码**
- 敏感信息用环境变量或密钥管理工具
- SQL 参数化，防注入
- 用户输入必须校验和转义

## 性能

- 数据库查询用索引，避免 N+1
- 大列表操作考虑分页或流式
- 缓存热点数据，设置合理过期时间
- 不要阻塞主线程

## 与 Claude Code 交互

- 完成任务后简洁汇报：做了什么 + 关键变更 + 需要关注的点
- 遇到不确定的事情直接说，不要编造答案
- 大文件修改前确认用户意图
- 遇到编译/测试失败主动排查原因