1. 为什么"AI Native"不是给旧流程贴个AI标签

这两年"AI Native"这个词被用得太泛了。很多团队嘴上说着转型，实际干的事无非是在原有瀑布或敏捷流程里塞一个代码补全插件，然后对外宣称自己已经是AI Native团队。我见过不少这样的案例，最后的结果往往是工具买了一堆，交付效率没涨，反而因为多了一层"AI环节"导致沟通成本上升。

真正的AI Native团队，核心变化不在于用了哪个模型，而在于整个软件开发生命周期（SDLC）的组织方式被重新设计。传统SDLC里，需求、设计、编码、测试、部署是一条线性流水线，人是每个环节的执行主体，工具是辅助。AI Native的SDLC里，Agent成为执行主体之一，人的角色从"执行者"转向"编排者"和"审核者"。这个转变听起来抽象，落到具体操作上其实非常实在——它决定了你的仓库怎么组织、文档怎么写、任务怎么拆、评审怎么做。

我所在的团队从去年开始系统性地做这件事，踩了不少坑，也沉淀出一套能跑通的落地方法。这篇手册不讲概念，只讲我们实际怎么搭、怎么用、哪些地方容易翻车。适合正在考虑或已经开始AI Native转型的技术负责人、一线开发、以及想搞清楚Agent到底怎么融入日常研发的同学。全文围绕一个核心问题展开：当Agent成为团队的一员，SDLC的每个环节到底要改什么。

2. 仓库即上下文：CLAUDE.md与项目知识库的搭建逻辑

2.1 为什么Agent需要一份"项目宪法"

传统开发里，新人入职靠的是老员工带、看代码、读零散的Wiki。这套方式对人有效，因为人能主动提问、能容忍信息缺失、能在模糊中摸索。但Agent不行。Agent的每一次执行都是一次"冷启动"，它没有长期记忆，没有办公室政治直觉，也不会主动问你"这个模块的边界在哪"。你给它什么上下文，它就在什么范围内工作。

所以AI Native团队的第一件事，是在仓库根目录放一份结构化的项目说明文件。业界现在比较通用的做法是CLAUDE.md（不同工具可能叫AGENTS.md或类似名字，本质一样）。这份文件不是给人看的README，而是给Agent看的"项目宪法"。它要回答几个问题：这个项目是干什么的、技术栈是什么、目录结构怎么组织、代码规范是什么、常用命令有哪些、哪些地方不能碰。

我见过很多团队把这份文件写成营销文案，什么"致力于打造业界领先的解决方案"，这种内容对Agent零价值。有效的CLAUDE.md应该是命令式的、具体的、可执行的。比如不要写"请遵循良好的代码规范"，而要写"所有Python函数必须带类型注解，使用black格式化，行宽88"。

2.2 一份能用的CLAUDE.md长什么样

我们团队实际用的模板大致是这样的结构，我把它拆开讲：

# 项目概述 一句话说明项目做什么，不超过50字。 # 技术栈 - 语言：Python 3.11 - 框架：FastAPI + SQLAlchemy 2.0 - 数据库：PostgreSQL 15 - 测试：pytest + httpx # 目录结构 - src/api/ 路由层，只做参数校验和响应组装 - src/service/ 业务逻辑层，所有业务规则在这里 - src/model/ 数据模型，SQLAlchemy ORM - tests/ 测试，与src结构镜像对应 # 常用命令 - 启动开发服务：make dev - 跑测试：make test - 格式化：make fmt # 硬性约束 - 禁止在路由层写业务逻辑 - 所有数据库操作必须通过service层 - 新增接口必须同步补测试 - 不要修改alembic/versions下的历史迁移文件

这份文件的关键在于约束要硬、要可验证。"禁止在路由层写业务逻辑"这种约束，Agent能理解也能遵守；"代码要优雅"这种就完全没法执行。

2.3 知识库的分层：从CLAUDE.md到模块级文档

只有一份根目录的CLAUDE.md是不够的。项目一大，Agent在具体模块工作时需要更细的上下文。我们的做法是分层：

