AI Agent 工程实践路线图：从 Codex、Claude Code 到 MCP 和 Skills 怎么学

AI Agent 现在最容易学乱。一边是 Codex、Claude Code、Cursor、Gemini CLI 这类编程工具。一边是 MCP、Skills、Hooks、权限、沙箱、长期记忆和多 Agent 工作流。如果从产品名字开始追，很快就会变成工具收藏夹。更稳的学习方式是从工程问题开始。你要让 Agent 可靠地完成什么任务？它需要读哪些文件？它能不能执行命令？它修改代码后谁来验收？它遇到权限、上下文、额度和失败状态时怎么停下来？这篇文章把 AI Agent 工程实践拆成一条路线图。它不是介绍单个工具，而是帮助你判断：先学什么，什么时候引入 Codex，什么时候引入 Claude Code，什么时候需要 MCP，什么时候再写 Skills。

先看结论

AI Agent 工程实践可以按七层学习。第一层是任务拆解。第二层是代码库上下文。第三层是命令执行和验证。第四层是工具接入，也就是 MCP、浏览器、数据库、文档和外部 API。第五层是可复用工作流，也就是 Skills、Hooks、项目规则和检查清单。第六层是权限、沙箱和审计。第七层是团队化运行，包括 PR、CI、回滚和成本监控。不要一开始就追求全自动。更实用的路线是：先让 Agent 在一个仓库里稳定完成小任务，再让它接入更多工具，最后才考虑长任务和多 Agent。如果你刚开始，可以先看 Codex 在 VS Code 怎么用。如果你已经会用 Codex，可以继续看 Claude Code 和 Codex 代码审查流程。如果你开始重复写提示词，再看 Codex Skills 怎么写自己的工作流。

这条路线适合谁

它适合三类人。第一类是开发者。你已经会写代码，但想把修 Bug、补测试、查依赖、改文档交给 Agent。第二类是小团队。你不想只靠个人提示词经验，而是希望形成可复制的团队流程。第三类是站点、工具或内部系统维护者。你有大量重复任务，例如发布文章、检查 SEO、整理变更、生成报告、同步翻译、部署静态站。这条路线不适合马上追求“完全无人值守”的场景。如果任务涉及生产数据、支付、隐私、账号权限或安全扫描，学习目标应该先是可控和可审计，而不是自动化率。

第一层：把任务说成可执行单元

AI Agent 最怕的不是任务难，而是目标含糊。一个好的任务描述至少包含五件事。

要改什么。
不能改什么。
如何验证。
失败时停在哪里。
最后要交付什么。例如“帮我优化项目”就太大。更好的写法是：

1
2
3
4
5


阅读 src/auth 和 tests/auth。
修复登录失败后错误提示不一致的问题。
不要改数据库 schema。
修改后运行 auth 相关测试。
如果测试环境缺依赖，说明缺什么，不要跳过验证。

这个阶段不需要 MCP。也不需要复杂 Skills。你真正要练的是把工程任务说成可执行的工作单元。

任务拆解检查表

输入范围是否明确。
输出文件是否明确。
禁止区域是否明确。
验证命令是否明确。
是否说明失败时该停还是继续。
是否避免把多个目标塞进一个请求。
是否给出真实错误日志或现象。
是否要求 Agent 汇报修改原因。
是否保留人工审批点。
是否让 Agent 先读项目规则。

第二层：理解 Codex 和 Claude Code 的分工

Codex 更适合在已有仓库里做文件级协作。它适合读代码、改文件、运行命令、解释测试失败。 Claude Code 很适合长上下文推理、命令行工作流和较长的工程讨论。 Cursor 更适合 IDE 内补全、局部编辑和交互式代码理解。这些工具不是互斥关系。它们可以按任务分工。

任务	更适合的入口	原因
小范围改 Bug	Codex	能读写文件并跑测试
复杂方案讨论	Claude Code	长上下文和解释能力强
局部代码补全	Cursor	IDE 体验更顺手
批量生成文档	Codex 或 Claude Code	需要读仓库和保持格式
代码审查	Codex + 图谱工具	需要结合 diff 和调用关系
长任务恢复	Codex + 任务记录	需要保存状态和验证点
如果你只选一个入口，建议先从 Codex 或 Claude Code 开始。
如果你已经有 VS Code 工作流，先用 Codex 更自然。
如果你长期在终端里工作，Claude Code 会更顺手。

第三层：让 Agent 读懂代码库

Agent 读懂代码库不是靠“多给上下文”。更好的办法是把上下文分成四类。

