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

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

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

核心原则

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

开发流程

每次修改后必须执行

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
• 提交前检查：

  git diff --staged --name-only  # 确认变更范围
  

• 不要 force push 除非明确要求
• 冲突处理：保留双方代码 + 注释说明，让用户决定

文档

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

安全

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

性能

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

与 Claude Code 交互

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