AI编程实战复盘：决定项目成败的6条工程规则

引言：AI编程真正难的不是"写"，而是"对"

如果你最近也在用 Codex、Claude、Cursor 之类的 AI 编程工具做真实项目，我想先说一个不太"爽文"的结论——决定项目成败的，往往不是模型会不会写代码，而是你有没有给它一个能稳定闭环、持续纠错、逐步收敛的工程环境。

前段时间，作者基于自己已有的待办服务端，尝试用 Codex CLI 加 OMX Codex 做一个 Android 客户端。过程非常典型：一开始推进很快，后面不断出现分页 bug、导航闪退、详情页空白、表单交互别扭、列表状态不同步……最后花了大量时间，不是在让 AI 生成代码，而是在修 AI 与工程现实之间的错位。

很多人对 AI 编程的期待还停留在"一句 prompt 换来一个可运行功能"，但只要项目稍微进入真实场景，你很快就会发现 AI 最容易失误的地方并不是语法，而是：上下文有没有继承、环境能不能自验证、接口契约是否足够严格、架构是否顺着平台主流路径走、UI/UX 约束有没有提前写清、任务拆分是不是足够小且可验证。

换句话说，AI 写代码的上限，取决于你的工程约束写得有多详尽。 下面这 6 条规则，就是这次项目里最有价值的复盘。

规则一：跨项目上下文没打通，AI 就会重复交学费

这次做 Android 客户端时，作者其实已经在另一个端里对齐过一部分产品边界和 UI/UX 取向——什么该做、什么不该做、哪些交互应该默认这样处理。但这些上下文没有被系统化沉淀下来，结果到了 Android 项目，AI 又重新走了一遍需求澄清、边界试探、风格判断、交互猜测的过程。

这类损耗在 AI 协作里非常隐蔽，因为它看起来不像 bug，更像"模型又理解偏了"。其实不是模型突然变差，而是你没有把上一个项目里已经付过代价的知识，变成下一个项目的默认前提。

可复用行动： 在工作流里新增一层全局上下文文件（如 global_rules.md），专门记录产品边界、默认 UI/UX 规范、架构禁区与偏好、常见非目标、验收口径、以及你允许 AI 自主决定的范围。每次开新项目时，先让 AI 读这份规则再进入需求和实现，质量会稳定很多。

背景知识：全局上下文文件与提示词工程

global_rules.md 这类全局上下文文件，本质上是「系统提示词」（System Prompt）的工程化落地。在大语言模型的对话架构中，System Prompt 具有最高优先级，能够持续影响模型在整个会话中的行为边界。然而大多数开发者只在单次对话中使用 System Prompt，而不是将其沉淀为可版本控制、可跨项目复用的工程资产。更进一步，这类文件还可以结合「检索增强生成」（RAG）机制，在项目规模扩大后按需注入相关规则片段，避免超出模型的上下文窗口限制（Context Window）。Anthropic 的 Claude 在其官方文档中也明确建议：对于长期协作场景，应将约束规则、角色定义和验收标准写入持久化的指令文件，而非每次重新口述。

规则二：没有可运行的本地环境，AI 就不是 Agent，只是高级补全

这次最致命的问题不是某个具体 bug，而是一个更底层的事实：终端环境里没有正确配置项目所需的运行时与构建工具，导致 AI 无法跑通最小验证命令。

结果就是 AI 没法完成它最关键的闭环——写代码→编译→看报错→自动修复→再验证。一旦这个闭环断掉，AI 的能力会立刻退化成"看起来很会写代码的文本生成器"。后面那些低级错误——函数参数传错顺序、框架 API 用法不符合约束、状态传递细节出错——本来都应该在它自己的验证环节里被拦住，最后却全都变成人肉测试成本。

背景知识：AI Agent 的工程闭环本质

Codex CLI、Claude、Cursor 等 AI 编程工具的底层架构差异决定了它们对工程环境的依赖程度。以 OpenAI Codex CLI 为例，它本质上是一个在本地终端运行的 Agent 循环（ReAct Loop），每一轮迭代包含「思考→行动→观察」三个步骤。当工具链不完整时，「观察」环节返回的是错误或空值，Agent 无法从中提取有效信号，整个推理链就会退化为纯文本预测模式。这与传统软件工程中的「快速反馈循环」（Fast Feedback Loop）原则高度吻合——测试驱动开发（TDD）之所以有效，正是因为它把验证周期压缩到秒级。AI Agent 的工程价值，本质上也是对这一原则的延伸：让机器自己完成「红-绿-重构」的循环，而不是把验证成本转嫁给人类。

核心结论： 能不能让 AI 跑通 build/test，决定了它是"工程代理"还是"代码生成器"。

可复用行动： 在任何技术栈开始前，先做四件事：

1. 确认终端里最基础的运行时、工具链、版本命令能正常工作
2. 确认项目对应的最小 build 命令能跑
3. 确认项目对应的最小 test 命令能跑
4. 确认 AI 自己也能调用这些命令

先让项目最小验证闭环成立，再进入大规模实现。这一步看起来像"环境杂活"，但它本质上是在决定——后面是 AI 自己 debug，还是你帮 AI debug。

规则三：API 文档不是注释，它本身就是 Prompt

这次项目里有两个典型问题：一是列表接口请求了"配置等于0"而服务端要求"配置大于等于1"；二是点击条目进入编辑页时，ID 因为包含特殊字符直接把路由拆坏了。

这两个 bug 的共同点是：AI 并不是胡来，它其实是在按一种很常见的"默认逻辑"做实现。如果接口契约或 schema 文档里没有明确写出取值范围、ID 格式约束、哪些字段必须编码校验，那 AI 很可能就会用"行业平均猜测