Update from Sync Service

wiki/AI工程/ClaudeCode软件开发最佳实践.md

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