永久规则：项目结构、测试命令、禁止修改目录、部署要求。
当前任务上下文：错误日志、相关文件、复现步骤。
代码索引：函数调用、路由入口、模块依赖、最近变更。
历史记忆：以前修过的坑、设计决策、迁移背景。不要把四类内容都塞进一个超长提示词。永久规则适合放在 AGENTS.md、CLAUDE.md 或项目文档里。当前任务上下文适合放在本次请求里。代码索引适合交给 code-review-graph、Serena 或 codebase-memory-mcp 这类工具。历史记忆适合写成短规则、ADR、Issue 或轻量知识库。如果你想看代码记忆工具对比，可以看 AI Agent 代码库记忆工具对比。

第四层：建立最小验证闭环

没有验证闭环的 Agent 只是高级文本生成器。工程实践里，至少要有三种验证。

静态验证：格式检查、类型检查、lint、Markdown front matter 检查。
行为验证：单元测试、集成测试、页面截图、API 响应检查。
人工验收：确认文案、风险、范围和业务判断。一个简单的本地任务可以这样组织：

1
2
3


git status --short
rg -n "TODO|FIXME" src tests
npm test -- --runInBand

如果是 Python 项目，可以这样：

1
2


python -m pytest tests/auth -q
python -m ruff check src tests

如果是 Hugo 文章，可以先做轻量检查：

1
2


Get-Content content/post/2026/07/156/index.zh-cn.md -TotalCount 20
Select-String -Path content/post/2026/07/156/index.zh-cn.md -Pattern "^title:|^date:|^slug:"

验证命令越清楚，Agent 越少编理由。

第五层：什么时候引入 MCP

MCP 解决的是工具接入问题。它让 Agent 通过统一协议访问浏览器、数据库、文档、文件搜索、代码索引、Office 文件和内部系统。但 MCP 不是越多越好。每接入一个 MCP，就多一个权限边界。学习 MCP 可以按这个顺序来。

先接只读工具，例如文档搜索、代码索引、网页抓取。
再接低风险写入工具，例如生成报告、创建草稿、写临时文件。
最后才接高风险工具，例如数据库写入、部署、外部 API 调用、邮件发送。

MCP 适合解决的问题

Agent 经常找不到正确文件。
Agent 需要查网页或官方文档。
Agent 需要操作浏览器验证页面。
Agent 需要读取 Word、Excel、PDF。
Agent 需要查询内部知识库。
Agent 需要用统一方式调用多个工具。

MCP 不适合解决的问题

任务目标不清楚。
项目没有测试。
权限边界没人定义。
你只是想让回答更聪明。
你还没有稳定的本地工作流。如果基础流程还没稳，先别急着装十几个 MCP。

第六层：什么时候写 Skills

Skills 解决的是重复工作流问题。它不是模型能力增强包。更准确地说，Skill 是你把“每次都要解释的做事规则”沉淀成文件。适合写 Skill 的场景包括：

每次发布文章都要检查 front matter。
每次部署都要走同一组命令。
每次翻译都要保持固定语言和文件名。
每次做 SEO 都要遵守冷却期。
每次处理视频都要先下载字幕再转写。
每次生成站点都要检查视觉和部署状态。不适合写 Skill 的场景包括：
只做一次的临时任务。
规则还没稳定。
你自己都没跑通过流程。
任务依赖大量临场判断。写 Skill 的顺序应该是先记录现有流程，再抽象。不要一开始就追求完美。先写一个能避免固定错误的版本。

第七层：把长任务拆成可恢复流程

长任务失败不是异常。它一定会发生。网络会断。模型会换。上下文会压缩。用户会中途补充新要求。所以长任务要有可恢复结构。一个可恢复任务至少包含：

当前目标。
已完成步骤。
待完成步骤。
关键文件路径。
已运行命令。
验证结果。
未解决风险。
下一步入口。如果你经常让 Agent 连续做几十分钟的工作，可以看 AI Agent 长任务中断后怎么恢复。

安全边界要比自动化更早设计

Agent 能运行命令以后，风险就不只是“回答错了”。它可能改文件、提交代码、访问密钥、调用外部服务，也可能把不该写入日志的内容写进日志。本地开发的最低边界是：

每次任务前看 git status --short。
不允许自动执行破坏性命令。
不允许自动删除未知目录。
不把密钥写进提示词、日志或文章。
外部请求要说明目标和用途。
对生产部署保留人工确认。
对权限变更保留 diff。
对生成文件和缓存文件设置忽略规则。团队环境还要增加：
Agent 使用独立账号或最小权限令牌。
写操作限定仓库和分支。
CI 里只暴露必要 secret。
PR 审查不能完全交给 Agent。
安全扫描结果要有人复核。
Agent 日志需要可追溯。
生产环境命令不能默认开放。

