AI编程翻车，常死在第一分钟

我以前判断一个 Coding Agent 好不好，喜欢看它能不能一口气改十几个文件。

现在我更在意另一件事：它开工前的第一分钟，到底读到了什么。

很多 AI 编程事故，不是模型突然变笨，也不是工具链不够先进。它从第一步就站错了地方：不知道这个仓库怎么启动，不知道哪条测试才算数，不知道哪个目录不能碰，不知道 PR 该交什么证据。

后面看起来像“Agent 乱改代码”，其实前面是人没给它铺轨道。

我踩过的坑：把规则当聊天内容

最早用 AI 写代码时，我也干过一件很偷懒的事：每次开新会话，复制一大段提示词进去。

“这是一个 TypeScript 项目。”

“请先看 README。”

“改完记得跑测试。”

“不要动某某目录。”

当时觉得挺精致，像是在训练一个懂事的助手。结果真实情况是：同样的规则，今天粘一遍，明天漏两句；这个人记得说测试命令，另一个人只说了需求；一次任务在根目录开，一次任务在子包里开，Agent 看到的上下文完全不同。

最麻烦的不是它不会做，而是它每次都像第一天入职。

你以为自己在“提示工程”，其实是在用嘴维护生产环境配置。

项目说明书，不是文档洁癖

最近几家工具的方向其实很一致。

OpenAI Codex 有 AGENTS.md，会在运行开始前读取全局和项目里的指令，并且按目录层级叠加；离当前工作目录越近的规则越靠后，也就更容易覆盖前面的通用规则。

GitHub Copilot 支持仓库级自定义指令，比如 .github/copilot-instructions.md，还支持路径级 instruction 文件，用来告诉 Copilot 这个仓库怎么构建、怎么测试、哪些约定不能破。

Claude Code 则有 CLAUDE.md、记忆文件和 Skills。官方文档里甚至把 /run、/verify 这类能力做成可复用技能，让 Agent 不是只“写完代码”，而是能按项目方式启动和验证。

这些东西表面看是配置文件，实际是 Agent 的入职手册。

如果一个团队已经开始让 AI 改仓库，却还没有一份给 Agent 看的项目说明书，我会默认它还停留在玩具阶段。

不是不能用，是每次都要赌。

真正该写进去的，不是口号

很多人第一次写 AGENTS.md 或 CLAUDE.md，会写成价值观宣言：

“代码要优雅。”

“保持简洁。”

“遵循最佳实践。”

这种话对人都不一定有用，对 Agent 更像噪音。

我现在更愿意写四类东西。

第一类是入口。

这个项目怎么装依赖，怎么启动，本地需要哪些环境变量，常见命令分别跑多久。比如 monorepo 里到底用 pnpm --filter，还是要先进某个 package；测试是全量跑，还是先跑受影响模块。

第二类是边界。

哪些目录可以改，哪些目录只读；哪些配置不能顺手重命名；哪些 migration、权限、账单、支付、审计相关改动必须停下来让人看。

第三类是验收。

改完以后最低要跑什么。不是笼统一句“run tests”，而是写清楚：改前端跑哪条，改 API 跑哪条，改 schema 要补哪类 snapshot，PR 描述里要贴什么证据。

第四类是已知坑。

比如某个测试第一次会超时，某个命令在本机和 CI 输出不一致，某个目录看起来废弃但其实线上还在引用。这些知识平时散在老员工脑子里，Agent 不会自动继承。

这四类写完，AI 编程的稳定性会比换一个更贵模型更明显。

我现在的做法：先给它一张开工卡

如果今天让我接一个新仓库，我不会第一步就让 Agent “帮我重构”。

我会先让它做一件更小、更无聊、但更值钱的事：生成一张开工卡。

这张卡只有几项：

• 项目做什么，最重要的入口在哪
• 安装、启动、测试、lint 的真实命令
• 哪些目录和文件属于高危区
• 改动后必须留下哪些验证证据
• 遇到失败时先查哪些日志、哪些已知问题

然后把这张卡沉淀到项目级说明文件里，而不是继续塞在聊天框。

这里有个反常识：写这张卡时，不要追求完整。

完整的文档通常没人维护。Agent 真正需要的是“开工前 60 秒必须知道的东西”。少一点，但每条都能影响行为。

我见过很多团队一上来就想做复杂多 Agent 编排、自动派单、自动评审。最后卡住的地方很朴素：Agent 连正确的测试命令都不知道，改完代码也不知道怎么证明自己没搞坏。

这不是智能问题，是交付流程问题。

分水岭不在会不会用 AI，而在能不能复用上下文

以后 AI 编程团队会有一个很明显的分水岭。

一类团队，每次开 Agent 都像开盲盒：靠人临时解释、靠模型现场猜、靠 reviewer 最后兜底。

另一类团队，会把仓库的工作方式逐步沉淀成机器可读的规则：项目说明、路径规则、验证脚本、技能命令、失败处理记录。

前者看起来也在用 AI，后者才是在把 AI 接进工程系统。

我的判断是：接下来很多人会高估“更强模型”的短期收益，低估“更清楚的项目说明书”的长期收益。

模型可以帮你写代码，但它不会凭空知道你们团队到底怎么交付。

如果你现在也在用 AI 写代码，可以回头看一眼自己的仓库：

一个新来的 Agent，开工前第一分钟能读到什么？

你们的规则是在文件里，还是还躺在某个人的嘴里？