AI Agent 驾驭指南

前言

如果你刚开始用 AI Agent 编程，大概经历过这样的场景：

让大模型改个 Bug，它把半个项目"顺手"重构了；让它写个函数，它信誓旦旦地调了一个根本不存在的 API；聊了一下午，它把早上说好的约定忘得一干二净。

这不是你运气差，而是大模型天生的工作方式导致的。这份指南不讲高深理论，只讲实战中真正管用的方法：为什么会出问题、怎么把任务说清楚、怎么用配置和流程把 agent "驯"得稳定可靠。

第一部分：认知篇 ------ 理解大模型

1. 大模型为什么难以驾驭？

用 AI agent 干活，经常会出现以下几类问题：

幻觉：一本正经地胡说八道。编造不存在的 API、不存在的参数、不存在的配置项，语气还特别自信。
遵从性差：你说"只改这一个函数"，它顺手把旁边三个文件也"优化"了；你说"不要加注释"，它每行都给你注释上。
长对话退化：聊得越久质量越差。开头还聪明伶俐，聊到后面连早上定好的约定都不记得了。

因为大模型本质上是个"超级接话机器"。它读了几乎整个互联网的文本，然后学会了一件事：给定前面的话，猜下一个词最可能是什么。它并不真正"理解"语义，而是通过计算，根据已有的文本（上下文），预测出下一个最有可能出现的词元（Token）。这个过程是自回归的，即模型每生成一个词，就会将其追加到输入中，再进行下一次预测，如此循环往复，直到生成完整的回答。

所以本质，大模型不是理解文字的意思，而是

还有一个关键概念：上下文窗口（context window） 。模型每次"接话"时，能看到的文字是有限的，这个额度就是上下文窗口。你可以把它想象成模型的书桌------桌面上能摊开的资料就那么多，塞满了就放不下新的，而且桌上东西越乱，越找不到重点。

2. 大模型能力边界

在我们使用大模型的过程中，我们可能逐渐会逐渐发现一些规律，有些事情大模型能干的很多，有些事情则不然。

擅长的（语感型任务）：

写代码、改代码、解释代码------互联网上这类样本最多，语感最好
模式化的工作：单元测试、类型补全、格式调整、写文档
知识密集的问答："这个报错一般是什么原因？"

不擅长的（精确型任务）：

精确计算：大数乘法、统计汇总------它靠"语感"算数，必错
数字符数、排序去重这类"笨功夫"：经常数错
实时信息：知识停在训练截止那天
超长逻辑链：一步错，步步错

第二部分：沟通篇 ------ 把任务说清楚

3.任务描述与拆解

很多人总抱怨大模型没有完整自己的希望的任务，但他们没有意识到，他们自己下达的任务就存在诸多问题。转换到工作中，我们在工作中如果遇到了不靠谱的领导，下任务时只说了个大概，但在验收时却多出了很多标准，对于执行任务的人一定是很无奈的，对于大模型也是一个，在下达任务时，如果没有明确一些任务的目标、要求、边界等，大模型也没法知道你的需求到底是什么。

3.1 明确目标、约束、验收标准

给 agent 下任务和给装修队下单是一个道理。你说"帮我把客厅弄一下"，装修队八成装不出你想要的样子。一张靠谱的需求单要有三样：

目标：干什么（把客厅刷成暖白色）
约束：什么不能碰（预算 5000，不要动吊顶，家具不用搬）
验收标准：做到什么程度算完（墙面无色差，踢脚线恢复原位）

给大模型下任务也是同理

arduino 复制代码

差："优化一下这个页面"

好："这个页面首屏加载要压到 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 按 Shift+Tab 切换，opencode 按 Tab，Cursor 也有对应的计划模式。

它拦住的是**"边想边做"式跑偏**：方向错了，在计划阶段就能拦下------改计划比改代码便宜两个数量级。而且规划摆在上下文开头，后面照着接话就不容易走偏。审批计划时重点看两样：打算动哪些文件、每步怎么验证。这两样对了，执行阶段基本稳。

grill-me

grill-me是一个skill，他让Agent反问用户问题。任务描述最常见的漏洞，不是写错了，而是你脑子里的信息没全写出来------你以为的常识，它不知道。补这个缺口最快的办法，是让它开工前主动盘问你：

arduino 复制代码

"开工前，把你需要确认的问题一次问完。
 每个问题附 2-3 个候选答案和你的倾向，我来挑。"

