1. 为什么给 Coding Agent 立规矩比选模型更重要很多人上手 Coding Agent 的第一反应是纠结模型选型——到底用哪个 CLI、哪个后端模型更聪明。我一开始也是这个思路折腾了小半个月换了好几个组合最后发现真正决定日常体验的根本不是模型本身而是你有没有给它立好规矩。这个结论听起来有点反直觉但只要你真正把 Coding Agent 用进日常开发流程就会立刻明白。模型再强如果每次都要你从头解释项目结构、代码规范、测试命令、提交格式那它本质上只是一个更聪明的补全工具而不是一个能替你干活的协作者。反过来一个中等能力的模型只要上下文喂得准、边界划得清、约束写得死产出质量往往比裸奔的强模型更稳定。我踩过的典型坑是这样的早期我直接开一个 CLI扔一句帮我加个接口它就开始自由发挥——文件放错目录、命名风格和项目不一致、测试没跑、顺手改了两个不相关的文件。你还不能说它错因为它确实完成了任务只是完成的方式和你的项目格格不入。问题不在模型在于我从来没告诉过它这个项目的规矩是什么。所以这篇内容我想聊的不是哪个 CLI 最好用而是一套我自己反复打磨、现在团队里也在用的六层治理架构。它的目标很朴素让 Coding Agent 从随机发挥的实习生变成懂规矩的靠谱同事。这套架构不绑定具体工具无论你用的是哪家的命令行 Agent思路都能直接迁移。适合已经在用或准备用 Coding Agent 的开发者尤其是那些用了几次觉得不靠谱就放弃了的人——大概率不是工具的问题是规矩没立。下面我按六个层次拆开讲从最基础的上下文约定到最外层的自动化钩子一层层往上搭。每一层我都会说清楚它解决什么问题、为什么这么设计、具体怎么落地、以及我在实操中踩过的坑。2. 第一层用 AGENTS.md 把项目规矩写成员工手册2.1 AGENTS.md 到底该写什么治理架构的地基是上下文约定文件业界现在比较通用的叫法是AGENTS.md有些工具里叫context.md或类似名字本质一样。你可以把它理解成给 Agent 看的员工手册——它每次开工前都会读一遍知道这个项目是什么、该怎么干活。我见过太多人把这个文件写成一句这是一个 React 项目然后抱怨 Agent 不懂事。这就好比你招了个新人只告诉他我们是个公司然后指望他直接上手核心业务。AGENTS.md的信息密度直接决定了 Agent 的输出质量我的经验是至少覆盖这几块项目定位与技术栈一句话说清项目干什么主要语言、框架、运行时版本。版本一定要写死比如Node 20.xpnpm 管理依赖否则 Agent 可能给你装个不兼容的包。目录结构与职责边界哪些目录放业务代码、哪些放工具函数、哪些是自动生成的不要动。这一条能挡掉大量文件放错地方的问题。编码规范命名风格、导入顺序、是否允许默认导出、注释语言。别嫌琐碎Agent 最擅长的就是严格执行明文规则。常用命令安装、启动、测试、构建、lint 的准确命令。这是被严重低估的一块后面第三层还会展开。禁区清单哪些文件绝对不能改、哪些操作必须先问、哪些依赖不许引入。我自己的AGENTS.md大概 80 到 150 行控制在 Agent 能完整读进上下文又不至于淹没重点的范围内。太短没约束力太长反而稀释了关键信息。2.2 为什么写死比描述更有效这里有个反直觉的经验给 Agent 的规矩要尽量写成可判定的硬规则而不是模糊的描述。举个例子代码要写得清晰这种话等于没说Agent 无法判定什么叫清晰。但函数超过 40 行必须拆分禁止使用 any 类型所有导出函数必须有 JSDoc就是可判定的——Agent 能逐条对照检查你也能在 review 时逐条验收。我在早期版本里写过尽量保持代码风格一致结果 Agent 每次风格都不一样因为它根本不知道一致的基准是什么。后来我改成参考src/utils/format.ts的风格它立刻就稳了。给参照物别给形容词这是写AGENTS.md最核心的一条心法。2.3 一个可直接抄的 AGENTS.md 骨架下面是我现在项目里用的骨架你可以按自己项目改# 项目约定 ## 项目概述 - 用途内部数据看板前后端同仓 - 技术栈TypeScript 5.x React 18 Vite后端 Node 20 Fastify - 包管理pnpm禁止使用 npm/yarn ## 目录职责 - src/components纯 UI 组件不含业务逻辑 - src/features按功能模块划分的业务代码 - src/lib通用工具改动需谨慎 - generated/自动生成禁止手动修改 ## 编码规范 - 命名组件 PascalCase函数 camelCase常量 UPPER_SNAKE - 禁止默认导出统一具名导出 - 禁止 any必要时用 unknown 类型守卫 - 注释用中文仅解释为什么不解释是什么 ## 常用命令 - 安装pnpm install - 开发pnpm dev - 测试pnpm test改完必须跑 - 类型检查pnpm typecheck - 格式化pnpm lint --fix ## 禁区 - 不修改 generated/ 下任何文件 - 不新增依赖需要时先说明理由 - 不改动 .env 与 CI 配置这份文件我迭代了七八版每加一条都是因为踩过一次坑。比如禁止默认导出这条就是因为 Agent 混用两种导出风格导致 import 报错改完必须跑测试这条是因为它曾经改完直接说完成了结果测试全红。提示AGENTS.md不是写完就完事它应该跟着项目一起演进。每次 Agent 犯了新错误先别急着骂它想想是不是规矩里没写清楚补上就行。3. 第二层用上下文分层喂料别把整个仓库塞进去3.1 全量塞上下文的代价很多人对 Coding Agent 有个误解以为把整个项目都塞给它它就能理解全局。实测下来这是灾难。上下文窗口是有限资源塞得越满关键信息越容易被淹没Agent 反而抓不住重点。而且大仓库动辄几万行全量喂进去既慢又贵还容易触发各种截断。我的做法是分层喂料把上下文按永远需要按需加载临时提供三档管理。永远需要AGENTS.md这类全局约定每次必带。按需加载具体模块的说明文档只在动到那个模块时才引入。临时提供当前任务相关的几个文件由 Agent 自己按需读取。关键在于第二档。我会在每个核心模块目录下放一个简短的README.md或CONTEXT.md说明这个模块的职责、对外接口、注意事项。Agent 在动这个目录时会自然读到它。这比把所有模块说明堆在一个巨型文件里有效得多。3.2 让 Agent 自己按需取书更进阶的做法是不主动喂而是告诉 Agent 去哪里找。在AGENTS.md里写清楚模块说明在各目录的 CONTEXT.md 中动手前先读对应文件然后依赖 Agent 的自主读取能力。这就像给新人一个文档库的索引而不是把整个文档库打印出来塞他手里。他需要哪块就翻哪块效率高得多。我实测下来这种方式下 Agent 对模块边界的理解明显更准越界改动少了很多。3.3 上下文污染的排查经验有个坑我踩得很深上下文污染。有一次 Agent 反复在一个已经废弃的旧接口上改代码我查了半天才发现是因为仓库里还留着一份过时的文档Agent 读到后把它当成了当前规范。从那以后我养成了一个习惯定期清理仓库里的僵尸文档。凡是和当前代码不符的说明、注释、示例要么更新要么删掉。对 Agent 来说它无法判断哪份文档是新的哪份是旧的你留着它就可能被误读。这一点在多人协作的项目里尤其重要因为文档腐烂是常态。注意上下文治理不只是加什么更是减什么。一个干净、无歧义的仓库对 Agent 的价值不亚于一份详尽的规范。4. 第三层把测试和校验命令变成 Agent 的验收标准4.1 为什么命令比描述更能约束行为这一层是我认为整套架构里性价比最高的一环。核心思路很简单把项目的测试、类型检查、lint 命令明确写进约定并要求 Agent 每次改完必须自己跑一遍。为什么这招管用因为命令的输出是客观的、可判定的。Agent 说我改好了没有意义但pnpm test全绿就是硬证据。你把验收标准从主观描述变成客观命令Agent 的行为立刻就有了锚点。我在AGENTS.md里专门有一段完成定义Definition of Done写清楚什么才算真正完成## 完成定义 一个任务只有在以下全部满足时才算完成 1. pnpm typecheck 无错误 2. pnpm test 全部通过 3. pnpm lint 无警告 4. 新增逻辑有对应测试 5. 变更说明写清楚改了什么、为什么自从加了这段Agent假装完成的情况几乎消失了。因为它知道不跑命令就没法交差。4.2 测试命令要快、准、可复现这里有个实操细节给 Agent 用的测试命令必须足够快。如果你让它每次改完跑一个要五分钟的全量测试它要么偷懒跳过要么你等得抓狂。我的做法是准备两套命令场景命令耗时用途快速反馈pnpm test:unit --changed秒级Agent 改完立即自检完整验收pnpm test分钟级提交前或 CI 跑在AGENTS.md里明确告诉 Agent日常改动跑快速命令准备提交时跑完整命令。这样既保证了反馈速度又不牺牲最终质量。4.3 让失败信息可读还有一个容易被忽略的点测试失败时的报错信息要足够清晰因为这是 Agent 自我修复的主要依据。如果报错是一堆堆栈没有上下文Agent 很难定位问题。我会在测试里加一些辅助断言信息比如expect(result, 用户名为空时应返回 400).toBe(400)。这种带说明的断言Agent 读起来一目了然修复准确率明显提升。这算是给人和Agent双重优化的写法一举两得。5. 第四层用 Subagents 做任务分工别让一个 Agent 干所有事5.1 单 Agent 的注意力涣散问题当任务变复杂单个 Agent 容易注意力涣散——它既要理解需求又要写代码又要跑测试又要写文档结果每样都做得马马虎虎。这跟人一样一个人同时干五件事质量必然下降。Subagents子代理的思路就是把任务拆开每个子代理专注一件事。比如一个负责探索代码库、定位相关文件一个负责写实现一个负责写测试一个负责review 改动。每个子代理的上下文更聚焦输出质量自然更高。5.2 怎么划分 Subagent 的职责划分的核心原则是按关注点拆而不是按文件拆。我常用的几个角色探索者只读不写负责在动手前摸清相关代码、依赖关系、潜在影响面。它的产出是一份现状报告供后续使用。实现者基于探索者的报告写代码专注逻辑正确性。测试者为改动补测试专注边界和异常。审查者以挑刺为目标 review 前面的产出专门找问题。这套分工的好处是每个角色的成功标准都很清晰。探索者的成功是信息准确完整实现者的成功是逻辑正确测试者的成功是覆盖到位审查者的成功是找出问题。目标清晰行为就稳定。5.3 子代理之间的交接是关键Subagent 架构最容易出问题的地方是交接。如果探索者的报告写得含糊实现者就会跑偏如果实现者不说明改了什么审查者就无从下手。我的经验是强制每个子代理产出结构化的交接物。探索者必须输出相关文件清单 关键函数说明 潜在风险点实现者必须输出改动文件清单 改动理由 未决问题。这些交接物既是下一环的输入也是你事后 review 的依据。提示Subagent 不是越多越好。我一般控制在 3 到 4 个角色再多协调成本就超过收益了。任务简单时一个 Agent 加清晰的规矩反而更快。6. 第五层用 Hooks 把事后检查变成事前拦截6.1 Hooks 解决的是信任问题前面几层都是约定和分工本质上是靠 Agent 自觉。但现实是Agent 再听话也可能犯错尤其是涉及危险操作时——比如误删文件、误改配置、提交敏感信息。Hooks钩子就是用来兜底的。它是在 Agent 执行特定动作前后自动触发的脚本可以拦截、校验、甚至阻止某些操作。这一层解决的是信任问题你不需要完全相信 Agent因为关键节点有硬性拦截。6.2 我实际配置的几个关键 Hook我目前用得最多的几个 Hook提交前 Hook在 Agent 执行 git 提交前自动跑 lint 和类型检查不通过就阻止提交。这挡住了大量带病提交。文件写入 Hook监控对敏感目录如配置、CI 文件的写入触发时要求二次确认。命令执行 Hook拦截危险命令模式比如递归删除、强制推送等直接阻断。格式化 Hook文件写入后自动跑格式化保证风格统一省得 Agent 自己纠结格式。这些 Hook 的价值在于把规则从建议升级成强制。约定是软的Hook 是硬的。两者配合才能既灵活又安全。6.3 Hook 设计的一条铁律快、静、准Hook 有个大坑如果它太慢或太吵就会变成负担。我早期配了个每次写入都跑全量测试的 Hook结果每次改文件都要等半分钟体验极差最后只能关掉。后来我总结出 Hook 设计的三条原则快单个 Hook 执行控制在秒级重活交给专门的命令别塞进 Hook。静只在真正需要时输出信息别每次都刷屏。准拦截规则要精确宁可少拦也别误伤误报多了你会想直接关掉它。7. 第六层CLI 工作流与人工把关的边界7.1 CLI 是入口不是全部最外层是工作流本身。无论你用哪个命令行 Agent它都只是整个流程的入口。真正决定效率的是你怎么组织人机协作的节奏。我的日常节奏是这样的先用探索型任务让 Agent 摸清现状我确认方向没问题再让它实现实现过程中它自己跑快速测试完成后我 review 关键改动跑完整测试最后提交提交前 Hook 自动校验。整个流程里Agent 干了大部分体力活我负责方向和验收。7.2 哪些环节必须人工把关有些环节我坚持人工介入绝不放手架构决策涉及模块划分、接口设计的改动必须我先定方向。依赖引入新增任何依赖都要我确认防止供应链风险。数据相关操作涉及数据库迁移、数据删除的必须人工复核。最终提交提交信息、提交范围由我确认不让 Agent 自作主张。这些环节的共同点是影响面大、不可逆。Agent 擅长的是可逆的、局部的、有明确验收标准的活把这些交给它把不可逆的决策留给自己这是人机协作的基本分工。7.3 六层架构的落地顺序建议如果你现在想从零搭这套架构别想着一次全上。我的建议顺序是先写AGENTS.md这是地基投入产出比最高。再把测试和校验命令写进完成定义让 Agent 有验收标准。然后做上下文分层清理僵尸文档。任务复杂了再引入 Subagents。最后按需加 Hooks从提交前校验开始。这个顺序的逻辑是从软约束到硬约束、从简单到复杂。每加一层你都能立刻感受到体验的提升而不是一上来就被复杂的配置劝退。8. 我在实际落地中踩过的几个坑聊完架构说几个具体的坑都是真金白银换来的。第一个坑规矩写太多Agent 反而记不住。我一度把AGENTS.md写到三百多行结果 Agent 开始忽略后面的内容。后来砍到一百行左右只留最关键的效果反而更好。规矩要精不要多。第二个坑Hook 误伤导致流程卡死。有次我配了个拦截规则结果把正常的文件写入也拦了Agent 直接卡住不动。排查半天才发现是正则写得太宽。Hook 上线前一定要在测试环境验证别直接上生产。第三个坑Subagent 交接信息丢失。早期我没强制结构化交接探索者的结论传到实现者那里就变味了。后来强制每个子代理输出固定格式的交接物问题才解决。交接物要有固定 schema不能靠自然语言自由发挥。第四个坑过度依赖 Agent 导致自己不看代码。有一阵我完全放手结果积累了一堆能跑但很丑的代码回头重构花的时间比省下的还多。Agent 是加速器不是替代品关键代码还是要自己过一遍。第五个坑忘了更新规矩。项目演进后AGENTS.md里的命令过时了Agent 照着跑一直失败。规矩文件要纳入日常维护改项目时顺手更新它别让它腐烂。9. 关于这套架构我最后想说的几句实在话这套六层治理架构不是银弹它解决的是让 Coding Agent 稳定产出这个问题而不是让 Agent 无所不能。它的核心思想其实很朴素把模糊的期望变成明确的规则把主观的判断变成客观的验收把不可逆的决策留给人。我用了大半年最大的感受是Agent 的能力上限取决于模型但它的产出下限取决于你的治理。模型再强没有规矩就是一匹脱缰的野马模型一般规矩到位也能稳定干活。对绝大多数日常开发场景来说下限比上限重要得多。如果你现在只打算做一件事那就先把AGENTS.md写好把测试命令写进完成定义。这两件事加起来可能就花你一个小时但带来的体验提升是立竿见影的。剩下的几层等你真正遇到对应的问题时再补完全来得及。工具会一直变今天流行的 CLI 明天可能就换了但立规矩这件事的思路是不变的。把这套思路内化无论换什么工具你都能快速搭起一套靠谱的工作流。这比追任何一个具体工具都值。
1. 为什么给 Coding Agent 立规矩比选模型更重要很多人上手 Coding Agent 的第一反应是纠结模型选型——到底用哪个 CLI、哪个后端模型更聪明。我一开始也是这个思路折腾了小半个月换了好几个组合最后发现真正决定日常体验的根本不是模型本身而是你有没有给它立好规矩。这个结论听起来有点反直觉但只要你真正把 Coding Agent 用进日常开发流程就会立刻明白。模型再强如果每次都要你从头解释项目结构、代码规范、测试命令、提交格式那它本质上只是一个更聪明的补全工具而不是一个能替你干活的协作者。反过来一个中等能力的模型只要上下文喂得准、边界划得清、约束写得死产出质量往往比裸奔的强模型更稳定。我踩过的典型坑是这样的早期我直接开一个 CLI扔一句帮我加个接口它就开始自由发挥——文件放错目录、命名风格和项目不一致、测试没跑、顺手改了两个不相关的文件。你还不能说它错因为它确实完成了任务只是完成的方式和你的项目格格不入。问题不在模型在于我从来没告诉过它这个项目的规矩是什么。所以这篇内容我想聊的不是哪个 CLI 最好用而是一套我自己反复打磨、现在团队里也在用的六层治理架构。它的目标很朴素让 Coding Agent 从随机发挥的实习生变成懂规矩的靠谱同事。这套架构不绑定具体工具无论你用的是哪家的命令行 Agent思路都能直接迁移。适合已经在用或准备用 Coding Agent 的开发者尤其是那些用了几次觉得不靠谱就放弃了的人——大概率不是工具的问题是规矩没立。下面我按六个层次拆开讲从最基础的上下文约定到最外层的自动化钩子一层层往上搭。每一层我都会说清楚它解决什么问题、为什么这么设计、具体怎么落地、以及我在实操中踩过的坑。2. 第一层用 AGENTS.md 把项目规矩写成员工手册2.1 AGENTS.md 到底该写什么治理架构的地基是上下文约定文件业界现在比较通用的叫法是AGENTS.md有些工具里叫context.md或类似名字本质一样。你可以把它理解成给 Agent 看的员工手册——它每次开工前都会读一遍知道这个项目是什么、该怎么干活。我见过太多人把这个文件写成一句这是一个 React 项目然后抱怨 Agent 不懂事。这就好比你招了个新人只告诉他我们是个公司然后指望他直接上手核心业务。AGENTS.md的信息密度直接决定了 Agent 的输出质量我的经验是至少覆盖这几块项目定位与技术栈一句话说清项目干什么主要语言、框架、运行时版本。版本一定要写死比如Node 20.xpnpm 管理依赖否则 Agent 可能给你装个不兼容的包。目录结构与职责边界哪些目录放业务代码、哪些放工具函数、哪些是自动生成的不要动。这一条能挡掉大量文件放错地方的问题。编码规范命名风格、导入顺序、是否允许默认导出、注释语言。别嫌琐碎Agent 最擅长的就是严格执行明文规则。常用命令安装、启动、测试、构建、lint 的准确命令。这是被严重低估的一块后面第三层还会展开。禁区清单哪些文件绝对不能改、哪些操作必须先问、哪些依赖不许引入。我自己的AGENTS.md大概 80 到 150 行控制在 Agent 能完整读进上下文又不至于淹没重点的范围内。太短没约束力太长反而稀释了关键信息。2.2 为什么写死比描述更有效这里有个反直觉的经验给 Agent 的规矩要尽量写成可判定的硬规则而不是模糊的描述。举个例子代码要写得清晰这种话等于没说Agent 无法判定什么叫清晰。但函数超过 40 行必须拆分禁止使用 any 类型所有导出函数必须有 JSDoc就是可判定的——Agent 能逐条对照检查你也能在 review 时逐条验收。我在早期版本里写过尽量保持代码风格一致结果 Agent 每次风格都不一样因为它根本不知道一致的基准是什么。后来我改成参考src/utils/format.ts的风格它立刻就稳了。给参照物别给形容词这是写AGENTS.md最核心的一条心法。2.3 一个可直接抄的 AGENTS.md 骨架下面是我现在项目里用的骨架你可以按自己项目改# 项目约定 ## 项目概述 - 用途内部数据看板前后端同仓 - 技术栈TypeScript 5.x React 18 Vite后端 Node 20 Fastify - 包管理pnpm禁止使用 npm/yarn ## 目录职责 - src/components纯 UI 组件不含业务逻辑 - src/features按功能模块划分的业务代码 - src/lib通用工具改动需谨慎 - generated/自动生成禁止手动修改 ## 编码规范 - 命名组件 PascalCase函数 camelCase常量 UPPER_SNAKE - 禁止默认导出统一具名导出 - 禁止 any必要时用 unknown 类型守卫 - 注释用中文仅解释为什么不解释是什么 ## 常用命令 - 安装pnpm install - 开发pnpm dev - 测试pnpm test改完必须跑 - 类型检查pnpm typecheck - 格式化pnpm lint --fix ## 禁区 - 不修改 generated/ 下任何文件 - 不新增依赖需要时先说明理由 - 不改动 .env 与 CI 配置这份文件我迭代了七八版每加一条都是因为踩过一次坑。比如禁止默认导出这条就是因为 Agent 混用两种导出风格导致 import 报错改完必须跑测试这条是因为它曾经改完直接说完成了结果测试全红。提示AGENTS.md不是写完就完事它应该跟着项目一起演进。每次 Agent 犯了新错误先别急着骂它想想是不是规矩里没写清楚补上就行。3. 第二层用上下文分层喂料别把整个仓库塞进去3.1 全量塞上下文的代价很多人对 Coding Agent 有个误解以为把整个项目都塞给它它就能理解全局。实测下来这是灾难。上下文窗口是有限资源塞得越满关键信息越容易被淹没Agent 反而抓不住重点。而且大仓库动辄几万行全量喂进去既慢又贵还容易触发各种截断。我的做法是分层喂料把上下文按永远需要按需加载临时提供三档管理。永远需要AGENTS.md这类全局约定每次必带。按需加载具体模块的说明文档只在动到那个模块时才引入。临时提供当前任务相关的几个文件由 Agent 自己按需读取。关键在于第二档。我会在每个核心模块目录下放一个简短的README.md或CONTEXT.md说明这个模块的职责、对外接口、注意事项。Agent 在动这个目录时会自然读到它。这比把所有模块说明堆在一个巨型文件里有效得多。3.2 让 Agent 自己按需取书更进阶的做法是不主动喂而是告诉 Agent 去哪里找。在AGENTS.md里写清楚模块说明在各目录的 CONTEXT.md 中动手前先读对应文件然后依赖 Agent 的自主读取能力。这就像给新人一个文档库的索引而不是把整个文档库打印出来塞他手里。他需要哪块就翻哪块效率高得多。我实测下来这种方式下 Agent 对模块边界的理解明显更准越界改动少了很多。3.3 上下文污染的排查经验有个坑我踩得很深上下文污染。有一次 Agent 反复在一个已经废弃的旧接口上改代码我查了半天才发现是因为仓库里还留着一份过时的文档Agent 读到后把它当成了当前规范。从那以后我养成了一个习惯定期清理仓库里的僵尸文档。凡是和当前代码不符的说明、注释、示例要么更新要么删掉。对 Agent 来说它无法判断哪份文档是新的哪份是旧的你留着它就可能被误读。这一点在多人协作的项目里尤其重要因为文档腐烂是常态。注意上下文治理不只是加什么更是减什么。一个干净、无歧义的仓库对 Agent 的价值不亚于一份详尽的规范。4. 第三层把测试和校验命令变成 Agent 的验收标准4.1 为什么命令比描述更能约束行为这一层是我认为整套架构里性价比最高的一环。核心思路很简单把项目的测试、类型检查、lint 命令明确写进约定并要求 Agent 每次改完必须自己跑一遍。为什么这招管用因为命令的输出是客观的、可判定的。Agent 说我改好了没有意义但pnpm test全绿就是硬证据。你把验收标准从主观描述变成客观命令Agent 的行为立刻就有了锚点。我在AGENTS.md里专门有一段完成定义Definition of Done写清楚什么才算真正完成## 完成定义 一个任务只有在以下全部满足时才算完成 1. pnpm typecheck 无错误 2. pnpm test 全部通过 3. pnpm lint 无警告 4. 新增逻辑有对应测试 5. 变更说明写清楚改了什么、为什么自从加了这段Agent假装完成的情况几乎消失了。因为它知道不跑命令就没法交差。4.2 测试命令要快、准、可复现这里有个实操细节给 Agent 用的测试命令必须足够快。如果你让它每次改完跑一个要五分钟的全量测试它要么偷懒跳过要么你等得抓狂。我的做法是准备两套命令场景命令耗时用途快速反馈pnpm test:unit --changed秒级Agent 改完立即自检完整验收pnpm test分钟级提交前或 CI 跑在AGENTS.md里明确告诉 Agent日常改动跑快速命令准备提交时跑完整命令。这样既保证了反馈速度又不牺牲最终质量。4.3 让失败信息可读还有一个容易被忽略的点测试失败时的报错信息要足够清晰因为这是 Agent 自我修复的主要依据。如果报错是一堆堆栈没有上下文Agent 很难定位问题。我会在测试里加一些辅助断言信息比如expect(result, 用户名为空时应返回 400).toBe(400)。这种带说明的断言Agent 读起来一目了然修复准确率明显提升。这算是给人和Agent双重优化的写法一举两得。5. 第四层用 Subagents 做任务分工别让一个 Agent 干所有事5.1 单 Agent 的注意力涣散问题当任务变复杂单个 Agent 容易注意力涣散——它既要理解需求又要写代码又要跑测试又要写文档结果每样都做得马马虎虎。这跟人一样一个人同时干五件事质量必然下降。Subagents子代理的思路就是把任务拆开每个子代理专注一件事。比如一个负责探索代码库、定位相关文件一个负责写实现一个负责写测试一个负责review 改动。每个子代理的上下文更聚焦输出质量自然更高。5.2 怎么划分 Subagent 的职责划分的核心原则是按关注点拆而不是按文件拆。我常用的几个角色探索者只读不写负责在动手前摸清相关代码、依赖关系、潜在影响面。它的产出是一份现状报告供后续使用。实现者基于探索者的报告写代码专注逻辑正确性。测试者为改动补测试专注边界和异常。审查者以挑刺为目标 review 前面的产出专门找问题。这套分工的好处是每个角色的成功标准都很清晰。探索者的成功是信息准确完整实现者的成功是逻辑正确测试者的成功是覆盖到位审查者的成功是找出问题。目标清晰行为就稳定。5.3 子代理之间的交接是关键Subagent 架构最容易出问题的地方是交接。如果探索者的报告写得含糊实现者就会跑偏如果实现者不说明改了什么审查者就无从下手。我的经验是强制每个子代理产出结构化的交接物。探索者必须输出相关文件清单 关键函数说明 潜在风险点实现者必须输出改动文件清单 改动理由 未决问题。这些交接物既是下一环的输入也是你事后 review 的依据。提示Subagent 不是越多越好。我一般控制在 3 到 4 个角色再多协调成本就超过收益了。任务简单时一个 Agent 加清晰的规矩反而更快。6. 第五层用 Hooks 把事后检查变成事前拦截6.1 Hooks 解决的是信任问题前面几层都是约定和分工本质上是靠 Agent 自觉。但现实是Agent 再听话也可能犯错尤其是涉及危险操作时——比如误删文件、误改配置、提交敏感信息。Hooks钩子就是用来兜底的。它是在 Agent 执行特定动作前后自动触发的脚本可以拦截、校验、甚至阻止某些操作。这一层解决的是信任问题你不需要完全相信 Agent因为关键节点有硬性拦截。6.2 我实际配置的几个关键 Hook我目前用得最多的几个 Hook提交前 Hook在 Agent 执行 git 提交前自动跑 lint 和类型检查不通过就阻止提交。这挡住了大量带病提交。文件写入 Hook监控对敏感目录如配置、CI 文件的写入触发时要求二次确认。命令执行 Hook拦截危险命令模式比如递归删除、强制推送等直接阻断。格式化 Hook文件写入后自动跑格式化保证风格统一省得 Agent 自己纠结格式。这些 Hook 的价值在于把规则从建议升级成强制。约定是软的Hook 是硬的。两者配合才能既灵活又安全。6.3 Hook 设计的一条铁律快、静、准Hook 有个大坑如果它太慢或太吵就会变成负担。我早期配了个每次写入都跑全量测试的 Hook结果每次改文件都要等半分钟体验极差最后只能关掉。后来我总结出 Hook 设计的三条原则快单个 Hook 执行控制在秒级重活交给专门的命令别塞进 Hook。静只在真正需要时输出信息别每次都刷屏。准拦截规则要精确宁可少拦也别误伤误报多了你会想直接关掉它。7. 第六层CLI 工作流与人工把关的边界7.1 CLI 是入口不是全部最外层是工作流本身。无论你用哪个命令行 Agent它都只是整个流程的入口。真正决定效率的是你怎么组织人机协作的节奏。我的日常节奏是这样的先用探索型任务让 Agent 摸清现状我确认方向没问题再让它实现实现过程中它自己跑快速测试完成后我 review 关键改动跑完整测试最后提交提交前 Hook 自动校验。整个流程里Agent 干了大部分体力活我负责方向和验收。7.2 哪些环节必须人工把关有些环节我坚持人工介入绝不放手架构决策涉及模块划分、接口设计的改动必须我先定方向。依赖引入新增任何依赖都要我确认防止供应链风险。数据相关操作涉及数据库迁移、数据删除的必须人工复核。最终提交提交信息、提交范围由我确认不让 Agent 自作主张。这些环节的共同点是影响面大、不可逆。Agent 擅长的是可逆的、局部的、有明确验收标准的活把这些交给它把不可逆的决策留给自己这是人机协作的基本分工。7.3 六层架构的落地顺序建议如果你现在想从零搭这套架构别想着一次全上。我的建议顺序是先写AGENTS.md这是地基投入产出比最高。再把测试和校验命令写进完成定义让 Agent 有验收标准。然后做上下文分层清理僵尸文档。任务复杂了再引入 Subagents。最后按需加 Hooks从提交前校验开始。这个顺序的逻辑是从软约束到硬约束、从简单到复杂。每加一层你都能立刻感受到体验的提升而不是一上来就被复杂的配置劝退。8. 我在实际落地中踩过的几个坑聊完架构说几个具体的坑都是真金白银换来的。第一个坑规矩写太多Agent 反而记不住。我一度把AGENTS.md写到三百多行结果 Agent 开始忽略后面的内容。后来砍到一百行左右只留最关键的效果反而更好。规矩要精不要多。第二个坑Hook 误伤导致流程卡死。有次我配了个拦截规则结果把正常的文件写入也拦了Agent 直接卡住不动。排查半天才发现是正则写得太宽。Hook 上线前一定要在测试环境验证别直接上生产。第三个坑Subagent 交接信息丢失。早期我没强制结构化交接探索者的结论传到实现者那里就变味了。后来强制每个子代理输出固定格式的交接物问题才解决。交接物要有固定 schema不能靠自然语言自由发挥。第四个坑过度依赖 Agent 导致自己不看代码。有一阵我完全放手结果积累了一堆能跑但很丑的代码回头重构花的时间比省下的还多。Agent 是加速器不是替代品关键代码还是要自己过一遍。第五个坑忘了更新规矩。项目演进后AGENTS.md里的命令过时了Agent 照着跑一直失败。规矩文件要纳入日常维护改项目时顺手更新它别让它腐烂。9. 关于这套架构我最后想说的几句实在话这套六层治理架构不是银弹它解决的是让 Coding Agent 稳定产出这个问题而不是让 Agent 无所不能。它的核心思想其实很朴素把模糊的期望变成明确的规则把主观的判断变成客观的验收把不可逆的决策留给人。我用了大半年最大的感受是Agent 的能力上限取决于模型但它的产出下限取决于你的治理。模型再强没有规矩就是一匹脱缰的野马模型一般规矩到位也能稳定干活。对绝大多数日常开发场景来说下限比上限重要得多。如果你现在只打算做一件事那就先把AGENTS.md写好把测试命令写进完成定义。这两件事加起来可能就花你一个小时但带来的体验提升是立竿见影的。剩下的几层等你真正遇到对应的问题时再补完全来得及。工具会一直变今天流行的 CLI 明天可能就换了但立规矩这件事的思路是不变的。把这套思路内化无论换什么工具你都能快速搭起一套靠谱的工作流。这比追任何一个具体工具都值。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化