前两天受「新湘会」邀请，我做了一场关于企业 AI 项目编程经验的分享。下面这篇文章是根据分享内容整理的，方便阅读。
想表达的核心观点是：软件开发规范在 AI 编程时代不是变轻了，而是越来越重要。 后文会先从编程比赛和工具聊起，再落到文档、架构、测试、CI/CD 和协作。
1 自我介绍
首先，我做一下自我介绍。
我是方圆，学的计算机专业。在美团做过测试开发、前端开发，后来在星环科技做工作流、智能体平台开发。
业余也在 GitHub 做一些 AI 开源项目，比较受欢迎，上万次下载，几千人加我好友。另外也在网上分享 AI 文章，我的微信公众号是「方圆AI分享」。
2 从编程比赛到工具：AI 在变强，工具与方式也在变
编程比赛里感受到的变化
我想先讲一下我参加编程比赛的经历，让大家感受一下 AI 在编程方面的变化。
我之前在星环公司工作，公司会每半年举办一次编程比赛。现场应该有不少技术人员，相信大家了解过或者参加过编程比赛，和工作面试时的算法题差不多。
比赛一共需要答 5 个题目，限时 3 小时，可以联网查资料，但是不允许和别人讨论。题目难度还是比较大的，每届差不多有 500 人参加。基本上你能答对一道题，就能进入前 100 名，获得三等奖 500 元。
编程题和数学题差不多，需要平时一直刷题保持手感，很枯燥无聊。我不想刷题，打算试试借助 AI 回答问题。
第一次 是 2023 年，最先进的模型是 GPT-4。模型编程能力还不够好，输出的代码有很多错误，一道题也没有答出来。
第二次 参加是 2024 年初，GPT-4 升级成了 GPT-4 Turbo，明显感觉到编程能力在提升。只花了 10 分钟就答对了一道题，还剩 4 道题没有回答正确，但是能感觉到在对的方向了。最后，模型 API 成本 10 块钱，获得奖金 500 元，大家可以先对比一下这个数字。
第三次，2024 年末。最顶级的模型是 o1-preview，推理模型，还有 Sonnet 3.5，编程模型。
我用这两个模型，只花了 2 个小时，答对了 4 道题。我可以负责任地说，没有一行代码是我写的，完全是复制粘贴。模型成本 100 元，获得奖金 12000。
大家可以再看看这两个数字，100 和 12000。我们可以说使用 AI 的 ROI 很高，很少的投入能创造很高的价值；是不是也可以说 智力正在变得非常廉价，以前价值 12000 的智力，现在只值 100 块钱。
模型之上：工具与编程方式
刚刚是让大家感受一下，模型编程能力的进步趋势。在模型之上，还有 AI 编程工具和使用 AI 编程的方式。
最初的工具只能做代码补全，就是你按一下 Tab 键，AI 自动帮你写后面几行代码。代表软件有 Cursor 和 GitHub Copilot。
后面，模型编程能力进步，特别是 Sonnet 3.5 模型，是转折点。编程工具重大升级，出现了 Windsurf、Cursor Chat Composer 这类产品。这时候流行了一种叫 Vibe Coding 的编程方式，就是你不要手写一行代码，只给 AI 说要求，代码全部由 AI 生成。
但是这种方式呢，不太可靠，常用于原型项目或者简单项目这种对错误容忍度较高的场景。于是出现了一个叫 Kiro 的编程工具，它要求先生成需求文档、设计文档、任务文档，最后再写代码。与之对应的是 Spec 编程方式，就是先写文档，给 AI 描述清楚需求，再开始写代码。这是目前主流的 AI 编程方式，很多公司都在用。
最近一段时间，出现了比较火的驾驭工程（也有人讨论 Harness Engineering 等类似概念），追求自动收集反馈、自动改进，借助 AI 可靠、高效、长时间自动编程，目前还在早期探索阶段，各家都分享了实践方法，但是有些区别。对应的工具有 Cursor、Claude Code 和 Codex。
3 AI 很强，为什么没有明显提效？规范为什么反而更要紧
模型编程能力这么强，AI 编程工具这么多，该怎么把 AI 引入到软件开发流程中呢？还有就是为什么引入之后没有看到明显提效呢？
我认为，其中一个关键是大家忽略了软件工程规范。
软件工程里，哪些实践经验仍然重要
软件工程中提到了很多软件开发过程中的实践经验。
比如有敏捷开发，通过站会即时快速沟通，小步快跑、频繁迭代。
有 DevOps，不要只看到写代码阶段，软件开发是有很多阶段的，包括计划、编程、构建、测试、部署、上线、运维、监控，根据产品反馈开始新一轮的开发，循环起来。
还有代码规范，注意代码的架构设计，注意分模块组织代码，确保代码易读性、可扩展，这样才能方便后续修 bug、快速增加功能，保证代码长期可维护，而不是很快腐烂，变成屎山。
那么为什么要重视这些软件工程的规范呢？其实这些规范一直很重要，特别是在有了 AI 编程之后，它变得更重要了。
之前不按照这些规范来，短时间内是没有影响的。
人工写代码是缓慢的，之前没有 AI 的时候，一天能产出 100 行核心代码都算是高效的。
如果开发排期比较紧，程序员只能专注于功能实现，聚焦眼前的利益，赶紧写完紧急的功能和代码，跳过文档、测试等软件规范。长此以往，渐渐地代码质量越来越差，新同事上手代码越来越困难，但是这些都能忍受。
因为人写代码的效率太低了，这些代价需要很久缓慢地才能感受到，整个过程好比温水煮青蛙。
但是有了 AI 编程之后，如果还是像之前一样，随心所欲、为所欲为地开发软件，代价是非常巨大的。AI 写代码是很快的，一天时间就能生产成千上万行代码，把原来的代码改得面目全非，不遵守规范的代价是巨大的。
反过来说，如果让 AI 依照这些规范编程，AI 可以准确快速地写代码，比人的效率高很多倍，收益巨大。
4 文档、依赖与架构：把上下文给足
下面，我挑几个关键环节，说一下具体如何使用 AI。我会从文档讲到外部依赖和仓库约定，再到架构与模块划分，都是在解决「AI 眼里，这个项目到底长什么样」。
文档：Spec Coding 和 Vibe Coding
首先要讲的是文档，其实就是 Spec Coding 和 Vibe Coding 的区别。为什么企业要使用 Spec Coding 的方式编程呢？因为纯 Vibe Coding 很难保证代码的质量。在 Vibe Coding 时，往往是给 AI 说一句话或者几句话需求，让它实现某个功能。
这种需求是非常模糊的，比如告诉 AI，「给我做一个淘宝」或者「给我做一个微信」，这种一句话需求，AI 不可能生成满意的代码。
和 AI 沟通，其实在一定程度上就和人沟通一样。我们在和其他人沟通的时候，脑子里想法很多，但是说的并不全面，其他人可能并不能完全理解。也可能是自己想得不够清楚，无法用语言清晰地表达。
要给 AI 清晰地表达出自己的需求，要先写一个能精确描述自己需求的文档，这就是 Spec Coding。
文档的形式多种多样，可以像 Kiro 那样，和 AI 协作完成需求文档、设计文档、任务文档。
我更习惯让 AI 只生成一个需求文档。我会创建一个叫做 spec-rules.md 的文件，如 PPT 展示的这样。
会要求 AI：当用户提出一个需求的时候，要先创建需求文档，包括需求描述、需求模板、技术方案、待讨论事项，AI 要和用户一起协作，完善这个需求文档。
在需求文档结尾，AI 会问我们几个问题，逼迫我们说清楚，或者想清楚我们到底要做什么。
一般需要和 AI 讨论两三轮，需求就确认差不多了。借助这个文档，我们能够尽可能清楚地给 AI 表达我们要的功能。
需求文档的一个具体例子
看一个需求文档具体的例子，这是我让 AI 开发一个注册功能的需求文档。
可以看到，有需求描述：通过邮箱注册账号，发送一次性验证码。有需求目标：安全的注册流程、良好的用户体验等等。还有技术方案，可以看到有接口设计、安全风控要求。最后「已确认设计点」，就是和 AI 的讨论结果。
最开始 AI 会在文档中问我们一些问题，比如一次性验证码怎么存，新增数据库表还是放到 Redis；直接使用邮箱作为用户名，还是额外增加用户名等等。
告诉 AI 我们的想法，AI 就会把待讨论事项，改成已经确认的设计点。
我想强调的是，这个需求文档看着很多内容，其实大部分都是 AI 写的，我只写了很少的一部分。其他大部分比如接口设计，都是 AI 设计出来的，我们只需要审核微调，确认方案合理，直接就能使用了。
这是我常用的生成需求文档的方法，大家可以参考一下。
也有其他方法，大家也都可以尝试一下，比如 Cursor、Claude Code 都有一种模式叫做 Plan 模式，不写代码，只和你讨论需求。
还有一个非常火的 skill，叫 Superpowers，会问你非常多的问题，生成一个特别详细的开发文档。
依赖说明与 AgentS.md / CLAUDE.md
除了需求文档，有时候还需要给 AI 提供其他依赖服务的使用文档。比如当前仓库的代码，需要调用另外一个服务的接口。这个服务是公司内部其他项目组开发的，当前代码仓库没有这个服务的代码。如果不给 AI 说明这个接口的参数是什么、响应结构是什么，AI 肯定不知道，它就会瞎写。所以正确的做法是，对于没有代码的外部依赖，要把使用文档放到当前仓库中，方便 AI 查看。
利用好 AGENTS.md 或者 CLAUDE.md 文档，把重要文档的说明、AI 要遵守的规则沉淀到这个文件中。
还有想强调一点：代码是最好的文档。AI 能力已经足够强了，最好能直接让 AI 看代码。如果做不到的话，就提供文档，但是一定要做到 代码和文档的一致性。
架构设计和模块划分
要采用主流的架构设计，比如 MVC 等，要整理代码的目录结构，按照功能模块组织代码。比如对于后端代码，按照 controllers、services、core、models、tests 等目录组织代码。
因为 AI 上下文有限，分模块组织代码，可以方便 AI 只加载必要的上下文，避免无关上下文对 AI 造成干扰。具体落地时，可以先在仓库里看清楚 controllers 里有哪些文件，services、core、models、tests 里分别有哪些文件；再看某一个 service 文件的代码；如果其中的核心逻辑已经实现好了，只是交给 AI 去补全或扩展这一层，那么在实际操作里，AI 往往只需要读取和它直接相关的 core、models、schema 等代码，而不必把整仓无关文件都塞进上下文。
5 测试、流水线与线上：让规范「跑起来」
自动化测试
我之前做过测试开发，非常深切地知道自动化测试有特别多好处，尤其是 AI 编程时代。有些公司可能没有设立专门的测试开发岗位，但是你一定要做自动化测试。
第一个 是可以加快 AI 编程速度，提高 AI 编程质量。可以想象一下，如果代码中引入了自动化测试，当 AI 完成一部分功能代码后，可以让 AI 同时生成相应的测试代码（或者使用 TDD，先写测试用例，再写功能代码），然后立即让 AI 执行测试，AI 可以马上看到测试结果；如果测试报错了，AI 可以立即根据错误信息自动修复代码，重新进行测试，直到测试通过。这样程序员只需要重点关注测试代码就行了，检查测试用例是否齐全，边界情况是否都覆盖到了。
第二个 好处是积累测试能力。如果是人工测试，每当代码调整后，需要手工测试一遍，随着功能越来越多，手工测试时间越来越长，而且人工不稳定，容易出错。如果有了自动化测试，这些测试代码都是可以复用的，每次代码变更后都可以重复执行，比人工可靠高效。
还有很多好处，比如尽早发现问题，降低修复成本。还有提高对代码的信心：AI 生成的代码，我们往往心里没底，但是如果每次发布前都完整执行一次自动化测试，会更加放心。
我这里提到的是广义的自动化测试，除了单元测试、集成测试、端到端测试，还有代码构建测试、代码格式检查。
拿 Python 后端举例，单元测试一般用 pytest。写用例时，可以用 monkey_patch 动态改掉对外部服务的依赖，这样本地跑测试不必依赖其他服务已经可用；如果涉及数据库，也可以尽量用本地 SQLite 等方式把依赖收束住。同时要关注测试覆盖率；我们一般会要求大部分功能都有对应的单元测试。代码格式和规范检查这边，我自己常用 Ruff 做代码格式和规范检查。
前端侧可以再用一套组合：单元测试、组件测试可以用 Vitest；端到端测试可以用 Playwright。端到端测试往往最重、跑得最久，通常只覆盖最核心的用户路径就够了。另外，建议在 AGENTS.md（或项目里约定的同类文件）里写清楚：每次改完代码要先跑构建、lint、测试，发现问题就让 AI 按日志自动修，修到通过为止。
下面是一次从开发、自动测试、自动修复到所有测试用例通过的过程演示
CI/CD 与合并前的门禁
经过前面的步骤，代码的生成速度已经很高了，后面还需要确保代码发布和部署不要成为瓶颈。我们需要做自动触发流水线，也就是持续集成和持续部署。
主流的代码仓库像 GitHub、GitLab 都支持自动触发流水线，写几个 YAML 文件即可开启，如下图所示
可以在代码合并前，自动触发构建、格式检查、单元测试、集成测试等，起码要确保代码没有这种错误，才可以合并。
合并之后再次执行自动测试中提到的检查，确保代码没有问题。另外，还要触发自动打包镜像，自动部署到测试环境，快速验证。
除了远程仓库的自动触发，程序员的本地开发环境也可以设置自动触发器，借助 pre-commit 工具，每次在代码提交前格式化代码等。还有使用 Claude Code 等创建自动 commit 命令，生成风格统一的 commit log。
线上日志与监控
使用 incident.io 这类工具，借助 AI 分析线上日志，自动监控运维。
小结：规范、AI 与「驾驭工程」
总之，首先就是要遵循上面软件工程的规范，在关键阶段引入 AI 提效。
最近 harness engineering，就是驾驭工程，不是比较火嘛，我认为按照上面规范来实践，其实就是在做驾驭工程了。
我们可以畅想一下，把 DevOps 的各个阶段都实现了自动化、引入了 AI。当 AI 收到了故障信息，它可以拿到最近一段时间的运行日志，可以查看最新的代码，它就能生成修复方案、修复代码。然后推送到远程仓库，就会触发自动测试、自动打包镜像、自动部署，部署之后再采集日志，确认是否修复完毕，这样效率是不是提高了很多。
6 重构、团队与几条经验
重构要先稳住行为
现在，我想说一下关于软件重构的事。AI 编程之前的代码，应该很少有代码完全遵守软件工程的规范。重构的方向呢，就是逐渐向这些规范靠拢。
重构可能最担心的是重构后功能异常，不能使用了。
我认为重构首先要补全自动测试，确保后续重构代码的正确性。在重构之前，可以在线上采集一些真实的请求数据，还有响应数据，这些可以作为测试用例；这样系统在重构的时候，可以用这些测试数据做回归测试，确保重构之后功能是正常的。
新的项目，就不用说了，直接按照软件规范来就行了。
团队如何一起用好 AI
首先就是大家要注重文档的沉淀，自己脑子里想的 AI 是无法读取到的，要变成文档的形式放到仓库中，让自己电脑的 AI 可以看到，其他同事的 AI 也能看到。
还有就是，每个人单独负责一个完整的功能模块，减少沟通成本。AI 其实大大扩展了个人能力的边界，比如我是后端开发，但是使用 AI，我也能开发出不错的前端页面。
注意 Git 分支规范，这其实还是属于软件工程规范的问题。比如要有 feature、bugfix、hotfix 分支等；提交代码，先要创建对应的分支。
然后就是代码审查，特别是 AI 写的代码：除了要通过自动触发的流水线测试外，还需要有其他同事，或者其他 AI 来检查。
AI 代码审查工具有很多，比如 CodeRabbit、GitHub Copilot、Claude Code Action，这些工具都可以用 AI 审查提交的代码，并给出修改建议。如果无法使用这些现有工具，企业内部也可以自建工具，Claude Code Action 是开源的，可以参考实现。
下图是 CodeRabbit 一类工具在 PR 里给出审查意见时的界面示意；更关键的是在 GitHub（或同等平台）里把合并规则设严：例如必须通过全部 CI 检查，并且把审查里提出的修改建议都处理完（resolve）之后，才允许合并。这样 AI 写的代码也不会只靠「感觉看过」就进主干。
几条有用经验
一定要用最先进的 AI 模型，使用 Anthropic 的 Opus、Sonnet 系列，或者使用 OpenAI 的 GPT 系列。
鼓励员工使用 Cursor、Codex、Claude Code。
企业内部可以定期组织 AI 使用经验分享，传授 AI 使用经验。
组织 AI 编程比赛，可以不再是算法题，而是做 AI 产品或者提效 skill。
(完)
