1. 为什么需要给 AI Agent 配一套工程工作流
1.1 从“能聊”到“能干”的鸿沟
很多人第一次接触 AI Agent 的时候，都会有一种惊艳感：你给它一段需求，它能给你写出像模像样的代码；你给它一个报错，它能分析得头头是道。但真正把它放进日常开发流程里跑上几天，问题就全暴露出来了——它会忘记昨天定好的接口规范，会在同一个坑里反复跌倒，会在你让它改 A 文件的时候顺手把 B 文件也“优化”了一遍，然后整个项目编译不过。
这不是模型能力的问题，而是工作流缺失的问题。一个没有工程工作流的 AI Agent，就像一个技术很强但完全没有工程素养的实习生：单点能力突出，协作能力为零。而“Skills”这套思路的核心，就是把这些散落的能力，用一套可复用、可约束、可验证的工程流程串起来。
我把它理解成给 AI Agent 装上一套“职业操作系统”。它不改变模型本身的智力水平，但它决定了这份智力能不能稳定地、可预期地输出成工程成果。这套工作流适合所有把 AI Agent 当作日常生产力工具的人——不管你是写代码的、做内容的、还是搞数据分析的，只要你的任务有“多步骤、有依赖、要复用”这三个特征，这套东西就能派上用场。
1.2 一个真实场景：没有工作流的 Agent 有多“野”
举个我实际踩过的例子。当时我让 Agent 帮我重构一个模块，需求写得很清楚：把三个重复的函数抽成一个公共方法，保持原有调用方式不变。结果它确实抽了，但它顺手把参数名改了，还把返回值的类型从对象改成了数组，理由是“这样更简洁”。代码是能跑，但所有调用方全炸了。
问题出在哪？出在我只给了它“目标”，没给它“约束”和“验证”。一个成熟的工程工作流应该包含四个环节：任务拆解、上下文管理、执行约束、结果验证。缺了任何一个，Agent 就会用它的“自由发挥”来填补空白，而自由发挥在工程场景里往往等于灾难。
所以这套 Skills 工作流要解决的，不是“让 Agent 更聪明”，而是“让 Agent 更可控”。它把人类工程师几十年沉淀下来的协作规范，翻译成 Agent 能理解、能执行的指令结构。下面我会把这套工作流拆成几个核心模块，逐个讲清楚怎么设计、为什么这么设计、以及实际用起来是什么效果。
2. 工作流的核心模块拆解
2.1 任务拆解：把“大活”切成 Agent 能消化的粒度
Agent 最容易翻车的地方，就是面对一个模糊的大任务。你让它“优化这个项目”，它不知道从哪下手，于是随机挑一个文件开始改。正确的做法是先把任务拆成原子级步骤，每一步都有明确的输入、输出和验收标准。
我常用的拆解模板是这样的：
- 步骤名：一句话说清楚这一步干什么
- 输入：这一步需要哪些文件、数据、上下文
- 输出：这一步完成后应该产出什么
- 验收标准：怎么判断这一步做对了
- 依赖：这一步必须在哪些步骤之后执行
举个例子，如果任务是“给现有项目加一个日志模块”，拆解后大概是：
| 步骤 | 输入 | 输出 | 验收标准 |
|---|---|---|---|
| 1. 梳理现有日志调用点 | 项目源码 | 调用点清单 | 清单覆盖所有文件 |
| 2. 设计日志接口 | 调用点清单 | 接口定义文档 | 接口能覆盖所有调用场景 |
| 3. 实现日志模块 | 接口定义 | 模块代码 | 单元测试通过 |
| 4. 替换旧调用 | 模块代码+调用点清单 | 修改后的源码 | 编译通过且行为不变 |
这么拆的好处是，每一步都足够小，Agent 不会“迷路”；每一步都有验收标准，做错了能立刻发现；步骤之间有明确依赖，不会出现顺序错乱。我实测下来，拆解粒度控制在“单步产出不超过 200 行代码或 500 字文档”是比较舒服的区间，太粗容易失控，太细又会让 Agent 频繁切换上下文导致效率下降。
注意：拆解这一步最好由人来主导，或者至少由人审核。让 Agent 自己拆自己的任务，它往往会拆得过于乐观，低估复杂度。
2.2 上下文管理：让 Agent 记住“我们之前说好的”
Agent 的上下文窗口是有限的，而且它没有真正的“长期记忆”。你今天跟它定好的规范，明天开新会话它就忘了。所以工作流里必须有一个上下文锚点机制，把关键约束固化下来，每次执行任务时都重新注入。
我的做法是维护一个context.md文件，里面记录几类信息：
- 项目规范：命名约定、代码风格、目录结构
- 接口契约：模块之间的调用约定，哪些不能改
- 历史决策：之前为什么选了方案 A 而不是方案 B
- 当前状态：项目进行到哪一步了，下一步是什么
每次给 Agent 派任务时，把这个文件的内容作为前置上下文一起传进去。这样它就不会出现“改着改着把之前的约定忘了”的情况。这个文件不需要写得很正式，用大白话写清楚就行，关键是持续更新。我一般会在每个步骤完成后，让 Agent 自己总结一下这一步产出了什么、有什么新约定，然后追加到文件里。
这里有个小技巧：上下文文件不要写太长，控制在 2000 字以内。太长了会挤占 Agent 处理实际任务的上下文空间，反而降低效果。如果内容确实多，就拆成多个文件，按需加载。
2.3 执行约束：给 Agent 划出“不能碰”的红线
约束这块是最容易被忽略的，但恰恰是最重要的。Agent 天生有“过度优化”的倾向，你不告诉它什么不能动，它就会觉得什么都可以动。所以工作流里必须明确列出禁止操作清单。
我通常会约束这几类：
- 禁止修改的文件：配置文件、第三方库、自动生成的代码
- 禁止改变的行为：公开接口的签名、数据库表结构、对外协议
- 禁止引入的依赖：未经审核的新库、有安全风险的包
- 禁止的操作：删除文件、执行破坏性命令、访问外部网络
这些约束要写成明确的指令，而不是模糊的“尽量不要”。比如不要写“尽量别改接口”，而要写“禁止修改api/目录下任何文件的函数签名”。Agent 对明确指令的遵守度远高于模糊建议。
另外，约束最好配合检查机制。比如我会在工作流里加一步“变更审查”，让 Agent 在提交前自己对照约束清单检查一遍，列出所有它做的修改，逐条确认没有越界。这个自检步骤能拦下大概七八成的越界操作。
2.4 结果验证：怎么知道 Agent 真的做对了
验证是工作流的最后一道防线。Agent 说“我做完了”不等于真的做完了，必须有一个独立的验证环节。验证方式根据任务类型不同而不同：
- 代码类任务：跑测试、跑编译、跑 lint，三者缺一不可
- 文档类任务：检查结构完整性、关键信息是否遗漏、格式是否合规
- 数据类任务：抽样检查、统计校验、边界值测试
我习惯把验证标准在任务开始前就写好，而不是做完再想。因为做完再想，很容易被 Agent 的产出“带偏”，觉得“好像也还行”。提前写好标准，就是给自己一个客观的尺子。
验证不通过怎么办？不要直接让 Agent “再改改”，而要告诉它具体哪里不通过、期望是什么、实际是什么。比如不要说“测试没过，你再看看”，而要说“测试用例test_login期望返回 200，实际返回 401，请检查认证逻辑”。信息越具体，Agent 修复的准确率越高。
3. 实操：从零搭一套可复用的 Agent 工作流
3.1 目录结构设计
先说一下我实际用的目录结构，这套结构跑了大半年，感觉比较顺手：
agent-workspace/ ├── context/ │ ├── project-spec.md # 项目规范 │ ├── interface-contract.md # 接口契约 │ └── decisions.md # 历史决策记录 ├── tasks/ │ ├── current.md # 当前任务拆解 │ └── archive/ # 已完成任务归档 ├── constraints/ │ └── forbidden.md # 禁止操作清单 ├── outputs/ │ └── step-XX/ # 每步产出 └── verify/ └── checklist.md # 验证清单这个结构的好处是职责分离：上下文、任务、约束、产出、验证各占一个目录，Agent 每次只需要加载相关部分，不会一次性被所有信息淹没。而且归档机制让历史可追溯，出了问题能快速定位是哪一步引入的。
3.2 任务派发的标准指令模板
每次给 Agent 派任务，我都用同一个模板，这样能保证信息不遗漏：
## 任务：[步骤名] ### 背景 [从 context/ 里摘取相关部分] ### 输入 [列出这一步需要的文件和数据] ### 要求 [具体做什么，越明确越好] ### 约束 [从 constraints/ 里摘取相关部分] ### 验收标准 [怎么判断做对了] ### 输出位置 [产出放到哪个目录]这个模板看起来啰嗦，但实测下来能大幅降低返工率。以前我图省事，只写一句“帮我改一下这个模块”，结果十次有八次要返工。用了模板之后，一次通过率能到七成以上，剩下三成也基本是小修小补。
3.3 一个完整的执行案例
假设任务是“给一个 Python 项目加类型注解”。按工作流走一遍：
第一步，拆解。我把它拆成：扫描无注解函数、生成注解建议、逐个文件应用、跑类型检查、修复检查报错。
第二步，准备上下文。从project-spec.md里摘出“使用 Python 3.10+ 语法、优先用内置类型而非 typing 模块”这条规范，从interface-contract.md里摘出“公开函数签名不得改变”这条契约。
第三步，派发第一个子任务。指令里明确写：只扫描src/目录、输出格式为“文件路径:行号:函数名”、不要修改任何文件。
第四步，验证。Agent 输出清单后，我抽查几个文件确认准确性，然后进入下一步。
第五步，应用注解。这一步约束最多：禁止改函数名、禁止改参数默认值、禁止改返回值逻辑。Agent 每改一个文件，就让它自己对照约束检查一遍。
第六步，跑类型检查。用mypy跑一遍，把报错信息整理成清单，再派给 Agent 修复。修复时同样有约束：只改类型相关代码，不改逻辑。
整个流程走下来，大概两三个小时能完成一个中型项目的类型注解补齐，而且质量比我自己手动改还稳定，因为 Agent 不会累、不会漏。
3.4 参数与配置的取舍逻辑
工作流里有几个关键参数需要根据实际情况调整，我说一下我的取值逻辑：
上下文长度：控制在 2000 字以内。超过这个数，Agent 对后面内容的注意力会明显下降。如果信息确实多，就拆成多个文件按需加载。
任务粒度：单步产出不超过 200 行代码。超过这个量，Agent 出错的概率会陡增，而且出错后排查成本也高。
验证频率：每步都验证。不要攒着一起验，问题越早发现修复成本越低。
重试次数：同一个问题最多让 Agent 重试 3 次。3 次还搞不定，说明要么任务拆得不够细，要么约束没写清楚，需要人来介入调整。
这些数值不是拍脑袋定的，是我在实际使用中逐步调出来的。你可以从这些值开始，然后根据自己的项目特点微调。
4. 常见问题与排查技巧
4.1 Agent 不遵守约束怎么办
这是最常见的问题。Agent 明明看到了“禁止修改接口”的约束，还是改了。排查下来通常是三个原因：
原因一：约束写得太模糊。“尽量不要改”这种表述，Agent 会理解成“可以改，但少改点”。改成“禁止修改”就老实了。
原因二：约束位置太靠后。Agent 的注意力对开头和结尾的内容最强，中间容易忽略。把关键约束放在指令的最前面，或者用醒目的标记框起来。
原因三：约束和任务目标冲突。比如你让它“优化性能”又让它“禁止改任何逻辑”，它就会陷入两难，然后随机选一个违反。这种情况要重新审视任务设计，看是不是目标本身就有矛盾。
4.2 任务拆解后 Agent 还是跑偏
拆解了还跑偏，通常是拆解的依赖关系没理清。比如步骤 3 依赖步骤 1 的产出，但你没在指令里说明，Agent 就会自己脑补一个输入，然后基于错误的前提往下做。
解决办法是在每个步骤的指令里明确写“本步骤的输入来自步骤 X 的产出，位于outputs/step-X/”。另外，步骤之间的产出最好有明确的格式约定，比如统一用 JSON 或 Markdown 表格，这样下游步骤解析起来不会出错。
4.3 验证环节发现的问题怎么分类处理
验证发现的问题我一般分三类：
| 问题类型 | 特征 | 处理方式 |
|---|---|---|
| 实现错误 | 逻辑写错了，但方向对 | 直接让 Agent 修复 |
| 理解偏差 | Agent 理解的需求和实际不符 | 重新澄清需求后再派任务 |
| 任务设计问题 | 拆解本身有问题 | 回到拆解环节重新设计 |
分类处理的好处是不会“一刀切”地让 Agent 反复重试。理解偏差和设计问题，重试多少次都没用，必须人来介入。
4.4 独家避坑技巧
最后分享几个我踩坑踩出来的经验：
技巧一：让 Agent 先复述任务再执行。派完任务后，先让它用自己的话复述一遍要做什么、有什么约束。复述对了再让它动手，能拦下大量理解偏差。
技巧二：关键步骤留“人工确认点”。不是每一步都要人确认，但在“不可逆”的操作前——比如删除文件、修改数据库、发布上线——一定要停下来等人确认。
技巧三：维护一个“翻车记录”。每次 Agent 出问题，就把问题现象、原因、解决办法记下来，下次派类似任务时把相关记录作为“负面示例”一起传进去。这个习惯坚持下来，翻车率会肉眼可见地下降。
技巧四：定期回顾工作流本身。工作流不是搭好就一劳永逸的，项目在变、Agent 能力在变，工作流也要跟着调。我大概每个月会花半小时回顾一下这个月的翻车记录，看看有没有系统性的问题需要改流程。
这套 Skills 工作流说到底，核心思想就一句话：把 Agent 当成一个能力强但需要明确指令的协作者，而不是一个能读心术的黑盒。你给它的结构越清晰、约束越明确、验证越严格，它的产出就越稳定。反过来，你越指望它“自己领会”，它就越容易给你惊喜——通常是惊吓。
我在实际使用中最大的体会是，搭工作流的前期投入大概两三天，但后面省下的返工时间是以周计的。而且这套东西一旦跑顺了，换个项目、换个 Agent 都能复用，边际成本几乎为零。如果你现在还在用“一句话派任务”的方式使唤 Agent，强烈建议花点时间把这套流程搭起来，回报率比想象中高得多。
