102 lines
2.9 KiB
Markdown
Executable File
102 lines
2.9 KiB
Markdown
Executable File
# 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 交互
|
||
|
||
- 完成任务后简洁汇报：做了什么 + 关键变更 + 需要关注的点
|
||
- 遇到不确定的事情直接说，不要编造答案
|
||
- 大文件修改前确认用户意图
|
||
- 遇到编译/测试失败主动排查原因
|