Codex与AI编程代理实战：从提示词到MCP的完整指南

Agentic coding（代理式编程）正在成为软件开发的下一个范式转移。与早期用 ChatGPT 生成代码片段再粘贴进编辑器不同，编程代理直接驻留在编辑器中，具备读取代码库、编辑多个文件、运行命令与测试、并根据结果反复迭代的自主性。Scrimba 推出的这门实操课程以 OpenAI 的 Codex 为主线，系统讲解了如何稳定、高效且安全地驾驭这类工具。

据课程讲师 Tom Chant 介绍，目前编程代理领域的两大代表是 OpenAI 的 Codex 和 Anthropic 的 Claude Code，但 GitHub Copilot、Devin、Windsurf、Cursor 等工具同样活跃。代理正在从"某家公司或某个模型的附属品"演变为一个独立的工具类别，跨平台标准也在逐步形成——这意味着即使课程以 Codex 为主，学到的技能在整个行业都通用。

编程代理的三种形态与人类角色的重新定位

课程将编程代理的使用方式分为三类：CLI 命令行代理，深受习惯终端工作的开发者欢迎；IDE 内嵌代理，直接生活在 VS Code 等编辑器中；以及桌面或 Web 代理，通过图形界面隐藏底层开发流程，更适合不直接写代码的人。课程本身选择 IDE 形态，因为它兼具图形界面的友好性与贴近代码的优势，尤其适合 Web 开发。

一个关键判断是：人类开发者绝不冗余。原因有两层。表层原因是 AI 会犯错；更深层的原因是代理是复杂工具，使用不当会泄露密钥与客户数据、产出难以维护的劣质代码。同一款代理既能生成整洁、文档完善、易于扩展的代码，也能生成混乱、难维护的代码——差别在于人怎么用。从构思、开发到部署，人类输入不是锦上添花，而是必需品。

提示词工程：用"任务-上下文-输出"消除歧义

课程用一个送货记录应用演示了新手常犯的错误。当被要求添加一个"记录丢失包裹"的按钮时，代理直接复制了原有事件处理逻辑，只把"delivered"换成"lost"。代码能跑，但违反了 DRY 原则——代理倾向于新增代码而非重构，这会制造臃肿、难以维护的代码库。

核心结论是：坏结果源于歧义。提高提示质量的关键，是在三个方面降低歧义——任务是什么、使用哪些上下文、输出应该长什么样。课程给出了一个可复用的结构：Task / Context / Output。改进后的提示要求代理"检查现有代码并尽可能复用共享逻辑""避免重复的事件处理器"，最终产出了只有一个事件监听器和一个处理函数的干净实现。

另一个重要洞察是：Codex 更擅长模仿而非解释。如果在意代码风格与结构，与其描述想要什么，不如展示一两个范本函数，然后让代理照着写。课程还介绍了一个社区惯例——用 TODO(AI) 注释标记留给 AI 处理的任务，代理可以据此批量定位工作区。

AGENTS.md：给代理持久化的项目记忆

代理式编程有两个结构性问题。其一是对话历史不共享：把代码库交给同事时，你在对话中做出的所有规格说明（比如配色用微妙的绿色、HTML 采用 BEM 命名规范）都会丢失，同事无法区分哪些是深思熟虑的决策、哪些是代理的随意发挥。其二是上下文膨胀：每次提示都会发送此前的完整对话和相关代码，对话变长后信息会被截断。

解决方案是 AGENTS.md。通过斜杠命令 init 可以自动生成这份文件，内容包括项目名称、技术栈、项目结构、启动命令和关键编码模式。它会随每次提示一起发送并享有特殊优先级，因此既能在对话被截断时保留核心规格，也能让协作的同事和他们的代理无缝接续。课程强调要定期用 init 命令更新它。

AGENTS.md 支持多层结构：根目录的文件影响整个项目，子目录的文件只作用于其下的代码，全局层级的文件则位于主目录的 .codex 文件夹中、作用于你所有项目。优先级顺序是全局 → 项目 → 文件夹，越靠近相关代码的文件优先级越高。虽然与 Codex 关系密切，但 AGENTS.md 已成为跨工具惯例，Devin、Cursor、Windsurf 等均会读取。