• 根级CLAUDE.md：全局约束、技术栈、目录约定
• 模块级CLAUDE.md：放在每个核心模块目录下，说明该模块的职责、对外接口、内部关键设计
• 决策记录（ADR）：放在docs/adr/下，记录"为什么这么设计"，Agent在改动相关代码前会读

这里有个实操心得：模块级文档不要写实现细节，要写边界和契约。实现细节会随代码变化而过时，边界和契约相对稳定。比如"用户服务对外只暴露get_user和update_user两个方法，其他方法为内部实现"——这种信息对Agent判断改动影响面极其有用。

2.4 文档维护的自动化：别让知识库腐烂

知识库最大的敌人是腐烂。人写的文档会过时，Agent读到的过时文档比没有文档更危险。我们的解法是把文档维护也交给Agent一部分：

在CI里加一个检查，当代码结构发生重大变化（比如新增了顶层模块、修改了公共接口）时，自动触发一个Agent任务，让它对比代码和文档，生成差异报告，由人确认后更新。这个流程我们跑了半年，文档新鲜度明显好于纯人工维护。

注意：不要让Agent自动修改CLAUDE.md并直接提交。这份文件是团队共识的载体，任何改动都应该经过人审。Agent可以提议，不能拍板。

3. Plan Mode：把"想清楚"变成流程里的强制环节

3.1 直接让Agent写代码为什么会翻车

刚开始用Agent的时候，我们的做法很直接：给个需求，让它写代码。结果惨不忍睹。Agent会自作主张地选技术方案、会漏掉边界条件、会在没理解现有代码的情况下重复造轮子。最要命的是，它写出来的东西看起来都对，跑起来一堆问题，排查成本比人自己写还高。

问题的根源在于：Agent跳过了"理解-规划-执行"里的前两步，直接进入执行。人写代码前会在脑子里过一遍方案，Agent不会，除非你强制它做。

Plan Mode就是干这个的。它的核心思想是：在Agent动手写代码之前，先让它输出一份执行计划，人审核通过后再执行。这个环节把Agent从"莽夫"变成"谋士"。

3.2 Plan Mode的实际操作流程

我们团队的Plan Mode流程是这样的：

1. 任务输入：人用自然语言描述需求，附上相关文件路径和约束
2. Agent调研：Agent读取相关代码和文档，理解现状
3. 计划输出：Agent输出一份结构化计划，包含：要改哪些文件、每个文件改什么、为什么这么改、有什么风险
4. 人审核：人检查计划，指出问题，Agent修订
5. 计划冻结：计划确认后，Agent按计划执行，不再自由发挥
6. 执行与验证：Agent执行并跑测试，人做最终review

这个流程里最关键的是第3步的计划格式。我们要求Agent的计划必须包含"影响面分析"——即这个改动会影响到哪些现有功能。这一条逼着Agent去理解代码的依赖关系，而不是孤立地看一个文件。

3.3 计划质量的判断标准

不是所有计划都是好计划。我们总结了几个判断标准，用来快速识别烂计划：

一个实操技巧：让Agent在计划里明确写出"我不确定的地方"。这听起来反直觉，但极其有用。Agent在不确定时会倾向于编造，逼它标注不确定点，人就能针对性地补充信息，避免它在错误假设上狂奔。

3.4 Plan Mode的边界：什么任务不需要计划

Plan Mode不是万能的，也不是所有任务都值得走一遍。我们的经验是：

• 需要Plan Mode：跨模块改动、新增核心功能、重构、涉及数据模型变更
• 不需要Plan Mode：单文件小修、改文案、加日志、修明显的bug

判断标准很简单：如果这个改动可能影响到你不熟悉的代码，就走Plan Mode。因为Agent和你一样，对不熟悉的代码容易判断失误，计划环节就是暴露这种失误的地方。

4. Agent编排：从单打独斗到流水线协作

4.1 单个Agent的能力天花板

一个Agent再强，也有能力天花板。它受限于上下文窗口、受限于单次任务的复杂度、受限于它被赋予的工具集。我们早期试图用一个"全能Agent"处理所有任务，结果发现它在复杂任务上表现极不稳定——前面几步做得好好的，到后面就开始胡来。

