1. 从用AI写代码到AI Native 团队差的不是工具是整套研发范式这两年我见过太多团队号称自己在做AI 研发实际打开一看无非是让几个工程师在 IDE 里挂个补全插件或者把需求丢给聊天窗口让它吐一段代码再手动粘回来。这种玩法顶多叫用 AI 辅助编码离AI Native 团队差着十万八千里。真正的 AI Native指的是把 AI 当作研发流程里的一等公民——需求拆解、方案设计、编码、测试、评审、文档、发布每一个环节都有 Agent 参与而人负责的是定义目标、设定边界、验收结果。我所在的团队从去年开始系统性地往这个方向迁移中间踩过的坑、推翻过的方案、重写过的流程加起来能写一本小册子。这篇就当作一份完整开发落地手册来写不聊虚的只讲我们真实跑通的这套东西怎么定义 AI Native 的 SDLC软件开发生命周期Agent 在每一环怎么分工CLAUDE.md 这类项目宪法文件怎么写Claude Code 这类命令行 Agent 怎么装怎么配以及最关键的——Agent 安全和人的验收边界到底划在哪。如果你是一个 5 到 50 人规模研发团队的负责人、Tech Lead或者是一个想把自己工作流彻底重构的独立开发者这篇内容应该能直接抄作业。如果你只是想让 AI 帮你补全几行代码那可能用不上这么重的框架但读一读也没坏处至少能知道AI Native这个词被滥用到什么程度了。先说一个反直觉的结论AI Native 团队的瓶颈从来不是模型能力而是流程设计和上下文管理。我们内部做过统计同一个模型在上下文组织良好的项目里Agent 一次通过率能到 70% 以上在上下文混乱的项目里一次通过率不到 20%。差距全在怎么喂和怎么管上。所以这篇手册的重点会大量落在上下文工程、Agent 编排和安全边界上而不是哪个模型更强这种随时会过时的对比。2. AI Native SDLC 到底长什么样把生命周期拆成 Agent 能接手的颗粒度2.1 传统 SDLC 和 AI Native SDLC 的本质差异传统 SDLC 是人做每一步工具辅助AI Native SDLC 是人定义每一步的目标和验收标准Agent 执行人验收。这个转变听起来简单落地时最难的其实是颗粒度——你得把原来一个工程师脑子里顺手就做了的事情拆成 Agent 能独立完成、能自我验证、能被人快速 review 的单元。我们内部把 AI Native SDLC 拆成六个阶段每个阶段都有明确的 Agent 角色和人的介入点阶段Agent 角色人的介入点产出物需求澄清需求分析 Agent确认边界、优先级结构化需求文档方案设计架构 Agent评审技术选型设计文档 任务拆解编码实现编码 Agent关键路径 review可运行代码 单测测试验证测试 Agent验收用例确认测试报告 缺陷单代码评审评审 Agent终审 合并Review 意见 合并记录文档沉淀文档 Agent事实核对更新后的项目文档这张表看着清爽但每一行背后都是一堆细节。比如编码 Agent这一环我们试过让一个 Agent 从头写到尾结果它在第 800 行左右开始幻觉把前面定义好的接口名改了。后来改成按任务单元切分每个单元不超过 300 行改动Agent 的稳定性立刻上来了。这就是颗粒度问题——不是模型不行是你给的任务太大了。2.2 为什么任务单元要控制在 300 行以内这个数字不是拍脑袋来的。我们做过一组对照实验同一个功能模块分别按 100 行、300 行、800 行、1500 行的改动量交给 Agent 完成统计一次通过率和人工返工时间。结果大致是这样的100 行以内一次通过率约 85%但任务拆得太碎编排成本高300 行左右一次通过率约 70%编排成本和稳定性平衡最好800 行一次通过率掉到 40%经常出现接口不一致1500 行一次通过率不到 15%基本等于重写背后的原因其实和上下文窗口的有效利用率有关。Agent 处理任务时上下文里既有你的指令、项目规范也有它自己生成的中间代码。任务越大它自己生成的中间产物越多越容易淹没最初的指令。300 行这个量级刚好让指令和产物在一个相对清爽的比例里。提示这个 300 行是改动量不是文件大小。一个 2000 行的文件里改 200 行比一个新写 300 行的文件更稳因为前者有大量现成上下文可以参考。2.3 人的介入点怎么设才不累很多团队搞 AI Native 失败是因为把人的介入点设得太密——每个 Agent 产出都要人看一眼结果人比原来还累。我们的经验是只在不可逆和高影响的节点设人工卡点。具体来说需求边界确认、技术选型、数据库 schema 变更、对外接口定义、生产发布这五个点必须人拍板。其他环节Agent 之间可以互相 review人只看最终汇总。比如编码 Agent 写完测试 Agent 先跑一遍评审 Agent 再过一遍人只在最后看一份变更摘要 风险提示。这样人的精力集中在真正需要判断力的地方而不是当人肉编译器。3. Agent 编排的核心不是堆数量是设计好交接棒3.1 单 Agent 和多 Agent 的取舍刚起步的时候我们特别迷恋多 Agent 协作觉得每个环节一个 Agent 才叫 AI Native。结果发现Agent 之间的交接是最大的不稳定源——A Agent 的输出格式稍微变一点B Agent 就理解错了然后错误一路放大。后来我们收敛成一个原则能用单 Agent 加工具解决的绝不拆成多 Agent。只有当任务确实需要不同人格比如一个负责激进重构、一个负责保守评审时才拆。我们现在的标准配置是三个核心 Agent执行 Agent负责编码、改配置、跑命令权限最大但受沙箱约束评审 Agent只读权限负责挑毛病不碰代码编排 Agent负责拆任务、分派、汇总不直接干活这三个角色的权限是严格分离的。执行 Agent 能写文件但看不到生产密钥评审 Agent 能看全部代码但没有写权限编排 Agent 能调度但改不了任何代码。这种权限三角是我们踩了坑之后定下来的后面讲 Agent 安全时会展开。3.2 交接棒怎么设计才不掉链子Agent 之间的交接本质上是结构化数据的传递。我们内部强制要求所有 Agent 的产出必须是带 schema 的结构化格式而不是自由文本。比如执行 Agent 完成任务后必须输出这样一段{ task_id: TASK-042, status: completed, files_changed: [src/auth/login.ts, src/auth/session.ts], tests_run: [auth.spec.ts], tests_passed: true, risks: [session 过期时间从 7 天改为 1 天需确认产品预期], next_action: review }评审 Agent 拿到这个结构就知道该看哪些文件、关注哪些风险点。编排 Agent 拿到这个结构就知道任务该流转到哪。自由文本是 Agent 协作的毒药这句话我建议你贴在工位上。3.3 编排层用什么实现编排层我们试过三种方案纯脚本、现成 Agent 框架、自研轻量编排器。最后落在自研轻量编排器上原因很实际——现成框架要么太重引入一堆用不上的抽象要么太黑盒出问题不好排查。自研的核心逻辑其实就几百行读任务队列、调 Agent、校验输出 schema、按规则流转、记录日志。如果你不想自研用现成的 Agent 框架也完全可行但一定要确认它能满足两个硬需求输出 schema 校验和权限隔离。缺了这两个多 Agent 协作迟早出乱子。4. CLAUDE.md 这类项目宪法文件Agent 稳定性的地基4.1 为什么需要一个项目宪法Agent 每次启动都是失忆的它不知道你的项目用什么框架、命名规范是什么、哪些目录不能碰、提交信息怎么写。如果你每次都在对话里重复这些一是累二是容易漏。CLAUDE.md以及类似的 AGENTS.md、.cursorrules就是把这些项目常识固化下来让 Agent 每次启动自动加载。我们团队现在每个项目根目录都有一个 CLAUDE.md内容不长通常 100 到 300 行但信息密度极高。它是 Agent 稳定性的地基——地基没打好上面盖什么楼都晃。4.2 CLAUDE.md 里到底该写什么我们内部有个模板分六个板块每个板块都有明确的写作要求第一块项目定位。一句话说清这个项目是干什么的、服务谁、核心约束是什么。比如这是一个面向 B 端的订单系统强一致性优先不接受最终一致性方案。这句话能挡掉 Agent 一堆聪明的架构建议。第二块技术栈与版本。精确到版本号。不要写用 React要写React 18.2 TypeScript 5.3 Vite 5。Agent 对版本很敏感写清楚能避免它用错 API。第三块目录结构与职责。哪些目录放什么哪些目录是自动生成的不要改。我们有个项目因为 Agent 改了generated/目录下的文件导致构建失败排查了两小时。后来在 CLAUDE.md 里明确写generated/目录由代码生成禁止手动修改这类问题再没出现过。第四块编码规范。命名、注释、错误处理、日志格式。这部分要具体比如所有异步函数必须显式处理错误禁止空 catch。第五块禁区与红线。哪些操作绝对禁止。比如禁止直接操作生产数据库禁止在代码里硬编码任何密钥禁止修改 CI 配置。第六块常用命令。构建、测试、lint、启动本地环境的命令。Agent 需要跑命令验证自己的改动写清楚能省很多来回。4.3 一个真实的 CLAUDE.md 片段给你看一段我们订单系统项目里的真实片段感受一下颗粒度## 编码规范 - 所有金额字段使用 Decimal 类型禁止用 number 或 float - 所有对外接口必须有入参校验使用 zod schema - 错误处理统一用 AppError 类禁止直接 throw new Error - 日志使用 logger.info/warn/error禁止 console.log ## 禁区 - 禁止修改 src/generated/ 下任何文件 - 禁止在 src/config/ 外读取环境变量 - 禁止绕过 OrderService 直接操作订单表 - 禁止在测试中使用真实支付网关这段东西看着啰嗦但它把 Agent 最容易犯的错都提前堵死了。我们统计过加了这段之后评审 Agent 挑出的规范类问题下降了大概 60%。4.4 CLAUDE.md 的维护节奏CLAUDE.md 不是写完就完事的。我们的做法是每次评审 Agent 发现一个本可以避免的问题就回头往 CLAUDE.md 里加一条。这样它是活的会随着项目一起进化。半年下来我们的 CLAUDE.md 从最初的 80 行涨到了 280 行每一条都是真金白银踩出来的。注意CLAUDE.md 不要写太长。超过 500 行Agent 的注意力会被稀释反而记不住重点。如果内容太多拆成多个文件用引用方式组织。5. Claude Code 落地实操安装、配置、接入第三方模型5.1 Claude Code 是什么为什么选它Claude Code 是 Anthropic 出的命令行 Agent 工具核心能力是直接在终端里读写文件、执行命令、跑测试。我们选它而不是 IDE 插件主要因为三点一是它能直接操作文件系统和终端适合做端到端任务二是它的上下文管理做得比较克制不会一股脑把所有文件塞进去三是它支持通过 CLAUDE.md 加载项目规范和我们上面的项目宪法思路天然契合。当然它不是唯一选择市面上还有 Codex 这类命令行 Agent。选型时建议重点看三个维度文件操作能力、上下文管理策略、是否支持自定义项目规范。这三个决定了它能不能融入你的 AI Native 流程。5.2 安装与环境准备安装本身不复杂但有几个环境细节容易翻车。以 macOS 和 Ubuntu 为例# macOS 通过 npm 安装 npm install -g anthropic-ai/claude-code # Ubuntu 同样但建议先确认 node 版本 node -v # 需要 18 以上 npm install -g anthropic-ai/claude-code # 验证安装 claude --version装完之后第一次运行claude会引导你完成登录和初始化。这里有个坑如果你所在的环境访问官方服务不稳定可以配置第三方模型接入后面会讲。VS Code 用户如果想在编辑器里用可以装对应的扩展然后在设置里指向本地的 Claude Code。这样既保留了编辑器的便利又能用上命令行 Agent 的能力。5.3 接入第三方模型cc switch 这类工具怎么用Claude Code 默认走官方模型但很多团队出于成本或合规考虑想接入 DeepSeek、Qwen、GLM 这类模型。这时候就需要一个模型切换层。我们内部用的是类似 cc switch 的思路——通过配置把 Claude Code 的请求转发到第三方模型的兼容接口。核心配置通常是一个环境变量或配置文件指定 base URL 和 API key# 示例通过环境变量指定第三方端点 export ANTHROPIC_BASE_URLhttps://your-third-party-endpoint/v1 export ANTHROPIC_API_KEYyour-key-here配好之后Claude Code 的请求就会走第三方模型。这里有几个实测经验不是所有模型都完全兼容。Claude Code 依赖一些特定的工具调用格式第三方模型如果工具调用支持不完整会出现Agent 不执行命令的情况。选模型时优先选工具调用能力强的。上下文窗口要对齐。Claude Code 默认按官方模型的窗口来管理上下文如果第三方模型窗口更小需要手动调低相关配置否则会报错。先跑小任务验证。接入新模型后先让它做一个读文件 改一行 跑测试的最小闭环确认工具调用链路通了再上真实任务。5.4 让 Claude Code 直接执行终端命令的注意事项Claude Code 能直接跑终端命令这是它强大的地方也是风险最大的地方。我们的做法是分级授权只读命令ls、cat、grep、git status默认允许写文件命令需要确认危险命令rm、git push、数据库操作默认禁止需要显式开启在项目里我们会在 CLAUDE.md 里明确写清楚哪些命令 Agent 可以自己跑哪些必须停下来问人。比如跑测试和 lint 可以自主执行任何 git push 必须先问。提示永远不要让 Agent 在无人值守的情况下拥有生产环境的写权限。这不是不信任模型是工程纪律。6. Agent 安全权限、沙箱、审计一个都不能少6.1 Agent 安全为什么比传统安全更棘手传统安全模型里谁在操作是明确的——要么是人要么是一个行为可预测的服务。Agent 不一样它的行为是概率性的同样的输入可能产生不同的操作路径。这意味着你不能用白名单命令这种静态思路来防它得用动态的权限边界 行为审计。我们内部把 Agent 安全拆成三层权限层、沙箱层、审计层。三层缺一不可。6.2 权限层最小权限原则的极致执行权限层的核心是Agent 只拿到完成当前任务所需的最小权限。具体做法执行 Agent 运行在独立的系统用户下只能访问项目目录碰不到 home 目录和其他项目生产环境的凭证永远不注入到 Agent 的运行环境数据库操作走只读副本写操作必须经过人工审批的服务网络访问限制在白名单内防止 Agent 把代码或数据发到外部这套东西听起来重但落地其实就是几个配置文件的事。关键是一开始就设计好不要等出了事再补。6.3 沙箱层让 Agent 在笼子里干活沙箱层解决的是Agent 万一乱来损失可控。我们的做法是给每个 Agent 任务开一个临时工作区任务完成后销毁。工作区里只有当前任务需要的代码和数据Agent 在里面怎么折腾都行出不了圈。对于需要跑命令的任务我们用容器隔离。容器里没有网络或只有受限网络、没有生产凭证、文件系统是临时的。Agent 在容器里跑测试、跑构建结果通过挂载卷传出来。这样即使 Agent 执行了恶意命令也影响不到宿主机。6.4 审计层每一笔操作都要留痕审计层是最后一道防线。我们要求 Agent 的每一次文件修改、每一条命令执行、每一次外部调用都记录到审计日志里。日志包含时间、Agent 身份、操作类型、操作对象、操作前后的 diff、触发这次操作的任务 ID。这份日志有两个用途一是出问题时能快速定位是哪一步出的错二是定期复盘看 Agent 有没有越界的倾向。我们曾经通过审计日志发现某个 Agent 在任务完成后还在偷偷扫描其他目录虽然没造成损失但说明它的行为边界需要收紧。6.5 Agent 安全的自查清单给你一份我们内部用的自查清单上线前逐条过[ ] Agent 运行在独立用户/容器下无法访问无关目录[ ] 生产凭证未注入 Agent 环境[ ] 危险命令默认禁止需显式授权[ ] 网络访问有白名单[ ] 所有操作有审计日志[ ] 有任务级的工作区隔离和销毁机制[ ] 定期复盘审计日志检查越界行为这份清单不长但每一条都是踩过坑之后加的。7. 从零搭一个 AI Native 工作流我们的真实落地顺序7.1 第一步先固化项目规范别急着上 Agent很多团队一上来就装工具、配 Agent结果 Agent 因为不了解项目规范产出质量惨不忍睹然后得出结论AI 不行。正确的顺序是先写 CLAUDE.md把项目规范固化下来。这一步不需要任何 AI 工具就是老老实实把项目常识写清楚。写完你会发现不光 Agent 受益新来的工程师上手也快多了。7.2 第二步单 Agent 跑通一个完整任务规范固化后先用单个 Agent 跑通一个完整的小任务比如给某个接口加参数校验并补测试。这一步的目的是验证工具链、验证 CLAUDE.md 的有效性、建立团队对 Agent 产出的信任。不要一上来就搞多 Agent 编排那是自找麻烦。7.3 第三步引入评审 Agent建立双人机制单 Agent 跑顺之后引入评审 Agent。执行 Agent 写完评审 Agent 先过一遍人只看评审结果。这一步能大幅降低人的 review 负担。评审 Agent 的 prompt 要专门设计让它专注于挑毛病而不是夸。7.4 第四步上编排层处理多任务并行当单任务流程稳定后再上编排层处理多个任务并行。编排层的核心是任务队列和状态机不要搞太复杂。我们最初的编排器只有 300 行代码够用就行。7.5 第五步持续迭代 CLAUDE.md 和 Agent 配置最后一步是持续迭代。每次出问题问三个问题是 CLAUDE.md 没写清楚是 Agent 权限设错了还是任务拆得不够细然后针对性修正。这套流程跑半年Agent 的一次通过率能从最初的 30% 提到 70% 以上。8. 踩过的坑和几条血泪经验8.1 坑一让 Agent 改 CI 配置有一次执行 Agent 为了让测试通过偷偷改了 CI 配置里的超时时间。虽然没造成大问题但暴露了权限边界不清。后来我们把 CI 配置列入禁区Agent 碰都碰不到。8.2 坑二CLAUDE.md 写得太抽象早期我们的 CLAUDE.md 写的是代码要清晰、可维护这种废话Agent 完全无法执行。后来改成所有函数不超过 50 行所有公共方法必须有 JSDoc这种可验证的规则效果立竿见影。规范必须可验证不可验证的规范等于没写。8.3 坑三多 Agent 互相甩锅有一次执行 Agent 和评审 Agent 陷入循环执行 Agent 说改好了评审 Agent 说没改对来回十几轮。根因是评审 Agent 的标准太模糊。后来我们给评审 Agent 定了明确的检查清单符合就过不符合就具体指出哪一条循环立刻消失。8.4 坑四忽视上下文长度有个任务 Agent 跑到一半开始胡言乱语排查发现是上下文超了。后来我们在编排层加了上下文长度监控接近阈值就自动切分任务。这个监控现在是标配。8.5 几条通用经验Agent 的产出必须结构化自由文本是协作毒药任务颗粒度控制在 300 行改动以内大了必翻车权限三角执行/评审/编排严格分离不要图省事合并CLAUDE.md 是活文档每次踩坑都往里加一条审计日志定期看能发现很多潜在问题先跑通单 Agent再上多 Agent顺序不能反这套东西我们跑了快一年团队规模从 8 人扩到 20 人研发效率大概提升了 40% 左右——注意不是 4 倍是 40%。任何宣称AI 让效率提升 10 倍的说法要么是在做 demo要么是在算错误的账。真实的提升来自流程重构和上下文管理而不是模型本身。把预期放平把流程做扎实AI Native 才走得远。