计划模式：先想后做，把决策权留在人类手中

当任务复杂、模糊或难以描述时，计划模式（plan mode）会指示代理先思考、必要时提出澄清问题，并产出一份计划，且不修改任何代码。课程用博客应用添加"最近浏览文章"功能作为案例——这是个影响面广、实现路径多样的改动。

代理给出的计划中暴露出若干它替用户做出的决策：用 localStorage 持久化、只展示最近五篇。这些决策未必错误，但用户从未主动提问过。计划模式的价值正在于把这些隐含决策提前摊开，让人在写代码之前审视并修正。课程还引导学员处理一个边界情况：如果用户读过的文章随后被删除，它是否仍应出现在最近浏览中？代理最终给出的方案是静默跳过不存在的文章 ID。

计划模式与常见的“直接生成代码”模式形成对照：后者往往在模型尚未充分理解需求边界时就动手写文件，一旦方向错误，返工成本远高于先审阅计划。实践中，计划模式产出的计划通常包含改动范围、涉及文件、实现步骤与潜在风险，人类可以在这一步否决或修正方案，而不必等到代码写完再逐行审查。需要注意的是，计划模式并不能替代规格测试，它约束的是“做什么、怎么做”的决策顺序，而非验证行为正确性。

技能（Skills）：把知识、观点与工作流封装成可复用的工具

技能本质上是围绕提示词的可复用封装，提供一致且可复现的工作流。最简单的技能只是省去重复输入的指令，但技能的真正威力在于封装模型本身不具备的知识和观点。

课程展示了两个实用技能。其一是"house style"重构技能：项目里大部分代码遵循统一风格，唯独某个 service.ts 文件充满了难以理解的循环结构。创建技能时，提示词明确要求代理去检视五个遵循规范的模块目录、从中学习房规，然后通过斜杠命令加文件路径调用，代理在保留应用功能的前提下完成了重构。

其二是仓库专属的开发排障技能。课程给学员的挑战是：修复一个被自己弄坏的站点。这个技能不应是通用调试清单（代理本来就会通用调试），而应捕获该仓库特有的护栏、平台约束、锁定依赖版本和调试策略。最终这个技能在约一分钟内定位到 sqlite3 包的版本被升级到了与代码库不兼容的版本，并给出修复建议。

测试：特征测试与规格测试的双轨策略

课程用牙医诊所的预约组件演示了测试在代理式编程中的两种用法。该组件的业务逻辑经过多年需求堆叠已变得纠缠——周日休息、工作日固定时段、周五提前打烊、周六仅上午、午餐时段不排班、15 分钟粒度、过滤已过时段的开始时间、排除与午餐重叠的时段。

特征测试（characterization test） 用于保护已有且确认正确的行为：让代理生成一组通过状态的测试来锁定当前行为，然后在重构后自动运行。课程中代理生成测试时曾因时区和日期假设失败，自行修正期望值后全部通过；随后要求代理重构 scheduler.js 提升可读性，35 个测试全部通过，行为得到保护。课程强调测试应"窄而具体"地在开发中运行，合并部署前再跑一轮广覆盖测试。

规格测试（spec test） 则用于新功能，遵循测试驱动开发（TDD）思路：先写一个描述期望行为的失败测试，审阅测试确认它测的是你想要的，再让代理写代码让它变绿。课程用折扣码功能说明了为什么必须分开：如果让代理"同时写代码和测试"，它就是在给自己批改作业。课程演示了这种做法的危险——代理自行决定折扣按行项目计算还是按总额计算、如何舍入到两位小数，并把这一从未被提问过的政策决定写进了测试。改为规格测试后，提示明确要求"按总额计算、四舍五入到两位小数"，代理据此产出正确的实现与测试。

特征测试（characterization test）这一术语源自 Michael Feathers 的《修改代码的艺术》，原意是在重构遗留代码前，用测试把代码的“实际行为”（而非“应有行为”）固定下来，作为安全网。它与回归测试的区别在于：回归测试假设已有明确规格，而特征测试承认规格可能缺失或过时，先以当前输出为准建立基线，再据此判断重构是否改变了行为。因此特征测试中出现的“奇怪”期望值未必是 bug，可能是历史遗留逻辑的忠实记录，需要人工判断哪些行为应当保留、哪些应当修正。

