1. 从用AI写代码到AI Native 团队差的不是工具是整套协作契约这两年我参与过几个号称全面拥抱 AI的团队也帮朋友的公司做过研发流程改造。一个很普遍的现象是大家把 Copilot、Claude、Cursor 装了个遍代码补全确实快了但一到需求评审、联调、上线节奏还是老样子——该堵的堵该返工的返工。工具换了流程没换人也没换最后得出的结论往往是AI 也就那样。问题出在哪出在大多数团队把 AI 当成了一个更快的打字员而不是把它当成一个有上下文、有记忆、有边界、需要被编排的团队成员。这就是 AI Native 团队和用了 AI 的团队最本质的区别。前者重新设计了整个软件开发生命周期SDLC让 AI 从需求澄清、方案设计、编码、测试到文档沉淀都占据一个明确的位置后者只是给旧流程贴了一层 AI 皮肤。这篇手册想聊的就是前者。它适合三类人一是正在推动团队 AI 化转型的技术负责人二是想搞清楚 Agent 到底怎么落地到真实项目里的工程师三是已经在用 Claude Code、Cursor 这类工具但总觉得没发挥出全部威力的开发者。我会把 AI Native 团队的完整落地路径拆开讲——从协作契约的设计、CLAUDE.md 这类团队记忆文件的写法、Plan Mode 的正确用法到 Agent 的架构选型、并发与安全、记忆机制再到怎么衡量这套东西到底有没有用。全程都是我在实际项目里踩过、验证过的东西不是概念科普。先给一个我自己的定义方便后面展开AI Native 团队 一套以 Agent 为核心执行单元、以结构化上下文为协作媒介、以人做决策与兜底的研发组织形态。关键词是结构化上下文和人做决策这两点后面会反复出现。2. AI Native SDLC 到底长什么样把每个阶段重新分配给人还是 Agent2.1 传统 SDLC 的瓶颈从来不在写代码很多人以为 AI 提效最大的环节是编码其实不是。我统计过自己参与的项目一个需求从提出到上线纯编码时间大概只占 25% 到 35%剩下的大头是需求澄清反复拉扯、方案设计来回讨论、联调时接口对不上、测试用例覆盖不全、上线后文档没人更新。编码快了一倍整体交付周期可能只缩短 10%。所以 AI Native SDLC 的设计重点不是让 AI 写更多代码而是让 AI 吃掉那些重复的、信息搬运型的、需要跨文件检索的工作。下面这张表是我在几个项目里实际跑下来各阶段人机分工的一个参考SDLC 阶段传统做法AI Native 做法人的角色需求澄清会议 口头确认Agent 读需求文档生成澄清问题清单和边界用例拍板、补充业务背景方案设计资深工程师手写设计文档Plan Mode 生成多套方案 影响面分析选型、权衡取舍编码手写Agent 按 CLAUDE.md 规范实现人 review审查关键逻辑测试手写用例Agent 基于需求生成用例 边界值补充业务特例联调人工对接口Agent 比对前后端契约标出不一致决策改哪边文档事后补Agent 随代码变更同步更新审核准确性这张表的核心逻辑是凡是信息已经存在只是需要被搬运、比对、展开的工作交给 Agent凡是需要判断、权衡、承担后果的工作留给人。这条线划清楚了AI Native 的落地就不会跑偏。2.2 为什么上下文比模型能力更决定成败我见过太多团队纠结用 GPT 还是 Claude 还是国产模型但真正决定 Agent 输出质量的是它拿到的上下文。同一个模型给它一份结构清晰的 CLAUDE.md 和一堆散乱的聊天记录产出质量能差出三倍。这里有个反直觉的结论在 AI Native 团队里写给 AI 看的文档比写给人看的文档更重要。因为人可以从模糊描述里脑补出意图AI 不行。你写接口要健壮一点人知道大概是要加校验和重试AI 可能给你加一堆 try-catch 然后吞掉异常。所以 AI Native 团队的第一项基建不是买工具而是建立一套机器可读的项目上下文体系。这套体系通常包含项目级记忆文件如 CLAUDE.md技术栈、目录约定、命名规范、禁止事项模块级说明每个核心模块的职责边界、依赖关系决策记录为什么选了这个方案而不是那个避免 Agent 反复重新发明轮子接口契约结构化的 API 定义让 Agent 能直接比对这套东西听起来像文档工作但它其实是 AI Native 团队的操作系统。没有它Agent 每次都是从零开始猜你永远在给它擦屁股。2.3 一个真实的落地节奏别想一步到位我建议的推进节奏是分三步别一上来就搞全流程自动化单点突破先在一个模块里把 CLAUDE.md 写扎实让 Agent 稳定产出符合规范的代码。这一步的目标是让团队相信 AI 能按我们的规矩干活。流程串联把 Plan Mode 引入方案设计把 Agent 引入测试用例生成形成设计-编码-测试的小闭环。组织固化把上下文文件纳入代码仓库管理把 Agent 的使用规范写进团队 onboarding新人第一天就学怎么和 Agent 协作。我见过跳过第一步直接搞第三步的团队结果就是上下文文件写得又长又空Agent 根本不遵守最后大家又退回手写。上下文文件的质量是靠一个个真实任务磨出来的不是一次性写出来的。3. CLAUDE.md 这类团队记忆文件怎么写才不沦为摆设3.1 大多数 CLAUDE.md 失败的原因写成了 README我翻过不少团队的 CLAUDE.md十个里有八个长这样项目简介、技术栈、如何启动、目录结构。这基本就是把 README 复制了一遍。问题是README 是给人看的人看完就懂了Agent 需要的是可执行的约束和明确的边界。一份有效的 CLAUDE.md核心不是介绍项目而是约束行为。它要回答的是Agent 在这个项目里什么能做、什么不能做、遇到某类问题该怎么做。举个具体对比无效写法本项目使用 TypeScript注重代码质量。有效写法所有新增函数必须显式标注返回类型禁止使用 any如需动态类型用 unknown 并做类型收窄错误处理统一用 Result 类型禁止直接 throw。后者才是 Agent 能直接执行的指令。前者它只能靠猜。3.2 一份可复用的 CLAUDE.md 骨架下面是我在项目里反复迭代出来的一份骨架你可以直接拿去改。注意每一块都对应一类Agent 容易犯错的地方# 项目上下文 ## 技术栈与版本 - 语言TypeScript 5.x严格模式开启 - 框架React 18 Vite - 测试Vitest Testing Library - 包管理pnpm禁止使用 npm/yarn ## 目录约定 - src/features/按业务域组织每个域自包含 - src/shared/跨域复用改动需谨慎 - 禁止在 features 之间直接互相 import必须通过 shared ## 编码规范 - 组件一律函数式禁止 class 组件 - 状态管理优先用局部 state跨组件才上 store - 所有异步操作必须有 loading 和 error 分支 ## 禁止事项 - 禁止引入新的 UI 库现有组件不够用时先提 issue - 禁止修改 shared/ 下的公共类型而不更新所有引用方 - 禁止在提交信息里写fix bug这类无意义描述 ## 常见任务指引 - 新增页面参考 src/features/user 的结构 - 新增 API先在 shared/api 定义类型再实现这份骨架的关键在于每一条都是可验证的。Agent 写完代码你可以对照检查它有没有违反。而注重代码质量这种话没法验证等于没说。3.3 记忆文件的维护让它随项目一起生长CLAUDE.md 不是写完就完事的。我的做法是每次 Agent 犯了同类错误两次以上就把对应的约束补进去。比如它老是忘记给异步操作加 error 分支那就在规范里明确写死。这样这份文件会越来越贴合项目的真实痛点。另外记忆文件要分层。项目根目录放全局约束各模块目录下可以放模块级的补充说明。Agent 处理某个模块时会同时读到全局和模块级的上下文这样既保证一致性又保留灵活性。提示记忆文件一定要纳入 Git 管理和代码一起 review。我见过把 CLAUDE.md 放在本地不提交的结果每个人机器上的 Agent 行为都不一样协作时全是坑。4. Plan Mode 的正确打开方式先想清楚再动手而不是让 Agent 边写边猜4.1 为什么直接让 Agent 写代码是最贵的做法新手用 Agent 最常见的操作是把需求一贴直接说帮我实现。然后 Agent 吭哧吭哧写了一堆你一看方向全错推倒重来。这个过程浪费的不只是 token还有你的 review 时间和耐心。Plan Mode 的价值就在这让 Agent 先输出打算怎么做你确认后再让它执行。这相当于把返工提前到了纸面阶段成本低得多。我自己的经验是用了 Plan Mode 之后Agent 产出的一次通过率能从大概 40% 提到 75% 以上。4.2 Plan Mode 里应该让 Agent 输出什么不是让它写一段我将要实现这个功能的空话而是要求它输出结构化的方案。我通常要求包含这几块任务拆解把需求拆成几个可独立验证的子任务影响面分析会改动哪些文件、哪些模块、有没有破坏性变更方案选择如果有多种实现路径列出各自的取舍验证方式怎么证明做完了、做对了风险点哪些地方可能出问题、需要人工确认举个实际例子。需求是给用户列表加一个按注册时间筛选的功能。让 Agent 在 Plan Mode 下输出它应该告诉你需要改列表组件、需要改查询 API、需要加一个日期选择器、可能影响分页逻辑、需要补测试用例。你一看发现它漏了时区处理这个坑就可以在计划阶段补上而不是等它写完再发现。4.3 Plan Mode 和人做决策的边界这里要强调一个原则Plan Mode 是让 Agent 提方案不是让它替你拍板。我见过有人把 Plan Mode 的输出直接当最终方案执行结果选了一个技术上可行但业务上不合适的路径。正确的用法是Agent 出方案人做选择。尤其是涉及架构变更、第三方依赖引入、数据模型调整这类决策必须人来定。Agent 擅长的是穷举可能性和分析影响面不擅长的是理解业务优先级和承担决策后果。注意Plan Mode 的输出要存档。我习惯把每次的方案计划存到项目的 docs/plans/ 目录下一是方便回溯当时为什么这么设计二是这些计划本身就是很好的上下文后续 Agent 处理相关任务时可以参考。5. Agent 架构选型别被框架绑架先搞清楚你要解决什么问题5.1 Agent 到底是什么和普通脚本、和 harness 有什么区别先把概念理清楚因为这块被各种热词搅得很乱。Agent的核心特征是它能自主决定下一步做什么。你给它一个目标它会自己规划步骤、调用工具、根据结果调整。而普通脚本是你把每一步都写死了它只负责执行。Harness这个词最近很火它指的是包裹在模型外面的那层脚手架——负责给模型喂上下文、解析模型的输出、执行模型要求的工具调用、把结果再喂回去。你可以理解为模型是发动机harness 是变速箱和传动系统。很多所谓的Agent 框架本质上就是在做 harness 的活。搞清这个区别很重要因为它决定了你的选型思路如果你只是想让模型按固定流程干活你需要的可能只是一个好的 harness而不是一个复杂的 Agent 框架。过度设计是这块最常见的坑。5.2 主流架构的取舍ReAct、Plan-and-Execute、多 Agent我实际用过的架构大概分三类各有适用场景架构核心思路适合场景主要问题ReAct边想边做每步根据观察调整探索性任务、调试容易绕圈、token 消耗大Plan-and-Execute先出完整计划再执行结构清晰的任务计划错了全盘错多 Agent多个 Agent 分工协作复杂、可并行的任务协调成本高、易失控我的建议是从 ReAct 起步任务稳定后再考虑 Plan-and-Execute多 Agent 除非任务真的能清晰拆分否则别碰。多 Agent 听起来很酷但实际项目里两个 Agent 之间的沟通成本经常比它们各自干的活还大。5.3 选型时真正该问的几个问题别一上来就问用哪个框架先问自己这个任务的步骤是固定的还是需要动态决策的Agent 需要访问哪些工具文件、数据库、API出错了怎么回滚有没有人工介入的检查点单次任务的 token 预算大概多少能不能接受这个 Agent 是跑一次还是长期运行这几个问题答清楚了框架选型基本就水到渠成了。我见过太多团队先选框架再想需求最后发现框架的能力和自己的需求根本不匹配。6. Agent 的记忆机制为什么你的 Agent 总是失忆6.1 短期记忆、长期记忆、工作记忆别混为一谈Agent 的记忆是个被说烂但很少说清的话题。我把它分成三层短期记忆当前这次对话/任务的上下文就是喂给模型的那些 token。它受限于上下文窗口超了就丢。长期记忆跨任务持久化的信息比如项目规范、历史决策。通常存在文件或数据库里需要时检索出来。工作记忆Agent 在执行一个复杂任务时中间产生的临时状态比如我已经改了哪几个文件还剩哪几步。大多数 Agent 失忆的问题出在长期记忆和工作记忆没有做好衔接。比如它改完一个文件下次再处理相关任务时完全不知道上次改过什么。6.2 用文件做长期记忆简单但有效我试过向量数据库、试过各种记忆框架最后发现对大多数团队项目来说用结构化的文件做长期记忆是最稳的。原因很简单可读、可版本控制、可人工修正。具体做法是维护几个文件context/decisions.md记录重要决策和原因context/conventions.md编码和协作规范context/glossary.md业务术语表避免 Agent 理解偏差Agent 每次启动时读这些文件就相当于回忆起了项目的来龙去脉。这比向量检索更可控因为你能直接看到它读到了什么。6.3 工作记忆的管理让 Agent 知道自己走到哪了复杂任务里Agent 很容易忘记自己已经做了什么。解决办法是让它显式地维护一个任务清单。比如用 TodoWrite 这类工具把任务拆成条目每完成一条就标记。这样即使上下文被截断它也能通过读清单恢复状态。我在实际项目里的经验是任务超过 5 步就一定要让 Agent 维护清单。否则它做到一半就开始重复劳动或者漏步骤。7. 并发、安全与Agent 到处跑落地时最容易被忽视的三件事7.1 Agent 怎么扛并发不是加机器那么简单AI Agent 怎么扛并发是最近被问得很多的问题。我的看法是先别急着扛并发先搞清楚你的 Agent 是不是真的需要并发。Agent 的并发和普通服务的并发不一样。普通服务是无状态的加机器就行Agent 是有状态的它带着上下文、带着工具调用、带着中间结果。并发跑多个 Agent最大的风险是它们互相踩脚——同时改同一个文件、同时调同一个有副作用的接口。我的处理原则是读操作可以并发多个 Agent 同时检索、分析没问题写操作必须串行或加锁改文件、写数据库要么排队要么用锁有副作用的工具调用要幂等比如发消息、下单必须能安全重试如果确实需要高并发通常的做法是给每个 Agent 分配独立的工作区独立的文件副本或分支最后再合并。这比让它们共享一个工作区安全得多。7.2 Agent 安全三个必须设的边界Agent 安全不是防黑客那么遥远日常就有很多风险点。我总结了三类必须设的边界权限边界Agent 能访问哪些文件、哪些接口、哪些数据。默认应该是最小权限需要什么开什么。操作边界哪些操作需要人工确认。比如删除文件、推送代码、调用支付接口这些必须卡一道人工确认。资源边界单次任务的 token 上限、执行时间上限、工具调用次数上限。防止 Agent 陷入死循环把预算烧光。我踩过最惨的一次坑是让 Agent 自动整理一个目录结果它把不该动的文件也整理了。从那以后凡是涉及删除和移动的操作我一律加人工确认。7.3 Agent Anywhere的诱惑与陷阱现在很流行让 Agent 无处不在——自动发消息、自动整理笔记、自动处理邮件。这些场景确实诱人但落地时要非常小心。我的建议是从低风险、高频、可回滚的场景开始。比如让 Agent 帮你把网页内容整理成 Markdown、帮你生成会议纪要草稿这些即使出错代价也小。而像自动回复客户消息自动提交代码这类一旦出错就是事故必须有人工审核环节。8. 怎么衡量 AI Native 改造到底有没有用8.1 别只看代码写了多少行衡量 AI Native 改造的效果最容易犯的错是看AI 生成了多少代码。这个指标毫无意义甚至有害——它鼓励 Agent 写更多冗余代码。我实际用的指标是这几个需求到上线的周期这是最终指标但受太多因素影响要结合其他指标看一次通过率Agent 产出不需要返工的比例反映上下文质量人工介入次数一个任务里人需要介入多少次反映自动化程度返工原因分布返工是因为需求不清、上下文缺失还是模型能力反映改进方向8.2 一个我常用的周度复盘方法每周我会花半小时做一次复盘记录这周 Agent 表现好的地方和翻车的地方。翻车的地方分两类一类是上下文没给够一类是模型能力确实不行。前者补上下文后者调整任务分配。坚持几周之后你会发现一个规律大部分翻车都是上下文问题不是模型问题。这个认知会彻底改变你的优化方向——从换更强的模型转向把上下文写得更清楚。9. 我在实际落地中踩过的几个坑第一个坑是过早追求全自动化。一开始我想让 Agent 从需求到提交全自动跑通结果每个环节都出问题排查起来极其痛苦。后来改成每个环节单独跑通、人工确认后再串联反而快得多。第二个坑是上下文文件写得太长。我以为写得越详细越好结果 Agent 读到后面就忘了前面。后来学会分层全局的放根目录模块的放模块目录按需加载。第三个坑是没有给 Agent 设预算上限。有一次一个 Agent 陷入循环一晚上烧掉了一大笔 token。从那以后所有 Agent 任务都设了执行时间和调用次数上限。第四个坑是把 Agent 的输出直接当最终结果。早期我太信任它结果它生成的测试用例看着很全实际漏了关键边界。现在我坚持Agent 产出必须经过人工 review尤其是测试和涉及数据的部分。10. 给准备启动 AI Native 改造的团队的最后几条建议如果你正准备在团队里推这套东西我的建议是先选一个痛但不致命的场景试点。比如文档同步、测试用例生成、代码 review 辅助这些场景失败了影响可控成功了又能快速建立信心。然后把上下文建设当成一等公民。别把它当成顺便写写的文档它是整个体系的地基。我甚至建议指定一个人专门负责维护项目的上下文文件就像维护 CI 配置一样。最后接受人机协作而不是人机替代。AI Native 团队不是把人换掉而是把人从重复劳动里解放出来去做真正需要判断力的事。这个心态摆正了落地过程会顺很多。这套东西我还在持续迭代每次项目跑完都会回头改上下文文件和协作规范。它不是一套一次成型的标准答案而是一个需要和团队一起生长的实践体系。