1. 从人写代码到人管意图AI Native 团队到底在变什么这两年AI Native这个词被喊得很响但真正落到一个研发团队里它到底意味着什么很多人其实是模糊的。我见过不少团队买了几套 AI 编程工具给每个人开了账号然后宣称自己AI Native 转型完成——结果三个月后代码库里多了一堆没人看得懂的生成代码评审时间反而变长了。这不是 AI Native这只是给旧流程贴了张 AI 的皮。我理解的 AI Native 团队核心变化只有一句话人的主要产出从代码变成了意图、约束和验收标准。以前一个工程师一天写 300 行代码现在他一天可能只写 30 行代码但写了 30 条清晰的约束、5 个可执行的验收用例、3 份给 Agent 看的上下文文档。代码由 Agent 生成人负责定义什么叫做对了。这个转变听起来轻巧实际落地时会撞上一堆具体问题Agent 拿不到足够的上下文怎么办多个 Agent 并行改同一个仓库怎么不打架生成的东西怎么保证不是看起来对但跑不通团队里老人不信任 AI 产出怎么办这些问题没有一个是靠换个更强的模型能解决的它们全是工程流程和协作规范的问题。这篇手册就是冲着这些具体问题来的。它适合三类人正在推动团队 AI 化转型的技术负责人、想把自己工作流重构成 Agent 协作模式的资深工程师、以及刚接触 Agent 开发想搞清楚一套完整 SDLC 到底长什么样的开发者。我会把从需求拆解、上下文工程、Agent 编排、到验收与安全的全链路讲透每个环节都给出可抄的配置和踩过的坑。不吹概念只讲能跑起来的东西。2. 上下文工程CLAUDE.md 这类文件为什么是 AI Native 的地基2.1 模型再强喂不对上下文照样白搭很多人对 Agent 的期待是我一句话它就能干活实测下来这是最坑的预期。Agent 的表现80% 取决于你给它的上下文质量20% 才取决于模型本身。一个没有上下文的 Agent就像一个刚入职、没人交接、还被要求当天上线功能的实习生——它只能靠猜猜出来的东西自然不能信。上下文工程要解决的核心问题是让 Agent 在动手之前就知道这个项目的规矩、边界和验收标准。这跟带新人的逻辑一模一样。你不会让新人上来就改核心模块你会先给他一份 README、一份代码规范、一份架构说明。Agent 也一样只不过它读文档的速度是人的几百倍所以你可以把规矩写得更细。2.2 CLAUDE.md 到底该写什么不该写什么CLAUDE.md以及各家工具对应的同类文件比如AGENTS.md、.cursorrules本质上是项目级的常驻上下文它会在每次会话开始时被注入。所以它的定位是每次都需要知道的稳定信息而不是这次任务的具体要求。我踩过的第一个坑就是把CLAUDE.md写成了流水账塞了几千行结果 Agent 反而抓不住重点。后来我总结出一个原则只写如果不知道就会做错的东西。具体来说这几类内容值得写项目定位与目录结构一句话说清这是什么项目主要目录各自负责什么。Agent 靠这个决定该去哪个目录找代码。技术栈与版本约束用什么语言、什么框架、什么版本。特别要写清楚禁止引入的新依赖否则 Agent 会热情地给你装一堆你没批准的库。构建、测试、运行的命令这是最高频被用到的信息。写清楚npm run test还是pytestAgent 才能自己验证。代码风格硬约束命名规范、错误处理方式、日志格式。这些是评审时最容易吵架的点提前写死。禁区哪些文件不许动、哪些操作必须人工确认。比如禁止直接修改数据库迁移文件。不该写的东西同样重要一次性的任务描述、临时的调试信息、大段的业务背景。这些应该放在当次对话里而不是常驻文件里。常驻文件越干净Agent 的注意力越集中。2.3 一份可直接抄的 CLAUDE.md 骨架下面这份骨架是我在多个项目里迭代出来的你可以直接拿去改# 项目说明 这是一个 [项目类型] 项目核心功能是 [一句话]。 # 目录结构 - src/core/ 核心业务逻辑改动需谨慎 - src/api/ 对外接口层 - tests/ 测试用例新增功能必须补测试 - scripts/ 构建与部署脚本 # 技术栈 - 语言TypeScript 5.x - 框架Node.js 20 Fastify - 测试Vitest - 禁止引入任何 ORM 框架用原生 SQL # 常用命令 - 安装依赖npm ci - 运行测试npm run test - 本地启动npm run dev - 类型检查npm run typecheck # 代码规范 - 所有导出函数必须有 JSDoc - 错误统一用 Result 类型返回禁止抛异常穿透 - 日志用 logger.info/warn/error禁止 console.log # 禁区 - 禁止修改 migrations/ 下的历史文件 - 禁止在未确认的情况下删除任何测试 - 涉及支付逻辑的改动必须标记 [NEEDS_REVIEW]这份文件不长但覆盖了 Agent 干活时最容易出错的几个点。实测下来有了它之后Agent 生成的代码跑不通的比例能降一大半。2.4 上下文分层常驻、任务、临时三层怎么分光有一个CLAUDE.md还不够。我后来把上下文分成三层效果明显更好层级载体生命周期内容常驻层CLAUDE.md / AGENTS.md长期项目规矩、命令、禁区任务层任务描述文件 / Issue单次任务需求、验收标准、相关文件临时层对话内单轮调试信息、报错、临时决策分层的意义在于控制注入量。常驻层每次都注入所以要精简任务层只在做这个任务时注入临时层用完即弃。很多团队把所有东西都堆进常驻文件结果 Agent 每次都在读一堆无关信息既慢又容易跑偏。提示任务层最好用结构化模板强制写清目标、验收标准、涉及文件、禁止事项四项。缺了验收标准Agent 就不知道什么时候算做完。3. Plan Mode 与任务拆解让 Agent 先想清楚再动手3.1 为什么直接开干是最贵的做法Agent 最诱人的地方是你说一句它就开始写但这也是最烧钱、最容易翻车的地方。一个没想清楚就动手的 Agent会沿着错误的方向一路狂奔改十几个文件最后你发现方向从一开始就错了只能全部回滚。这个过程消耗的 token、时间和你的信任都是实打实的成本。Plan Mode规划模式就是解决这个问题的。它的逻辑很简单先让 Agent 输出一份计划人确认后再执行。这跟资深工程师带团队是一个道理——你不会让新人直接改生产代码你会先让他说一遍打算怎么改。3.2 一份好的计划应该长什么样我要求 Agent 输出的计划必须包含这几块缺一块就打回重做任务理解用自己的话复述一遍需求。这一步能立刻暴露理解偏差。改动清单列出要改哪些文件、每个文件改什么。粒度到函数级别最好。依赖与风险这次改动会影响哪些其他模块有没有破坏性变更。验证方案怎么证明改对了。跑哪些测试、手动验证哪些场景。不确定项哪些地方它没把握需要人拍板。第五点特别关键。一个诚实的 Agent 会告诉你这里我不确定而一个自信的 Agent 会直接猜。我宁愿它多问几句也不想它猜错。3.3 任务拆解的粒度多大算合适任务拆得太粗Agent 一次要处理太多东西容易顾此失彼拆得太细又会产生大量碎片化的会话上下文来回切换反而低效。我的经验是一个任务对应一次可独立验证的改动。判断标准很简单这个任务做完之后能不能用一组测试或一次手动操作来验证它对不对能粒度就合适不能就还得拆。举个例子实现用户登录功能太粗了它包含接口、校验、会话、错误处理一堆东西。拆成实现登录接口的参数校验、实现登录成功后的会话签发、实现登录失败的错误返回就合适多了每个都能单独测。3.4 计划评审人该在哪些点上卡住计划评审不是走过场。我一般重点看三个地方改动范围有没有动到不该动的文件范围是不是比预期大验证方案它打算怎么证明自己对了如果验证方案是我觉得对直接打回。不确定项它标出来的不确定项是不是真的需要我拍板还是它偷懒不想查这里有个反直觉的经验Agent 主动标出的不确定项越多通常说明它越靠谱。因为这说明它在认真评估边界而不是盲目自信。反倒是那些什么都确定的计划往往藏着没被发现的坑。4. Agent 编排与并行协作多 Agent 怎么不打架4.1 单 Agent 的天花板在哪单 Agent 能搞定的事其实不少但一旦任务规模上去就会撞到天花板。最典型的问题是上下文窗口一个复杂任务涉及几十个文件全塞进一个 Agent 的上下文里要么超限要么注意力被稀释开始犯低级错误。另一个问题是串行效率。一个 Agent 一次只能干一件事改完 A 再改 B改完 B 再改 C。如果 A、B、C 之间没有依赖完全可以并行但单 Agent 做不到。4.2 编排模式主管-工人、流水线、对等协作多 Agent 编排常见三种模式各有适用场景模式结构适用场景风险主管-工人一个主 Agent 拆任务多个子 Agent 执行任务可清晰拆分主 Agent 成为瓶颈流水线每个 Agent 负责一个阶段串行传递流程固定的场景单点失败会阻塞全链对等协作多个 Agent 平级互相评审需要交叉验证的任务协调成本高我实际用得最多的是主管-工人模式。主 Agent 负责拆解和汇总子 Agent 各自负责一个独立模块。关键是要给每个子 Agent 划定清晰的边界——它只能改自己负责的文件不能越界。4.3 并行改同一仓库冲突是怎么产生的并行最大的坑是文件冲突。两个子 Agent 同时改同一个文件后写的会覆盖先写的而且这种覆盖往往悄无声息。我踩过一次两个 Agent 分别改了同一个工具函数结果合并后逻辑全乱了测试还恰好没覆盖到。解决办法有几个层次最粗暴但有效任务拆解时就保证文件不重叠。每个子 Agent 负责的文件集合互不相交。加锁机制如果实在无法避免重叠用文件锁或 Git 分支隔离改完再合并。事后校验合并后强制跑全量测试用测试兜底。我一般优先用第一种因为它在源头就避免了问题。拆任务的时候多花五分钟确认文件不重叠比事后排查冲突省事得多。4.4 用 Git 分支做 Agent 隔离的实操如果任务确实无法完全隔离文件我会用 Git 分支给每个 Agent 做隔离。具体做法# 为每个子任务创建独立分支 git checkout -b agent/task-login-validation git checkout -b agent/task-session-issue # 每个 Agent 在自己的分支上工作 # 完成后由主 Agent 或人负责合并 git checkout main git merge agent/task-login-validation这样即使两个 Agent 改了同一个文件冲突也会在合并时显式暴露出来而不是被静默覆盖。合并冲突虽然烦但至少是可见的、可控的。注意分支隔离会增加合并成本所以只在对等协作或文件必然重叠时才用。能靠任务拆解避免的就别上分支。5. 验收与测试怎么判断 Agent 干得对不对5.1 看起来对是最大的陷阱Agent 生成的代码有个特点读起来特别顺逻辑特别自洽但就是跑不通。因为它是在预测下一个 token而不是在真正执行。它写出来的代码符合语法、符合常见模式但可能引用了一个不存在的函数或者参数顺序搞反了。所以验收的第一原则是永远不要靠读代码来判断对错要靠跑。代码读起来再漂亮测试不过就是不过。5.2 验收标准必须在任务开始前定好这是我最想强调的一点。验收标准不能等 Agent 干完了再想必须在任务描述里就写清楚。原因很简单Agent 会朝着你给的验收标准去优化。你不给标准它就自己编一个编出来的标准往往和你的预期差很远。好的验收标准是可执行的比如新增的接口在给定输入下返回预期输出写成测试用例现有测试全部通过类型检查无错误特定边界场景手动验证通过代码质量高、逻辑清晰这种标准没用因为没法执行Agent 也没法自证。5.3 自动化验收链路怎么搭我一般会搭一条自动化验收链路Agent 每完成一个任务就自动跑一遍#!/bin/bash set -e echo 1. 类型检查 npm run typecheck echo 2. 单元测试 npm run test echo 3. 集成测试 npm run test:integration echo 4. 构建 npm run build echo 全部通过这条链路的意义在于把对不对的判断权交给机器。人不用逐行读代码只需要看链路是否全绿。全绿了再人工抽查关键逻辑效率高得多。5.4 人工评审该看什么不该看什么自动化链路过了之后人工评审不是重读一遍代码而是看几个机器看不出来的东西设计意图这个改动符不符合整体架构方向有没有引入不该有的耦合边界处理异常路径、并发场景、极端输入这些测试未必覆盖到。可维护性命名是否清晰有没有留下以后没人看得懂的代码。安全有没有引入注入、越权之类的风险。格式、风格、明显的语法问题交给 linter 和类型检查人不用管。人的时间要花在机器判断不了的地方。6. Agent 安全与沙箱别让自动化变成事故源6.1 Agent 能执行命令就意味着它能搞破坏Agent 和普通代码补全最大的区别是它能执行命令。它能跑rm、能改配置、能发网络请求、能操作数据库。这既是它的能力来源也是最大的风险来源。一个没约束好的 Agent可能因为理解偏差就把生产数据删了。我见过最惊险的一次是 Agent 为了清理测试数据执行了一条没有WHERE条件的DELETE。幸好那是在测试库要是在生产库后果不堪设想。6.2 沙箱隔离的几种做法沙箱的核心思路是给 Agent 一个受限的执行环境让它即使犯错也伤不到要害。常见做法容器隔离Agent 在独立容器里跑文件系统、网络都受限。权限最小化Agent 用的账号只有必要权限删不了关键资源。网络白名单只允许访问必要的服务其他一律拒绝。只读挂载敏感目录以只读方式挂载Agent 改不了。这些措施单独看都不复杂但组合起来能挡住绝大多数误操作。6.3 危险操作的确认机制有些操作风险太高不适合完全自动化必须人工确认。我一般会把这些操作列成一张清单Agent 遇到时必须停下来问删除文件或数据修改生产环境配置执行数据库迁移推送代码到主分支调用外部付费接口实现上可以在 Agent 的工具层加一道拦截命中清单里的操作就暂停并请求确认。这道拦截看起来麻烦但它拦下的每一次都可能是省下的一次事故。6.4 审计日志出了事怎么回溯Agent 干了什么必须留痕。我要求所有 Agent 的命令执行、文件改动、外部调用都记进审计日志包含时间、操作、参数、结果。平时没人看但一旦出问题这份日志就是唯一的线索来源。日志要记到什么粒度我的标准是能凭日志完整复现一次事故。如果复现不了说明记漏了。7. 团队协作与流程重构AI Native 不是一个人的事7.1 从个人提效到团队范式差在哪一个人用 AI 提效和整个团队 AI Native是两码事。个人提效靠的是个人技巧团队范式靠的是共享的规范和流程。如果每个人都有自己的CLAUDE.md、自己的验收标准、自己的 Agent 用法那团队协作时就会一团乱。团队 AI Native 的关键是把个人的好做法沉淀成团队规范统一的上下文文件模板、统一的任务描述格式、统一的验收链路、统一的安全清单。这样新人进来能快速上手Agent 的行为也可预期。7.2 代码评审怎么适应 Agent 产出传统的代码评审假设代码是人写的所以关注点在于人有没有想清楚。但 Agent 产出的代码问题往往不在想没想清楚而在跑没跑通、符不符合约束。所以评审流程要调整先过自动化链路再人工评审。自动化链路负责筛掉跑不通的人工评审负责筛掉跑通了但设计不对的。顺序反了人就会把大量时间浪费在读跑不通的代码上。7.3 知识沉淀把踩过的坑变成团队资产Agent 会反复犯同类错误。今天这个 Agent 踩了忘了处理空输入的坑明天另一个 Agent 还会踩。解决办法是把这些坑沉淀成团队级的检查项写进上下文文件或验收清单。我维护了一份Agent 常见错误清单每次发现新坑就加一条。这份清单越来越长但 Agent 犯重复错误的概率越来越低。这就是团队资产的价值——它让整个团队的 Agent 都变聪明了。7.4 新人如何快速融入 AI Native 流程新人融入 AI Native 团队最大的障碍不是技术而是信任。老人不信任 AI 产出新人不知道怎么和 Agent 协作。我的做法是让新人从评审 Agent 产出开始而不是从指挥 Agent 干活开始。评审的过程就是学习团队规范的过程。等他看懂了 Agent 该怎么用、什么算合格再让他自己指挥。8. 我踩过的几个真实坑和对应的解法8.1 上下文太长导致 Agent 失忆有段时间我发现 Agent 老是忘记项目的基本规矩明明CLAUDE.md里写了它还是违反。排查后发现是上下文太长关键信息被淹没了。解法是把常驻文件精简到只留不知道就会做错的内容其他移到任务层。8.2 并行任务的文件冲突前面提过的那次冲突两个 Agent 改了同一个工具函数合并后逻辑全乱。解法是任务拆解时强制保证文件不重叠实在不行就上分支隔离。8.3 验收标准缺失导致的返工早期我经常不给验收标准让 Agent 自己发挥结果它做出来的东西和我想的完全不一样只能返工。后来强制要求每个任务都写验收标准返工率大幅下降。8.4 危险操作没有拦截那次差点删库的经历之后我加了危险操作确认机制。虽然偶尔会打断流程但比起事故的代价这点打断完全值得。9. 关于工具选型的一点个人看法工具这块我不想给绝对答案因为每个团队的情况不一样。但有几个判断维度可以参考上下文管理能力能不能方便地注入项目级上下文能不能分层。执行能力能不能跑命令、跑测试还是只能生成代码。安全控制有没有沙箱、有没有危险操作拦截。可编排性能不能多 Agent 协作能不能接自定义流程。至于具体用哪个框架、哪个工具我的建议是先用起来再优化。纠结选型的时间往往比选错工具浪费的时间还多。先跑通一个最小闭环再根据实际痛点换工具比纸上谈兵强得多。我在实际使用中最深的一个体会是AI Native 的难点从来不在 AI而在 Native。工具会越来越强模型会越来越聪明但团队能不能把 AI 真正融进研发流程靠的是规范、是纪律、是持续沉淀。那些转型成功的团队不是因为用了最贵的工具而是因为他们把上下文写清楚了、把验收标准定死了、把安全边界划明白了。这些事听起来不酷但它们才是真正决定成败的东西。如果你现在正准备推动团队 AI 化我的建议是从一个小项目、一个小团队开始把上面这套流程跑一遍踩一遍坑再逐步推广。别一上来就全团队铺开那样出了问题你都不知道从哪查起。