后来我们转向了多Agent编排的思路。核心洞察是：把复杂任务拆成多个子任务，每个子任务交给一个专注的Agent，Agent之间通过结构化的产物传递信息。这其实就是软件工程里"关注点分离"原则在Agent层面的应用。

4.2 我们实际用的Agent角色划分

我们团队目前稳定运行的角色划分是这样的：

• 规划Agent：负责Plan Mode，输出执行计划
• 编码Agent：按计划写代码，专注单一模块
• 测试Agent：根据代码和需求生成测试用例
• 审查Agent：检查代码是否符合规范、是否有明显bug
• 文档Agent：更新相关文档

这些Agent不是同时运行的，而是按流水线顺序执行。每个Agent的输入是上一个Agent的输出加上原始需求。这种设计的好处是每个Agent的上下文都很干净，不需要它同时理解需求和历史代码。

4.3 Agent之间的信息传递：结构化产物是关键

多Agent协作最容易翻车的地方是信息传递。如果Agent A的输出是一段自由文本，Agent B读起来就会各种误解。我们的解法是强制结构化产物。

比如规划Agent的输出必须是这样的JSON结构：

{ "task_id": "T-2024-001", "summary": "为用户模块新增手机号登录", "files_to_modify": [ {"path": "src/api/auth.py", "action": "modify", "reason": "新增登录路由"}, {"path": "src/service/user.py", "action": "modify", "reason": "新增手机号校验逻辑"} ], "files_to_create": [ {"path": "tests/test_phone_login.py", "reason": "覆盖新功能"} ], "risks": ["可能影响现有邮箱登录的session逻辑"], "uncertainties": ["手机号格式校验规则未明确"] }

编码Agent读这个结构，就不会跑偏。测试Agent读这个结构，就知道要覆盖哪些场景。结构化产物是Agent协作的"接口契约"。

4.4 编排的失败模式与应对

多Agent编排不是银弹，我们踩过的坑包括：

坑一：Agent之间互相甩锅。规划Agent说"细节由编码Agent决定"，编码Agent说"规划没给清楚"。解法是明确每个Agent的决策边界，规划Agent必须给出足够细的指令，编码Agent只能在指令范围内做实现选择。

坑二：错误在流水线里放大。规划Agent的一个小错误，到编码Agent变成大错误，到测试Agent变成一堆失败的测试。解法是在每个环节加验证，规划后有人审，编码后有测试，测试失败要回溯到规划环节而不是让编码Agent硬修。

坑三：上下文丢失。Agent B看不到Agent A看到的原始需求，导致理解偏差。解法是把原始需求作为每个Agent的固定输入，而不是只传上一个Agent的输出。

实操建议：编排流程不要一上来就搞五六个Agent。从两个开始（规划+编码），跑顺了再加测试和审查。每加一个Agent，都要问自己"这个环节真的需要独立Agent吗，还是可以让现有Agent多做一点"。

5. Agent安全与沙箱：别让自动化变成自动闯祸

5.1 Agent能造成的破坏比你想的大

Agent有了执行权限之后，能做的事远超"写代码"。它能跑命令、能改文件、能调API、能访问数据库。这意味着一个配置错误或者一次理解偏差，可能造成真实破坏——删错文件、改错配置、往生产库写脏数据。

我们团队早期就出过一次事故：一个Agent在"清理临时文件"的任务里，把tmp目录下的东西全删了，结果那个目录里有一个手动放的、没进版本控制的配置文件。虽然最后从备份恢复了，但那次之后我们彻底重构了Agent的权限模型。

5.2 沙箱的层次：从文件系统到网络

Agent沙箱不是一个开关，而是分层的。我们的做法是：

• 文件系统层：Agent只能访问项目目录，且对关键目录（如.git、config/）只读
• 命令层：白名单机制，只允许跑预定义的命令（make、pytest、git status等），禁止任意shell
• 网络层：默认禁网，需要联网的任务单独申请，且限制目标域名
• 数据层：Agent不能直接连生产数据库，只能连测试库，且测试库定期重置

这四层里，命令白名单是最容易被忽视但最重要的。很多团队觉得"Agent跑个命令而已"，但rm -rf和git push --force这种命令的破坏力是灾难级的。白名单机制能挡住绝大多数意外。

