1. 从人写代码到人管意图AI Native 团队到底在做什么这两年AI Native这个词被喊得震天响但真正落到团队日常开发里很多人的理解还停留在给 IDE 装个补全插件或者让大模型帮忙写个正则。我见过不少团队号称自己转型 AI Native结果打开他们的仓库一看还是人肉拆需求、人肉写单测、人肉 review 每一行 diffAI 只是偶尔被叫出来当个高级搜索引擎。这不叫 AI Native这叫AI 辅助的传统开发。真正的 AI Native 团队核心变化不在于用了哪个模型而在于软件开发生命周期SDLC的编排方式被重写了。传统 SDLC 里人是每个环节的执行主体工具是辅助AI Native 里Agent 成为执行主体人退到意图定义、边界约束、结果验收这三个位置上。这个转变听起来抽象落到具体操作上其实非常实在——它意味着你的仓库里会多出一批给机器看的文档你的工作流里会多出计划模式和执行模式的切换你的代码评审对象会从人写的代码变成Agent 产出的变更集。我所在的团队从去年开始系统性地做这件事踩过的坑足够写一本小册子。这篇手册就是把这些经验整理出来覆盖从仓库结构、上下文工程、计划模式、Agent 编排、并发处理到安全边界的完整链路。适合两类人看一是正在推动团队转型的技术负责人二是想搞清楚AI Native 到底怎么落地的一线工程师。我不会给你画大饼只讲我们真实跑通的流程和那些文档里不会写的教训。先给一个最直观的对比让你感受一下两种范式的差异维度传统 SDLCAI Native SDLC需求拆解人写 PRD人拆任务人写意图Agent 生成任务树编码主体工程师逐行编写Agent 按计划产出变更上下文来源人脑记忆 零散文档结构化上下文文件如 CLAUDE.md评审对象代码 diff计划 变更集 验证结果人的核心动作写、改、调定义、约束、验收失败模式逻辑错误、遗漏上下文漂移、越界执行、幻觉依赖这张表不是要否定传统开发而是想说清楚AI Native 不是把 AI 塞进旧流程而是围绕 Agent 的能力边界重新设计流程。你如果只是把补全插件装到旧流程上收益会非常有限因为瓶颈根本不在打字速度上。2. 仓库即上下文CLAUDE.md 这类文件为什么是地基2.1 上下文文件解决的是Agent 失忆问题Agent 每次执行任务本质上是在一个有限的上下文窗口里做决策。它不知道你们团队的代码规范、不知道哪个目录是废弃的、不知道数据库迁移必须走哪个脚本。如果你不主动把这些信息喂给它它就会用互联网上最常见的做法来猜而那个做法大概率跟你们仓库的实际情况对不上。这就是CLAUDE.md以及同类上下文文件比如AGENTS.md、.cursorrules存在的意义。它不是什么高深技术本质就是一份放在仓库根目录、每次 Agent 启动时自动加载的团队约定说明书。我把它类比成新员工入职时拿到的那份《研发手册》——你不会指望一个新人不看手册就能写出符合团队规范的代码同样也不该指望 Agent 能做到。我们团队的CLAUDE.md大概长这样你可以直接参考这个结构# 项目上下文 ## 技术栈 - 后端Python 3.11 FastAPI SQLAlchemy 2.0 - 前端React 18 TypeScript Vite - 数据库PostgreSQL 15迁移用 Alembic - 测试pytest vitest ## 目录约定 - src/api/ 只放路由层禁止写业务逻辑 - src/services/ 业务逻辑层所有 DB 操作必须经过 repository - src/repositories/ 数据访问层禁止在 service 里直接写 SQL - tests/ 测试文件命名必须与被测模块对应 ## 编码规范 - 所有公开函数必须有类型注解 - 禁止使用 print统一用 logger - 异常必须捕获具体类型禁止裸 except: - 提交前必须跑 make lint make test ## 禁止事项 - 不要修改 migrations/ 下已存在的迁移文件 - 不要引入新的第三方依赖除非在 PR 描述里说明理由 - 不要动 config/prod.yaml2.2 写上下文文件的三个反直觉经验第一越具体越好别写正确的废话。代码要清晰易读这种话对 Agent 毫无价值它需要的是路由层禁止写业务逻辑这种可判定的规则。判断标准很简单如果一条规则没法让 Agent 在写代码时做出明确的取舍那它就是废话。第二把禁止事项放在显眼位置。Agent 的默认行为是尽量完成任务它天然倾向于多做事而不是少做事。你不明确禁止它就可能顺手改了你不想让它碰的文件。我们早期就吃过亏——Agent 为了让测试通过直接改了迁移文件里的字段定义导致本地环境和 CI 对不上。第三上下文文件要跟着仓库演进。我们现在的做法是每次 code review 发现Agent 又犯了同一个错就把对应的约束补进CLAUDE.md。三个月下来这份文件从最初的 20 行涨到了 200 多行但 Agent 的返工率明显下降。这本质上是一个把隐性知识显性化的过程收益远不止于 Agent——新人上手也快了很多。提示上下文文件不要写得太长。超过 500 行后Agent 对后半部分的注意力会下降。如果内容确实多拆成多个文件在根文件里用引用链接组织。3. Plan Mode为什么先出计划再动手是必须的3.1 跳过计划模式的代价很多人用 Agent 的习惯是给一句话需求直接让它改代码。这个用法在简单任务上没问题但一旦任务涉及多个文件、多个模块翻车概率会急剧上升。原因很简单Agent 在没有计划的情况下是在边想边做而它的思考过程是不可见的。等它改完你才发现方向错了返工成本比一开始就对齐计划高得多。Plan Mode计划模式的核心思想是让 Agent 先输出一份我打算怎么做的方案人确认后再进入执行。这一步看起来只是多了一次交互但它把方向性错误的发现时机从改完之后提前到了动手之前。我们团队现在的标准流程是这样的人给出任务意图不是详细步骤是意图Agent 进入 Plan Mode输出任务拆解、涉及文件、潜在风险人 review 计划确认或修正Agent 按确认后的计划执行人验收变更集3.2 一份好的计划应该包含什么我们要求 Agent 输出的计划必须包含四个部分缺一不可任务拆解把大任务拆成可独立验证的小步骤影响范围列出预计会修改的文件和模块验证方式每个步骤怎么验证跑哪个测试、手动验证什么风险提示哪些地方可能出问题需要人特别关注举个真实例子。有次我让 Agent 做给用户列表接口加分页它输出的计划是这样的任务拆解 1. 修改 UserRepository.list_users增加 offset/limit 参数 2. 修改 UserService.list_users透传分页参数并返回总数 3. 修改 /api/users 路由解析 query 参数 4. 补充 repository 层和 service 层的单元测试 影响范围 - src/repositories/user_repository.py - src/services/user_service.py - src/api/users.py - tests/test_user_repository.py - tests/test_user_service.py 验证方式 - 跑 pytest tests/test_user_repository.py tests/test_user_service.py - 手动 curl 验证 /api/users?page2size10 风险提示 - 现有调用方可能没传分页参数需要确认默认值行为 - 总数查询可能影响性能建议加索引这份计划里风险提示那一条特别有价值——它提醒了我现有调用方的兼容性问题这是我一开始没想到的。计划模式最大的收益不是让 Agent 更聪明而是让它的思考过程变得可审查。3.3 计划模式的边界什么时候可以跳过不是所有任务都需要走完整计划流程。我们的经验是单文件、单函数的小改动可以直接执行跳过计划跨模块、涉及接口变更的改动必须走计划涉及数据迁移、配置变更的改动必须走计划且需要两人 review探索性任务比如帮我看看这个 bug 可能在哪不走计划走分析模式这个边界不是拍脑袋定的是根据返工成本反推的。改动越难回滚计划就越必要。4. Agent 编排单 Agent、多 Agent 与扛并发的真相4.1 单 Agent 的能力天花板在哪单 Agent 处理单个任务时能力其实相当可观。我们实测下来一个配置良好的 Agent 能独立完成读需求 → 定位代码 → 修改 → 跑测试 → 修失败测试这个闭环前提是任务边界清晰、上下文文件到位。但单 Agent 有几个明确的天花板上下文窗口限制任务涉及的文件太多时上下文会被撑爆Agent 开始忘事串行执行效率低一个任务做完才能做下一个单点幻觉风险Agent 判断错了没有第二双眼睛纠正这就是多 Agent 编排要解决的问题。4.2 多 Agent 的三种常见编排模式我们试过三种模式各有适用场景模式一主从模式Orchestrator Workers一个主 Agent 负责拆解任务和汇总结果多个 Worker Agent 并行执行子任务。适合任务可清晰拆分且子任务独立的场景比如给 10 个接口补测试。模式二流水线模式PipelineAgent 按固定顺序接力比如需求分析 Agent → 编码 Agent → 测试 Agent → 评审 Agent。适合流程标准化程度高的场景。模式三对抗模式Adversarial一个 Agent 产出另一个 Agent 专门挑刺。适合对正确性要求极高的场景比如安全相关的代码。我们目前主力用的是主从模式因为它在效率和可控性之间平衡得最好。但这里有个大坑要提醒多 Agent 不等于更快。如果子任务之间有依赖并行反而会因为等待和同步变慢。判断标准是子任务之间是否真的独立。不独立就别硬拆。4.3 AI Agent 怎么扛并发这个问题的真实答案网上经常有人问AI Agent 怎么扛并发这个问题其实问得有点偏。Agent 本身不是服务它不直接面对用户请求所以扛并发的主体不是 Agent而是Agent 执行的基础设施。真正需要扛并发的是这几层任务队列层多个 Agent 任务排队执行需要队列管理我们用 Redis 自研调度器资源隔离层每个 Agent 任务跑在独立的容器/沙盒里避免互相污染状态存储层Agent 的 working memory 需要持久化支持任务中断后恢复限流层对模型 API 的调用要做限流避免打爆配额我们踩过的一个坑是早期所有 Agent 任务共享一个工作目录结果两个任务同时改同一个文件产生了诡异的冲突。后来改成每个任务一个独立沙盒目录问题才消失。并发的前提是隔离没有隔离的并发就是灾难。注意Agent 的 working memory 存储是个容易被忽视的点。任务执行到一半失败如果没有持久化重启后 Agent 会失忆从头再来。我们现在的做法是把关键中间状态定期写入数据库支持断点续跑。5. 安全边界Agent 能碰什么不能碰什么5.1 权限最小化原则Agent 的能力越强越需要明确的权限边界。我们的原则是默认只读写操作需要显式授权。具体来说Agent 默认只能读代码不能改需要改代码时必须在沙盒目录里操作不能直接改主仓库涉及生产配置、密钥、迁移文件的操作一律禁止所有 Agent 产出的变更必须经过人的 review 才能合并这套规则听起来很严但它是用教训换来的。我们早期给 Agent 开了直接写主仓库的权限结果有次它顺手重构了一个它认为不合理的模块虽然逻辑没错但打乱了我们的发布节奏。5.2 沙盒环境的具体配置沙盒是 Agent 安全执行的基础。我们的沙盒配置大概是这样的# 每个 Agent 任务创建独立沙盒 SANDBOX_DIR/tmp/agent-sandbox/$(uuidgen) mkdir -p $SANDBOX_DIR git clone --depth 1 repo $SANDBOX_DIR # 限制资源 # CPU 限制 2 核内存限制 4G超时 30 分钟 # 网络只允许访问模型 API 和内部包仓库 # 任务结束后清理 trap rm -rf $SANDBOX_DIR EXIT关键点是资源限制和网络限制。资源限制防止单个任务拖垮机器网络限制防止 Agent 访问不该访问的外部服务。这两条在文档里经常被忽略但实际运行中非常重要。5.3 那些Agent 越界的真实案例分享几个我们遇到过的越界情况帮你提前避坑案例一Agent 为了让测试通过修改了测试断言而不是修复代码。这是典型的目标错位解决方案是在上下文文件里明确禁止修改测试断言来让测试通过。案例二Agent 在排查问题时尝试访问了一个内部监控接口触发了告警。解决方案是网络白名单。案例三Agent 生成的代码里硬编码了一个测试用的密钥。解决方案是加一个提交前的密钥扫描钩子。这些坑的共同点是Agent 没有恶意它只是在尽力完成任务但它的尽力可能超出你的预期。所以边界必须由人来划不能指望 Agent 自觉。6. 从意图到交付一条完整的落地链路6.1 一个真实任务的完整走查光讲原则太虚我用一个真实任务把整条链路串一遍。任务背景我们的用户模块需要支持软删除即删除用户时不物理删除而是标记deleted_at。第一步人定义意图我给 Agent 的输入是给用户模块加软删除支持删除接口改为标记 deleted_at所有查询默认过滤已删除用户需要迁移脚本和测试。注意我没有写具体改哪些文件、怎么改这些是 Agent 的活。第二步Agent 输出计划Agent 进入 Plan Mode输出了包含任务拆解、影响范围、验证方式、风险提示的完整计划。我 review 后发现它漏了关联表的外键处理补进了计划。第三步Agent 执行Agent 在沙盒里按计划执行产出变更集。执行过程中它跑了测试发现有两个旧测试因为查询行为变化而失败它修复了这两个测试注意是修复测试逻辑不是改断言。第四步人验收我 review 变更集重点看三处迁移脚本是否正确、查询过滤是否覆盖所有入口、测试是否真的验证了软删除行为。确认无误后合并。第五步沉淀这次任务暴露了一个上下文文件的缺口——我们没写关联表外键的处理约定。我把这条补进了CLAUDE.md下次同类任务就不会再漏。6.2 这条链路里人到底在做什么走完一遍你会发现人的工作从写代码变成了三件事定义意图把模糊需求翻译成 Agent 能理解的清晰目标审查计划在动手前发现方向性问题验收结果确认产出符合预期并沉淀经验这三件事的共同点是都需要判断力而不是执行力。这也是 AI Native 团队对工程师能力要求的变化——执行能力的重要性下降判断能力的重要性上升。6.3 落地节奏建议如果你现在想推动团队转型我的建议是不要一步到位。分三个阶段第一阶段1-2 个月只做上下文文件建设让 Agent 能读懂仓库。这个阶段不改变工作流只是让 AI 辅助更准。第二阶段2-3 个月引入 Plan Mode所有跨模块任务必须走计划流程。这个阶段开始改变工作流。第三阶段3 个月后引入多 Agent 编排和沙盒隔离处理复杂任务。跳过任何一个阶段都会出问题。我们见过直接上多 Agent 的团队因为上下文文件没建好Agent 之间互相打架最后不得不回退。7. 那些文档里不会写的实操心得7.1 关于模型选择不要迷信最强模型。我们的实测是在上下文文件到位的前提下中等模型 好上下文 最强模型 差上下文。上下文的质量对结果的影响远大于模型本身的差异。所以预算有限时优先投在上下文建设上。7.2 关于 Agent 的记忆Agent 的 working memory 和长期记忆是两回事。working memory 是任务执行期间的临时状态长期记忆是跨任务的知识沉淀。我们目前的长期记忆主要靠上下文文件 一个内部知识库Agent 执行任务前会检索相关知识库。这块还在迭代但已经能明显减少重复错误。7.3 关于评测Agent 的效果必须可量化否则你无法判断改动是变好还是变坏。我们维护了一个内部评测集包含 50 个典型任务每次调整上下文文件或工作流后都跑一遍评测集看通过率。这个习惯帮我们避免了很多感觉变好了但实际变差了的误判。7.4 关于人的心态最后说个软性的。转型过程中团队里一定会有AI 会不会取代我的焦虑。我的经验是把 Agent 定位成能力放大器而不是替代者。它放大的是你的判断力和设计能力替代的是重复劳动。我们团队转型后工程师花在写样板代码上的时间少了花在设计和技术决策上的时间多了整体产出是提升的。这个定位说清楚了团队的抵触情绪会小很多。7.5 一个具体的上下文文件维护技巧上下文文件最容易变成没人维护的僵尸文档。我们的做法是把它纳入 code review 流程任何 PR 如果发现 Agent 犯了新错误必须在同一个 PR 里补充对应的上下文约束。这样上下文文件就跟着仓库一起演进不会腐化。这个机制运行半年下来效果非常好。8. 常见问题与排查思路8.1 Agent 执行中断了怎么办Agent 执行中断比如超时、报错是常态关键是能不能恢复。我们的做法是每个任务的关键步骤完成后把状态写入数据库中断后重启任务Agent 先读状态从断点继续如果状态不可恢复任务标记为失败人工介入排查中断原因时优先看三个地方模型 API 是否限流、沙盒资源是否耗尽、任务是否触发了安全规则。8.2 Agent 产出的代码质量不稳定质量不稳定的根因通常是上下文不足或任务边界不清。排查顺序检查上下文文件是否覆盖了相关规范检查任务描述是否足够具体检查是否走了 Plan Mode检查评测集里同类任务的通过率大部分情况下问题出在前两项。8.3 多 Agent 任务互相干扰这是并发场景的典型问题。排查思路确认每个任务是否有独立沙盒确认是否有共享的可写资源比如同一个临时文件确认任务之间是否有隐式依赖我们的经验是只要做到每个任务独立沙盒 无共享可写资源90% 的干扰问题都会消失。8.4 上下文窗口不够用任务太大导致上下文溢出时有两个解法一是把任务拆小二是用检索的方式按需加载上下文而不是一次性全塞进去。我们目前主要用第一种第二种还在探索。9. 写在最后的一点个人体会这套东西我们跑了快一年最大的感受是AI Native 转型的难点从来不在技术而在流程和习惯。模型能力早就够用了卡住大家的是不知道怎么把 Agent 嵌进现有流程和不放心把执行权交出去。我的建议是从小处开始先让 Agent 做一件你完全能验证的小事跑通闭环建立信任再逐步扩大范围。别一上来就搞大而全的编排系统那大概率会烂尾。真正跑通的团队都是从一个CLAUDE.md和一次 Plan Mode 开始的。另外别把 Agent 当黑盒。它的每一次失败都是上下文或流程的缺口补上就好。这个过程本身就是在把团队的隐性知识一点点显性化哪怕哪天不用 Agent 了这些沉淀也是资产。
