前言如果你刚开始用 AI Agent 编程 大概经历过这样的场景让大模型改个 Bug它把半个项目顺手重构了让它写个函数它信誓旦旦地调了一个根本不存在的 API聊了一下午它把早上说好的约定忘得一干二净。这不是你运气差而是大模型天生的工作方式导致的。这份指南不讲高深理论只讲实战中真正管用的方法为什么会出问题、怎么把任务说清楚、怎么用配置和流程把 agent 驯得稳定可靠。第一部分认知篇 —— 理解大模型1. 大模型为什么难以驾驭用 AI agent 干活经常会出现以下几类问题幻觉一本正经地胡说八道。编造不存在的 API、不存在的参数、不存在的配置项语气还特别自信。遵从性差你说只改这一个函数它顺手把旁边三个文件也优化了你说不要加注释它每行都给你注释上。长对话退化聊得越久质量越差。开头还聪明伶俐聊到后面连早上定好的约定都不记得了。因为大模型本质上是个超级接话机器。它读了几乎整个互联网的文本然后学会了一件事给定前面的话猜下一个词最可能是什么。它并不真正“理解”语义而是通过计算根据已有的文本上下文预测出下一个最有可能出现的词元Token。这个过程是自回归的即模型每生成一个词就会将其追加到输入中再进行下一次预测如此循环往复直到生成完整的回答。所以本质大模型不是理解文字的意思而是还有一个关键概念上下文窗口context window。模型每次接话时能看到的文字是有限的这个额度就是上下文窗口。你可以把它想象成模型的书桌——桌面上能摊开的资料就那么多塞满了就放不下新的而且桌上东西越乱越找不到重点。2. 大模型能力边界在我们使用大模型的过程中我们可能逐渐会逐渐发现一些规律有些事情大模型能干的很多有些事情则不然。擅长的语感型任务写代码、改代码、解释代码——互联网上这类样本最多语感最好模式化的工作单元测试、类型补全、格式调整、写文档知识密集的问答这个报错一般是什么原因不擅长的精确型任务精确计算大数乘法、统计汇总——它靠语感算数必错数字符数、排序去重这类笨功夫经常数错实时信息知识停在训练截止那天超长逻辑链一步错步步错第二部分沟通篇 —— 把任务说清楚3.任务描述与拆解很多人总抱怨大模型没有完整自己的希望的任务但他们没有意识到他们自己下达的任务就存在诸多问题。转换到工作中我们在工作中如果遇到了不靠谱的领导下任务时只说了个大概但在验收时却多出了很多标准对于执行任务的人一定是很无奈的对于大模型也是一个在下达任务时如果没有明确一些任务的目标、要求、边界等大模型也没法知道你的需求到底是什么。3.1 明确目标、约束、验收标准给 agent 下任务和给装修队下单是一个道理。你说帮我把客厅弄一下装修队八成装不出你想要的样子。一张靠谱的需求单要有三样目标干什么把客厅刷成暖白色约束什么不能碰预算 5000不要动吊顶家具不用搬验收标准做到什么程度算完墙面无色差踢脚线恢复原位给大模型下任务也是同理差优化一下这个页面 好这个页面首屏加载要压到 2 秒内目标。 不要改接口协议不要引入新的大型依赖约束。 用 Lighthouse 跑分Performance 不低于 90 且现有测试全部通过验收标准。一个好的任务应该包含任务目标、任务约束、验收标准如果还能给出明确的任务方案则更好。3.2 迭代优于一次性大任务新人最容易犯的错一上来就把巨型需求甩给 agent——帮我把这个项目从 Vue 2 迁移到 Vue 3。这就像让装修队三个月后交房时再看——返工时你会哭的。大任务里任何一步的理解偏差都会被后面的步骤放大最后整体跑偏。正确做法是小步走第 1 步先迁移构建配置跑通 第 2 步迁移一个最简单的页面验证模式 第 3 步总结成迁移规范写进 AGENTS.md 第 4 步按规范批量迁移每批跑一次测试每一步都有验证有验证就有退路。宁可慢不可失控。3.3 大任务的拆解方法三个常用切法按模块拆登录、订单、支付分开做互不干扰按层次拆先数据层、再服务层、再 UI 层按风险拆最没把握的部分先做小实验探路确认可行后再铺开拆分标准就一条每一小步做完你都能在几分钟内判断对不对。判断不了说明步子还是太大。3.4 最佳实践Plan 模式Plan模式 就是先计划再修改在Plan模式下agent 先只读探索代码产出一份书面计划改哪些文件、分几步、每步怎么验证你批准后才开始动手。Claude Code 按 ShiftTab 切换opencode 按 TabCursor 也有对应的计划模式。它拦住的是**边想边做式跑偏**方向错了在计划阶段就能拦下——改计划比改代码便宜两个数量级。而且规划摆在上下文开头后面照着接话就不容易走偏。审批计划时重点看两样打算动哪些文件、每步怎么验证。这两样对了执行阶段基本稳。grill-megrill-me是一个skill他让Agent反问用户问题。任务描述最常见的漏洞不是写错了而是你脑子里的信息没全写出来——你以为的常识它不知道。补这个缺口最快的办法是让它开工前主动盘问你开工前把你需要确认的问题一次问完。 每个问题附 2-3 个候选答案和你的倾向我来挑。让它出选择题而不是问答题开放问题你得从零想选择题你只负责挑快一个量级。这招尤其适合你自己也没完全想清楚的任务——agent 问着问着你把需求理清了算是意外的免费咨询。通过Agent对你的反问你会对自己的需求有更清晰的认知。多方案对比你让 agent 出方案它端上来的第一个方案是语感最顺的惯性路径1.2 的闭卷语感又出现了。你一旦点头就被它锚定后面再改都是在它底下修修补补。差给我一个迁移方案 好给我 2-3 个可行方案各列优缺点、工作量和风险 最后附你的推荐和理由。强制对比会逼它把搜索范围放宽更重要的是选方向的决定权回到了你手里——三个方案里经常藏着比默认答案好得多的选项。三招各管一个失效环节Plan 模式拦跑偏grill-me 堵信息缺口多方案防锚定。它们也不冲突复杂任务的完整流程往往是先进 Plan 模式在里面用 grill-me 把问题问清、用多方案对比选定方向最后审批计划开工。 通过前期准备工作减少后续返工的工作量。第三部分工程篇 —— 用配置换取稳定性4. 善用 AGENTS.md4.1 AGENTS.md 是什么怎么来的还记得那个最烦人的痛点吗每次新会话agent 都失忆。技术栈、命令、规范每开一个新窗口都要重新交代一遍光热身就要几分钟。AGENTS.md 就是解药一个放在项目根目录的 Markdown 文件agent 每次启动都会自动读取它。它的来历最早由 OpenAI Codex CLI 引入因为太实用各家编程 agent 纷纷采纳或兼容Claude Code 有自己的 CLAUDE.md 也兼容 AGENTS.mdCursor、opencode、Gemini CLI 等都支持逐渐成了事实标准。4.2 机制为什么它能提高稳定性机制很简单agent 每次启动AGENTS.md 的内容会被自动注入上下文通常被加载到优先级最高的System Prompt中就像把最重要的内容永远摆在书桌最显眼的位置。这正好对症下药解决两个根子问题对抗失忆跨会话的约定有了持久载体不用每次重复交代对抗跑偏规范以书面形式存在遵从度比口头约束高得多——项目用 pnpm写在手册里比你在对话里说十遍都管用。4.3 如何写出一个好的 AGENTS.md核心原则当成写给新实习生的入职手册来写。合格的入职手册要短。没人会认真看 100 页的手册。控制在 100 行以内重要的事放前面模型对开头和结尾的内容更敏感中间容易被忽略。只写它自己发现不了的信息。代码要写好这种废话不要写测试用 vitest 不用 jest因为历史原因这种才值得写。多用不要。约束比期望好用。不要动 legacy/ 目录、不要自行升级依赖防跑偏效果立竿见影。包含命令。怎么构建、怎么跑测试、怎么 lint——给它命令它就能自验证第 10 章会用到。一个实用的骨架# AGENTS.md ## 1. 项目概述 一段话说清楚项目是什么、技术栈、仓库结构。 前 10 行必须让 AI 建立项目心智模型。 ## 2. 快速命令 构建、启动、格式化、质量检查的命令速查表。 环境变量配置说明env 文件位置、启动脚本自动 source。 ## 3. 后端架构 包结构树ASCII 每个包的用途注释。 核心子系统的简要说明 详细文档链接。 前后端术语映射如有差异。 ## 4. 前端架构 技术栈、路由方案、API 层约定、组件库规范。 详细文档链接。 ## 5. 关键约定 5-10 条硬性编码规则违反会直接导致问题的。 每条规则附详细文档链接。 ## 6. 本地开发及验证流程 「改 → 构建 → 启动 → 验证」的完整闭环。 curl 验证模板、Token 获取、日志路径。 ## 7. 质量检查 lint、format、build、test 命令矩阵。 ## 8. 参考项目约定 参考项目列表 优先级规则。 ## 9. 文档导航 所有详细文档的索引表。最后一条最容易被忽视AGENTS.md 是活文档。每次 agent 犯错、你纠正了它就想想这个教训要不要写进手册。踩一个坑补一条手册越写越厚agent 越用越稳。5. 善用 Skills5.1 Skills 是什么能做什么AGENTS.md 解决永远要知道的信息Skills 解决特定任务的标准流程。Skill 就是给 AI 编程助手Claude Code、CodeBuddy 等加装的能力包。本质上它是一种结构化的 Prompt Engineering——通过标准的文件格式把分散在人脑中的领域知识、操作流程和最佳实践转化为 AI 可理解、可执行的指令集。物理上看它就是一个文件夹里面放一个SKILL.md文件再加上一些可选的脚本和参考资料其核心是指令告诉 AI 该怎么干活按什么步骤来、上下文告诉AI项目背景、团队规范这些它不可能凭空知道的东西、工具一些辅助脚本、配置模板AI 可以直接拿来用机制上有个精巧的设计叫渐进式披露agent 平时只看到每个 Skill 的目录页名称 简介用到哪个才翻开哪本。就像工具挂在墙上——一眼扫过去知道有什么用的时候才取下来不会把工作台堆满还记得书桌比喻吗。Skills 能做什么固化复杂流程比如发布版本要跑十几个步骤写成 Skill以后一句话触发沉淀领域知识比如我们公司的 API 错误码规范写成 Skill 随取随用跨会话记忆社区流行的 memory-bank 类 Skill把重要信息分类存档、按需加载相当于给金鱼记忆的 AI 装了一块记忆硬盘——会话关了记忆还在5.2 如何编写好的 Skills一个 Skill 只干一件事。发布流程和代码规范分成两个不要揉在一起触发描述写清楚。Skill 的描述决定了它什么时候被使用描述含糊该用的时候它想不起来步骤可执行。写成先跑 X 命令检查 Y 输出再做 Z而不是认真仔细地处理好发布让流程自验证。步骤里嵌入检查点跑测试、看输出agent 自己就能发现偏差判断一个 Skill 写得好不好就问一个问题新来的同事拿着这份 SOP能不能不问任何人就把事办了。6. 工具调用与 MCP6.1 工具agent 的手和脚没有工具的大模型本质只是一个文字处理器。有了工具大模型才真正长出了手脚能读写文件、执行命令、搜索代码成为了我们说的“Agent”。工具调用的流程是agent 分析任务 → 决定用哪个工具 → 传参调用 → 拿到结果 → 决定下一步。一轮干不完就多轮循环看起来就有了自主干活的样子。这个过程也叫ReAct Loop这套工具和循环你基本不用操心。Claude Code、opencode、Cursor 这类编程 agent 出厂就内置了读写文件、搜索代码、执行命令、抓取网页——开箱即用。你平时看到的打开文件看了看跑了一遍测试背后就是一次次工具调用只是完全无感——就像走路时你不会想到自己在调用腿部肌肉。真正需要你主动出手装工具的只有一种情况内置工具够不着的外部世界——数据库、浏览器、公司内部系统。这就是下一节 MCP 登场的地方。6.2 MCP工具的USB 接口工具虽好但早期各家 agent 接工具的方式互不兼容同一个功能要为每个平台各写一遍。MCP就是为解决这个问题的开放协议——像 USB 接口一样定义了工具和 agent 之间的标准插口。模型上下文协议MCP是一种开放协议旨在标准化 AI 应用与外部工具和数据源之间的集成。 通过使用 MCP开发人员可以增强 AI 模型的功能使他们能够生成更准确、更相关和上下文感知的响应。实际使用不需要深入协议细节记住三点现成的 MCP server 开箱即用文件系统、Git、数据库查询、浏览器操作、文档检索……配置一次所有支持 MCP 的 agentClaude Code、opencode、Cursor 等都能用可以为团队内部系统写一个 MCP server让 agent 直连内部工具第四部分实战篇 —— 构建可靠的工作流7. 减少不确定性7.1 确定性的事交给确定性的东西记住这个原则凡是能写脚本的就不要让模型用脑子做。模型是语感型选手让它做精确计算经常会出现问题常见踩雷场景让模型数一下有多少条记录、算个汇总——数字经常是错的让模型按这个规则重新排序这两千行——总有几行排错让模型按模板批量改 50 个文件——改到第 30 个开始自由发挥正确姿势是让它当指挥脚本当乐器差帮我把 data.json 里的记录按时间排序并统计总数 好写一个脚本把 data.json 里的记录按时间排序并统计总数然后运行它后者模型写脚本它擅长脚本做计算脚本擅长各干各的擅长事结果就是确定的。7.2 何时该脚本化识别标准同一套规则要重复应用到大量数据上的都该脚本化。排序、统计、批量重命名、格式转换、批量文件修改……拆细一点符合以下几个标准中的一条或者几条就该考虑要脚本化数据量大条目一多模型的数感就撑不住——它不是在数数是在猜下一个词。规则清晰按创建时间倒序重复的只留一条一句话没有歧义。准确性要求高错一条就脏数据、要返工的活别赌它的语感。重复性高今天干完下周还会再干的活。一次性的小事可以偷懒但要重复跑第二次的就值得花三分钟让 agent 写个脚本。四个信号背后是同一条分工原则规则明确的交给脚本需要理解和判断的留给模型。把这两千行按时间排序是前者把这段文案改得亲切一点是后者——后者没有规则可写硬要脚本化只会得到僵硬的结果。脚本化的好处也不止准确性可复现脚本跑一万遍结果都一样——相当于把模型手里的骰子1.2换成齿轮确定性不再看运气可审计让脚本自己输出统计处理 2000 条成功 1998跳过 2比让模型口头汇报靠谱——它汇报的数字同样可能是编的可沉淀脚本进了 repo 就是资产下次一句话重跑。和 AGENTS.md第 4 章一个思路把怎么做沉淀成文件而不是每次重新交代省上下文让模型逐条处理 2000 行上下文长度大模型消耗的token也多使用脚本则只用很少的token甚至可以不用token。8. 上下文管理8.1 token 与上下文窗口上下文就是 AI 在回答你这一刻手边能看到、能拿来参考的信息。你可以把它想象成一张工作桌。你刚刚问的问题是桌上的任务单你上传的文件是参考资料前面确认过的要求和结论也是桌上放着的纸张。AI 每次回答问题都会根据这些信息判断你现在想做什么、前面聊到了哪里、接下来该怎么回答。模型的书桌上下文窗口是有限的。这就是为什么把整个项目都喂给它行不通——桌子就这么大全堆上去重要的东西反而被挤到角落。8.2 上下文污染不是塞得越多越好新手常犯的另一个错把能找到的资料全部贴给模型心想信息越全越好。恰恰相反。无关信息会污染上下文就像你正专心写代码旁边同事一直聊昨晚的球赛——球赛本身没错但它占用了你的注意力。模型也一样桌上的垃圾越多它越容易接错话把废弃代码当有效约束、把旧方案当新需求。实践建议给文件要给相关的别以防万一地多给贴日志要贴报错那段别贴全量日志。8.3 长对话退化该开新会话时就开一个会话聊得越久桌上的东西越多早期的重要约定就越容易被挤模糊。你一定体会过下午的 agent 明显比上午的笨。一个会话干一件事干完就换新会话。发现 agent 开始忘事、答非所问果断开新窗口别恋战。重要的结论决策、规范、踩过的坑及时沉淀到 AGENTS.md第 4 章别指望它记住。9. 善用子 agent9.1 上下文无关的任务扔给子 agent主会话的上下文是宝贵资源书桌又来了。有些活儿很占桌面但产出其实很小在整个代码库里调研支付模块的现状——要读几十个文件结论就几行审一遍这次改动有没有安全问题——要翻大量代码结论是有/没有这类任务用子 agent主 agent 派一个分身去干分身自己开一张新书桌读它需要读的一切干完后只把结论交回来中间过程一概不占主会话的桌面。就像项目经理把调研外包给顾问顾问回去翻了三天资料最后交回一页纸报告——你不用陪他翻资料你的会议室主上下文保持清爽。9.2 任务并行与隔离适用场景与边界适合交给子 agent 的调研类代码库摸底、方案调研、日志排查审查类代码 review、安全扫描并行任务互不依赖的几个模块派多个子 agent 同时干不适合的强依赖主对话上下文的任务——子 agent 看不到你们的聊天记录所有背景要在任务里重新交代需要反复来回讨论的任务——每次来回都要重新描述背景得不偿失一句话子 agent 换来主上下文的清爽代价是背景信息要重新交代。信息密度低、过程重的活儿这笔交易就划算。10. 验证闭环与安全网10.1 让 agent 自验证agent 说已完成只是它的主观感受不是事实。你要的不是口头汇报而是客观证据。规则很简单能在机器上验证的就不要用眼睛验证。让它改完代码跑测试改完后运行测试贴出结果让它修完 Bug 编译一遍确认编译通过再交给我有 lint 就让它 lint有类型检查就让它跑类型检查把验收标准直接写进任务里第 3 章的三要素agent 会自己闭环。你的 review 从检查对不对变成抽查它有没有骗我工作量骤降。10.2 人工检查点有些门必须你来开分级设卡危险操作必须人工确认高危删文件、改数据库、发布上线、git push、花钱的 API 调用——必须人工点头中危批量修改、依赖变更——agent 做完后人工过目低危单文件小改、注释文档——抽查即可大多数编程 agent 支持权限配置把这些门槛设成默认既安全又不啰嗦。原则事故的代价越高检查点越靠前。最后说一句技术成长不只是写代码职业规划和自我包装同样重要。我整理了一份简历、面试和职业规划的学习资料适合想在职场上走得更远的朋友看看。资料展示下面是我整理的AI大模型学习资料和工具包预览适合收藏后按主题逐步学习。如果你想看完整资料目录可以在评论区留言「资料」也欢迎告诉我你更关注AI大模型里的哪类内容。