1. 从人写代码到人管 AgentAI Native 团队到底在变什么这两年AI Native这个词被喊得太多多到有点廉价。但如果你真的带过团队、跑过完整交付周期就会发现它不是一个营销词而是一次研发流程的底层重构。传统 SDLC软件开发生命周期里需求、设计、编码、测试、部署是一条人肉流水线每个环节靠文档和会议衔接而 AI Native 的 SDLC 里多了一类新同事——Agent它不只是补全代码而是能读需求、拆任务、改文件、跑命令、提 PR。我所在的团队从去年开始把 Claude Code 这类命令行 Agent 引入日常开发踩了大概三个月的坑才把流程跑顺。这篇手册就是把这套东西完整讲清楚AI Native 团队怎么组织、Agent 怎么接、CLAUDE.md 怎么写、安全边界怎么划、模型怎么换。适合两类人看——一类是准备把 Agent 引入团队的技术负责人另一类是已经在用 Claude Code 但总觉得没发挥出威力的开发者。先说一个反直觉的结论AI Native 团队的核心竞争力不在于你用了多强的模型而在于你有没有把上下文喂对。同一个 Claude Code有人用它一天改 30 个文件不出错有人用它改 3 个文件就崩差别几乎全在项目根目录那个CLAUDE.md和任务拆解方式上。下面我按真实落地顺序一层层拆。2. AI Native SDLC 的四个阶段Agent 到底插在哪一环2.1 传统 SDLC 与 AI Native SDLC 的对照很多人以为AI Native就是把 IDE 换成带 AI 的编辑器这是最大的误解。真正的差别在于每个阶段的产出物和责任人变了。我整理了一张对照表这是我们团队内部培训时用的阶段传统 SDLCAI Native SDLC关键变化需求产品写 PRD人读产品写 PRDAgent 先做需求澄清与拆解Agent 参与需求理解设计架构师画图写文档架构师定约束Agent 生成方案草案人定边界Agent 填细节编码人写人下指令Agent 执行人 review人从写变审测试人写用例Agent 生成用例 人补边界覆盖率提升但需防幻觉部署人配 CI/CDAgent 生成脚本人审权限权限是红线这张表最关键的一列是关键变化。你会发现人的角色从生产者变成了约束制定者 审核者。这不是偷懒而是把人的精力从重复劳动里解放出来投到真正需要判断力的地方。2.2 为什么 Agent 必须嵌入全流程而不是只做补全只把 Agent 当代码补全工具是浪费。我举个真实例子我们有个需求是给订单接口加一个幂等校验。如果只用补全你得自己找到接口文件、自己写校验逻辑、自己写测试。而用 Claude Code 这类 Agent你可以直接说阅读src/api/order.py为create_order接口增加基于request_id的幂等校验复用src/utils/idempotent.py里的现有实现并补充单元测试。Agent 会自己读文件、找依赖、改代码、写测试、跑测试。它完成的是一个任务闭环而不是一行代码。这就是 AI Native SDLC 和AI 辅助编码的本质区别——前者是任务级后者是行级。2.3 一个完整的 AI Native 交付闭环长什么样我们团队现在跑的标准闭环是这样的产品在 issue 里写清需求附带验收标准技术负责人把 issue 拆成 3-5 个 Agent 可执行的任务每个任务写清输入、输出、约束开发者用 Claude Code 逐个执行任务每个任务一个独立会话每个任务完成后人 review diff跑测试全部通过后Agent 生成 commit message 和 PR 描述CI 跑完人合并这个闭环里第 2 步是最容易被忽略但最关键的。任务拆得不好Agent 就会跑偏拆得好Agent 的产出质量能稳定在初级工程师偏上的水平。3. CLAUDE.mdAI Native 团队的项目宪法3.1 CLAUDE.md 到底解决什么问题Claude Code 每次启动会话时会自动读取项目根目录的CLAUDE.md。这个文件的作用是把团队隐性知识显性化让 Agent 不用每次都被重新教育。你可以把它理解成给新入职工程师的 onboarding 文档只不过读者是 Agent。没有它Agent 每次都要重新猜你的技术栈、代码规范、目录结构有了它Agent 一上来就知道这个项目用 pnpm 不用 npm测试用 vitest 不用 jest提交信息用 conventional commits。我见过太多人抱怨Claude Code 改的代码风格不对一问项目里根本没有CLAUDE.md。这不是 Agent 的问题是你没告诉它规则。3.2 一份能直接抄的 CLAUDE.md 结构下面这份是我们团队打磨了三个月的版本你可以直接拿去改# 项目概述 这是一个基于 FastAPI 的订单服务Python 3.11使用 Poetry 管理依赖。 # 技术栈 - 语言Python 3.11 - 框架FastAPI SQLAlchemy 2.0 - 数据库PostgreSQL 15 - 测试pytest pytest-asyncio - 代码检查ruff mypy # 目录结构 - src/api/ 接口层只做参数校验和调用 service - src/service/ 业务逻辑层 - src/repository/ 数据访问层 - tests/ 测试与 src 目录结构镜像 # 编码规范 - 所有函数必须有类型注解 - 禁止在 api 层写业务逻辑 - 数据库操作必须走 repository 层 - 异常统一用 src/exceptions.py 里定义的异常类 # 常用命令 - 安装依赖poetry install - 跑测试poetry run pytest - 代码检查poetry run ruff check . - 类型检查poetry run mypy src # 禁止事项 - 不要修改 alembic 迁移文件 - 不要直接操作生产数据库 - 不要引入新的第三方依赖除非明确说明理由这份文件的核心逻辑是把Agent 容易做错的事提前写死。比如禁止在 api 层写业务逻辑就是因为早期 Agent 老是把逻辑塞进接口函数里。3.3 CLAUDE.md 的三个常见写法错误错误一写成 README 的复制品。README 是给人看的讲的是这个项目是什么CLAUDE.md 是给 Agent 看的讲的是你该怎么干活。前者可以讲背景故事后者必须全是可执行规则。错误二规则太抽象。代码要优雅这种话 Agent 理解不了。所有函数必须有类型注解才是可执行的。错误三一次写太多。我建议 CLAUDE.md 控制在 100-200 行。太长了 Agent 反而抓不住重点而且维护成本高。真正复杂的规则可以拆到子目录的CLAUDE.md里Claude Code 支持分层读取。提示CLAUDE.md 是活文档。每次 Agent 犯了新错误就把对应的规则补进去。三个月下来这份文件会变成团队最值钱的资产之一。4. Agent 接入实操从安装到跑通第一个任务4.1 环境准备不同系统的安装差异Claude Code 的安装本身不复杂但不同系统有坑。我按系统分别说macOS官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code。如果你用 Homebrew 管理 node注意别装成系统自带的旧版本 node否则会报奇怪的错。装完跑claude --version验证。Ubuntu / Linux同样走 npm但要注意权限问题。如果你不想用 sudo建议用 nvm 管理 node把全局包目录设到用户目录下。另外 Ubuntu 上偶尔会遇到node-gyp编译问题装个build-essential基本能解决。Windows建议在 WSL2 里跑原生 Windows 支持一直不太稳定。WSL2 里按 Ubuntu 的方式装就行。装完之后第一次运行claude会让你登录。这里有个常见问题部分地区可能提示不可用。这种情况通常和网络环境有关具体处理方式请参考官方文档的说明我这里不展开。4.2 在 VS Code 里接入 Claude Code很多人不知道 Claude Code 有 VS Code 扩展。装了之后你可以在编辑器里直接开一个 Claude Code 面板边看代码边下指令体验比纯终端好很多。配置步骤在 VS Code 扩展市场搜 Claude Code 安装打开命令面板Cmd/Ctrl Shift P运行 Claude Code: Open首次使用会让你确认工作目录选你的项目根目录之后就可以在面板里直接对话了VS Code 版本最大的好处是diff 可视化。Agent 改完代码你能直接在编辑器里看到红绿 diff逐行 review比在终端里看 patch 舒服太多。4.3 跑通第一个任务从读代码开始新手最容易犯的错是一上来就让 Agent 改代码。正确做法是先让它读。第一个任务建议这样下阅读src/service/order_service.py用中文总结这个文件的核心职责、主要函数、以及它依赖了哪些其他模块。不要修改任何文件。这个任务的价值在于你能通过 Agent 的总结判断它有没有真正理解你的代码。如果总结得离谱说明你的 CLAUDE.md 或者项目结构有问题先修这个别急着改代码。确认 Agent 理解正确后再下第二个任务比如给某个函数加日志。任务粒度从小到大逐步建立信任。4.4 让 Agent 执行终端命令的正确姿势Claude Code 能直接执行终端命令这是它比纯对话式 AI 强的地方。但这也是风险最高的地方。默认情况下Claude Code 执行命令前会问你确认。我的建议是前期全部手动确认跑顺之后再考虑放行白名单命令。可以放行的安全命令包括ls、cat、grep、git status、git diff、跑测试的命令。绝对不要放行的rm -rf、git push --force、任何涉及数据库写操作、任何涉及生产环境的命令。我们团队的做法是在 CLAUDE.md 里明确写# 命令执行约束 - 允许自动执行ls, cat, grep, find, git status, git diff, pytest - 需要人工确认git commit, git push, 任何 pip/poetry 安装 - 禁止执行rm -rf, git push --force, 任何 DROP/TRUNCATE 语句这样 Agent 自己就知道边界在哪。5. 模型可替换不绑定单一供应商的接入策略5.1 为什么团队要考虑多模型接入Claude Code 默认用 Anthropic 的模型但实际团队使用中有几个现实问题成本、可用性、以及不同任务对模型能力的需求差异。比如写复杂业务逻辑强模型明显更好但跑批量格式化、写简单测试用便宜模型就够了。所以成熟的 AI Native 团队通常会配置多模型切换能力。社区里有不少工具能做这件事原理都是通过配置把 Claude Code 的请求转发到不同的模型服务上。具体工具选择这里不展开重点讲配置思路。5.2 多模型配置的核心参数无论用什么工具核心配置项就几个配置项作用注意事项base_url模型服务的接口地址必须支持 Anthropic 兼容协议api_key鉴权密钥不要硬编码进代码用环境变量model指定模型名不同服务商命名不同max_tokens单次输出上限太小会截断太大会浪费配置方式一般是改环境变量比如export ANTHROPIC_BASE_URL你的服务地址 export ANTHROPIC_API_KEY你的密钥 export ANTHROPIC_MODEL模型名改完重启 Claude Code 生效。5.3 什么任务用什么模型一份实用对照我们团队内部有个简单的分工原则架构设计、复杂重构用能力最强的模型这种任务省下的返工时间远超模型差价日常功能开发用中等模型性价比最高写测试、写文档、格式化用便宜模型量大管饱代码 review用强模型因为 review 需要理解全局这个分工不是死的但核心逻辑是把贵模型的额度花在需要判断力的任务上把便宜模型用在执行力任务上。注意切换模型后Agent 的行为风格会变。同一个 CLAUDE.md不同模型的理解可能不一样。切换后建议先跑一个熟悉的任务验证一下。6. Agent 安全比技术选型更重要的事6.1 Agent 安全的三条红线Agent 能读文件、能改代码、能跑命令这意味着它一旦跑偏破坏力比传统工具大得多。我们团队定了三条红线红线一绝不接触生产环境。Agent 的工作目录永远是本地或隔离的开发环境。任何指向生产数据库、生产服务器的配置都不应该出现在 Agent 能读到的文件里。红线二敏感信息不进上下文。API key、数据库密码、用户数据这些绝对不能出现在 Agent 读取的文件里。我们团队的做法是把敏感配置全部放.env并在.gitignore和 CLAUDE.md 里双重声明不要读 .env。红线三破坏性操作必须人工确认。前面讲过的命令白名单本质就是这条红线的落地。6.2 权限最小化Agent 应该只看到它需要的一个常见错误是让 Agent 在项目根目录随便跑。正确做法是按任务限定工作目录。比如你要改订单模块就让 Agent 的工作目录限定在src/order/和tests/order/别让它看到整个仓库。这样即使它跑偏影响范围也可控。Claude Code 支持通过参数指定工作目录具体用法看官方文档。核心思路就是给 Agent 的权限永远比它当前任务需要的多一点但不多太多。6.3 审计与回滚Agent 改错了怎么办再小心也会出错。所以必须有两道保险第一道Git。每个 Agent 任务开始前确保工作区是干净的。任务完成后先git diff看改动确认无误再 commit。这样任何错误都能git checkout回滚。第二道任务日志。我们团队要求每个 Agent 会话结束后把任务描述 关键决策 改动文件列表记到一个日志文件里。出问题时能快速定位是哪个任务引入的。这两道保险加起来基本能保证 Agent 出错时损失可控。7. 团队协作AI Native 团队的组织方式7.1 角色重新划分引入 Agent 后团队角色会发生微妙变化。我们团队现在的分工是技术负责人定 CLAUDE.md、拆任务、审关键改动开发者执行 Agent 任务、review diff、补边界测试Agent执行具体编码、写测试、生成文档注意开发者没有消失只是工作内容变了。以前 80% 时间写代码现在 80% 时间在拆任务、审代码、处理 Agent 搞不定的边界情况。7.2 任务拆解的粒度标准这是 AI Native 团队最需要训练的技能。我们的标准是一个任务Agent 应该在 5-15 分钟内完成改动不超过 5 个文件。超过这个粒度Agent 容易迷失低于这个粒度人拆任务的时间比 Agent 干活的时间还长不划算。拆任务时每个任务要写清三件事输入读哪些文件、输出改哪些文件、达到什么效果、约束不能做什么。7.3 代码 review 的重点转移以前 review 代码重点在逻辑对不对、风格好不好。现在 review Agent 产出的代码重点变成有没有引入幻觉Agent 有时会调用不存在的函数、引用不存在的模块有没有越界Agent 有时会顺手改一些你没让它改的文件边界处理够不够Agent 写的代码通常 happy path 很顺边界情况容易漏这三点是我们团队 review 时的固定检查项。8. 踩坑实录我们团队真实遇到的五个问题8.1 Agent 反复改同一个文件改不对现象让 Agent 改一个函数它改了三遍都不对每次都说这次应该对了。根因任务描述太模糊Agent 在猜你的意图。或者 CLAUDE.md 里缺少相关约束Agent 不知道项目的既有约定。解法停下来别让它继续改。重新写任务描述把期望的输入输出用具体例子写清楚。如果还不行说明这个任务超出了 Agent 当前能力人工介入。8.2 Agent 把测试改绿了但逻辑是错的现象Agent 跑测试发现失败然后去改测试而不是改代码测试是绿了但业务逻辑错了。根因任务描述里没说清测试是验收标准不能改。解法在 CLAUDE.md 里明确写测试文件是验收标准除非任务明确要求否则不要修改测试。这个坑我们踩过一次之后写进规则就再没犯过。8.3 上下文太长导致 Agent 失忆现象一个长会话跑到后面Agent 忘了前面说过的约束开始乱改。根因上下文窗口有限会话太长会丢失早期信息。解法一个任务一个会话。任务完成后关掉重开别在一个会话里连续做多个不相关的任务。这是最简单也最有效的办法。8.4 模型切换后行为突变现象换了模型之后同样的任务Agent 的产出风格完全变了甚至违反了 CLAUDE.md 里的规则。根因不同模型对指令的遵循程度不同。解法切换模型后先跑一个回归测试任务——一个你熟悉的、有标准答案的任务验证新模型是否遵守规则。不遵守就换回去。8.5 Agent 生成的 commit message 不符合规范现象Agent 自动生成的 commit message 格式乱七八糟。根因CLAUDE.md 里没写 commit 规范。解法在 CLAUDE.md 里加一段# 提交规范 使用 conventional commits 格式 - feat: 新功能 - fix: 修复 - refactor: 重构 - test: 测试 - docs: 文档 格式type(scope): description加完之后Agent 生成的 commit message 就规范了。9. 从能用到好用进阶优化思路9.1 建立团队自己的 Prompt 库跑顺之后你会发现有些任务反复出现比如给接口加参数校验写单元测试生成 API 文档。这些任务的 prompt 可以沉淀下来形成团队共享的 Prompt 库。我们团队的做法是在仓库里建一个prompts/目录每个常用任务一个 markdown 文件写清任务模板和注意事项。新人来了直接抄省去大量试错。9.2 用 Agent 生成 Agent 的规则这是个有意思的玩法让 Agent 自己分析项目生成 CLAUDE.md 的初稿。阅读整个项目总结技术栈、目录结构、编码规范生成一份 CLAUDE.md 初稿。Agent 生成的初稿通常不完美但能覆盖 70% 的内容人工补 30% 就行比从零写快很多。9.3 度量 Agent 的实际收益别只凭感觉说Agent 提效了。我们团队会记录几个指标每个任务的平均耗时人 AgentAgent 产出的一次通过率返工率跑了一个季度数据大概是简单任务提效 60%中等任务提效 30%复杂任务基本没提效甚至更慢。这个数据帮我们明确了什么任务该用 Agent什么任务不该用。10. 一些个人体会写到这里我想说几句掏心窝的话。AI Native 不是买几个工具、装几个插件就完事的。它是一次工作方式的重构重构的核心是人怎么和 Agent 分工。我见过太多团队工具买了一堆流程一点没变最后得出结论AI 也就那样。问题不在 AI在于人没变。我们团队跑了一年最大的收获不是省了多少人力而是把资深工程师从重复劳动里解放出来让他们去做真正需要判断力的事。Agent 干不了的恰恰是最值钱的那部分。如果你正准备在团队里推这套东西我的建议是别一上来就全面铺开。先找一两个愿意折腾的人在一个小模块上跑通闭环把 CLAUDE.md、任务拆解、review 流程都磨顺了再往外推。磨刀不误砍柴工这个道理在 AI Native 时代依然成立。最后分享一个小技巧每次 Agent 犯了新错误别只是骂它把对应的规则补进 CLAUDE.md。三个月后你会发现这份文件比任何文档都值钱因为它记录的是你们团队真实的、踩过坑的经验。