最近圈子里聊 Codex 这类编码智能体的人越来越多但真正让我觉得聊到点子上的是这个标题从“写代码”到“设计环境”。初看有点反直觉代码不写难道让 AI 自己写吗实际用过一段时间后你会发现重点确实不在“写”上而在你怎么给智能体布置一个能干活、能干对活的场景。所谓“实战课”教的不是某条 prompt 怎么写而是怎么把项目上下文、工具链、验收标准、权限边界这些东西设计成一个智能体可以自主运转的“工作间”。这门课的受众其实很明确被 AI 编程助手“种草”过、但实际用起来总觉得“它不会干活”的开发者以及团队里准备把智能体引入日常开发流程的技术负责人。如果你以为它教的是 prompt 技巧可能会失望但如果你想知道为什么同一个 Codex有人用起来像实习生有人用起来像资深工程师那这门课正好能解答。1. 范式转变从“自己动手”到“交代语境”1.1 传统编程是“操作逻辑”智能体编程是“营造条件”传统开发里我们写每一行代码本质上是在向机器下达精确指令变量怎么存、循环怎么走、异常怎么抛。代码本身就是完整的逻辑描述人脑负责设计机器负责执行。但用 Codex 这类智能体时你的角色变了——你不是机器的操作者而是智能体的“合作对象”。你给它的不是一个函数实现而是一堆条件项目要解决什么问题、依赖哪些库、代码风格是什么、哪些文件可以动、哪些目录碰都不能碰。它拿到这些条件后自己去读代码、改文件、跑测试。这和“写代码”是完全不同的心智模型。传统编程里每一条指令都必须足够明确否则机器就懵。智能体不一样它擅长在模糊条件下做概率性推断所以你反而要花更多精力去“框定”它的活动范围。我见过很多人把 Codex 当搜索引擎用问它“这段代码怎么优化”然后它回答一坨文本完事。这不是智能体的正确打开方式。正确的方式是给它一个环境让它在这环境里自己动手改、自己验证、自己给你看结果。1.2 环境设计的三个核心维度实战课花了很大篇幅讲的其实就是环境设计的三个维度。第一个是上下文也就是智能体能看到什么。第二个是工具集也就是它能操作什么。第三个是反馈回路也就是它怎么知道自己做对了还是做错了。这三个维度相互作用缺一个环节智能体都会变成“看起来很聪明但帮不上忙”的玩具。上下文解决的问题是“看”。如果智能体只看到你临时丢给它的几句话它就只能凭训练数据里的惯性去猜你的项目长什么样。而如果你提前准备了项目说明、目录结构、接口文档、代码规范它就能基于真实情况做判断。工具集解决的问题是“做”。光会生成代码没有用得让它真正能读文件、改文件、执行命令、跑测试。反馈回路解决的问题是“改”。它改完代码后怎么知道有没有改坏有没有引入新 bug如果跑完测试全是红的它得能根据报错信息继续修正。这三个维度有点像你带一个新人入职先给他看部门手册再给他电脑和权限最后给他一个能跑测试的脚本。没有这些新人再聪明也只能干瞪眼。2. 实战课里的核心技术点拆解2.1 把需求拆成智能体能执行的任务很多人在实际使用中最挫败的时刻是给 Codex 提了一个“帮我优化一下项目”的需求然后它回了一堆建议并没有动手改代码。这其实不是它懒而是你给的需求粒度太粗。实战课里反复强调一件事智能体需要的是任务级的描述而不是目标级的愿景。什么叫任务级比如“把utils/date.ts里的格式化函数改成支持时区参数并更新所有调用点”。什么叫目标级比如“把这个项目的时间处理都优化一下”。前者有明确边界、明确对象、明确验收标准后者是开放题。智能体不是不能做开放题但它做开放题时往往选择最保守、最不会出错的道路结果就是给你写一堆建议文档。所以实战课教的内容里第一个核心技能是需求拆解。把一个大的功能描述拆成若干个子任务每个子任务有输入、有输出、有改动范围。拆的时候还要注意依赖关系比如先改数据结构再改调用方最后改测试。拆完之后把这些子任务写进一个文档或直接丢给智能体它会按你的步骤来。这个过程的本质是把你自己脑子里的“实现路径”外化成文字。很多人觉得这不还是我自己在想对但这个过程不是白费的——你想清楚了智能体才能执行你想不清楚它只能替你做一堆无用功。2.2 给智能体一张“项目地图”实战课里有一节专门讲“环境说明书”听起来有点像写 README但又有本质区别。普通 README 是给人类看的重点写“这项目是干嘛的、怎么安装、怎么用”。给智能体看的说明要重点写“这个项目的代码组织方式是什么、哪些是核心逻辑、哪些是自动生成文件、修改时要注意什么、测试命令是什么、lint 规则是什么”。我按课程里的思路整理过一份模板核心结构大概是这样的# 项目地图 ## 项目一句话目标 这是一个构建 REST API 服务的示例项目核心业务是用户注册与数据报表。 ## 技术栈与目录规则 - 后端某语言框架入口文件位于 src/main.js - 数据库某类型数据库schema 文件在 db/schema.sql - 所有 API 路由定义在 src/routes/ 目录下 - 测试文件放在 tests/ 目录对应源文件的同名 .test.js - 不要在 dist/ 与 node_modules/ 目录下修改任何内容 ## 构建、测试、运行命令 - 安装依赖npm install - 运行测试npm test - 启动服务npm start ## 修改规范 - 新增接口时必须同时补测试 - 不得修改公共工具函数签名除非同步更新所有调用点 - 错误提示统一使用中文格式参考现有代码风格写这份文档本身不复杂但它体现了一个关键思维转变你不再是给智能体一条临时指令而是给它一个持续可复用的“工作环境”。项目地图写好之后每次启动智能体都让它先读这份文档它后续的行为会稳定很多。我不知道你有没有体验过那种“每次让 AI 改东西都像对一个失忆的人重新交代一遍”的崩溃感——项目地图就是解决这个的。它不是一份死文档而是智能体的长期记忆锚点。2.3 定义工具边界与权限实战课里最“实战”的部分其实是讲权限的。Codex 这类智能体一旦接入终端就有了真实的文件读写能力和命令执行能力。这时候你面临的问题就不是“它会不会”而是“它能做什么、不能做什么”。课程里给了一个非常实用的思路用最小权限原则来设计智能体的工作空间。什么意思如果你只是让它重构一个模块那就只给它那个模块所在目录的写权限如果你不想让它碰线上配置那就把.env、deploy/这类关键目录设为只读或直接隐藏。你可以在环境说明里写清楚也可以在工具配置层做限制。两者的区别是说明是软约束智能体会尽量遵守但偶尔忽略工具配置是硬约束从机制上就禁止操作。我自己实际测试下来的感受是软约束写得好能把 90% 的问题挡在外面剩下的 10% 需要用硬约束兜底。比如你告诉它“不要修改db/schema.sql”它大概率不会改但如果你把那个文件改成只读权限它就彻底不能改了。实战课里不建议依赖软约束因为智能体偶尔会有“过度理解需求”的时候——你让它新增一个字段它顺手把另一个表也改了这在它看来是“合理的连带修改”对你来说却可能是一场灾难。3. 实操设计一个最小可用的智能体环境3.1 定义目标与验收条件纸上谈兵容易实际操作才见真章。课程里有一个完整案例我简化为“模拟项目X”目标是让 Codex 在这个项目上完成一个任务给现有的用户列表接口增加分页和筛选功能并且保证所有测试通过。这个任务的第一步不是写代码而是写验收条件。我和课程里的思路一样先把验收条件列清楚接口GET /users新增page、pageSize、keyword三个查询参数page默认值为 1pageSize默认值为 20最大不超过 100keyword可选非空时按用户名模糊匹配返回数据结构改为{ list, total, page, pageSize }原有测试全部通过新增分页相关测试覆盖率达到 90% 以上不修改任何数据库迁移文件验收条件写得越明确智能体的自由度就越受控。很多人觉得给智能体太多限制会束缚它的能力这个想法其实不对。智能体的能力体现在“给定约束下找到最优实现”而不是“无边界地自由发挥”。约束越清晰它越清楚自己的任务范围反而不容易跑偏。3.2 编写环境说明文档有了验收条件之后我按课程里的方法给模拟项目X写了一份精简版的项目地图放在仓库根目录的AGENTS.md里。文件内容不追求大而全只写智能体干活时真正需要的信息。一位有经验的朋友告诉我项目地图最忌讳的是“把 README 复制一遍”。智能体需要的是“决策规则”不是“项目介绍”。比如与其写“本项目使用某某框架”不如写“所有数据库查询必须走src/db下的封装方法禁止直接拼 SQL”。前者是信息后者是规则。智能体看到规则才会按你的方式做事看到信息只会增加上下文长度不一定产生正确行为。我写过一份相对精简的版本关键内容大概是# AGENTS.md ## 角色 你是一位资深某后端开发者。你的任务是完成用户列表接口的分页与筛选功能。 ## 约束 1. 只能修改 src/routes/users.js 和 src/services/userService.js 两个文件。 2. 新增辅助函数必须放在 src/utils/ 下并附带对应测试。 3. 禁止改动 db/ 目录下的任何文件。 4. 所有代码必须遵循项目的 ESLint 规则运行 npm run lint 检查。 5. 完成修改后必须运行 npm test确保全部通过。 ## 提示 - 用户表已有索引 idx_users_name模糊查询直接在 username 字段上操作即可。 - 分页参数校验可以参考 src/utils/validator.js 里已有的方法。写完之后我先在本地手动模拟了一遍流程发现只允许改两个文件的话有些逻辑实现起来会比较别扭。于是我微调了约束允许新增一个src/utils/paginate.js。这一步很重要——约束不是一成不变的而是需要根据实际任务动态调整的。课程里称之为“环境迭代”就是说环境和代码一样不是一次写好的是在跟智能体的协作过程中慢慢打磨出来的。3.3 设置可验证的反馈回路写完项目地图接下来的任务是配置测试命令。这个环节课程里讲得特别细因为它是智能体“自我纠错”的基础。简单的任务比如给接口加几个参数通常不需要额外的反馈机制项目自带的测试命令就够了。但如果是更复杂的重构课程建议你在环境里加一个自定义的验证脚本把 verify 步骤固化成一条命令。比如写一个npm run verify依次执行 lint、类型检查、单元测试、构建任何一个环节失败都会输出具体错误信息和退出码。这个做法的价值在于智能体在执行任务的过程中每次修改完代码会主动去跑这个命令然后根据报错信息进行下一轮修改。没有这个反馈回路它也能工作但只能靠“看代码”来判断写得对不对那是它最不擅长的部分。有了可执行命令它就能像人类工程师一样“改一下、跑一下、看结果”。我还给模拟项目X的工作空间加了一个非常简单实用的东西任务日志。也就是要求智能体在修改代码前先在项目根目录的handoff.md里写清楚它准备怎么改、改了哪些文件、每一项改动对应哪条需求。这样即使它在某个步骤上跑偏了我也可以通过日志快速定位。这个做法后来成为我所有智能体项目的标配。3.4 实际运行第一次就失败很正常环境搭好之后我实际让 Codex 开始跑任务。第一次结果并不理想主要是两个问题第一个问题是它把分页参数解析放到了userService里导致 Service 层拿到了req对象耦合了 HTTP 细节。第二个问题是测试覆盖率的检查没有做它只跑了原有测试新增用例写得很少。这两个问题都是环境说明里没有约束的部分。我原来的AGENTS.md只说了“不得修改哪些文件”但没有说“各层职责边界”。它选择了一种能通过测试但不优雅的实现方式这在“验收条件”层面是合格的但在“架构一致性”层面不合格。于是我在AGENTS.md里补充了职责说明- Service 层只接收纯参数不得直接依赖请求/响应对象。 - 参数解析逻辑放在路由层业务逻辑放在 Service 层。同时我把验收条件里的“新增分页相关测试覆盖率达到 90%”写得更显眼并告诉智能体必须用jest --coverage检查。之后第二次运行就顺利多了它生成了分页测试、分别覆盖了正常页、空列表、超过最大页数等场景全部通过。这个过程中的收获不是“它终于做对了”而是让我意识到多数失败不是智能体能力不够而是环境设计漏了信息。你补的每一条规则都是在教它怎么在你这个项目里像你一样思考。4. 常见问题与排查技巧实录4.1 智能体总是“答非所问”先查上下文污染用过一段时间之后我发现最容易让人血压升高的问题就是它经常绕开你想让它改的内容去改一些完全无关的东西。遇到这种情况我的第一反应不是质问它“为什么不听话”而是去检查会话上下文里有没有夹杂其他项目的片段。很多时候我在同一个对话里先让它修了 A 模块的 bug又让它做 B 模块的新功能Codex 就会把 A 模块的思路带到 B 模块里。解决方式很简单一个任务开一个会话并在环境说明里专门写一行“当前任务只针对本次需求忽略对话历史中与本次任务无关的内容”。这个动作听着蠢但真的能显著减少串频。智能体没有“遗忘”能力它只能通过系统提示和上下文的引导来倾斜注意力所以我们必须主动帮它清理“工作台”。4.2 智能体改了不该改的文件权限边界没设硬约束我有一次让智能体改一个 API 的返回值它改完之后顺带把另一个无关模块的缩进全部格式化了。这种问题靠文字约束基本无效因为它会觉得“统一格式是我职责范围内的事”。后来我直接在工具配置层把无关目录设置成只读它再也没碰过那些文件。教训就是能靠权限解决的问题不要靠 prompt 解决。如果项目里存在绝对不可变动的文件比如数据库迁移脚本、部署配置、锁文件那就用文件系统权限或工具配置把它们锁死。很多团队觉得这样做麻烦但麻烦一次能避免无数次“AI 自作主张”。这跟管理人类实习生是一个道理你不能指望新人自觉“只看该看的文件”你得把不该看的资料锁进柜子里。4.3 智能体反复修改同一段代码进入死循环这个问题的典型表现是它改一次代码跑一次测试发现失败再改一次又失败再改一次……二十轮之后依然失败。出现这种情况通常是它在上一个错误里做出了一个错误的假设却没有真正理解报错信息于是围绕同一个错误反复打转。课程里给了一个非常有效的办法设置“失败切换”机制。也就是在环境说明里写清楚如果同一测试连续失败 3 次停止修改回到最初的版本并输出一份“当前假设与报错分析”文档。这个机制强迫它跳出循环把问题重新描述一遍。很多人在这个过程中发现它重新描述问题时自己也会意识到错误出在哪。这个设计本质上是在给智能体注入“人类工程师的止损意识”。人写代码也会陷入钻牛角尖的状态但我们会强迫自己停一下重新审视智能体不会。它更像是“最大化得分”的模型如果当前动作在它看来是最合理的它会一直重复。所以我们要通过环境规则帮它建立“失败的退出条件”。4.4 速度很慢、成本很高怎么优化Codex 这类智能体的每次操作都会计入 token 消耗普通开发可能觉得无所谓但如果你让它处理一个大型仓库它可能会频繁读入大量文件还没开始改上下文已经塞满了。这个问题的核心是上下文管理。我的做法是尽量缩小初始上下文。不要让它“先浏览整个项目”而是只告诉它关键目录和关键文件的位置。比如在项目地图里明确写“阅读src/routes/users.js前先看src/utils/validator.js”而不是让它自己漫游。同时对于大型 repo可以为智能体单独创建一个“精简索引文件”把常被引用的类型定义、工具函数签名汇总到一个文件里它只需要读那一个文件就能获取大部分必要信息。成本优化还有一条很实用把不需要智能体做的事写进“禁止清单”比如“不要优化与本次任务无关的代码”“不要运行npm install”“不要执行迁移脚本”。每一条禁止项都是在帮它省下无谓的计算也是在帮你的账户省额度。从实际结果看一个设计良好的环境平均 token 消耗能比“裸奔”模式少一半以上。4.5 实战课真正值得学的是“环境设计”的心智模型说回标题本身从“写代码”到“设计环境”这个转变最大的障碍不是技能而是心智模型。传统开发者的第一反应永远是“代码怎么写”但智能体开发的第一反应应该是“条件怎么给”。代码最终由智能体生成但生成代码所需的约束、信息、工具和反馈全部来自你设计的环境。这就像你不再亲自下厨而是开了一家餐厅。你的职责不再是颠勺炒菜而是设计菜单、采购食材、制定标准、培训厨师。看起来你离厨房远了但菜品质量反而取决于你的管理能力。Codex 实战课教的就是这套管理能力怎么拆任务、怎么写地图、怎么设权限、怎么建反馈。这些技能本质上是一种“技术管理”能力不是传统意义上的编码能力。我个人实际操作中的体会是这门课结束后我看待智能体代码的方式变了很多。以前我关注“它生成的那段代码是否优雅”现在我更关注“它修改代码之前有没有读过完整上下文”“它跑测试失败后会不会继续追问报错信息”。代码优雅与否是结果环境设计得是否合理才是原因。最后再分享一个小技巧如果你准备在自己的项目里试这套思路别一上来就搞复杂的工具链配置。先拿一个中等规模的项目、写一份两页不到的AGENTS.md、设定一条反馈命令跑两三个真实任务。这比看十节课都管用。环境是试出来的不是想出来的。 
长河君 · 2026/10/21 17:38:06 · 阅读 1.2k 从写代码到设计环境：Codex编码智能体实战心法
最近圈子里聊 Codex 这类编码智能体的人越来越多但真正让我觉得聊到点子上的是这个标题从“写代码”到“设计环境”。初看有点反直觉代码不写难道让 AI 自己写吗实际用过一段时间后你会发现重点确实不在“写”上而在你怎么给智能体布置一个能干活、能干对活的场景。所谓“实战课”教的不是某条 prompt 怎么写而是怎么把项目上下文、工具链、验收标准、权限边界这些东西设计成一个智能体可以自主运转的“工作间”。这门课的受众其实很明确被 AI 编程助手“种草”过、但实际用起来总觉得“它不会干活”的开发者以及团队里准备把智能体引入日常开发流程的技术负责人。如果你以为它教的是 prompt 技巧可能会失望但如果你想知道为什么同一个 Codex有人用起来像实习生有人用起来像资深工程师那这门课正好能解答。1. 范式转变从“自己动手”到“交代语境”1.1 传统编程是“操作逻辑”智能体编程是“营造条件”传统开发里我们写每一行代码本质上是在向机器下达精确指令变量怎么存、循环怎么走、异常怎么抛。代码本身就是完整的逻辑描述人脑负责设计机器负责执行。但用 Codex 这类智能体时你的角色变了——你不是机器的操作者而是智能体的“合作对象”。你给它的不是一个函数实现而是一堆条件项目要解决什么问题、依赖哪些库、代码风格是什么、哪些文件可以动、哪些目录碰都不能碰。它拿到这些条件后自己去读代码、改文件、跑测试。这和“写代码”是完全不同的心智模型。传统编程里每一条指令都必须足够明确否则机器就懵。智能体不一样它擅长在模糊条件下做概率性推断所以你反而要花更多精力去“框定”它的活动范围。我见过很多人把 Codex 当搜索引擎用问它“这段代码怎么优化”然后它回答一坨文本完事。这不是智能体的正确打开方式。正确的方式是给它一个环境让它在这环境里自己动手改、自己验证、自己给你看结果。1.2 环境设计的三个核心维度实战课花了很大篇幅讲的其实就是环境设计的三个维度。第一个是上下文也就是智能体能看到什么。第二个是工具集也就是它能操作什么。第三个是反馈回路也就是它怎么知道自己做对了还是做错了。这三个维度相互作用缺一个环节智能体都会变成“看起来很聪明但帮不上忙”的玩具。上下文解决的问题是“看”。如果智能体只看到你临时丢给它的几句话它就只能凭训练数据里的惯性去猜你的项目长什么样。而如果你提前准备了项目说明、目录结构、接口文档、代码规范它就能基于真实情况做判断。工具集解决的问题是“做”。光会生成代码没有用得让它真正能读文件、改文件、执行命令、跑测试。反馈回路解决的问题是“改”。它改完代码后怎么知道有没有改坏有没有引入新 bug如果跑完测试全是红的它得能根据报错信息继续修正。这三个维度有点像你带一个新人入职先给他看部门手册再给他电脑和权限最后给他一个能跑测试的脚本。没有这些新人再聪明也只能干瞪眼。2. 实战课里的核心技术点拆解2.1 把需求拆成智能体能执行的任务很多人在实际使用中最挫败的时刻是给 Codex 提了一个“帮我优化一下项目”的需求然后它回了一堆建议并没有动手改代码。这其实不是它懒而是你给的需求粒度太粗。实战课里反复强调一件事智能体需要的是任务级的描述而不是目标级的愿景。什么叫任务级比如“把utils/date.ts里的格式化函数改成支持时区参数并更新所有调用点”。什么叫目标级比如“把这个项目的时间处理都优化一下”。前者有明确边界、明确对象、明确验收标准后者是开放题。智能体不是不能做开放题但它做开放题时往往选择最保守、最不会出错的道路结果就是给你写一堆建议文档。所以实战课教的内容里第一个核心技能是需求拆解。把一个大的功能描述拆成若干个子任务每个子任务有输入、有输出、有改动范围。拆的时候还要注意依赖关系比如先改数据结构再改调用方最后改测试。拆完之后把这些子任务写进一个文档或直接丢给智能体它会按你的步骤来。这个过程的本质是把你自己脑子里的“实现路径”外化成文字。很多人觉得这不还是我自己在想对但这个过程不是白费的——你想清楚了智能体才能执行你想不清楚它只能替你做一堆无用功。2.2 给智能体一张“项目地图”实战课里有一节专门讲“环境说明书”听起来有点像写 README但又有本质区别。普通 README 是给人类看的重点写“这项目是干嘛的、怎么安装、怎么用”。给智能体看的说明要重点写“这个项目的代码组织方式是什么、哪些是核心逻辑、哪些是自动生成文件、修改时要注意什么、测试命令是什么、lint 规则是什么”。我按课程里的思路整理过一份模板核心结构大概是这样的# 项目地图 ## 项目一句话目标 这是一个构建 REST API 服务的示例项目核心业务是用户注册与数据报表。 ## 技术栈与目录规则 - 后端某语言框架入口文件位于 src/main.js - 数据库某类型数据库schema 文件在 db/schema.sql - 所有 API 路由定义在 src/routes/ 目录下 - 测试文件放在 tests/ 目录对应源文件的同名 .test.js - 不要在 dist/ 与 node_modules/ 目录下修改任何内容 ## 构建、测试、运行命令 - 安装依赖npm install - 运行测试npm test - 启动服务npm start ## 修改规范 - 新增接口时必须同时补测试 - 不得修改公共工具函数签名除非同步更新所有调用点 - 错误提示统一使用中文格式参考现有代码风格写这份文档本身不复杂但它体现了一个关键思维转变你不再是给智能体一条临时指令而是给它一个持续可复用的“工作环境”。项目地图写好之后每次启动智能体都让它先读这份文档它后续的行为会稳定很多。我不知道你有没有体验过那种“每次让 AI 改东西都像对一个失忆的人重新交代一遍”的崩溃感——项目地图就是解决这个的。它不是一份死文档而是智能体的长期记忆锚点。2.3 定义工具边界与权限实战课里最“实战”的部分其实是讲权限的。Codex 这类智能体一旦接入终端就有了真实的文件读写能力和命令执行能力。这时候你面临的问题就不是“它会不会”而是“它能做什么、不能做什么”。课程里给了一个非常实用的思路用最小权限原则来设计智能体的工作空间。什么意思如果你只是让它重构一个模块那就只给它那个模块所在目录的写权限如果你不想让它碰线上配置那就把.env、deploy/这类关键目录设为只读或直接隐藏。你可以在环境说明里写清楚也可以在工具配置层做限制。两者的区别是说明是软约束智能体会尽量遵守但偶尔忽略工具配置是硬约束从机制上就禁止操作。我自己实际测试下来的感受是软约束写得好能把 90% 的问题挡在外面剩下的 10% 需要用硬约束兜底。比如你告诉它“不要修改db/schema.sql”它大概率不会改但如果你把那个文件改成只读权限它就彻底不能改了。实战课里不建议依赖软约束因为智能体偶尔会有“过度理解需求”的时候——你让它新增一个字段它顺手把另一个表也改了这在它看来是“合理的连带修改”对你来说却可能是一场灾难。3. 实操设计一个最小可用的智能体环境3.1 定义目标与验收条件纸上谈兵容易实际操作才见真章。课程里有一个完整案例我简化为“模拟项目X”目标是让 Codex 在这个项目上完成一个任务给现有的用户列表接口增加分页和筛选功能并且保证所有测试通过。这个任务的第一步不是写代码而是写验收条件。我和课程里的思路一样先把验收条件列清楚接口GET /users新增page、pageSize、keyword三个查询参数page默认值为 1pageSize默认值为 20最大不超过 100keyword可选非空时按用户名模糊匹配返回数据结构改为{ list, total, page, pageSize }原有测试全部通过新增分页相关测试覆盖率达到 90% 以上不修改任何数据库迁移文件验收条件写得越明确智能体的自由度就越受控。很多人觉得给智能体太多限制会束缚它的能力这个想法其实不对。智能体的能力体现在“给定约束下找到最优实现”而不是“无边界地自由发挥”。约束越清晰它越清楚自己的任务范围反而不容易跑偏。3.2 编写环境说明文档有了验收条件之后我按课程里的方法给模拟项目X写了一份精简版的项目地图放在仓库根目录的AGENTS.md里。文件内容不追求大而全只写智能体干活时真正需要的信息。一位有经验的朋友告诉我项目地图最忌讳的是“把 README 复制一遍”。智能体需要的是“决策规则”不是“项目介绍”。比如与其写“本项目使用某某框架”不如写“所有数据库查询必须走src/db下的封装方法禁止直接拼 SQL”。前者是信息后者是规则。智能体看到规则才会按你的方式做事看到信息只会增加上下文长度不一定产生正确行为。我写过一份相对精简的版本关键内容大概是# AGENTS.md ## 角色 你是一位资深某后端开发者。你的任务是完成用户列表接口的分页与筛选功能。 ## 约束 1. 只能修改 src/routes/users.js 和 src/services/userService.js 两个文件。 2. 新增辅助函数必须放在 src/utils/ 下并附带对应测试。 3. 禁止改动 db/ 目录下的任何文件。 4. 所有代码必须遵循项目的 ESLint 规则运行 npm run lint 检查。 5. 完成修改后必须运行 npm test确保全部通过。 ## 提示 - 用户表已有索引 idx_users_name模糊查询直接在 username 字段上操作即可。 - 分页参数校验可以参考 src/utils/validator.js 里已有的方法。写完之后我先在本地手动模拟了一遍流程发现只允许改两个文件的话有些逻辑实现起来会比较别扭。于是我微调了约束允许新增一个src/utils/paginate.js。这一步很重要——约束不是一成不变的而是需要根据实际任务动态调整的。课程里称之为“环境迭代”就是说环境和代码一样不是一次写好的是在跟智能体的协作过程中慢慢打磨出来的。3.3 设置可验证的反馈回路写完项目地图接下来的任务是配置测试命令。这个环节课程里讲得特别细因为它是智能体“自我纠错”的基础。简单的任务比如给接口加几个参数通常不需要额外的反馈机制项目自带的测试命令就够了。但如果是更复杂的重构课程建议你在环境里加一个自定义的验证脚本把 verify 步骤固化成一条命令。比如写一个npm run verify依次执行 lint、类型检查、单元测试、构建任何一个环节失败都会输出具体错误信息和退出码。这个做法的价值在于智能体在执行任务的过程中每次修改完代码会主动去跑这个命令然后根据报错信息进行下一轮修改。没有这个反馈回路它也能工作但只能靠“看代码”来判断写得对不对那是它最不擅长的部分。有了可执行命令它就能像人类工程师一样“改一下、跑一下、看结果”。我还给模拟项目X的工作空间加了一个非常简单实用的东西任务日志。也就是要求智能体在修改代码前先在项目根目录的handoff.md里写清楚它准备怎么改、改了哪些文件、每一项改动对应哪条需求。这样即使它在某个步骤上跑偏了我也可以通过日志快速定位。这个做法后来成为我所有智能体项目的标配。3.4 实际运行第一次就失败很正常环境搭好之后我实际让 Codex 开始跑任务。第一次结果并不理想主要是两个问题第一个问题是它把分页参数解析放到了userService里导致 Service 层拿到了req对象耦合了 HTTP 细节。第二个问题是测试覆盖率的检查没有做它只跑了原有测试新增用例写得很少。这两个问题都是环境说明里没有约束的部分。我原来的AGENTS.md只说了“不得修改哪些文件”但没有说“各层职责边界”。它选择了一种能通过测试但不优雅的实现方式这在“验收条件”层面是合格的但在“架构一致性”层面不合格。于是我在AGENTS.md里补充了职责说明- Service 层只接收纯参数不得直接依赖请求/响应对象。 - 参数解析逻辑放在路由层业务逻辑放在 Service 层。同时我把验收条件里的“新增分页相关测试覆盖率达到 90%”写得更显眼并告诉智能体必须用jest --coverage检查。之后第二次运行就顺利多了它生成了分页测试、分别覆盖了正常页、空列表、超过最大页数等场景全部通过。这个过程中的收获不是“它终于做对了”而是让我意识到多数失败不是智能体能力不够而是环境设计漏了信息。你补的每一条规则都是在教它怎么在你这个项目里像你一样思考。4. 常见问题与排查技巧实录4.1 智能体总是“答非所问”先查上下文污染用过一段时间之后我发现最容易让人血压升高的问题就是它经常绕开你想让它改的内容去改一些完全无关的东西。遇到这种情况我的第一反应不是质问它“为什么不听话”而是去检查会话上下文里有没有夹杂其他项目的片段。很多时候我在同一个对话里先让它修了 A 模块的 bug又让它做 B 模块的新功能Codex 就会把 A 模块的思路带到 B 模块里。解决方式很简单一个任务开一个会话并在环境说明里专门写一行“当前任务只针对本次需求忽略对话历史中与本次任务无关的内容”。这个动作听着蠢但真的能显著减少串频。智能体没有“遗忘”能力它只能通过系统提示和上下文的引导来倾斜注意力所以我们必须主动帮它清理“工作台”。4.2 智能体改了不该改的文件权限边界没设硬约束我有一次让智能体改一个 API 的返回值它改完之后顺带把另一个无关模块的缩进全部格式化了。这种问题靠文字约束基本无效因为它会觉得“统一格式是我职责范围内的事”。后来我直接在工具配置层把无关目录设置成只读它再也没碰过那些文件。教训就是能靠权限解决的问题不要靠 prompt 解决。如果项目里存在绝对不可变动的文件比如数据库迁移脚本、部署配置、锁文件那就用文件系统权限或工具配置把它们锁死。很多团队觉得这样做麻烦但麻烦一次能避免无数次“AI 自作主张”。这跟管理人类实习生是一个道理你不能指望新人自觉“只看该看的文件”你得把不该看的资料锁进柜子里。4.3 智能体反复修改同一段代码进入死循环这个问题的典型表现是它改一次代码跑一次测试发现失败再改一次又失败再改一次……二十轮之后依然失败。出现这种情况通常是它在上一个错误里做出了一个错误的假设却没有真正理解报错信息于是围绕同一个错误反复打转。课程里给了一个非常有效的办法设置“失败切换”机制。也就是在环境说明里写清楚如果同一测试连续失败 3 次停止修改回到最初的版本并输出一份“当前假设与报错分析”文档。这个机制强迫它跳出循环把问题重新描述一遍。很多人在这个过程中发现它重新描述问题时自己也会意识到错误出在哪。这个设计本质上是在给智能体注入“人类工程师的止损意识”。人写代码也会陷入钻牛角尖的状态但我们会强迫自己停一下重新审视智能体不会。它更像是“最大化得分”的模型如果当前动作在它看来是最合理的它会一直重复。所以我们要通过环境规则帮它建立“失败的退出条件”。4.4 速度很慢、成本很高怎么优化Codex 这类智能体的每次操作都会计入 token 消耗普通开发可能觉得无所谓但如果你让它处理一个大型仓库它可能会频繁读入大量文件还没开始改上下文已经塞满了。这个问题的核心是上下文管理。我的做法是尽量缩小初始上下文。不要让它“先浏览整个项目”而是只告诉它关键目录和关键文件的位置。比如在项目地图里明确写“阅读src/routes/users.js前先看src/utils/validator.js”而不是让它自己漫游。同时对于大型 repo可以为智能体单独创建一个“精简索引文件”把常被引用的类型定义、工具函数签名汇总到一个文件里它只需要读那一个文件就能获取大部分必要信息。成本优化还有一条很实用把不需要智能体做的事写进“禁止清单”比如“不要优化与本次任务无关的代码”“不要运行npm install”“不要执行迁移脚本”。每一条禁止项都是在帮它省下无谓的计算也是在帮你的账户省额度。从实际结果看一个设计良好的环境平均 token 消耗能比“裸奔”模式少一半以上。4.5 实战课真正值得学的是“环境设计”的心智模型说回标题本身从“写代码”到“设计环境”这个转变最大的障碍不是技能而是心智模型。传统开发者的第一反应永远是“代码怎么写”但智能体开发的第一反应应该是“条件怎么给”。代码最终由智能体生成但生成代码所需的约束、信息、工具和反馈全部来自你设计的环境。这就像你不再亲自下厨而是开了一家餐厅。你的职责不再是颠勺炒菜而是设计菜单、采购食材、制定标准、培训厨师。看起来你离厨房远了但菜品质量反而取决于你的管理能力。Codex 实战课教的就是这套管理能力怎么拆任务、怎么写地图、怎么设权限、怎么建反馈。这些技能本质上是一种“技术管理”能力不是传统意义上的编码能力。我个人实际操作中的体会是这门课结束后我看待智能体代码的方式变了很多。以前我关注“它生成的那段代码是否优雅”现在我更关注“它修改代码之前有没有读过完整上下文”“它跑测试失败后会不会继续追问报错信息”。代码优雅与否是结果环境设计得是否合理才是原因。最后再分享一个小技巧如果你准备在自己的项目里试这套思路别一上来就搞复杂的工具链配置。先拿一个中等规模的项目、写一份两页不到的AGENTS.md、设定一条反馈命令跑两三个真实任务。这比看十节课都管用。环境是试出来的不是想出来的。