核心工程原则
目的
本指南规定 AI 辅助快速验证想法、开发 POC 时遵循的工程标准。
目标是让项目在快速推进的同时保持:
- 简单
- 一致
- 可复现
- 易于理解
- 便于人和 AI Agent 维护
- 架构不会无意走样
- 跨仓库一致
核心原则:
凡是不需要项目单独决策的事项,一律标准化。
不要在每个项目中重新选择包管理器、格式化工具、Lint 工具、任务运行器、提交规范和预提交钩子。
产品和架构可以因项目而异,工程工具链则保持统一。
以验证速度为先
这类项目的首要用途是快速验证想法。
以下内容,确有必要再引入:
- 抽象
- 分层
- 框架
- 服务
- 基础设施
- 文档
- 流程
- 通用扩展能力
选择能解决当前问题的最简实现。
快速开发不等于草率行事:不要图一时省事而给日后留下混乱,或让 AI 辅助开发变得不可靠。
减少无谓选择
已经标准化的事项,不要反复决策。
指南指定了某项工具,就必须使用;例外须经用户明确批准。
不要仅因下列原因替换标准化工具:
- 另一个工具更流行
- 某个框架推荐了别的工具
- 生成的模板用了别的工具
- AI Agent 更熟悉别的工具
- 网上的其他项目用了不同的工具
确实存在技术不兼容时,先向用户说明,再变更标准化工具链。
禁止悄悄替换工具。
优先选择主流、经过充分验证的方案
AI Agent 依据训练数据生成代码,而不是查阅实时文档。
刚发布的版本或小众技术栈在训练数据中出现较少,更容易因幻觉引发问题:崩溃、调错 API、行为不一致。
因此,默认选择主流、经过充分验证的方案:
- 运行时使用 LTS 或成熟版本:默认用 Node.js Active LTS,机器学习用 Python 3.12。
- 库优先选主流、文档完善的方案,不选刚发布或冷门的替代品。
- 刚发布的主版本、小众框架和小众运行时(如基于 Bun 的技术栈)须经用户明确批准,并在项目 ADR 中记录理由。
- 默认选型时,兼容性和稳定性优先于微小的性能提升。
选型时,把模型对该技术的熟悉程度与基准测试、功能列表一并纳入考量。
优先解决根本原因,不要掩盖症状
当出现警告、Lint 错误、测试失败、类型错误或其他校验问题时:
- 弄清该规则或检查在保护什么。
- 找出真正的根本原因。
- 只要合理,就修复底层问题。
- 先了解影响,再考虑调整配置。
禁止:
- 盲目修改代码直到警告消失
- 仅为让 CI 变绿而禁用规则
- 未理解问题就添加忽略注释
- 为了让测试通过而削弱测试
- 掩盖失败而不解决
若某条规则确实不适合本项目,可以调整其配置,但必须意图明确、有技术依据。
最终原则
本指南旨在建立可预期的工程环境,让人和 AI Agent 能快速开展工作,不必反复选择同样的工具和工作流,也不必增加无谓的流程。
当某项选择与产品无关时:
将其标准化。
当版本或技术栈成熟度不同时:
选经过充分验证的那个。
当变更影响架构时:
明确写出来。
当校验未通过时:
先弄清原因。
当多种语言并存时:
保持它们的边界清晰。
当 AI Agent 参与项目时:
缩小不必要的决策空间,让正确做法成为默认。