本页目录

本页目录

核心工程原则

目的

本指南规定 AI 辅助快速验证想法、开发 POC 时遵循的工程标准。

目标是让项目在快速推进的同时保持:

  • 简单
  • 一致
  • 可复现
  • 易于理解
  • 便于人和 AI Agent 维护
  • 架构不会无意走样
  • 跨仓库一致

核心原则:

凡是不需要项目单独决策的事项,一律标准化。

不要在每个项目中重新选择包管理器、格式化工具、Lint 工具、任务运行器、提交规范和预提交钩子。

产品和架构可以因项目而异,工程工具链则保持统一。

以验证速度为先

这类项目的首要用途是快速验证想法。

以下内容,确有必要再引入:

  • 抽象
  • 分层
  • 框架
  • 服务
  • 基础设施
  • 文档
  • 流程
  • 通用扩展能力

选择能解决当前问题的最简实现。

快速开发不等于草率行事:不要图一时省事而给日后留下混乱,或让 AI 辅助开发变得不可靠。

减少无谓选择

已经标准化的事项,不要反复决策。

指南指定了某项工具,就必须使用;例外须经用户明确批准。

不要仅因下列原因替换标准化工具:

  • 另一个工具更流行
  • 某个框架推荐了别的工具
  • 生成的模板用了别的工具
  • AI Agent 更熟悉别的工具
  • 网上的其他项目用了不同的工具

确实存在技术不兼容时,先向用户说明,再变更标准化工具链。

禁止悄悄替换工具。

优先选择主流、经过充分验证的方案

AI Agent 依据训练数据生成代码,而不是查阅实时文档。

刚发布的版本或小众技术栈在训练数据中出现较少,更容易因幻觉引发问题:崩溃、调错 API、行为不一致。

因此,默认选择主流、经过充分验证的方案:

  • 运行时使用 LTS 或成熟版本:默认用 Node.js Active LTS,机器学习用 Python 3.12。
  • 库优先选主流、文档完善的方案,不选刚发布或冷门的替代品。
  • 刚发布的主版本、小众框架和小众运行时(如基于 Bun 的技术栈)须经用户明确批准,并在项目 ADR 中记录理由。
  • 默认选型时,兼容性和稳定性优先于微小的性能提升。

选型时,把模型对该技术的熟悉程度与基准测试、功能列表一并纳入考量。

优先解决根本原因,不要掩盖症状

当出现警告、Lint 错误、测试失败、类型错误或其他校验问题时:

  1. 弄清该规则或检查在保护什么。
  2. 找出真正的根本原因。
  3. 只要合理,就修复底层问题。
  4. 先了解影响,再考虑调整配置。

禁止:

  • 盲目修改代码直到警告消失
  • 仅为让 CI 变绿而禁用规则
  • 未理解问题就添加忽略注释
  • 为了让测试通过而削弱测试
  • 掩盖失败而不解决

若某条规则确实不适合本项目,可以调整其配置,但必须意图明确、有技术依据。

最终原则

本指南旨在建立可预期的工程环境,让人和 AI Agent 能快速开展工作,不必反复选择同样的工具和工作流,也不必增加无谓的流程。

当某项选择与产品无关时:

将其标准化。

当版本或技术栈成熟度不同时:

选经过充分验证的那个。

当变更影响架构时:

明确写出来。

当校验未通过时:

先弄清原因。

当多种语言并存时:

保持它们的边界清晰。

当 AI Agent 参与项目时:

缩小不必要的决策空间,让正确做法成为默认。