1. 为什么“AI Native 团队”不是把 AI 塞进流程而是重写流程1.1 从“人写代码、AI 补全”到“人定边界、Agent 执行”过去两年大多数团队对 AI 的使用还停留在“副驾驶”阶段工程师写代码AI 帮忙补全几行、生成单元测试、解释一段报错。这个阶段的核心特征是人仍然是唯一的执行主体AI 只是一个更聪明的输入法。但当我们谈“AI Native 团队”时讨论的对象已经变了——不是“人怎么用 AI 提效”而是“当 Agent 成为一等公民之后整个软件开发生命周期SDLC该怎么重新设计”。我自己的团队从去年下半年开始做这件事踩了不少坑也沉淀出一套能跑通的落地方法。先说结论AI Native 不是给现有流程加一个 AI 工具而是把 SDLC 的每一个环节重新问一遍——“这一步如果默认由 Agent 来做人只负责定义边界和验收会变成什么样”这个问题的答案会直接改变你的仓库结构、代码评审方式、CI/CD 设计甚至团队的角色分工。举个最直观的例子传统 SDLC 里代码评审是“人看人写的代码”AI Native 里代码可能是 Agent 写的评审的重点从“这段逻辑对不对”变成了“这个 Agent 的上下文给得够不够、约束写得清不清楚、验收标准是否可自动执行”。评审对象从代码本身部分转移到了驱动代码生成的上下文和约束上。1.2 AI Native SDLC 的五个阶段重构把 SDLC 拆开看AI Native 化之后每个阶段的变化大致是这样的阶段传统做法AI Native 做法核心变化需求人写 PRD人拆任务人写意图与验收标准Agent 拆任务并生成任务卡需求变成“可被 Agent 消费的结构化输入”设计人画架构图人评审人定约束与接口契约Agent 生成方案草案设计产物变成“约束 契约”编码人写代码Agent 在仓库内执行人审上下文与 diff人从写代码转为写约束、审结果测试人写用例Agent 生成用例并自跑人定验收门槛测试从“写用例”转为“定标准”运维人看告警Agent 读日志、提修复 PR人审批闭环从“人驱动”转为“事件驱动 人审批”这张表不是理论推演是我们实际跑下来觉得最舒服的分工。关键洞察是人负责“定义正确”Agent 负责“执行正确”。一旦这个边界模糊要么人累死要么 Agent 失控。1.3 为什么是现在三个前提条件同时成熟了AI Native 团队能落地不是概念炒作而是三个条件同时到位了第一Agent 的执行能力跨过了“能干活”的门槛。以 Claude Code 这类终端内 Agent 为代表它不再是“给你一段代码让你复制”而是能直接在仓库里读文件、改文件、跑命令、看结果、再迭代。这个闭环能力是质变。第二上下文工程Context Engineering有了可操作的载体。CLAUDE.md这类约定文件让“给 Agent 的上下文”从口头描述变成了仓库里可版本化、可评审、可复用的资产。这是 AI Native 团队最核心的基础设施之一。第三模型能力足够强强到可以“少给指令、多给约束”。早期用 AI 写代码你得把每一步都写清楚现在你只需要把边界、契约、验收标准写清楚中间的实现路径 Agent 自己能规划。这让“人定边界”的分工真正可行。理解了这三点你就明白为什么我说 AI Native 不是加工具而是重写流程——因为工具的能力边界变了流程必须跟着变。2. 核心基础设施仓库、上下文与 Agent 运行环境2.1 仓库结构要为 Agent 而设计传统仓库结构是给人看的src/、tests/、docs/。AI Native 仓库要额外为 Agent 设计“入口”和“约束”。我们团队现在的仓库根目录大致长这样repo/ ├── CLAUDE.md # Agent 的主上下文入口 ├── .agent/ │ ├── tasks/ # 任务卡Agent 按卡执行 │ ├── skills/ # 可复用的技能定义 │ └── constraints/ # 硬约束Agent 不可违反 ├── src/ ├── tests/ └── docs/为什么要把.agent/单独拎出来因为 Agent 的上下文需要可版本化、可评审、可复用。任务卡不是聊天记录而是仓库里的文件能进 Git、能走 PR、能被 review。这一点非常关键——很多团队用 AI 写代码上下文全在聊天窗口里人一走、窗口一关经验就丢了。把上下文落进仓库才是团队级资产。CLAUDE.md放在根目录是因为 Claude Code 这类工具会默认读取它作为项目级上下文。它的内容不是“项目介绍”而是给 Agent 的操作手册这个项目怎么跑、怎么测、有哪些禁忌、代码风格是什么、哪些目录不能碰。写得好不好直接决定 Agent 的输出质量。2.2 CLAUDE.md 到底该写什么一份可抄的模板我见过太多团队的CLAUDE.md写成 README 的翻版全是“本项目是一个 XX 系统”。这对 Agent 没用。Agent 需要的是可执行的约束和可验证的标准。下面是我们团队实际在用的模板骨架# 项目上下文 ## 技术栈 - 语言TypeScript 5.x / Node 20 - 框架NestJS - 测试Jest Supertest - 包管理pnpm ## 常用命令 - 安装pnpm install - 开发pnpm dev - 测试pnpm test - 单测某文件pnpm test path - 类型检查pnpm typecheck ## 代码约束 - 禁止使用 any必须显式类型 - 所有对外接口必须有 Zod schema 校验 - 新增依赖必须说明理由写入 PR 描述 - 禁止修改 src/legacy/ 下的文件除非任务卡明确要求 ## 验收标准 - 所有新增函数必须有单测覆盖率不低于 80% - 提交前必须通过 pnpm typecheck 和 pnpm test - 不允许跳过 lint ## 目录说明 - src/modules/业务模块按领域划分 - src/shared/共享工具改动需谨慎 - tests/集成测试这份模板的核心逻辑是命令要能直接跑约束要能直接判验收要能自动验。凡是不能自动验证的约束写进去也是摆设。比如“代码要优雅”这种话Agent 无法执行人也没法验收不如不写。提示CLAUDE.md不要写太长。超过 200 行Agent 的注意力会被稀释。把细节拆到.agent/constraints/下的分文件里主文件只放最关键的入口信息。2.3 Agent 运行环境本地、容器还是云端Agent 跑在哪里是个必须提前想清楚的问题。我们试过三种方案各有取舍本地终端运行如 Claude Code 直接在开发者机器上跑优点是快、上下文全、能直接访问本地文件缺点是环境不一致、安全边界弱、难以团队共享。适合个人探索和快速原型。容器化运行把 Agent 跑在 Docker 容器里仓库挂载进去网络和文件系统都受限。优点是环境一致、安全可控、可复现缺点是要维护镜像、调试稍麻烦。适合团队标准化。云端 Agent 服务Agent 跑在远端通过 API 交互。优点是随时随地可用、算力不受限缺点是上下文同步复杂、延迟高、数据出境要评估。适合分布式团队。我们最终选的是容器化为主、本地为辅日常开发在本地跑保证速度CI 和批量任务在容器里跑保证一致性和安全。这个组合的关键是同一份CLAUDE.md和.agent/目录在两种环境下都能用不搞两套配置。2.4 模型接入不要绑死单一供应商热词里频繁出现“使用 cc switch 接入 deepseek、qwen、glm 等模型”“第三方 API 使用技巧”这背后是一个很现实的诉求不同任务用不同模型成本和效果都要平衡。我们的做法是抽象一层“模型路由”任务类型推荐模型档位理由复杂架构设计、跨文件重构高能力模型需要强推理和长上下文日常编码、单文件修改中等模型性价比高够用格式化、重命名、简单替换轻量模型或本地规则不需要大模型省成本代码评审、风险识别高能力模型需要判断力关键不是“用哪个模型”而是让模型选择成为配置项而不是硬编码。这样当新模型出来、当成本变化、当某个模型在特定任务上表现更好时你能快速切换而不是重写整套流程。注意接入第三方模型时务必确认数据流向和合规要求。涉及敏感代码或数据的场景优先选择数据不出内网或明确不用于训练的接入方式。3. Agent 架构与技能设计让 Agent 真正“会干活”3.1 Agent 和 Harness 的区别别把两者混为一谈热词里有个高频问题“harness 和 agent 区别”。这个问题问得很好因为很多人把两者混着用导致架构设计混乱。简单说Agent 是“会思考和行动的实体”Harness 是“让 Agent 能跑起来的脚手架”。Agent 负责决策——读什么文件、改什么代码、跑什么命令Harness 负责提供能力——文件读写、命令执行、网络访问、上下文注入、结果回传。打个比方Agent 是司机Harness 是车。司机决定去哪、怎么开车提供发动机、方向盘、刹车。你不能指望司机自己造一辆车也不能指望车自己知道目的地。这个区分为什么重要因为它决定了你的优化方向。如果 Agent 表现不好可能是决策问题提示词、上下文、任务卡写得不好也可能是能力问题Harness 没提供某个工具、权限不够、反馈不及时。分清楚才能对症下药。我们团队的经验是80% 的 Agent 失败根因在 Harness 而不是 Agent。比如 Agent 改完代码没法跑测试是因为 Harness 没给它执行命令的权限Agent 反复改错文件是因为 Harness 没把仓库结构清晰地注入上下文。先把 Harness 做扎实Agent 的表现会自然提升。3.2 技能Skill设计把重复劳动沉淀成可复用单元“Agent Skill 教程”是热词说明大家都在找怎么让 Agent 学会特定技能。我们的做法是把高频、稳定、可验证的操作沉淀成 Skill 文件放在.agent/skills/下。一个 Skill 的本质是“一段结构化的操作说明 验收标准”。比如“新增一个 API 接口”这个 Skill# Skill: 新增 API 接口 ## 触发条件 任务卡要求新增一个 HTTP 接口 ## 步骤 1. 在 src/modules/domain/ 下创建 controller 和 service 2. 定义 Zod schema 做入参校验 3. 在 module 中注册 4. 补充单测覆盖正常和异常路径 5. 更新 docs/api.md ## 验收 - pnpm typecheck 通过 - pnpm test 通过 - 新接口有至少 3 个测试用例 ## 禁忌 - 不要直接改 src/shared/ 下的通用工具 - 不要引入新的 HTTP 框架Skill 的价值在于把“老员工的经验”变成“Agent 能读的文档”。新人来了看 Skill 能快速上手Agent 读了 Skill 能稳定输出。而且 Skill 可以版本化、可以评审、可以迭代——这比把经验留在某个人脑子里强太多。3.3 任务卡Agent 执行的原子单位任务卡Task Card是 AI Native 团队的核心工作单元。它不是“需求文档”而是Agent 能直接消费的执行指令。一张好的任务卡包含四部分目标一句话说清要做什么可验证上下文涉及哪些文件、哪些模块、相关背景约束不能做什么、必须遵守什么验收怎么判断做完了举个例子# Task: 为用户模块增加手机号登录 ## 目标 在现有邮箱登录基础上增加手机号 验证码登录方式 ## 上下文 - 相关文件src/modules/user/auth.service.ts - 参考实现邮箱登录逻辑 - 验证码服务src/shared/sms/已存在直接用 ## 约束 - 不修改现有邮箱登录逻辑 - 验证码有效期 5 分钟存 Redis - 手机号必须做格式校验 ## 验收 - 新增单测覆盖正常登录、验证码错误、验证码过期、手机号格式错误 - pnpm test 全绿 - 更新 docs/api.md任务卡写得好Agent 一次就能做对写得模糊Agent 就会反复试错浪费 token 也浪费时间。我们内部有个说法写任务卡的时间就是省下来的返工时间。3.4 Agent 记忆短期、长期与项目级“Agent 记忆”是热词但很多人对它的理解停留在“让 Agent 记住聊天历史”。在团队场景下记忆要分三层短期记忆当前任务的上下文随任务结束而丢弃。这是 Agent 运行时自带的。长期记忆跨任务的偏好和决策比如“这个团队偏好函数式写法”“这个项目不用 ORM”。这类记忆适合放在CLAUDE.md或.agent/constraints/里作为持久上下文。项目级记忆仓库特有的知识比如“这个模块的历史包袱”“这个接口不能动的原因”。这类记忆适合放在docs/或代码注释里Agent 按需读取。关键原则是记忆要落盘不要留在对话里。对话里的记忆不可复用、不可评审、不可传承。落盘的记忆才是团队资产。4. 实操落地从零搭一个 AI Native 工作流4.1 环境准备安装与配置以 Claude Code 为例说下我们团队的标准配置流程。不同系统略有差异但思路一致。macOS / Linux# 安装具体方式以官方文档为准 # 安装后验证 claude --version # 在项目根目录初始化 cd your-repo claudeUbuntu 环境基本一致注意 Node 版本要够新建议 20否则可能遇到兼容问题。如果遇到权限问题检查 npm 全局目录的权限配置。VS Code 集成装好扩展后在 VS Code 里可以直接调用 Agent好处是能结合编辑器上下文。配置要点是让扩展读取项目根目录的CLAUDE.md这样 Agent 的上下文和终端里一致。提示安装过程中如果提示“当前地区不可用”这是服务可用性问题不是技术问题。团队落地时优先确认所选工具的可用性和合规性再决定是否纳入标准流程。4.2 第一个任务让 Agent 跑通“读-改-测”闭环新手最容易犯的错是一上来就让 Agent 做复杂任务。正确做法是先用一个极小任务验证闭环。我们团队的标准“Hello World”任务是给一个已有函数补一个边界条件测试。步骤在.agent/tasks/下建一张任务卡写清楚目标函数、要覆盖的边界、验收标准启动 Agent让它读任务卡观察它是否读对了文件、改对了地方、跑通了测试如果失败先看是 Harness 问题还是任务卡问题不要急着改提示词这个任务小到 5 分钟能做完但能验证整条链路上下文注入、文件读写、命令执行、结果反馈。链路通了再上复杂任务。4.3 让 Agent 直接执行终端命令权限与安全边界“Claude Code 如何直接执行终端命令”是热词这确实是 Agent 能力的关键一环。但直接给 Agent 终端权限风险很大。我们的做法是分级授权命令类型授权策略例子只读命令默认允许ls、cat、git status测试/构建默认允许pnpm test、pnpm build写操作需确认git commit、文件删除危险操作禁止或强确认rm -rf、git push --force、改 CI 配置实现方式上可以在 Harness 层做命令白名单/黑名单也可以在 Agent 配置里设审批规则。核心原则是Agent 能自己跑测试和构建但不能自己合并代码、不能自己发布。人保留最终审批权。注意千万不要让 Agent 拥有生产环境的写权限。所有涉及生产的操作必须走人工审批。这不是不信任 Agent而是工程纪律。4.4 代码评审的新姿势审上下文不只审 diffAI Native 团队的代码评审重点变了。以前是“逐行看逻辑”现在是先看驱动这次改动的任务卡和上下文再看 diff。我们的评审清单任务卡是否清晰目标和验收是否可验证Agent 是否遵守了CLAUDE.md里的约束新增代码是否有对应测试测试是否真的在验证行为有没有偷偷改了不该改的文件依赖变更是否合理这个转变的意义在于如果任务卡和约束写得好diff 的质量是自然结果。与其在 diff 上反复挑刺不如在源头上把上下文管好。我们团队现在的评审时间反而比以前短了因为大部分低级问题在 Agent 执行阶段就被约束挡住了。4.5 CI/CD 集成让 Agent 成为流水线的一环Agent 不能只在本地跑要进 CI。我们的做法是PR 触发 Agent 自检Agent 读任务卡检查 diff 是否符合验收标准输出报告失败自动重试如果测试失败Agent 尝试修复最多重试 N 次人工审批卡点Agent 的自检报告作为参考最终合并仍需人审批这样做的价值是把重复的检查工作交给 Agent人只做判断。但要注意Agent 的自检不能替代人的评审它是“第一道过滤网”不是“最终裁决者”。5. 常见问题与排查技巧实录5.1 Agent 改错文件、反复试错怎么办这是最高频的问题。根因通常是上下文不足或约束不清。排查顺序检查CLAUDE.md是否说清了目录结构和禁忌检查任务卡是否指明了具体文件路径检查 Harness 是否把仓库结构注入了上下文如果都做了还错考虑加“改文件前先确认路径”的约束我们踩过的坑早期任务卡只写“修改用户模块”Agent 就在整个src/里乱找。后来改成“修改src/modules/user/auth.service.ts的login方法”命中率立刻上来了。能具体就具体别让 Agent 猜。5.2 Token 消耗过快、成本失控“AI Agent token 是什么意思”是热词说明很多人对成本没概念。Token 就是模型处理文本的计量单位输入输出都算。Agent 反复读大文件、反复试错token 消耗会飙升。控制成本的手段上下文精简只注入相关文件不要整个仓库塞进去任务卡精准减少试错就是减少 token模型分级简单任务用轻量模型缓存复用相同上下文不要重复计算我们团队的经验是优化任务卡质量比换便宜模型更省成本。因为一次做对的成本远低于反复试错的成本。5.3 Agent 输出不稳定、时好时坏不稳定的根因通常是上下文有随机性。比如任务卡描述模糊、相关文件没固定、约束有歧义。解决办法是把变量固定下来任务卡模板化、上下文清单化、约束明确化。还有一个容易被忽略的点模型版本变化。同一个提示词模型升级后表现可能变。所以关键任务的提示词和任务卡要版本化模型升级后回归测试。5.4 常见问题速查表现象可能原因排查方向改错文件上下文不足任务卡指明路径CLAUDE.md 写清结构反复试错验收标准不清任务卡写可验证的验收条件Token 飙升上下文过大精简注入分级模型输出不稳定上下文有随机性模板化任务卡固定上下文违反约束约束不可执行约束要能自动验证测试跑不过Harness 权限不足检查命令执行权限改了不该改的禁忌没写清CLAUDE.md 明确禁止目录5.5 独家避坑技巧最后分享几个我们踩坑换来的经验第一先做 Harness再做 Agent。很多人一上来就调提示词其实先把文件读写、命令执行、上下文注入做扎实Agent 表现会自然好。第二任务卡要短。一张任务卡超过一屏Agent 就容易抓不住重点。宁可拆成多张也不要写一张巨长的。第三约束要能自动验证。“代码要优雅”没法验证“函数必须有单测”可以验证。只写能验证的约束。第四保留人工审批卡点。Agent 可以自检、可以提 PR但合并和发布必须人批。这是底线。第五上下文要落盘。聊天记录会丢仓库文件不会。把经验写进CLAUDE.md和 Skill才是团队资产。这套东西我们跑了小半年最大的体会是AI Native 不是让 AI 替人干活而是让人把精力从“执行”转移到“定义”。定义清楚边界、约束、验收标准剩下的交给 Agent。这个转变一开始别扭但一旦跑通团队的产出节奏会明显不一样。