1. 从“人写代码”到“人管意图”AI Native 团队到底在变什么“AI Native 团队完整开发落地手册”这个标题第一次看到时我脑子里冒出来的不是兴奋而是一堆很具体的问题团队里到底谁在写代码代码评审还看 diff 吗需求文档是不是直接变成提示词测试用例谁来维护上线出问题谁背锅这些问题不解决所谓“AI Native”就只是把聊天窗口塞进工作流本质还是老一套。我真正开始认真对待这件事是在一个六人小团队里做实验。我们把一个中等复杂度的内部工具从零到一交给“人 Agent”混合模式来做结果前两周效率确实起飞第三周开始出现大量返工Agent 生成的模块之间接口对不上、测试覆盖看着很高但全是无效断言、有人改了CLAUDE.md之后所有人的 Agent 行为都变了却没人知道。那次之后我才明白AI Native 不是“用 AI 写代码”而是把研发流程本身重新设计成 Agent 可参与、可约束、可审计的形态。这篇手册面向的是正在或准备把 Agent 引入日常研发的团队可能是三五个人的小团队也可能是几十人的中型研发组。它不讲空泛的“AI 提效”而是把 SDLC软件开发生命周期拆开讲清楚每个环节 Agent 该做什么、不该做什么、人怎么介入、怎么防止失控。关键词里的CLAUDE.md、Plan Mode、Agent Skill、多 Agent、Agent 记忆、Agent 安全都会落到具体操作上。先说一个反直觉的结论AI Native 团队最大的成本不是模型调用费而是“上下文维护成本”。Agent 每次执行都要重新理解项目结构、约定、历史决策如果这些信息散落在聊天记录、口头约定和某个人的脑子里Agent 就会反复犯错人就要反复纠正。所以整篇手册的核心线索只有一条把团队的隐性知识显性化、结构化让 Agent 能稳定读取。后面所有章节都是这条线索的展开。2. 把项目知识写成 Agent 能读的“宪法”CLAUDE.md 与上下文工程2.1 为什么一个 Markdown 文件能决定 Agent 的表现很多人第一次接触CLAUDE.md会以为它只是个说明文档写不写无所谓。实际用下来它更像是给 Agent 的“项目宪法”——Agent 每次进入这个仓库第一件事就是读它然后据此决定用什么风格写代码、遵循什么目录结构、跑什么命令、避开哪些文件。它写得好不好直接决定 Agent 是“熟练工”还是“每天失忆的新人”。我踩过最典型的一个坑早期我们的CLAUDE.md只写了“这是一个 Node 项目用 pnpm”。结果 Agent 一会儿用 npm一会儿用 yarn锁文件被改得乱七八糟。后来我们把包管理器、Node 版本、lint 命令、测试命令、提交信息格式全部写进去返工率立刻下降。原因很简单Agent 不会“猜”它只会根据上下文做最可能的推断你不写清楚它就按训练数据里的主流习惯来而主流习惯未必是你的项目习惯。一份能用的CLAUDE.md我建议至少覆盖这几块项目定位一句话说清这个仓库是干什么的避免 Agent 把无关逻辑塞进来。技术栈与版本语言、框架、包管理器、运行时版本越具体越好。目录约定哪个目录放什么新文件应该建在哪。命令清单安装、开发、构建、测试、lint、格式化的确切命令。代码风格命名、注释语言、错误处理方式、日志规范。禁区不允许改的文件、不允许引入的依赖、不允许使用的 API。提交与评审约定commit message 格式、PR 描述要求。2.2 上下文分层全局、仓库、任务三级结构只写一个CLAUDE.md很快会膨胀到几千行Agent 读起来成本高人维护也痛苦。我的做法是分三层层级文件位置内容更新频率全局层用户级配置个人偏好、通用风格、常用命令低仓库层仓库根目录CLAUDE.md项目结构、技术栈、约定、禁区中任务层任务目录或临时文件当前任务目标、验收标准、相关文件高全局层放“我这个人怎么干活”仓库层放“这个项目怎么干活”任务层放“这次要干什么”。三层叠加Agent 拿到的上下文既稳定又聚焦。实测下来任务层用临时文件而不是塞进仓库层能显著减少“历史任务污染”——否则 Agent 会把上个任务的假设带到下个任务里。2.3 上下文工程的三个实操心得第一写“为什么”比写“是什么”更重要。比如不要只写“用 Zod 做校验”而要写“用 Zod 做校验因为我们需要运行时校验且希望类型自动推导不要引入 Yup”。Agent 理解了动机遇到边界情况时更可能做出符合预期的选择。第二负面清单要具体。写“不要乱改配置”没用要写“不要修改vite.config.ts里的base字段它和部署路径绑定”。越具体Agent 越不会误伤。第三定期清理。CLAUDE.md会随着项目演进而过时过时的约定比没有约定更危险。我习惯每个迭代结束花十分钟过一遍删掉已经不适用的条目。这件事看起来小但它是 AI Native 团队能否长期稳定的关键。3. Plan Mode把“先想后做”变成 Agent 的硬约束3.1 Plan Mode 解决的是什么问题Agent 最让人头疼的行为模式是“上来就改”。你让它加个功能它直接开始写代码写到一半发现方向错了已经改了十几个文件。Plan Mode 的价值就在于强制 Agent 先输出计划、等人确认、再执行。它把“想”和“做”拆成两个阶段人只需要在计划阶段介入一次就能避免大量无效改动。我现在的习惯是任何涉及三个以上文件、或者涉及核心逻辑的改动一律先走 Plan Mode。计划里必须包含要改哪些文件、每个文件改什么、为什么这么改、有什么风险、怎么验证。计划写得越细执行阶段越省心。3.2 一份合格计划的检查清单拿到 Agent 的计划后我会按这个清单过一遍范围是否准确有没有漏掉关联文件有没有多改无关文件。方案是否合理有没有更简单的做法有没有引入不必要的依赖。风险是否识别有没有提到兼容性、数据迁移、并发等问题。验证是否可执行测试怎么写怎么手动验证回滚方案是什么。是否符合约定有没有违反CLAUDE.md里的禁区。只要有一项不过关就打回重做计划。这个阶段多花五分钟执行阶段能省半小时。很多人觉得 Plan Mode 拖慢速度其实是把返工成本提前消化了。3.3 Plan Mode 与多 Agent 的配合当任务足够大时我会让一个 Agent 专门做规划输出计划后交给另一个 Agent 执行。规划 Agent 不碰代码执行 Agent 不做决策职责清晰。这样做的好处是规划 Agent 可以专注于“想清楚”执行 Agent 可以专注于“做对”两者的上下文互不干扰。但要注意规划 Agent 和执行 Agent 必须共享同一份仓库层上下文否则执行 Agent 可能不知道规划 Agent 假设的约定。我的做法是把计划写成文件执行 Agent 启动时先读计划再读CLAUDE.md确保信息一致。4. Agent Skill把重复动作沉淀成可复用能力4.1 Skill 和普通提示词的区别Agent Skill这个词最近很热但很多人没搞清它和普通提示词的区别。我的理解是提示词是“这次怎么做”Skill 是“以后都这么做”。Skill 是一段被封装、被命名、可被 Agent 自动识别和调用的能力它通常包含触发条件、执行步骤、输入输出约定和失败处理。举个例子我们团队有个高频动作把某个网页内容整理成 Markdown 存进知识库。早期每次都要写一遍提示词后来封装成 SkillAgent 只要识别到“保存网页”意图就自动走这套流程抓取、清洗、转 Markdown、按规范命名、存入指定目录、更新索引。整个过程人只需要确认一次。4.2 一个 Skill 应该包含什么我总结的 Skill 模板大致是这样名称与描述一句话说清这个 Skill 干什么方便 Agent 匹配。触发条件什么情况下该用这个 Skill。前置检查执行前需要确认什么比如权限、依赖、目标目录是否存在。执行步骤分步骤写清楚每步的输入输出。失败处理出错时怎么回退怎么报告。示例至少一个完整示例方便 Agent 模仿。这套结构看起来啰嗦但它能极大降低 Agent 的“自由发挥”空间。Skill 越规范输出越稳定。4.3 Skill 的测试与版本管理Skill 也是代码也要测试和版本管理。我们的做法是给每个 Skill 配一组测试用例给定输入期望输出是什么。每次修改 Skill 后跑一遍确保没破坏原有行为。同时 Skill 文件进 Git改动走评审避免有人悄悄改了 Skill 导致所有人行为变化。这里有个容易忽略的点Skill 的命名要稳定。如果今天叫save-web明天改成web-to-markdownAgent 的匹配就会乱。命名一旦确定尽量不改要改就做好迁移。5. 多 Agent 协作分工、通信与冲突处理5.1 什么时候该上多 Agent不是所有任务都值得多 Agent。我的判断标准是任务能否被清晰拆分成互不重叠的子任务且子任务之间的接口足够稳定。如果拆分后子任务还要频繁互相修改对方的产出那多 Agent 反而增加协调成本不如单 Agent 串行做。适合多 Agent 的典型场景一个负责后端接口一个负责前端页面一个负责测试三者通过明确的接口契约协作。不适合的场景一个功能的核心逻辑需要反复调整牵一发动全身。5.2 通信靠文件不靠聊天多 Agent 协作最大的坑是“聊天式通信”——Agent A 在对话里告诉 Agent B 一个约定Agent B 转头就忘了或者理解偏了。我的做法是所有跨 Agent 的约定都落到文件里接口定义写进interface.md数据结构写进schema.json任务分工写进tasks.md。Agent 之间不直接对话而是读写这些文件。这样做的好处是可审计、可复现。出了问题翻文件就知道哪个环节理解错了。坏处是前期要多写一些文档但相比返工成本这笔投入非常划算。5.3 冲突处理与合并策略多 Agent 并行改代码冲突几乎必然发生。我们的策略是文件级隔离尽量让不同 Agent 改不同文件从源头减少冲突。接口先行先定接口再并行实现接口不变就不冲突。定期合并不要等到最后才合并每完成一个子任务就合并一次。人工兜底真冲突了人来判断保留哪个不要让 Agent 自己“猜”。实测下来文件级隔离能解决八成冲突。剩下两成靠接口先行和定期合并。真正需要人工介入的很少。6. Agent 记忆让经验跨会话留存6.1 记忆的三种类型Agent 记忆常被说得玄乎其实拆开就三类短期记忆当前会话内的上下文会话结束就没了。长期记忆跨会话保留的事实、偏好、决策通常存文件或数据库。情景记忆特定场景下的经验比如“上次这个模块改动引发了什么问题”。短期记忆靠上下文窗口长期记忆靠文件情景记忆靠结构化的经验库。三者配合Agent 才能越用越顺手。6.2 记忆怎么写才有用我见过很多团队的“记忆”就是一堆流水账Agent 读了等于没读。有用的记忆应该满足具体、可操作、有上下文。比如不要写“上次改登录出问题了”而要写“上次改登录模块时因为没同步更新 session 过期时间导致用户频繁掉线修复方式是同时改auth.ts和session.ts”。这种记忆 Agent 读了能直接用。流水账读了只会增加噪音。6.3 记忆的清理与遗忘记忆不是越多越好。过时的记忆会误导 Agent。我们的做法是给每条记忆加时间戳和适用范围定期清理超过一定时间且不再适用的条目。同时重大决策类记忆长期保留操作细节类记忆定期归档。7. Agent 安全与并发上线前必须回答的问题7.1 Agent 安全的几个真实风险Agent 安全不是危言耸听。我遇到过和听说过的问题包括Agent 误删文件、Agent 把密钥写进代码、Agent 执行了危险命令、Agent 把内部数据发到外部服务。这些都不是理论风险是真实发生过的。防范的核心思路是最小权限 人工确认 可回滚Agent 只能访问完成任务必需的目录和命令。危险操作删除、部署、发请求必须人工确认。所有改动进 Git随时可回滚。7.2 Agent 怎么扛并发AI Agent 怎么扛并发是个好问题。Agent 本身是无状态的执行单元扛并发靠的是架构任务队列所有任务进队列Agent 从队列取任务避免同时改同一文件。文件锁同一文件同一时间只允许一个 Agent 改。幂等设计任务可重复执行而不产生副作用。限流控制同时运行的 Agent 数量避免资源打满。我们实测下来任务队列 文件锁能解决绝大多数并发问题。剩下的靠幂等和限流兜底。7.3 上线前的安全检查清单密钥是否从代码里剥离走环境变量或密钥管理。Agent 是否有权限执行部署、删除等危险操作。是否有操作日志能追溯每个 Agent 做了什么。是否有回滚方案出问题能快速恢复。是否有异常告警Agent 行为异常时能及时发现。这份清单不长但每一条都对应过真实事故。8. 把 SDLC 重写成 Agent 可参与的流水线8.1 需求阶段从文档到结构化意图传统需求是给人看的文档AI Native 团队的需求要同时给人和 Agent 看。我的做法是把需求拆成结构化字段目标、范围、验收标准、相关文件、约束条件。Agent 读这些字段就能理解要做什么人读这些字段也能快速评审。8.2 开发阶段Plan、执行、验证三段式开发阶段固定走三段Plan Mode 出计划执行 Agent 按计划改代码验证 Agent 跑测试和检查。三段之间有人工确认点确保方向不偏。8.3 测试与评审Agent 做初筛人做决策Agent 适合做测试初筛跑单测、跑 lint、检查覆盖率、找明显问题。人适合做决策这个设计合不合理这个取舍对不对。分工明确效率最高。8.4 部署与运维自动化但保留人工闸门部署可以自动化但关键节点保留人工闸门。比如自动构建、自动测试、自动部署到预发但上生产要人工点一下。这样既享受自动化效率又保留最终控制权。9. 我踩过的坑和给你的建议第一个坑过早追求全自动。我们一开始想让 Agent 端到端做完所有事结果错误累积最后返工比手动做还慢。后来改成“关键节点人工确认”效率反而上来了。AI Native 不是无人化是人机分工优化。第二个坑上下文不统一。不同 Agent 读不同版本的约定产出对不上。后来强制所有 Agent 读同一份仓库层上下文问题消失。第三个坑忽视记忆维护。记忆库膨胀后 Agent 反而变笨。定期清理后恢复正常。如果让我给刚起步的团队一条建议先把CLAUDE.md写好再谈其他。这一个文件写扎实了后面所有环节都会顺很多。它看起来最不起眼却是整个 AI Native 体系的地基。