5.3 权限最小化：Agent不该有的权限就别给

权限最小化原则在Agent场景下尤其重要。我们的实践是：

• Agent默认只有读权限，写权限按任务临时授予
• 涉及删除的操作，必须走"移动到回收站"而不是直接删
• 涉及外部API调用的，用受限的token，且设置调用频率上限
• 涉及git操作的，Agent只能创建分支和提交，不能push到主分支

这些限制会让Agent"不那么方便"，但安全永远优先于方便。一个能随便push到主分支的Agent，迟早会给你制造一次生产事故。

5.4 审计与回滚：出事了能查、能退

再严的沙箱也可能有漏网之鱼，所以审计和回滚能力是底线。我们要求：

• Agent的每一次文件修改、命令执行都记录日志，包含时间、Agent ID、操作内容
• 每次Agent任务开始前，自动创建一个git stash或临时分支，任务结束后可一键回滚
• 关键操作（如数据库变更）前，自动备份相关数据

这套机制的价值不在于日常，而在于出事的时候。有一次一个Agent误改了配置文件，我们靠审计日志五分钟定位到问题，靠临时分支十秒回滚。没有这套机制，那次事故至少要排查半天。

6. 从需求到部署：AI Native SDLC的完整链路

6.1 需求阶段：把模糊需求变成Agent能吃的输入

传统需求阶段，产品经理写个PRD，开发自己理解。AI Native团队里，需求要写成Agent能直接消费的形式。我们的做法是需求必须包含：

• 明确的验收标准：不是"用户能登录"，而是"用户用手机号+验证码能登录，验证码错误时返回400，验证码过期时返回410"
• 边界条件：空值、超长、特殊字符怎么处理
• 影响范围：这个需求会影响哪些现有功能

这个要求逼着产品经理把需求想清楚，反而减少了很多后期的扯皮。我个人的观察是，AI Native转型最大的收益之一，是倒逼需求质量提升。

6.2 设计阶段：Agent辅助而非替代

设计阶段我们不让Agent做主，但让它做辅助。具体做法是：人先出设计草案，Agent做"红队审查"——专门挑设计的漏洞、边界情况、潜在冲突。Agent在这个角色上表现很好，因为它没有"这是我设计的"这种心理包袱，挑刺挑得很客观。

6.3 编码阶段：Plan Mode + 分模块执行

编码阶段就是前面讲的Plan Mode流程。这里补充一个细节：大任务要拆成小任务。一个"实现用户中心"的任务，Agent很难一次做好。拆成"用户信息查询接口"、"用户信息更新接口"、"头像上传"等子任务，每个子任务单独走Plan Mode，成功率高得多。

6.4 测试阶段：Agent生成 + 人审边界

测试用例让Agent生成，效率很高。但Agent生成的测试有个通病：只覆盖happy path，边界情况覆盖不足。我们的做法是Agent生成基础用例，人专门补充边界用例。另外，Agent生成的测试要检查是否"假测试"——即那种永远通过的、没有真正断言的测试。

6.5 部署阶段：Agent不碰生产

部署阶段我们坚持人来做最终操作。Agent可以准备部署脚本、可以跑预发布环境的验证、可以生成部署checklist，但按下生产部署按钮的必须是人。这条红线我们从来没破过，也不打算破。

7. 团队协作模式的真实变化

7.1 人的角色：从写代码到审代码

AI Native团队里，一线开发的时间分配发生了根本变化。以前70%时间写代码，现在可能30%写代码、40%审Agent产出、30%处理Agent搞不定的复杂问题。这个转变对开发者的能力要求不一样了——审代码的能力比写代码的能力更重要了。

审Agent的代码和审人的代码不一样。人的代码有风格、有习惯，你能从代码里读出作者的意图。Agent的代码没有这些，它可能这段写得很好那段写得很烂，可能在一个文件里用了三种不同的风格。审Agent代码要更关注逻辑正确性和边界处理，而不是风格一致性（风格问题让格式化工具解决）。

7.2 沟通成本：文档变得更重要

Agent不参加站会，不读群消息，不看邮件。所有Agent需要的信息，都必须在它能访问的地方——也就是仓库里的文档。这导致一个反直觉的结果：AI Native团队的文档要求比传统团队高得多。

