1. 从“人肉流水线”到“AI Native 团队”为什么我要重写整套开发手册过去大半年我一直在带一个不到十人的小团队做产品迭代。说实话最初听到“AI Native”这个词的时候我跟很多一线开发者的反应一样——又是一个包装概念。毕竟我们已经在用 Copilot 补全代码、用 ChatGPT 查报错、用 Claude 读文档这难道还不算 AI Native 吗直到有一次复盘我拉了一下数据团队里每个人每天花在“等 AI 生成代码、复制粘贴、手动验证、再复制回去”上的时间平均超过两个小时。更离谱的是同一个模块三个人用三种不同的提示词风格产出的代码结构完全不一样合并的时候冲突比手写还多。那一刻我才意识到我们只是把 AI 当成了一个更快的“打字员”整个软件开发生命周期SDLC的骨架还是人肉流水线。这就是我决定动手重写整套开发手册的起点。所谓AI Native 团队不是“用了 AI 工具的团队”而是把 AI 当作团队的一等公民——它有明确的职责边界、有可复用的技能包、有标准化的协作协议甚至有自己的“工位”运行环境和“交接文档”CLAUDE.md 这类上下文文件。而SDLC的每一个环节从需求拆解、方案设计、编码、测试到部署都要重新回答一个问题这一步到底是人主导还是 Agent 主导还是人机协同这篇手册适合三类人看一是正在小团队里推 AI 协作、但被混乱的提示词和不可复现的结果折磨的技术负责人二是想从“会用 AI 写代码”进阶到“会设计 Agent 工作流”的开发者三是单纯好奇 AI Native 到底怎么落地、不想再听空泛概念的一线工程师。我会把踩过的坑、验证过的配置、以及那些文档里不会写的经验全部摊开讲。2. 核心概念拆解Agent、Skill、Harness 到底谁管谁在动手搭流程之前必须先把几个高频词的关系理清楚。我发现团队里最大的沟通成本不是技术难题而是大家对“Agent”这个词的理解根本不在一个频道上。有人说 Agent 就是那个会自己调工具的模型有人说 Agent 是一整套包含记忆和规划的系统还有人把写好的提示词模板也叫 Agent。这种混乱直接导致架构设计反复推翻。2.1 Agent 不是模型是“带手脚和记忆的执行单元”我的定义很直接Agent 模型 工具集 记忆 执行循环。模型负责推理和决策工具集是它的手脚读写文件、执行命令、调用 API记忆让它不重复犯错执行循环则保证它能根据结果调整下一步。缺了任何一环它都只是个“会聊天的函数”。举个实际例子。我们有一个 Agent 专门负责“把产品需求文档转成技术任务列表”。它的工具集里只有三个读取指定目录下的 Markdown 文件、调用一个内部的任务创建接口、以及写入一个日志文件。记忆部分我们用一个简单的 JSON 文件存历史任务拆解结果每次启动时注入上下文。执行循环设定为最多五轮如果五轮内没有产出合格的任务列表就交回给人。这个 Agent 不写代码、不做设计职责极其单一但正因为边界清晰它的输出稳定性远高于那些“什么都能干”的通用助手。注意不要试图用一个 Agent 包揽所有环节。我试过让一个 Agent 从需求一直做到部署结果它在第三步就开始胡编 API 参数因为上下文太长、职责太杂模型根本分不清当前该用哪套规则。2.2 Skill 是可复用的“操作说明书”不是提示词Agent Skill这个词最近很热但很多人把它等同于“写得更长的提示词”。我的理解是Skill 是一份结构化的操作说明书包含触发条件、输入输出格式、依赖工具、以及失败回退策略。它和提示词的本质区别在于——提示词是给模型看的自然语言Skill 是给系统看的契约。我们团队内部维护了一个 Skill 仓库每个 Skill 是一个独立目录里面至少有三个文件manifest.yaml声明名称、版本、依赖工具、prompt.md具体的指令模板、examples/至少两个输入输出样例。比如“生成数据库迁移脚本”这个 Skill它的 manifest 里明确写了依赖read_file和write_file两个工具prompt 里规定了必须输出可回滚的 SQLexamples 里放了两个真实案例。这样做的好处是任何 Agent 只要挂载这个 Skill就能获得一致的行为不需要每次重新调提示词。2.3 Harness 是“工位和流水线”Agent 是“工人”Harness 和 Agent 的区别我用一个类比解释Agent 是工人Harness 是工位、工具墙和传送带的总和。Harness 负责给 Agent 提供运行环境、注入上下文、管理工具权限、记录执行日志、以及在出错时决定是重试还是上报。一个设计良好的 Harness可以让同一个 Agent 在不同项目里快速切换因为环境配置和权限边界都由 Harness 统一管理。我们早期犯的错就是把所有东西都塞进 Agent 的提示词里结果换个项目就要重写一遍。后来把环境变量、工具白名单、日志路径这些抽到 Harness 层Agent 本身只保留业务逻辑复用率立刻上来了。现在我们的 Harness 配置文件大概长这样# harness.yaml agent: requirement-splitter model: claude-sonnet tools: - read_file - write_file - create_task context: - ./CLAUDE.md - ./docs/prd/*.md limits: max_turns: 5 timeout: 120s logging: path: ./logs/requirement-splitter/ level: debug这份配置里CLAUDE.md就是团队的“交接文档”里面写了项目背景、代码规范、当前迭代目标。每次 Agent 启动Harness 会自动把它注入上下文省去了反复交代背景的麻烦。3. 落地前的关键决策Plan Mode 与上下文文件怎么定概念理清之后下一个问题就是具体怎么让 Agent 干活这里有两个决策点直接决定了后续流程是顺畅还是灾难。我见过太多团队一上来就让 Agent 直接写代码结果产出不可控、无法审查、出了问题找不到原因。正确的做法是先规划、再执行而规划的质量取决于上下文文件的质量。3.1 Plan Mode让 Agent 先“说清楚要干什么”再动手Plan Mode是我强烈建议每个团队都强制启用的模式。它的核心逻辑很简单Agent 在真正修改任何文件之前必须先输出一份执行计划包括要改哪些文件、每个文件改什么、预期结果是什么、以及可能的风险点。这份计划会先交给人审查人确认之后 Agent 才进入执行阶段。我们实测下来启用 Plan Mode 之后Agent 产出代码的一次通过率从不到四成提升到了七成以上。原因不复杂——模型在“写计划”的时候被迫把模糊的需求拆成了具体步骤很多逻辑漏洞在计划阶段就暴露了。比如有一次Agent 计划里写着“修改用户表的 email 字段类型”我一看就发现它漏掉了关联的索引重建直接打回去重写计划省了后面一堆麻烦。Plan Mode 的提示词模板我们迭代了十几版最终稳定下来的核心结构是这样的你是一个规划助手。在修改任何文件之前请先输出执行计划。 计划必须包含 1. 涉及的文件列表完整路径 2. 每个文件的修改内容摘要不超过三句话 3. 修改之间的依赖顺序 4. 可能影响的其他模块 5. 验证方式如何确认修改成功 如果信息不足请列出需要澄清的问题不要猜测。提示Plan Mode 的输出不要直接丢给执行 Agent中间一定要有人工审查环节。我们试过全自动流转结果 Agent 把一个测试环境的配置改到了生产目录虽然最后回滚了但教训很深刻。3.2 CLAUDE.md团队的“交接文档”怎么写才有效CLAUDE.md这个名字来源于 Claude 的上下文约定但本质上它就是一份放在项目根目录的 Markdown 文件用来告诉 AI 这个项目的背景、规范和当前状态。很多团队也把它叫AGENTS.md或CONTEXT.md叫法不重要重要的是内容。我见过两种极端一种是写得像 README全是项目介绍对 AI 干活毫无帮助另一种是写得像提示词大全几百行规则模型根本记不住。我的经验是CLAUDE.md 控制在 80 到 150 行之间只写三类信息不可变的约束、当前迭代的目标、以及常见的坑。不可变的约束包括代码风格、目录结构约定、禁止使用的库。比如我们规定所有数据库操作必须走 ORM禁止裸写 SQL所有 API 返回必须用统一的响应包装类。当前迭代的目标每周更新一次写清楚这周要完成哪几个功能、优先级如何。常见的坑则是历史踩雷记录比如“不要修改config/legacy目录下的任何文件那是旧系统的兼容层”。这里有个细节值得展开CLAUDE.md 的更新频率。我们一开始是每月更新一次结果 Agent 经常引用过时的目标产出偏离方向。后来改成每周一早上由技术负责人花十分钟更新效果立竿见影。这十分钟的投入换来的是整周 Agent 产出的准确性性价比极高。4. 完整 SDLC 流程从需求到部署的 Agent 编排概念和决策点都清楚了接下来进入实操环节。我把整个 SDLC 拆成了五个阶段每个阶段明确人和 Agent 的分工。需要说明的是这套流程不是一步到位的我们花了大概六周时间逐步替换和调优中间推翻过两次架构。下面这套是当前稳定运行的版本。4.1 需求拆解阶段Agent 做粗筛人做终审需求进来的时候通常是一段模糊的产品描述。这个阶段我们用一个专门的“需求拆解 Agent”它的任务是把描述转成结构化的任务列表每个任务包含标题、验收标准、预估复杂度和依赖关系。Agent 的输入是产品文档和 CLAUDE.md输出是一个 JSON 格式的任务列表。我们设定了一个硬性规则Agent 拆解出的任务必须由产品负责人和技术负责人各审一遍。产品负责人看验收标准是否准确技术负责人看依赖关系和复杂度是否合理。两边都通过之后任务才会进入开发队列。这个阶段最容易出的问题是“过度拆解”。Agent 有时候会把一个简单的功能拆成十几个子任务粒度太细反而增加管理成本。我们的解决办法是在提示词里加一条约束“每个任务的预估工作量不低于半天不超过三天。如果超出这个范围请合并或继续拆分。”这条约束加上之后任务粒度明显合理了。4.2 方案设计阶段Plan Mode 的主战场方案设计是 Plan Mode 发挥最大价值的环节。每个任务进入开发之前对应的 Agent 必须先产出一份技术方案内容包括数据模型变更、接口定义、关键流程、以及测试策略。这份方案会作为后续编码的输入也是代码审查的依据。我们在这里做了一个关键设计方案设计 Agent 和编码 Agent 是分开的。方案 Agent 只读不写它的工具集里没有write_file只有read_file和search。这样做的好处是方案 Agent 不会“边想边改”产出更纯粹。编码 Agent 则拿到方案之后才开始工作职责边界清晰。方案审查我们采用“双人确认”制一个资深开发看技术合理性一个测试同学看可测性。两边都签字之后方案才会被锁定编码 Agent 才能启动。这个流程听起来有点重但实测下来它把后期返工率降低了至少一半。4.3 编码实现阶段小步提交与自动验证编码阶段的核心原则是“小步快跑”。我们要求编码 Agent 每次只处理一个任务完成后立即提交提交信息必须包含任务编号和变更摘要。提交之后Harness 会自动触发一轮验证包括语法检查、单元测试、以及一个轻量的静态分析。这里有个细节Agent 提交的代码我们不要求它自己写测试而是由另一个“测试生成 Agent”根据方案里的测试策略来生成。这样做的原因是让同一个 Agent 既写实现又写测试它容易“自圆其说”测试覆盖不到真正的边界情况。分开之后测试 Agent 会从方案出发独立设计用例发现问题的概率高很多。注意编码 Agent 的上下文里一定要包含最近的提交记录和当前分支状态。我们踩过的坑是Agent 在一个过时的分支上工作产出和主干冲突严重。后来在 Harness 里加了强制检查每次启动前先拉取最新代码冲突就直接终止。4.4 测试与审查阶段Agent 初审人做终审代码提交之后先由审查 Agent 做一轮初审。审查 Agent 的检查项包括是否符合 CLAUDE.md 里的规范、是否有明显的逻辑漏洞、是否缺少必要的错误处理、以及测试覆盖率是否达标。初审不通过的直接打回给编码 Agent 修改不占用人的时间。初审通过之后才进入人工审查。人工审查我们只关注三件事业务逻辑是否正确、边界条件是否考虑周全、以及是否有安全或性能隐患。其他细节交给 Agent 把关。这样人的精力集中在真正需要判断力的地方审查效率提升明显。测试环节我们采用“Agent 执行、人看报告”的模式。测试 Agent 负责跑用例、收集结果、生成报告。报告里会标注失败的用例、失败原因、以及建议的修复方向。人只需要看报告决定是打回修复还是接受当前状态。4.5 部署与回滚阶段自动化为主人工兜底部署阶段我们尽量做到自动化。通过验证的代码合并到主干之后Harness 会自动触发构建和部署到预发环境。预发环境跑一轮冒烟测试通过之后才允许上生产。生产部署采用灰度策略先放量百分之五观察十分钟没有异常再逐步扩大。回滚机制是必须提前设计好的。我们的做法是每次部署都保留上一个版本的完整快照回滚命令封装成一个脚本任何人执行都能一键回滚。Agent 在部署过程中如果检测到异常指标会自动触发回滚并通知值班人员。这套机制上线以来触发过三次自动回滚每次都把影响控制在最小范围。5. 踩坑实录那些文档里不会写的经验前面讲的都是“应该怎么做”但实际落地过程中真正花时间的往往是那些意料之外的问题。这一章我挑几个印象最深的坑把排查过程和解决方法完整还原出来希望能帮你少走弯路。5.1 Agent 执行中断从日志里找线索最常见的问题就是 Agent 跑到一半突然停了报一个模糊的错误比如“execution terminated due to error”。第一次遇到的时候我们完全懵了不知道是模型的问题、工具的问题还是环境的问题。后来养成了习惯先看 Harness 的日志再看 Agent 自己的执行日志最后看工具调用的返回。有一次排查发现是 Agent 在调用一个内部 API 时返回了一个非 JSON 格式的错误页面Agent 解析失败就终止了。解决办法是在工具层加一层容错所有 API 调用都先检查响应格式不符合预期的就返回一个标准错误对象让 Agent 能继续处理而不是直接崩溃。这个改动之后类似的意外终止减少了八成以上。5.2 上下文污染Agent 为什么会“忘记”规则另一个高频问题是 Agent 不遵守 CLAUDE.md 里的规则。明明写了“禁止裸写 SQL”它还是给你来一段SELECT * FROM。排查之后发现是上下文太长了模型在生成的时候“注意力”被其他内容分散了。我们的解决办法是分层注入上下文。CLAUDE.md 里的核心约束放在系统提示的最前面用特殊标记包起来比如critical_rules标签。当前任务相关的上下文放在后面。这样模型在处理具体任务时核心约束始终在它的“视野”里。另外我们把 CLAUDE.md 拆成了两个文件一个是不变的规则文件一个是每周更新的目标文件分别注入避免互相干扰。5.3 并发冲突多个 Agent 同时改一个文件当团队规模上来之后多个 Agent 同时工作的情况很常见。我们遇到过一次两个 Agent 同时修改同一个配置文件后提交的把先提交的覆盖了导致一个功能莫名其妙失效。排查了半天才发现是并发写入的问题。解决办法是在 Harness 层加一个文件锁机制。Agent 在修改文件之前先申请锁拿到锁才能写写完释放。申请不到锁的 Agent 会等待或者被调度到其他任务。这个机制实现起来不复杂但效果立竿见影之后再没出现过覆盖问题。5.4 常见问题速查表为了方便团队新成员快速上手我把高频问题和解决方法整理成了一张表贴在内部文档的首页。问题现象可能原因排查方向解决方法Agent 执行中断工具返回格式异常查看工具调用日志工具层加容错返回标准错误对象Agent 不遵守规则上下文过长或规则位置靠后检查提示词结构核心规则前置用标签标记产出代码风格不一致Skill 未统一或提示词差异大对比不同 Agent 的 Skill 配置统一挂载同一 Skill禁止自定义提示词文件被覆盖并发写入无锁查看提交时间戳Harness 层加文件锁任务拆解粒度过细提示词缺少粒度约束检查拆解 Agent 的提示词增加工作量范围约束测试覆盖不足实现和测试由同一 Agent 完成检查测试生成流程拆分实现 Agent 和测试 Agent6. 团队协作与安全边界AI Native 不是放任自流最后想聊聊协作和安全。AI Native 团队最容易走偏的地方就是把“自动化”等同于“无人化”。我见过一些团队恨不得所有环节都让 Agent 自己跑人只负责最后点个合并按钮。这种做法短期看起来效率很高长期一定出问题因为 Agent 没有业务判断力也没有责任意识。6.1 权限分级Agent 能碰什么不能碰什么我们给 Agent 设了三层权限。第一层是只读权限只能看文件、搜索代码不能做任何修改方案设计 Agent 和审查 Agent 属于这一层。第二层是受限写权限只能修改指定目录下的文件编码 Agent 属于这一层它的写入范围被限制在src/和tests/目录。第三层是执行权限可以运行命令、部署服务只有部署 Agent 拥有而且它的操作需要人工二次确认。权限配置写在 Harness 里Agent 本身无法绕过。这样做的好处是即使 Agent 被提示词注入攻击它能造成的破坏也被限制在权限范围内。安全边界不是靠信任而是靠机制。6.2 人工兜底哪些环节必须有人签字有三个环节我们坚持必须人工签字不允许 Agent 自动通过。第一是方案锁定技术方案必须由资深开发确认后才能进入编码。第二是生产部署部署到生产环境之前必须由值班人员确认。第三是数据变更任何涉及数据库结构或数据迁移的操作必须由 DBA 审核。这三个环节的共同点是一旦出错影响范围大、恢复成本高。Agent 可以辅助准备材料、生成脚本、执行预检查但最终的“确认”动作必须由人完成。这不是对 Agent 的不信任而是对风险的敬畏。6.3 持续迭代手册本身也要版本管理最后一点经验这套手册本身也要当作代码来管理。我们把它放在 Git 仓库里每次流程调整都提交一个 commit写清楚改了什么、为什么改。每个月做一次回顾看看哪些环节的 Agent 产出质量下降了哪些规则已经过时了。我个人的体会是AI Native 团队的竞争力不在于用了多先进的模型而在于这套协作流程的迭代速度。模型每个月都在更新但流程的沉淀和优化才是真正拉开差距的地方。我们团队从最初的混乱到现在相对稳定靠的不是某个神奇的工具而是持续不断地记录问题、调整配置、更新手册。这个过程没有终点但每一步的改进都能实实在在感受到。