版本控制、密钥安全与上下文管理

代理乐于大量产出代码，因此 Git 卫生尤为重要。核心规则是保持提交小而描述清晰——让审阅者面对 800 行混杂多种改动的提交是灾难，而拆成若干聚焦的小提交则友好得多。配置类文件（AGENTS.md、README 等）属于代码库而非个人，应当推送；只有纯属个人偏好、对同事无价值的文件才应排除。若团队混用不同代理（比如同时存在 CLAUDE.md 和 AGENTS.md），需要代码库所有者出面协调冲突。

密钥安全方面，课程给出了几条硬性准则：绝不把密钥输入聊天窗口；不要让密钥进入日志；给 API 令牌设置较短的过期时间与严格的消费上限；推送前亲自检查 diff。案例中，代理曾在控制器里直接打印来自 .env 的密钥、把密钥硬编码在注释代码中，而 .gitignore 只忽略了 .env 却漏掉了 .env.local——这些都是需要人工排查的典型隐患。

上下文管理方面，主流模型可处理约 100 万 token（粗略换算约 400 万字符）。当接近窗口上限时，代理会通过压缩（compacting）把对话归纳成摘要，或通过截断（truncation）丢弃早期内容，两者都是有损的，可能导致行为异常。课程建议每个任务使用独立会话，在 Codex 的 VS Code 扩展中可通过 Cmd/Ctrl+Shift+P 执行 Developer: Reload Window 开启全新会话。

权限、config.toml 与 MCP 工具生态

权限设置通常分三档：每次询问、智能审批、完全放行。课程认为中间档是多数开发者的首选，完全放行则不应轻率启用。更细粒度的控制通过 config.toml 实现，其中 approval_policy（on-request / untrusted / never）控制何时请求批准，sandbox_mode（workspace-write / read-only / danger-full-access）控制文件系统访问范围。该文件可放在项目内，也可放在主目录的 .codex 文件夹作为全局配置。课程还提示了两个常见排障点：组织策略无法被个人配置覆盖，以及项目级配置需要仓库被 VS Code 标记为可信。

MCP（Model Context Protocol，模型上下文协议）被称为"AI 的 USB-C"，为代理连接外部工具提供标准化接口。课程用 ShadCN 的 MCP 服务器重构一个混乱的看板应用 UI：从 ShadCN 的 61 个可用组件列表中检索并应用统一的设计规范，修复了边框圆角不一致、虚线边框混杂、阴影随机、按钮尺寸错乱等问题。注册 MCP 服务器通常写入全局 config.toml，项目内会生成 components.json。重构耗时约六分钟，且由于提示中只要求统一 UI 组件而未提及配色，原本大胆的配色方案被完整保留。课程推荐了 GitHub、Playwright（可让代理打开站点、交互并验证前端功能）和 File System 等 MCP 服务器。

MCP 采用客户端-服务器架构：代理所在的宿主应用作为客户端，外部工具以服务器形式暴露能力，双方通过标准化的 JSON-RPC 消息通信。一个 MCP 服务器可以声明自己提供的“工具”（可调用的函数）、“资源”（可读取的数据）和“提示”（预置的提示模板），代理在运行时动态发现这些能力，而无需为每个工具单独编写集成代码。这正是它被称为“AI 的 USB-C”的原因——用统一接口替代了过去为每个外部服务定制插件的碎片化做法。

核心要点

• 代理不是替代品：人类开发者仍是关键齿轮，AI 既能产出优秀代码也能产出危险代码，差别在于使用方式。
• 提示词降低歧义：遵循"任务-上下文-输出"结构，并为代码质量而非仅 UI 结果做提示；需要特定风格时展示范本而非描述。
• AGENTS.md 是持久记忆：它随每次提示发送并享有优先级，解决对话不可共享与截断丢失的问题，应定期更新。
• 测试必须保持独立性：用特征测试保护已有行为，用规格测试驱动新功能；不要让代理同时写代码和测试，否则它就是在给自己批改作业并替你做出政策决策。
• 安全与上下文需主动管理：检查 diff、隔离密钥、保持提交聚焦，并为每个任务开启新会话。