让它出选择题而不是问答题：开放问题你得从零想，选择题你只负责挑，快一个量级。这招尤其适合你自己也没完全想清楚的任务------agent 问着问着，你把需求理清了，算是意外的免费咨询。

通过Agent对你的反问，你会对自己的需求有更清晰的认知。

多方案对比

你让 agent 出方案，它端上来的第一个方案，是语感最顺的惯性路径（1.2 的闭卷语感又出现了）。你一旦点头，就被它锚定，后面再改都是在它底下修修补补。

arduino 复制代码

差："给我一个迁移方案"

好："给我 2-3 个可行方案，各列优缺点、工作量和风险，
    最后附你的推荐和理由。"

强制对比会逼它把搜索范围放宽，更重要的是，选方向的决定权回到了你手里------三个方案里，经常藏着比默认答案好得多的选项。

三招各管一个失效环节：Plan 模式拦跑偏，grill-me 堵信息缺口，多方案防锚定。它们也不冲突：复杂任务的完整流程，往往是先进 Plan 模式，在里面用 grill-me 把问题问清、用多方案对比选定方向，最后审批计划开工。通过前期准备工作，减少后续返工的工作量。

第三部分：工程篇 ------ 用配置换取稳定性

4. 善用 AGENTS.md

4.1 AGENTS.md 是什么，怎么来的

还记得那个最烦人的痛点吗：每次新会话，agent 都失忆。技术栈、命令、规范，每开一个新窗口都要重新交代一遍，光"热身"就要几分钟。

AGENTS.md 就是解药：一个放在项目根目录的 Markdown 文件，agent 每次启动都会自动读取它。

它的来历：最早由 OpenAI Codex CLI 引入，因为太实用，各家编程 agent 纷纷采纳或兼容（Claude Code 有自己的 CLAUDE.md 也兼容 AGENTS.md，Cursor、opencode、Gemini CLI 等都支持），逐渐成了事实标准。

4.2 机制：为什么它能提高稳定性

机制很简单：agent 每次启动，AGENTS.md 的内容会被自动注入上下文，通常被加载到优先级最高的System Prompt中，就像把最重要的内容永远摆在书桌最显眼的位置。

这正好对症下药，解决两个根子问题：

对抗失忆：跨会话的约定有了持久载体，不用每次重复交代
对抗跑偏：规范以书面形式存在，遵从度比口头约束高得多------"项目用 pnpm"写在手册里，比你在对话里说十遍都管用。

4.3 如何写出一个好的 AGENTS.md

核心原则：当成写给新实习生的入职手册来写。合格的入职手册要：

短。没人会认真看 100 页的手册。控制在 100 行以内，重要的事放前面（模型对开头和结尾的内容更敏感，中间容易被忽略）。
只写"它自己发现不了"的信息。"代码要写好"这种废话不要写；"测试用 vitest 不用 jest，因为历史原因"这种才值得写。
多用"不要"。约束比期望好用。"不要动 legacy/ 目录"、"不要自行升级依赖"，防跑偏效果立竿见影。
包含命令。怎么构建、怎么跑测试、怎么 lint------给它命令，它就能自验证（第 10 章会用到）。

一个实用的骨架：

shell 复制代码

# 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. 善用 Skills

5.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. 工具调用与 MCP

6.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 的 agent（Claude Code、opencode、Cursor 等）都能用
可以为团队内部系统写一个 MCP server，让 agent 直连内部工具

第四部分：实战篇 ------ 构建可靠的工作流

7. 减少不确定性

7.1 确定性的事，交给确定性的东西

记住这个原则：凡是能写脚本的，就不要让模型"用脑子"做。

模型是"语感型选手"，让它做精确计算，经常会出现问题，常见踩雷场景：

让模型"数一下有多少条记录"、"算个汇总"------数字经常是错的
让模型"按这个规则重新排序这两千行"------总有几行排错
让模型"按模板批量改 50 个文件"------改到第 30 个开始自由发挥

正确姿势是让它当"指挥"，脚本当"乐器"：

kotlin 复制代码

差：帮我把 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. 善用子 agent

9.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 Coding 效率翻倍：AGENTS.md 实践指南-阿里云开发者社区

AI真好玩系列-Agent Skill深度调研⑨memory-bank | 给AI装上跨会话的持久记忆硬盘AI真好玩系列 - 掘金

mp.weixin.qq.com/s/SZv3pDXPr...