ENGINEERING RULES
文件三：03_ENGINEERING_RULES.md
# 文件三：03_ENGINEERING_RULES.md
# 架构、代码与工程永久规则
版本：1.0
状态：长期有效
作用：防止 AI 随着项目变大，把代码写成无法维护的“毛线团”。
# 1. 总原则
代码首先必须：
- 正确。
- 其次：
- 可维护。
- 然后：
- 可扩展。
- 最后才是：
- 聪明。
禁止为了炫技引入不必要复杂度。
# 2. 单一职责
一个模块尽可能只负责一个主要职责。
- 避免：
- 一个文件同时：
- UI
- 数据库
- API
- 认证
- 缓存
- 日志
- 全做。
# 3. 分层原则
原则上保持：
`
UI
↓
业务逻辑
↓
Service
↓
API
↓
数据访问
↓
Database
`
避免跨层乱调。
# 4. 前端不得直接访问数据库
禁止前端包含：
- 数据库密码。
- 数据库连接。
- 管理员数据库能力。
# 5. API统一管理
不得每个组件随便：
`
fetch("http://...")
`
应建立统一API Client。
- 负责：
- Base URL。
- 认证。
- 超时。
- 错误处理。
- 状态码。
# 6. 配置与业务代码分离
以下必须尽可能配置化：
- API地址。
- 端口。
- 域名。
- 数据库地址。
- 第三方接口。
- 模型名称。
- 字体。
- 功能开关。
- 环境变量。
# 7. 禁止环境硬编码
正式业务代码禁止绑定：
- localhost。
- 192.0.2.10。
- 开发端口。
- 本地绝对路径。
- 个人电脑路径。
# 8. 模块边界
公共功能应抽离。
- 但禁止过度抽象。
- 规则：
- 重复一次：
- 可以接受。
- 重复两次：
- 关注。
- 重复三次以上：
- 评估公共抽象。
# 9. 禁止循环依赖
例如：
- A依赖B。
- B又依赖A。
- 必须拆分公共职责。
# 10. 控制文件体积
如果一个文件越来越大：
- 应分析是否职责过多。
- 但禁止为了“文件短”机械拆分。
# 11. 函数规则
函数应该：
- 职责明确。
- 名称可理解。
- 输入清晰。
- 输出稳定。
- 副作用可控。
# 12. 命名规则
禁止大量：
- a
- b
- x
- temp
- test1
- data2
- newnew
- final2
使用可以看懂意义的名称。
# 13. 禁止魔法值
例如：
`
if (role === 7)
`
应有清晰定义。
# 14. 错误必须处理
禁止：
`
try {
...
} catch {}
`
吞掉错误。
# 15. 异步必须处理失败
Promise。
- Fetch。
- Database。
- File。
- AI。
- Third-party API。
- 必须考虑：
- 成功。
- 失败。
- 超时。
# 16. API统一返回规范
尽可能统一：
`
{
"success": true,
"data": {},
"error": null
}
`
或项目既有标准。
- 不能不同接口完全随机返回。
# 17. HTTP状态码合理使用
200：
- 成功。
- 201：
- 创建成功。
- 400：
- 请求错误。
- 401：
- 未认证。
- 403：
- 无权限。
- 404：
- 不存在。
- 409：
- 冲突。
- 429：
- 频率限制。
- 500：
- 服务器错误。
# 18. 数据验证
前端验证：
- 用于用户体验。
- 后端验证：
- 用于安全和数据完整性。
- 后端验证不可省略。
# 19. 数据库操作原则
优先：
- 参数化查询。
- ORM安全接口。
- 事务。
- 索引。
- 分页。
禁止直接拼接用户输入形成SQL。
# 20. 数据迁移规则
修改数据库结构：
- 必须考虑已有数据。
- 不得直接：
- 删表。
- 删字段。
- 改字段类型。
- 而不考虑迁移。
# 21. 第三方依赖规则
新增依赖之前必须判断：
- 是否真的需要。
- 是否已有能力实现。
- 是否仍维护。
- 是否安全。
- 是否增加项目复杂度。
# 22. 禁止为了一个小功能安装巨大框架
能用现有能力安全完成，就不要随意增加依赖。
# 23. Lock文件必须保留
例如：
- package-lock.json。
- pnpm-lock.yaml。
- yarn.lock。
# 24. 不得擅自升级核心依赖
尤其：
- 框架主版本。
- 数据库。
- 认证库。
- 构建工具。
- UI框架。
升级必须说明影响。
# 25. 删除代码规则
删除前确认：
- 是否引用。
- 是否动态调用。
- 是否部署使用。
- 是否兼容旧逻辑。
# 26. 重构规则
重构必须满足：
- 业务行为尽可能不变。
- 接口尽可能不变。
- 数据不损坏。
- 测试重新通过。
# 27. AI修改代码必须最小化影响
修一个Bug：
- 优先改最少相关代码。
- 不得顺便把整个项目重新组织一遍。
# 28. 禁止无关修改
任务是：
- 修登录Bug。
- 不得顺便：
- 改首页。
- 换字体。
- 改目录。
- 升级框架。
- 重新命名几百个变量。
# 29. 临时代码规则
临时代码必须明确：
- TODO。
- TEMP。
- DEBUG。
- 并在上线前清理。
# 30. 日志代替随意console
开发期可以合理使用console。
- 生产环境应使用正式日志策略。
- 禁止留下大量：
- console.log(secret)
- console.log(password)
# 31. 环境分离
至少区分：
- development。
- production。
- 必要时：
- test。
# 32. 本地开发不能成为隐性依赖
项目不能依赖：
- 某个人电脑已有文件。
- 手工复制资源。
- 未记录环境变量。
- 历史缓存。
# 33. 干净安装必须能运行
目标：
- 项目代码
依赖声明
配置文档
- 即可重新搭建。
# 34. 每次修改必须记录
涉及文件。
- 修改原因。
- 影响范围。
- 配置变化。
- 依赖变化。
- 数据库变化。
# 35. AI完成编码任务后必须进行自检
至少：
- 语法。
- 引用。
- 类型。
- 构建。
- 受影响功能。
# 36. 代码通过 ≠ 任务完成
必须区分：
- 【代码写完】
- 【编译通过】
- 【运行通过】
- 【测试通过】
六大规则共同执行协议
以下内容同时适用于全部六份文件。
A. AI每次任务开始前
先阅读：
- 与当前任务有关的规则文件。
- 如果任务涉及多个领域：
- 全部读取。 例如：
- 修改登录：
- 必须读取：
- 01_REQUIREMENTS_RULES.md
- 03_ENGINEERING_RULES.md
- 04_SECURITY_RULES.md
- 05_TESTING_RULES.md 修改视觉：
- 读取：
- 01_REQUIREMENTS_RULES.md
- 02_DESIGN_SYSTEM_RULES.md
- 05_TESTING_RULES.md 准备上线：
- 六份全部读取。
B. 规则冲突优先级
如发生冲突：
- 安全与数据完整性 明确用户需求 产品规则 架构规则 设计规则 优化建议
C. AI不能自行修改规则
除非用户明确要求：
- “修改规则文件”。
- 否则：
- 这些文件只读。
D. 现有项目与规则冲突怎么办
不得为了符合规则立即大规模重写。
- 先输出：
- 规则：
- 当前实现：
- 差异：
- 严重程度：
- 建议迁移方式： 再决定是否修复。
E. 每次修改之前
先回答自己：
- 我正在解决什么问题？
- 哪些文件必须修改？
- 哪些文件不应该碰？
- 是否涉及数据？
- 是否涉及权限？
- 是否影响API？
- 是否影响UI？
- 如何验证？
F. 每次修改之后
必须检查：
- 代码是否能运行。
- 是否引入新错误。
- 相关功能是否正常。
- 是否影响其他模块。
- 是否需要更新文档。
G. 禁止假完成
以下情况不得说：
- “全部完成”。
- 仍有未测试。
- 仍有报错。
- Build失败。
- 接口未验证。
- 缺少环境。
- 第三方服务没测试。 应明确：
- 已完成：
- 未完成：
- 无法验证：
- 风险：
H. 修改范围原则
永远优先：
- 小范围。
- 可验证。
- 可回滚。
- 低耦合。 而不是：
- 一次改几十个无关文件。
I. 项目长期目标
本项目必须尽量保持：
- 可理解。
- 可修改。
- 可维护。
- 可测试。
- 可部署。
- 可恢复。
- 可扩展。
- 安全。 最终目标不是：
- “AI这次把它跑起来了。”
- 而是：
- “即使换一个AI、换一台电脑、换一个开发者，这个项目依然能够继续维护。”
AI任务统一结束报告模板
每一次AI开发任务结束，都使用：
本次任务
修改文件
新增文件
删除文件
修改功能
配置变化
依赖变化
数据库变化
安全影响
实际测试
Build状态
未验证内容
已知问题
后续建议
最后只能使用：
- ✅ 完成并验证
- ⚠️ 完成但仍有未验证项目
- ❌ 未完成
- 三种结论之一。