我们团队的规矩是：任何口头讨论出的结论，必须在24小时内落到文档里，否则视为没讨论过。这条规矩刚开始执行很痛苦，但坚持下来之后，团队的沟通效率反而提升了，因为大家不用再靠记忆和反复确认来同步信息。

7.3 代码评审：从"看风格"到"看逻辑"

前面提过，Agent代码的评审重点变了。我们团队的评审checklist大致是：

• 逻辑是否符合需求（对照验收标准逐条检查）
• 边界条件是否处理（空值、异常、并发）
• 是否有隐藏的副作用（改了不该改的状态）
• 测试是否真实有效（不是假测试）
• 是否引入了新的依赖（Agent有时会自作主张加库）

风格问题基本不看，交给自动化工具。这个转变让评审更聚焦，也更快。

8. 踩过的坑与沉淀下来的经验

8.1 坑一：过度信任Agent的"自信"

Agent有个特点：它不知道的时候也会很自信地输出。早期我们被这个坑过好几次——Agent信誓旦旦地说"这个函数在xxx文件里"，结果根本没有。后来我们的规矩是：Agent提到的任何事实性信息，都要验证。文件路径、函数名、API签名，全部要核实。这个验证成本不低，但比基于错误信息做决策的成本低多了。

8.2 坑二：上下文窗口的隐性限制

Agent的上下文窗口是有限的，但它的表现不是"到上限就报错"，而是"到上限就开始遗忘早期信息"。这个隐性限制很坑。我们的应对是：长任务要分段，每段重新提供关键上下文。不要指望Agent记住你半小时前说的话。

8.3 坑三：Agent的"过度工程"倾向

Agent有时候会过度设计。你让它加个日志，它给你搞一套日志框架；你让它改个配置，它给你重构整个配置系统。这个倾向的根源是Agent倾向于"展示能力"。我们的应对是在CLAUDE.md里明确写"最小改动原则"，并在Plan Mode里检查计划是否超出了任务范围。

8.4 坑四：测试通过不等于功能正确

Agent写的代码经常能通过它自己写的测试，但功能是错的。原因是它写的测试和它写的代码有同样的理解偏差。我们的应对是：测试用例要由不同的人或不同的Agent来写，避免"自己考自己"。

8.5 沉淀下来的几条铁律

跑了大半年，我们团队沉淀了几条铁律，写在这里供参考：

• 任何Agent产出，未经人审不得合并
• 任何涉及删除、覆盖的操作，必须有回滚方案
• 任何Agent任务，必须有明确的验收标准
• 任何文档更新，必须与代码改动同步
• 任何新Agent的引入，必须先在沙箱里跑够一周

这些铁律听起来保守，但正是这些保守的约束，让我们的AI Native转型没有翻车。激进地放开权限、激进地信任Agent，短期看起来效率高，长期一定会付出代价。

9. 关于工具选型的一点个人看法

工具这块我不想给具体推荐，因为变化太快，今天推荐的明天可能就过时了。但选型的思路可以分享：优先选那些把"人审"环节设计进流程的工具。有些工具追求全自动，从需求到部署一条龙，听起来很爽，但实际用起来你会发现你根本不敢让它全自动。反而是那些在关键节点强制人介入的工具，用起来更踏实。

另外，工具的可观测性很重要。Agent做了什么、为什么这么做、中间产物是什么，这些信息要能查到。黑盒Agent在生产环境里是灾难。

最后说一句关于"AI Native"的心态。我见过两种极端：一种是把Agent当神，什么都交给它；一种是把Agent当玩具，觉得它啥也干不了。这两种都走不远。比较健康的心态是：把Agent当一个能力很强但需要明确指令、需要监督、会犯错的初级同事。你对初级同事怎么管理，就怎么管理Agent。这个类比不完美，但足够指导日常决策。

这套方法我们跑了大半年，交付效率确实提升了，但提升不是来自"Agent写得比人快"，而是来自"流程更清晰、文档更完整、评审更聚焦"。Agent只是把这些本来就该做好的事情，逼着团队真正做好了。这可能是AI Native转型最容易被忽视的价值。