用一个真实项目练习

最好的练习不是空跑 demo，而是选一个你愿意承担结果的小项目。这个项目可以是个人博客、内部脚本、测试仓库、文档站、浏览器小工具或 CLI。不要一开始选择生产核心系统。练习项目最好满足这些条件：

代码或文档已经放进 Git。
有明确入口文件。
有最少一个可运行检查。
任务范围可以控制在 3 到 8 个文件。
失败不会影响真实用户。
可以接受多次试错。
你能看懂 Agent 的修改。
你知道如何回滚。
项目里没有必须保密的密钥。
项目依赖能在本机恢复。第一轮不要让它改文件。让它回答三个问题：入口在哪里，验证命令是什么，最可能影响当前任务的文件有哪些。如果它连这三个问题都答不准，不要继续让它改代码。先补项目规则。先给目录说明。先让它重新读文件。第二轮选择一个小问题，例如修复文案、补 Markdown 表格、调整配置示例或给函数增加测试。要求它改完后说明修改了哪些文件、为什么改这些文件、没有改哪些相邻文件、验证命令是什么、验证结果如何。第三轮再引入工具。如果要查网页，就给浏览器。如果要查代码结构，就给图谱。如果要读文档，就给文档搜索。如果要跑命令，就限定工作目录和验证命令。每次只加一种工具。不要一次把所有 MCP 都打开。

一条 30 天学习计划

如果你想系统学，可以按 30 天分四周。

第 1 周：单工具稳定使用

第 1 天：用 Codex 阅读一个小模块。
第 2 天：让 Codex 修一个低风险 Bug。
第 3 天：让 Codex 补一个测试。
第 4 天：让 Codex 改一篇文档。
第 5 天：学习如何限制修改范围。
第 6 天：总结常用验证命令。
第 7 天：整理一份项目任务模板。

第 2 周：上下文和审查

第 8 天：写一个简短 AGENTS.md。
第 9 天：让 Agent 解释项目目录。
第 10 天：比较 Codex 和 Claude Code 的输出。
第 11 天：尝试 code-review-graph。
第 12 天：练习只审查 diff。
第 13 天：记录误判案例。
第 14 天：把常见任务拆成三类。

第 3 周：MCP 和工具

第 15 天：接入一个只读 MCP。
第 16 天：用浏览器验证页面。
第 17 天：用文档 MCP 查资料。
第 18 天：用代码索引减少重复读取。
第 19 天：设置工具权限边界。
第 20 天：记录工具失败模式。
第 21 天：写一页 MCP 使用规范。

第 4 周：Skills 和团队流程

第 22 天：把最常用任务写成 Skill 草稿。
第 23 天：用 Skill 跑一次真实任务。
第 24 天：补充失败处理。
第 25 天：加入验收清单。
第 26 天：设计 PR 描述模板。
第 27 天：把 Agent 工作接入 CI。
第 28 天：做一次回滚演练。
第 29 天：总结成本和时间节省。
第 30 天：删掉没用的规则。

衡量学习是否有效

学习 AI Agent 不能只看“它回答得像不像”。更应该看工程指标。

单个任务平均耗时。
人工审查耗时。
修改文件数量。
一次通过测试比例。
需要人工返工的次数。
因上下文不足失败的次数。
因权限不清失败的次数。
因工具配置失败的次数。
因模型能力不足失败的次数。
最终是否能形成可复用流程。好的趋势不是 Agent 每次都多写代码。好的趋势是任务范围越来越清楚，验证命令越来越稳定，返工原因越来越具体，规则文件越来越短，Skills 越来越少但更准。如果每次都要写更长提示词，说明规则没有沉淀。如果每次都要重新解释目录，说明项目文档不足。如果每次都要人工找测试命令，说明验证入口不稳定。如果工具越来越多但结果没有变好，说明不是工具问题。

最后一张路线图

AI Agent 工程实践不是从“找最强模型”开始。它应该从“让一个小任务可靠完成”开始。先会写任务。再会给上下文。再会验证结果。再接入 MCP。再沉淀 Skills。再做团队权限、CI 和成本控制。如果每一层都能闭环，Codex、Claude Code、MCP 和 Skills 就不会是一堆分散名词。它们会变成一套能持续工作的工程系统。