1. 从“用AI提效”到“AI Native”一次研发范式的彻底换轨过去两年我参与过不少团队从零搭建 AI 辅助研发流程的项目。大多数团队的做法是在原有 SDLC 上加一层“AI 工具”比如让工程师用 AI 补全代码、用 AI 写单测、用 AI 生成文档。这种模式我称之为“AI Assisted”——人还是主体AI 是工具。但真正让我感到范式变化的是接触到AI Native 团队之后。所谓 AI Native不是“用了 AI 的团队”而是把 Agent 作为研发流程中的一等公民让 Agent 承担从需求拆解、方案设计、编码实现、测试验证到部署运维的完整闭环人类工程师的角色从“执行者”转变为“编排者”和“审核者”。这套《AI Native 团队完整开发落地手册》要解决的正是大多数团队在落地时最头疼的问题Agent 到底怎么编排SDLC 每个阶段 Agent 该做什么、不该做什么CLAUDE.md 这类上下文文件怎么写才有效Plan Mode 和直接执行模式怎么选多 Agent 协作时并发和安全怎么扛这些问题在官方文档里往往只有零散说明真正踩过坑的人才知道细节有多要命。这篇文章适合三类人一是正在推动团队 AI 转型的技术负责人二是想搭建自己 Agent 工作流的独立开发者三是对 AI Native SDLC 感兴趣但不知道从哪下手的工程师。我会把整套手册拆成可复现的模块从架构设计、上下文工程、Plan Mode 实操、多 Agent 编排、并发与安全、到常见问题排查全部用我实际跑过的方案来讲。读完你至少能搭出一套能跑通的最小可用 AI Native 研发流程。2. AI Native SDLC 的整体架构与核心设计思路2.1 为什么传统 SDLC 加 AI 工具不够用传统 SDLC 的假设是“每个阶段由人主导工具辅助”。需求阶段产品经理写 PRD设计阶段架构师画图开发阶段工程师写代码测试阶段 QA 写用例。AI 工具进来之后只是把每个环节的效率提升了一点但阶段之间的交接成本、上下文丢失、返工率这些根本问题没有解决。我见过最典型的场景工程师用 AI 生成了代码但 AI 不知道上游 PRD 里的约束条件结果生成的接口签名和设计文档对不上返工重来。问题不在于 AI 能力不够而在于上下文没有在阶段之间流动。AI Native SDLC 的核心设计思路就是让 Agent 携带完整上下文贯穿整个流程每个阶段的产出自动成为下一阶段的输入人类只在关键决策点介入。2.2 Agent 在 SDLC 各阶段的角色划分我把 AI Native SDLC 拆成六个阶段每个阶段对应一类 Agent 角色。这里的关键是职责边界要清晰否则多 Agent 协作会变成互相甩锅。阶段Agent 角色核心职责人类介入点需求分析Requirement Agent解析原始需求生成结构化 PRD识别歧义确认需求边界方案设计Architect Agent基于 PRD 生成技术方案输出接口定义审核架构决策任务拆解Planner Agent把方案拆成可执行任务标注依赖关系确认优先级编码实现Coder Agent按任务生成代码自测通过后提交Code Review测试验证Tester Agent生成测试用例执行验证输出报告确认覆盖度部署运维Ops Agent生成部署配置监控运行状态审批上线这张表看起来简单但实际落地时最容易出问题的是阶段之间的上下文传递。Requirement Agent 生成的 PRD 如果只是自然语言Architect Agent 解析时就会丢失细节。我的做法是强制每个 Agent 的输出都包含结构化元数据比如 PRD 里必须包含constraints、acceptance_criteria、out_of_scope三个字段这样下游 Agent 能精确提取。2.3 为什么选择 Agent 编排而不是单体大模型有团队问过我为什么不直接用一个超强的大模型把整个 SDLC 的 prompt 都塞进去我的回答是上下文窗口再大也有边界而且单体模型的错误会级联放大。一个 Agent 在需求阶段理解错了后面所有阶段全错而且很难定位是哪一步出的问题。Agent 编排的好处是错误隔离和可观测性。每个 Agent 的输入输出都是显式的出问题能快速定位到具体环节。另外不同阶段对模型能力的要求不同需求分析需要强推理编码需要强代码能力测试需要强逻辑覆盖。用 Agent 编排可以针对每个阶段选最合适的模型成本和效果都更优。注意Agent 编排不是越多越好。我见过一个团队把 SDLC 拆成 20 多个 Agent结果编排复杂度爆炸调试成本比收益还高。我的经验是6 到 8 个 Agent 是甜点区再多了就要考虑合并。3. 上下文工程CLAUDE.md 与 Agent 记忆的实战写法3.1 CLAUDE.md 到底该写什么CLAUDE.md 是 Agent 进入项目时的“第一份上下文”它的质量直接决定 Agent 后续行为是否符合预期。我见过很多团队的 CLAUDE.md 写成了一本项目百科结果 Agent 根本抓不住重点。我的写法是只写三类信息项目约束、协作规范、关键路径。项目约束包括技术栈版本、代码风格、禁止使用的库。比如## 项目约束 - 语言TypeScript 5.3严格模式 - 框架Next.js 14 App Router - 禁止使用moment.js用 date-fns 替代 - 测试框架Vitest覆盖率要求 80%协作规范包括提交信息格式、分支命名、PR 模板。关键路径则是告诉 Agent“遇到什么情况该看哪个文件”。比如“接口定义在src/types/api.ts数据库 schema 在prisma/schema.prisma”。提示CLAUDE.md 不要超过 200 行。超过这个长度Agent 的注意力会被稀释关键约束反而被忽略。我通常把详细文档放在docs/目录CLAUDE.md 里只放索引和硬约束。3.2 Agent 记忆的分层设计Agent 记忆分三层会话记忆、项目记忆、长期记忆。会话记忆是当前对话的上下文项目记忆是 CLAUDE.md 和代码库索引长期记忆是跨会话的经验沉淀。会话记忆的管理关键是及时压缩。Agent 跑长任务时上下文会迅速膨胀。我的做法是每完成一个子任务就让 Agent 输出一份摘要把详细过程丢弃只保留结论和关键决策。这样上下文始终保持在可控范围。项目记忆的构建靠代码库索引。我通常用repomix把代码库打包成单个文件让 Agent 一次性加载。但要注意排除node_modules、dist、.git这些目录否则索引文件会大到无法处理。长期记忆我用的方案是结构化日志。每次 Agent 完成任务后把“任务类型、输入、输出、遇到的问题、解决方案”写入一个 JSONL 文件。下次遇到类似任务时先检索这个日志把相关经验注入上下文。这个方案实测下来很稳Agent 的重复错误率能降低 60% 以上。3.3 上下文注入的时机与顺序上下文注入不是越多越好时机和顺序同样关键。我的经验是系统约束在最前面任务描述在中间参考资料在最后。这样 Agent 先建立约束框架再理解任务最后查资料逻辑最顺。另外动态上下文要按需注入。比如 Coder Agent 执行任务时只注入相关模块的代码而不是整个代码库。我通常用文件路径匹配的方式根据任务描述里的关键词自动检索相关文件注入上下文。这个逻辑可以用一个简单的脚本实现def inject_context(task_description, repo_index): keywords extract_keywords(task_description) relevant_files [] for file_path, content in repo_index.items(): if any(kw in file_path or kw in content for kw in keywords): relevant_files.append((file_path, content)) return relevant_files[:10] # 限制数量避免上下文爆炸这个脚本看起来简单但实测效果比全量注入好很多。Agent 的响应速度更快而且不容易被无关信息干扰。4. Plan Mode 实操从需求到可执行任务的完整链路4.1 Plan Mode 与直接执行模式的取舍Plan Mode 的核心是先规划再执行Agent 不直接改代码而是输出一份执行计划人类确认后再进入执行。直接执行模式则是 Agent 边想边做适合简单任务。我的判断标准是任务涉及超过 3 个文件或者有跨模块依赖就必须用 Plan Mode。因为这种任务一旦方向错了返工成本极高。而单文件的小修改直接执行效率更高。Plan Mode 的另一个价值是可审计。计划本身就是一份文档记录了 Agent 的决策依据。出了问题可以回溯是哪一步的假设错了。这在团队协作场景下尤其重要因为你需要向其他人解释“为什么 Agent 这么做”。4.2 需求解析把模糊描述变成结构化 PRD原始需求往往是模糊的比如“做一个用户登录功能”。Requirement Agent 的任务是把它变成结构化 PRD。我的 prompt 模板是这样的你是一个需求分析 Agent。请把以下原始需求解析为结构化 PRD。 原始需求{raw_requirement} 输出格式 ## 功能描述 一句话说明这个功能做什么 ## 约束条件 - 技术约束 - 业务约束 - 性能约束 ## 验收标准 - 可测试的具体条件 ## 不在范围内 - 明确排除的内容 ## 待确认问题 - 需要人类确认的歧义点这个模板的关键是强制 Agent 输出“不在范围内”和“待确认问题”。这两个字段能有效防止范围蔓延也能让人类快速发现理解偏差。4.3 任务拆解从 PRD 到可执行任务列表Planner Agent 拿到 PRD 后要拆成可执行任务。我的拆解原则是每个任务不超过 2 小时工作量且能独立验证。任务之间用依赖关系连接形成 DAG。任务列表的格式我固定为{ tasks: [ { id: T1, description: 定义 User 类型和登录接口签名, depends_on: [], acceptance: 类型定义通过 tsc 检查接口签名与 PRD 一致, estimated_hours: 1 }, { id: T2, description: 实现登录接口的数据库查询逻辑, depends_on: [T1], acceptance: 单元测试覆盖正常和异常路径, estimated_hours: 2 } ] }这个格式的好处是机器可读。Coder Agent 可以直接按任务列表执行Tester Agent 可以按 acceptance 字段生成测试用例。整个流程自动化程度很高。注意任务拆解时一定要标注depends_on否则并行执行时会出问题。我踩过一次坑两个任务都修改同一个文件并行执行导致冲突。后来强制要求 Planner Agent 检查文件级依赖问题才解决。4.4 Plan Mode 的审核与迭代Plan Mode 输出的计划需要人类审核。我的审核清单有三条任务粒度是否合理、依赖关系是否正确、验收标准是否可测。任何一条不满足就打回让 Planner Agent 重新拆解。迭代时不要让 Agent 从头再来而是基于现有计划修改。我会把审核意见作为输入让 Agent 只调整有问题的部分。这样能保留已经正确的部分减少反复。5. 多 Agent 编排并发、安全与错误处理5.1 多 Agent 协作的三种模式多 Agent 协作有三种模式串行、并行、层级。串行适合有严格依赖的任务链并行适合独立任务层级适合需要协调的复杂任务。我的经验是默认串行能并行才并行。因为并行虽然快但调试复杂度高。我通常只在任务之间没有文件冲突、没有数据依赖时才并行。比如 Tester Agent 生成测试用例和 Ops Agent 生成部署配置这两个任务互不干扰可以并行。层级模式我用得比较少主要是在大型重构场景。一个 Orchestrator Agent 负责协调多个 Worker AgentOrchestrator 不直接干活只做任务分配和结果汇总。这种模式的好处是职责清晰但缺点是 Orchestrator 容易成为瓶颈。5.2 并发控制Agent 怎么扛住高并发Agent 并发的问题不在 Agent 本身而在共享资源。多个 Agent 同时读写同一个文件、同一个数据库、同一个 API就会出问题。我的解决方案是资源锁 队列。资源锁的实现很简单每个共享资源对应一个锁文件Agent 操作前先申请锁操作完释放。锁的粒度要细比如按文件路径加锁而不是全局锁。这样不同文件的操可以并行。队列则是用来控制并发数的。我通常限制同时运行的 Agent 不超过 5 个超出的任务排队等待。这个数字是根据 API 速率限制和本地资源定的你可以根据自己的情况调整。import asyncio from asyncio import Semaphore semaphore Semaphore(5) async def run_agent_task(task): async with semaphore: # 申请资源锁 lock await acquire_lock(task.resource) try: result await execute_agent(task) finally: await release_lock(lock) return result这个模式实测下来很稳即使任务量突增也不会出现资源竞争导致的错误。5.3 Agent 安全权限边界与操作审计Agent 安全的核心是最小权限原则。Coder Agent 只能改代码文件不能碰数据库配置。Ops Agent 只能读部署配置不能直接执行上线操作。每个 Agent 的权限在配置文件里显式声明运行时强制检查。操作审计则是记录每个 Agent 的所有写操作。我通常把审计日志写到独立的文件包含时间戳、Agent ID、操作类型、目标资源、操作结果。出了问题可以快速回溯。提示Agent 的删除操作一定要加二次确认。我见过 Agent 误删整个目录的案例原因是 prompt 里说“清理临时文件”Agent 理解成了删除tmp/目录。后来我强制要求所有删除操作必须经过人类确认问题才杜绝。5.4 错误处理Agent 执行失败怎么办Agent 执行失败分三类可重试错误、需修正错误、致命错误。可重试错误比如网络超时直接重试即可。需修正错误比如代码编译失败要把错误信息反馈给 Agent让它修正后重试。致命错误比如权限不足直接终止并通知人类。我的重试策略是最多重试 3 次每次重试前注入错误信息。如果 3 次都失败就把任务标记为阻塞等待人类介入。这个策略能覆盖 90% 以上的临时错误。错误信息注入的格式很重要。我通常把错误日志的最后 50 行和相关的代码片段一起注入让 Agent 有足够信息定位问题。只给错误信息不给代码Agent 往往改不对。6. 常见问题与排查技巧实录6.1 Agent 输出格式不符合预期这是最常见的问题。Agent 输出的 JSON 多了个逗号或者字段名拼错了导致下游解析失败。我的解决方案是用 schema 校验 自动修复。每次 Agent 输出后先用 JSON Schema 校验不通过就让 Agent 重新输出并附上校验错误信息。如果 Agent 反复输出错误格式就要检查 prompt 里的格式说明是否清晰。我通常会在 prompt 里给一个完整的示例而不是只描述字段。示例比描述有效得多。6.2 上下文丢失导致 Agent 行为漂移长任务跑到后面Agent 忘了前面的约束开始自由发挥。这是上下文窗口的固有问题。我的解决方案是定期重注入关键约束。每完成一个子任务就把 CLAUDE.md 里的硬约束重新注入一次。这样 Agent 始终记得边界在哪。另一个技巧是用检查点。在关键决策点让 Agent 输出当前状态摘要后续任务基于摘要继续而不是基于完整历史。这样上下文始终精简。6.3 多 Agent 互相等待导致死锁并行任务如果有循环依赖就会死锁。比如 T1 等 T2T2 等 T1。我的解决方案是在任务拆解阶段就检测循环依赖。用拓扑排序检查 DAG如果有环就打回让 Planner Agent 重新拆解。运行时的死锁检测也很重要。我通常给每个任务设置超时时间超时后自动标记为失败释放占用的资源。这样即使有死锁也不会卡住整个流程。6.4 Agent 执行 terminated due to error 的排查思路这个错误信息很泛需要看详细日志。我的排查顺序是先看 Agent 的最后一次输出判断是理解错误还是执行错误。再看资源锁状态判断是否死锁。最后看 API 调用记录判断是否触发了速率限制。大多数情况下这个错误是上下文超限导致的。Agent 的输入太大模型直接拒绝处理。解决方案是压缩上下文或者换用支持更大窗口的模型。6.5 常见问题速查表问题现象可能原因排查方法解决方案输出格式错误prompt 格式说明不清检查 prompt 示例补充完整示例行为漂移上下文丢失检查上下文长度定期重注入约束死锁循环依赖拓扑排序检查重新拆解任务执行终止上下文超限检查输入大小压缩上下文权限错误权限配置过严检查权限声明调整权限边界重复错误缺少经验沉淀检查长期记忆补充结构化日志7. 我在实际落地中的几点体会这套手册我在三个团队落地过最大的体会是AI Native 不是技术问题是流程问题。技术方案再先进如果团队的工作习惯不改变Agent 就只是个高级玩具。我见过团队把 Agent 接入了但工程师还是习惯自己写代码Agent 生成的 PR 没人 review最后 Agent 变成了摆设。另一个体会是从小处着手。不要一上来就搞全流程 AI Native先从单个环节开始比如让 Agent 只做测试用例生成。跑通了再扩展到编码再扩展到需求分析。每一步都要有可量化的收益否则很难推动。最后分享一个实用技巧给 Agent 写“负面清单”。告诉 Agent 不要做什么往往比告诉它要做什么更有效。比如“不要修改config/目录下的文件”、“不要引入新的依赖”、“不要改变现有接口签名”。这些约束能避免很多意外问题。我在 CLAUDE.md 里专门有一节叫“禁止事项”实测下来Agent 的越界行为减少了 80% 以上。
AI Native团队开发落地手册：Agent编排与SDLC全流程实战
1. 从“用AI提效”到“AI Native”一次研发范式的彻底换轨过去两年我参与过不少团队从零搭建 AI 辅助研发流程的项目。大多数团队的做法是在原有 SDLC 上加一层“AI 工具”比如让工程师用 AI 补全代码、用 AI 写单测、用 AI 生成文档。这种模式我称之为“AI Assisted”——人还是主体AI 是工具。但真正让我感到范式变化的是接触到AI Native 团队之后。所谓 AI Native不是“用了 AI 的团队”而是把 Agent 作为研发流程中的一等公民让 Agent 承担从需求拆解、方案设计、编码实现、测试验证到部署运维的完整闭环人类工程师的角色从“执行者”转变为“编排者”和“审核者”。这套《AI Native 团队完整开发落地手册》要解决的正是大多数团队在落地时最头疼的问题Agent 到底怎么编排SDLC 每个阶段 Agent 该做什么、不该做什么CLAUDE.md 这类上下文文件怎么写才有效Plan Mode 和直接执行模式怎么选多 Agent 协作时并发和安全怎么扛这些问题在官方文档里往往只有零散说明真正踩过坑的人才知道细节有多要命。这篇文章适合三类人一是正在推动团队 AI 转型的技术负责人二是想搭建自己 Agent 工作流的独立开发者三是对 AI Native SDLC 感兴趣但不知道从哪下手的工程师。我会把整套手册拆成可复现的模块从架构设计、上下文工程、Plan Mode 实操、多 Agent 编排、并发与安全、到常见问题排查全部用我实际跑过的方案来讲。读完你至少能搭出一套能跑通的最小可用 AI Native 研发流程。2. AI Native SDLC 的整体架构与核心设计思路2.1 为什么传统 SDLC 加 AI 工具不够用传统 SDLC 的假设是“每个阶段由人主导工具辅助”。需求阶段产品经理写 PRD设计阶段架构师画图开发阶段工程师写代码测试阶段 QA 写用例。AI 工具进来之后只是把每个环节的效率提升了一点但阶段之间的交接成本、上下文丢失、返工率这些根本问题没有解决。我见过最典型的场景工程师用 AI 生成了代码但 AI 不知道上游 PRD 里的约束条件结果生成的接口签名和设计文档对不上返工重来。问题不在于 AI 能力不够而在于上下文没有在阶段之间流动。AI Native SDLC 的核心设计思路就是让 Agent 携带完整上下文贯穿整个流程每个阶段的产出自动成为下一阶段的输入人类只在关键决策点介入。2.2 Agent 在 SDLC 各阶段的角色划分我把 AI Native SDLC 拆成六个阶段每个阶段对应一类 Agent 角色。这里的关键是职责边界要清晰否则多 Agent 协作会变成互相甩锅。阶段Agent 角色核心职责人类介入点需求分析Requirement Agent解析原始需求生成结构化 PRD识别歧义确认需求边界方案设计Architect Agent基于 PRD 生成技术方案输出接口定义审核架构决策任务拆解Planner Agent把方案拆成可执行任务标注依赖关系确认优先级编码实现Coder Agent按任务生成代码自测通过后提交Code Review测试验证Tester Agent生成测试用例执行验证输出报告确认覆盖度部署运维Ops Agent生成部署配置监控运行状态审批上线这张表看起来简单但实际落地时最容易出问题的是阶段之间的上下文传递。Requirement Agent 生成的 PRD 如果只是自然语言Architect Agent 解析时就会丢失细节。我的做法是强制每个 Agent 的输出都包含结构化元数据比如 PRD 里必须包含constraints、acceptance_criteria、out_of_scope三个字段这样下游 Agent 能精确提取。2.3 为什么选择 Agent 编排而不是单体大模型有团队问过我为什么不直接用一个超强的大模型把整个 SDLC 的 prompt 都塞进去我的回答是上下文窗口再大也有边界而且单体模型的错误会级联放大。一个 Agent 在需求阶段理解错了后面所有阶段全错而且很难定位是哪一步出的问题。Agent 编排的好处是错误隔离和可观测性。每个 Agent 的输入输出都是显式的出问题能快速定位到具体环节。另外不同阶段对模型能力的要求不同需求分析需要强推理编码需要强代码能力测试需要强逻辑覆盖。用 Agent 编排可以针对每个阶段选最合适的模型成本和效果都更优。注意Agent 编排不是越多越好。我见过一个团队把 SDLC 拆成 20 多个 Agent结果编排复杂度爆炸调试成本比收益还高。我的经验是6 到 8 个 Agent 是甜点区再多了就要考虑合并。3. 上下文工程CLAUDE.md 与 Agent 记忆的实战写法3.1 CLAUDE.md 到底该写什么CLAUDE.md 是 Agent 进入项目时的“第一份上下文”它的质量直接决定 Agent 后续行为是否符合预期。我见过很多团队的 CLAUDE.md 写成了一本项目百科结果 Agent 根本抓不住重点。我的写法是只写三类信息项目约束、协作规范、关键路径。项目约束包括技术栈版本、代码风格、禁止使用的库。比如## 项目约束 - 语言TypeScript 5.3严格模式 - 框架Next.js 14 App Router - 禁止使用moment.js用 date-fns 替代 - 测试框架Vitest覆盖率要求 80%协作规范包括提交信息格式、分支命名、PR 模板。关键路径则是告诉 Agent“遇到什么情况该看哪个文件”。比如“接口定义在src/types/api.ts数据库 schema 在prisma/schema.prisma”。提示CLAUDE.md 不要超过 200 行。超过这个长度Agent 的注意力会被稀释关键约束反而被忽略。我通常把详细文档放在docs/目录CLAUDE.md 里只放索引和硬约束。3.2 Agent 记忆的分层设计Agent 记忆分三层会话记忆、项目记忆、长期记忆。会话记忆是当前对话的上下文项目记忆是 CLAUDE.md 和代码库索引长期记忆是跨会话的经验沉淀。会话记忆的管理关键是及时压缩。Agent 跑长任务时上下文会迅速膨胀。我的做法是每完成一个子任务就让 Agent 输出一份摘要把详细过程丢弃只保留结论和关键决策。这样上下文始终保持在可控范围。项目记忆的构建靠代码库索引。我通常用repomix把代码库打包成单个文件让 Agent 一次性加载。但要注意排除node_modules、dist、.git这些目录否则索引文件会大到无法处理。长期记忆我用的方案是结构化日志。每次 Agent 完成任务后把“任务类型、输入、输出、遇到的问题、解决方案”写入一个 JSONL 文件。下次遇到类似任务时先检索这个日志把相关经验注入上下文。这个方案实测下来很稳Agent 的重复错误率能降低 60% 以上。3.3 上下文注入的时机与顺序上下文注入不是越多越好时机和顺序同样关键。我的经验是系统约束在最前面任务描述在中间参考资料在最后。这样 Agent 先建立约束框架再理解任务最后查资料逻辑最顺。另外动态上下文要按需注入。比如 Coder Agent 执行任务时只注入相关模块的代码而不是整个代码库。我通常用文件路径匹配的方式根据任务描述里的关键词自动检索相关文件注入上下文。这个逻辑可以用一个简单的脚本实现def inject_context(task_description, repo_index): keywords extract_keywords(task_description) relevant_files [] for file_path, content in repo_index.items(): if any(kw in file_path or kw in content for kw in keywords): relevant_files.append((file_path, content)) return relevant_files[:10] # 限制数量避免上下文爆炸这个脚本看起来简单但实测效果比全量注入好很多。Agent 的响应速度更快而且不容易被无关信息干扰。4. Plan Mode 实操从需求到可执行任务的完整链路4.1 Plan Mode 与直接执行模式的取舍Plan Mode 的核心是先规划再执行Agent 不直接改代码而是输出一份执行计划人类确认后再进入执行。直接执行模式则是 Agent 边想边做适合简单任务。我的判断标准是任务涉及超过 3 个文件或者有跨模块依赖就必须用 Plan Mode。因为这种任务一旦方向错了返工成本极高。而单文件的小修改直接执行效率更高。Plan Mode 的另一个价值是可审计。计划本身就是一份文档记录了 Agent 的决策依据。出了问题可以回溯是哪一步的假设错了。这在团队协作场景下尤其重要因为你需要向其他人解释“为什么 Agent 这么做”。4.2 需求解析把模糊描述变成结构化 PRD原始需求往往是模糊的比如“做一个用户登录功能”。Requirement Agent 的任务是把它变成结构化 PRD。我的 prompt 模板是这样的你是一个需求分析 Agent。请把以下原始需求解析为结构化 PRD。 原始需求{raw_requirement} 输出格式 ## 功能描述 一句话说明这个功能做什么 ## 约束条件 - 技术约束 - 业务约束 - 性能约束 ## 验收标准 - 可测试的具体条件 ## 不在范围内 - 明确排除的内容 ## 待确认问题 - 需要人类确认的歧义点这个模板的关键是强制 Agent 输出“不在范围内”和“待确认问题”。这两个字段能有效防止范围蔓延也能让人类快速发现理解偏差。4.3 任务拆解从 PRD 到可执行任务列表Planner Agent 拿到 PRD 后要拆成可执行任务。我的拆解原则是每个任务不超过 2 小时工作量且能独立验证。任务之间用依赖关系连接形成 DAG。任务列表的格式我固定为{ tasks: [ { id: T1, description: 定义 User 类型和登录接口签名, depends_on: [], acceptance: 类型定义通过 tsc 检查接口签名与 PRD 一致, estimated_hours: 1 }, { id: T2, description: 实现登录接口的数据库查询逻辑, depends_on: [T1], acceptance: 单元测试覆盖正常和异常路径, estimated_hours: 2 } ] }这个格式的好处是机器可读。Coder Agent 可以直接按任务列表执行Tester Agent 可以按 acceptance 字段生成测试用例。整个流程自动化程度很高。注意任务拆解时一定要标注depends_on否则并行执行时会出问题。我踩过一次坑两个任务都修改同一个文件并行执行导致冲突。后来强制要求 Planner Agent 检查文件级依赖问题才解决。4.4 Plan Mode 的审核与迭代Plan Mode 输出的计划需要人类审核。我的审核清单有三条任务粒度是否合理、依赖关系是否正确、验收标准是否可测。任何一条不满足就打回让 Planner Agent 重新拆解。迭代时不要让 Agent 从头再来而是基于现有计划修改。我会把审核意见作为输入让 Agent 只调整有问题的部分。这样能保留已经正确的部分减少反复。5. 多 Agent 编排并发、安全与错误处理5.1 多 Agent 协作的三种模式多 Agent 协作有三种模式串行、并行、层级。串行适合有严格依赖的任务链并行适合独立任务层级适合需要协调的复杂任务。我的经验是默认串行能并行才并行。因为并行虽然快但调试复杂度高。我通常只在任务之间没有文件冲突、没有数据依赖时才并行。比如 Tester Agent 生成测试用例和 Ops Agent 生成部署配置这两个任务互不干扰可以并行。层级模式我用得比较少主要是在大型重构场景。一个 Orchestrator Agent 负责协调多个 Worker AgentOrchestrator 不直接干活只做任务分配和结果汇总。这种模式的好处是职责清晰但缺点是 Orchestrator 容易成为瓶颈。5.2 并发控制Agent 怎么扛住高并发Agent 并发的问题不在 Agent 本身而在共享资源。多个 Agent 同时读写同一个文件、同一个数据库、同一个 API就会出问题。我的解决方案是资源锁 队列。资源锁的实现很简单每个共享资源对应一个锁文件Agent 操作前先申请锁操作完释放。锁的粒度要细比如按文件路径加锁而不是全局锁。这样不同文件的操可以并行。队列则是用来控制并发数的。我通常限制同时运行的 Agent 不超过 5 个超出的任务排队等待。这个数字是根据 API 速率限制和本地资源定的你可以根据自己的情况调整。import asyncio from asyncio import Semaphore semaphore Semaphore(5) async def run_agent_task(task): async with semaphore: # 申请资源锁 lock await acquire_lock(task.resource) try: result await execute_agent(task) finally: await release_lock(lock) return result这个模式实测下来很稳即使任务量突增也不会出现资源竞争导致的错误。5.3 Agent 安全权限边界与操作审计Agent 安全的核心是最小权限原则。Coder Agent 只能改代码文件不能碰数据库配置。Ops Agent 只能读部署配置不能直接执行上线操作。每个 Agent 的权限在配置文件里显式声明运行时强制检查。操作审计则是记录每个 Agent 的所有写操作。我通常把审计日志写到独立的文件包含时间戳、Agent ID、操作类型、目标资源、操作结果。出了问题可以快速回溯。提示Agent 的删除操作一定要加二次确认。我见过 Agent 误删整个目录的案例原因是 prompt 里说“清理临时文件”Agent 理解成了删除tmp/目录。后来我强制要求所有删除操作必须经过人类确认问题才杜绝。5.4 错误处理Agent 执行失败怎么办Agent 执行失败分三类可重试错误、需修正错误、致命错误。可重试错误比如网络超时直接重试即可。需修正错误比如代码编译失败要把错误信息反馈给 Agent让它修正后重试。致命错误比如权限不足直接终止并通知人类。我的重试策略是最多重试 3 次每次重试前注入错误信息。如果 3 次都失败就把任务标记为阻塞等待人类介入。这个策略能覆盖 90% 以上的临时错误。错误信息注入的格式很重要。我通常把错误日志的最后 50 行和相关的代码片段一起注入让 Agent 有足够信息定位问题。只给错误信息不给代码Agent 往往改不对。6. 常见问题与排查技巧实录6.1 Agent 输出格式不符合预期这是最常见的问题。Agent 输出的 JSON 多了个逗号或者字段名拼错了导致下游解析失败。我的解决方案是用 schema 校验 自动修复。每次 Agent 输出后先用 JSON Schema 校验不通过就让 Agent 重新输出并附上校验错误信息。如果 Agent 反复输出错误格式就要检查 prompt 里的格式说明是否清晰。我通常会在 prompt 里给一个完整的示例而不是只描述字段。示例比描述有效得多。6.2 上下文丢失导致 Agent 行为漂移长任务跑到后面Agent 忘了前面的约束开始自由发挥。这是上下文窗口的固有问题。我的解决方案是定期重注入关键约束。每完成一个子任务就把 CLAUDE.md 里的硬约束重新注入一次。这样 Agent 始终记得边界在哪。另一个技巧是用检查点。在关键决策点让 Agent 输出当前状态摘要后续任务基于摘要继续而不是基于完整历史。这样上下文始终精简。6.3 多 Agent 互相等待导致死锁并行任务如果有循环依赖就会死锁。比如 T1 等 T2T2 等 T1。我的解决方案是在任务拆解阶段就检测循环依赖。用拓扑排序检查 DAG如果有环就打回让 Planner Agent 重新拆解。运行时的死锁检测也很重要。我通常给每个任务设置超时时间超时后自动标记为失败释放占用的资源。这样即使有死锁也不会卡住整个流程。6.4 Agent 执行 terminated due to error 的排查思路这个错误信息很泛需要看详细日志。我的排查顺序是先看 Agent 的最后一次输出判断是理解错误还是执行错误。再看资源锁状态判断是否死锁。最后看 API 调用记录判断是否触发了速率限制。大多数情况下这个错误是上下文超限导致的。Agent 的输入太大模型直接拒绝处理。解决方案是压缩上下文或者换用支持更大窗口的模型。6.5 常见问题速查表问题现象可能原因排查方法解决方案输出格式错误prompt 格式说明不清检查 prompt 示例补充完整示例行为漂移上下文丢失检查上下文长度定期重注入约束死锁循环依赖拓扑排序检查重新拆解任务执行终止上下文超限检查输入大小压缩上下文权限错误权限配置过严检查权限声明调整权限边界重复错误缺少经验沉淀检查长期记忆补充结构化日志7. 我在实际落地中的几点体会这套手册我在三个团队落地过最大的体会是AI Native 不是技术问题是流程问题。技术方案再先进如果团队的工作习惯不改变Agent 就只是个高级玩具。我见过团队把 Agent 接入了但工程师还是习惯自己写代码Agent 生成的 PR 没人 review最后 Agent 变成了摆设。另一个体会是从小处着手。不要一上来就搞全流程 AI Native先从单个环节开始比如让 Agent 只做测试用例生成。跑通了再扩展到编码再扩展到需求分析。每一步都要有可量化的收益否则很难推动。最后分享一个实用技巧给 Agent 写“负面清单”。告诉 Agent 不要做什么往往比告诉它要做什么更有效。比如“不要修改config/目录下的文件”、“不要引入新的依赖”、“不要改变现有接口签名”。这些约束能避免很多意外问题。我在 CLAUDE.md 里专门有一节叫“禁止事项”实测下来Agent 的越界行为减少了 80% 以上。