1. 从人写代码到人管 AgentAI Native 团队到底变了什么这两年我参与过几个号称AI Native的团队搭建也帮朋友的公司做过研发流程改造。说实话大部分团队对 AI Native 的理解还停留在给每个人配个 AI 编程助手这个层面——买账号、发通知、开个分享会然后就没有然后了。三个月后回头看代码提交量没涨需求交付周期没缩短唯一的变化是代码评审里多了几句这段是 AI 写的我没细看。问题出在哪出在大家把 AI Native 当成了一个工具升级问题而它本质上是一个研发范式重构问题。工具升级只需要采购和培训范式重构要动的是流程、角色分工、质量标准和协作方式。我自己的判断标准很简单一个团队是不是真的 AI Native不看它用了多少 AI 工具而看它的交付单元是什么。传统团队的交付单元是人天一个人一天能写多少代码、改多少 bugAI Native 团队的交付单元是Agent 任务一个 Agent 在给定上下文和约束下能自主完成多少可验证的工作。这个转变听起来抽象落到日常就是你不再问这个功能要几天而是问这个任务的验收标准是什么、上下文给全了没有、Agent 能不能自己跑完测试。1.1 为什么配个助手这条路走不通我见过最典型的失败模式是这样的团队引入了 AI 编程工具工程师用它来补全函数、写单元测试、解释报错。效率确实有提升大概 15% 到 30%但很快就撞到天花板了。原因有三个。第一上下文是碎的。工程师每次和 AI 对话都要重新解释项目结构、业务背景、代码规范。AI 没有项目级的记忆每次都是从零开始。这就像你雇了个记忆力只有五分钟的专家每次都要重新给他讲一遍项目背景。第二质量责任是模糊的。AI 生成的代码谁负责工程师说我审过了但审到什么程度有没有跑过集成测试边界条件考虑了吗没有明确的责任划分AI 生成的代码就成了质量的黑洞。第三流程是没变的。需求还是那样提评审还是那样开测试还是那样跑。AI 只是加速了写代码这一个环节但写代码在整个交付链路里可能只占 30% 的时间。加速 30% 的 30%整体提升不到 10%。1.2 AI Native 的真正含义把 Agent 当成团队成员我理解的 AI Native核心是三个转变。从人执行到人定义、Agent 执行。人的核心工作变成写清楚任务定义、验收标准、上下文约束然后让 Agent 去执行。这要求团队有很强的任务拆解和规格说明能力——这恰恰是很多团队最弱的地方。从代码为中心到上下文为中心。Agent 的表现高度依赖它拿到的上下文。项目里有没有一份清晰的CLAUDE.md或类似的上下文文件直接决定了 Agent 是聪明助手还是添乱机器。上下文工程Context Engineering成了新的核心技能。从事后评审到过程可验证。Agent 执行的任务必须有可自动验证的验收标准。测试、类型检查、lint、构建这些不是可选项而是 Agent 能不能自主闭环的前提。没有自动化验证Agent 就只能做建议不能做执行。这三个转变对应到具体实践就是后面要展开的上下文文件怎么写、Agent 任务怎么定义、验证闭环怎么搭、安全边界怎么划。2. 上下文工程CLAUDE.md 这类文件到底该写什么很多人第一次接触CLAUDE.md这类项目上下文文件时会把它当成一个项目说明文档来写——介绍项目背景、技术栈、目录结构。写完之后发现 Agent 的表现没什么提升就觉得这玩意儿是噱头。我踩过这个坑。后来才想明白CLAUDE.md不是给人看的项目文档而是给 Agent 看的操作手册。它的目标不是介绍项目而是让 Agent 在最少追问的情况下做出符合团队预期的决策。2.1 上下文文件的三层结构我现在的做法是把上下文文件分成三层每层解决不同的问题。第一层约束层必须遵守的硬规则。这一层写的是 Agent 绝对不能违反的东西。比如用哪个包管理器、代码风格用哪个 linter 配置、提交信息格式、分支命名规范、哪些目录不能动、哪些依赖不能引入。这一层要短、要硬、要可验证。我一般控制在 20 行以内。第二层决策层遇到选择时的默认倾向。这一层写的是当有多种做法时优先选哪个。比如状态管理优先用哪个库、错误处理用哪种模式、测试用哪个框架、API 设计遵循什么风格。这一层是 Agent 最需要的因为 Agent 最常卡在这里该怎么做的决策点上。第三层背景层理解项目所需的必要信息。这一层才是传统意义上的项目介绍但要极度克制。只写 Agent 真正需要知道的核心业务概念、关键模块的职责、外部依赖的用途。不要写历史沿革、不要写团队八卦、不要写本项目致力于打造一流的……这种废话。我实测下来一份好的上下文文件大概在 100 到 300 行之间。太短了 Agent 信息不够太长了 Agent 抓不住重点而且每次对话都要消耗 token。2.2 一个可复用的上下文文件骨架下面是我在多个项目里迭代出来的骨架你可以直接拿去改。# 项目上下文 ## 硬约束 - 包管理器pnpm禁止 npm/yarn - 代码风格ESLint Prettier提交前必须通过 - 提交信息Conventional Commits 格式 - 禁止修改/legacy 目录、*.generated.ts 文件 - 新增依赖必须先说明理由等待确认 ## 技术决策默认值 - 状态管理Zustand不用 Redux - 数据请求TanStack Query - 表单React Hook Form Zod - 测试Vitest Testing Library - 错误处理统一走 AppError 类禁止裸抛 Error ## 核心概念 - Workspace用户的工作空间一个用户可有多个 - Pipeline工作空间下的自动化流程是核心业务对象 - RunPipeline 的一次执行记录不可变 ## 关键模块 - src/core/业务核心逻辑改动需谨慎 - src/adapters/外部服务适配层隔离变化 - src/ui/纯展示层不含业务逻辑 ## 验证命令 - 类型检查pnpm typecheck - 单元测试pnpm test - 完整验证pnpm verify提交前必跑这份骨架的关键在于每一条都是可执行的指令而不是描述性的说明。用 pnpm是指令本项目使用 pnpm 作为包管理器是描述。Agent 对指令的遵循度远高于对描述的遵循度。2.3 上下文文件的维护节奏上下文文件不是写完就完事的。我的经验是每次 Agent 犯了一个本不该犯的错就往上下文文件里加一条规则。比如 Agent 又用了 npm 装包说明约束层不够醒目Agent 又写了个裸抛 Error说明决策层没覆盖到。这个过程持续两三周后上下文文件会稳定下来Agent 的低级错误率会明显下降。我自己的项目里这个迭代大概让 Agent 的一次通过率从 40% 提到了 75% 左右。注意上下文文件不要写成百科全书。我见过有人写了 800 行结果 Agent 反而抓不住重点因为关键约束被淹没在大量背景信息里。宁可分多个文件比如CLAUDE.md放核心约束docs/architecture.md放架构说明也不要堆在一个文件里。3. Agent 任务的定义与拆解从帮我写个功能到可执行规格上下文文件解决的是Agent 知道什么任务定义解决的是Agent 要做什么。这两件事缺一不可。我见过上下文写得很好但任务定义一塌糊涂的团队Agent 照样跑不出可用结果。核心问题是大部分人给 Agent 的任务描述是给人看的不是给 Agent 执行的。帮我加个用户导出功能——这句话对人来说信息量够因为人有常识、有项目背景、会主动追问。但 Agent 不会追问或者追问得很笨它会按自己的理解直接开干然后给你一个你不想要的东西。3.1 可执行任务规格的五个要素我现在要求团队里所有交给 Agent 的任务必须包含五个要素。缺一个Agent 的产出质量就会明显下降。要素一目标What。用一句话说清楚要达成什么。要具体到可验证。加个导出功能不行在 Pipeline 详情页加一个按钮点击后把当前 Pipeline 的所有 Run 记录导出为 CSV 文件才行。要素二验收标准Acceptance Criteria。这是最容易被忽略、也最重要的一条。验收标准必须是可自动验证的。比如点击按钮后 2 秒内开始下载、CSV 包含 Run 的 id、状态、开始时间、耗时四列、空数据时导出只有表头的 CSV。有了这些Agent 才能自己判断做完了没有。要素三上下文Context。告诉 Agent 相关的代码在哪、参考哪个已有实现、涉及哪些模块。比如参考src/features/workspace/export.ts的实现模式、复用src/core/run.ts里的listRuns方法。要素四约束Constraints。这个任务特有的限制。比如不要引入新的 CSV 库用现有的papaparse、导出逻辑放在src/features/pipeline/下、不要改动Run的类型定义。要素五验证方式Verification。明确告诉 Agent 怎么自测。比如跑pnpm test确保现有测试通过、为新功能补一个单元测试覆盖空数据场景。把这五个要素写清楚一个任务描述大概 15 到 30 行。看起来比帮我加个导出功能麻烦多了但 Agent 的一次通过率能从 30% 提到 70% 以上。这个投入产出比是划算的。3.2 任务拆解的粒度控制任务拆得太粗Agent 会跑偏拆得太细人累死还不如自己写。我摸索出来的粒度标准是一个任务对应一次可独立验证的代码变更变更范围控制在 3 到 5 个文件以内。超过 5 个文件的任务Agent 很容易在某个环节跑偏而且跑偏之后很难定位是哪一步出的问题。这时候应该拆成多个任务每个任务有独立的验收标准。举个实际例子。实现用户权限系统这种任务Agent 基本做不好。拆成下面这样就好多了定义权限相关的类型和常量1 个文件实现权限检查的核心函数带单元测试2 个文件在 API 层接入权限检查3 个文件在前端路由层接入权限检查2 个文件补充权限相关的集成测试1 个文件每个子任务都能独立验证跑偏了也容易回滚。3.3 任务模板的实际使用我把上面这套东西固化成了一个模板团队里所有人提 Agent 任务都用这个格式。用了一段时间后大家发现写任务描述本身就是一次很好的需求梳理——很多模糊的地方在写验收标准的时候就暴露出来了。## 任务Pipeline Run 记录导出 ### 目标 在 Pipeline 详情页添加导出按钮将当前 Pipeline 的所有 Run 记录导出为 CSV。 ### 验收标准 - [ ] 按钮位于页面右上角文案为导出记录 - [ ] 点击后 2 秒内触发下载 - [ ] CSV 列id, status, startedAt, duration - [ ] 空数据时导出仅含表头的 CSV - [ ] 导出失败时显示 toast 错误提示 ### 上下文 - 参考实现src/features/workspace/export.ts - 数据来源src/core/run.ts 的 listRuns - UI 组件src/ui/Button.tsx ### 约束 - 使用现有 papaparse不引入新依赖 - 逻辑放在 src/features/pipeline/export.ts - 不改动 Run 类型定义 ### 验证 - 运行 pnpm test确保现有测试通过 - 新增单元测试覆盖空数据场景 - 运行 pnpm typecheck这个模板的价值不在于格式本身而在于它强迫你把我以为说清楚了变成确实说清楚了。4. 验证闭环让 Agent 能自己判断做完了没有前面反复提到可验证这一节展开讲为什么它是 AI Native 的命门。传统开发里验证是人的工作。写完代码人跑一下看看对不对。Agent 执行任务时如果验证也要人来做那人的时间就被绑死在跑测试、看结果上Agent 的自主性就没了。Agent 能不能自主闭环取决于验证能不能自动化。4.1 验证的三个层次我把验证分成三层从快到慢从局部到整体。第一层静态验证。类型检查、lint、格式化。这一层最快几秒钟出结果。Agent 每改完一个文件就应该跑一次。这一层能拦住大部分低级错误类型不匹配、未使用的变量、格式问题。第二层单元测试。针对具体函数的测试秒级到十秒级。Agent 改完一个模块就应该跑相关测试。这一层能拦住逻辑错误边界条件、异常处理、状态转换。第三层集成验证。端到端的测试、构建、启动检查。这一层慢分钟级。Agent 完成一个完整任务后跑一次。这一层能拦住集成问题模块间接口不匹配、配置错误、依赖缺失。关键是要把这三层串成一条命令让 Agent 一条命令跑完所有验证。我一般会在package.json里定义一个verify脚本{ scripts: { typecheck: tsc --noEmit, lint: eslint . --max-warnings 0, test: vitest run, build: vite build, verify: pnpm typecheck pnpm lint pnpm test pnpm build } }然后在上下文文件里明确写完成任务后必须运行pnpm verify全部通过才算完成。这样 Agent 就有了自主判断做完了没有的能力。4.2 测试是给 Agent 写的不只是给人写的这一点很多人没转过弯来。传统上测试是给人回归用的所以写得比较人性化——描述性的测试名、宽松的断言、大量的 mock。但 Agent 用测试来判断自己做得对不对测试的写法就要调整。测试名要精确。it(works correctly)对 Agent 没用it(returns empty array when no runs exist)才有用。Agent 看到测试名就知道这个测试在验证什么行为。断言要严格。宽松的断言比如只检查没抛错对 Agent 没有指导意义。要断言具体的返回值、具体的状态变化。失败信息要清晰。测试失败时Agent 会读失败信息来定位问题。expect(received).toBe(expected)这种默认信息不够最好自定义失败信息告诉 Agent 期望什么、实际什么、可能的原因。我实测下来把测试从给人看改成给 Agent 看之后Agent 修复测试失败的成功率从 50% 提到了 80% 左右。因为失败信息清晰了Agent 不用猜。4.3 验证失败的自动修复循环有了自动化验证就可以搭一个验证-修复的循环Agent 执行任务 → 跑验证 → 失败 → 读失败信息 → 修复 → 再跑验证。这个循环能自动跑几轮直到通过或者连续失败。我一般设置最多 3 轮自动修复。超过 3 轮还修不好说明任务定义有问题或者上下文不够这时候应该停下来让人介入而不是让 Agent 无限循环烧 token。这个循环的关键是失败信息的质量。如果失败信息是测试失败这种模糊的Agent 修不好如果是期望listRuns返回空数组实际返回了undefined可能原因是没有处理空数据分支Agent 基本一轮就能修好。提示不要迷信全自动。我见过有人追求 Agent 完全自主结果 Agent 在一个错误的方向上反复尝试烧了大量 token 还污染了代码库。设置合理的轮次上限和人工介入点比追求全自动更实际。5. 安全边界Agent 能碰什么、不能碰什么Agent 有了执行能力之后安全问题就绕不开了。它能改代码、能跑命令、能装依赖这些能力用好了是效率用不好是灾难。我见过 Agent 误删文件、误改配置、误装依赖的案例虽然大部分能恢复但浪费的时间够呛。安全边界的核心原则是最小权限 可回滚 可审计。5.1 文件系统层面的边界最直接的做法是用工具本身的权限配置。比如 Claude Code 这类工具支持配置允许和禁止的操作范围。我的配置原则是允许读整个项目目录允许写src/、tests/、docs/等业务目录禁止写.env、*.lock、package.json依赖变更需人工确认、CI 配置文件、部署脚本禁止执行rm -rf、git push、npm publish、任何涉及生产环境的命令这些配置要写在项目级的配置文件里而不是靠人每次口头提醒。配置是硬的提醒是软的。5.2 依赖变更的特殊处理依赖变更是我最警惕的一类操作。Agent 为了完成任务很可能会引入新依赖而新依赖可能带来安全风险、体积膨胀、版本冲突。我的做法是上下文文件里明确禁止 Agent 自行添加依赖。如果任务确实需要新依赖Agent 必须停下来说明理由等人工确认后再加。这个停下来的动作很重要它把依赖决策权留在了人手里。实测下来这个约束会让 Agent 偶尔卡住但卡住比乱装依赖好。而且卡住的时候Agent 会明确告诉你我需要 X 依赖来做 Y这本身就是有价值的信息。5.3 敏感信息的隔离Agent 处理代码时可能会接触到敏感信息API key、数据库连接串、用户数据。这些信息绝对不能进入 Agent 的上下文更不能被 Agent 写进代码或日志。具体做法敏感配置全部走环境变量代码里只引用变量名.env文件加入.gitignore且禁止 Agent 读取上下文文件里明确写禁止在代码中硬编码任何密钥、token、连接串测试数据用假数据不用真实用户数据这一条没有商量余地。我见过有人图省事把测试环境的连接串写进代码结果被 Agent 复制到了另一个文件里差点提交上去。5.4 审计与回滚Agent 的每一次操作都应该可追溯。我的做法是Agent 的每次任务执行对应一个独立的 git 分支任务完成后人工 review diff 再合并关键操作依赖变更、配置修改单独记录这样即使 Agent 搞砸了回滚一个分支就行不会污染主干。而且 review diff 的过程本身也是学习——你能看到 Agent 是怎么理解你的任务的哪里理解对了哪里理解偏了。6. 团队协作当 Agent 成为同事之后前面讲的都是技术层面这一节讲人的层面。Agent 进入团队后协作方式会发生一些微妙但重要的变化。6.1 角色分工的调整传统团队里工程师的核心能力是写代码。AI Native 团队里工程师的核心能力变成三样任务定义能力、上下文维护能力、验证设计能力。任务定义能力就是前面讲的把模糊需求变成可执行规格的能力。这个能力强的工程师能让 Agent 产出高质量结果这个能力弱的Agent 就是添乱。上下文维护能力就是持续迭代上下文文件、让 Agent 越来越懂项目的能力。这是个长期活儿需要有人专门负责。验证设计能力就是设计自动化验证、让 Agent 能自主闭环的能力。这个能力决定了 Agent 的自主程度。这三样能力传统工程师不一定具备。所以团队转型时培训的重点不是怎么用 AI 工具而是这三样能力。6.2 代码评审的变化Agent 生成的代码评审重点和人工写的代码不太一样。人工写的代码评审重点是逻辑对不对、设计好不好。Agent 生成的代码逻辑和设计通常不会太离谱因为上下文和任务定义约束了评审重点变成有没有理解偏、有没有过度实现、有没有引入不必要的复杂度。我评审 Agent 代码时会特别关注三个点有没有做任务没要求的事。Agent 有时候会热心地顺手改点别的这些改动往往是问题源头。有没有引入不必要的抽象。Agent 倾向于过度设计一个简单功能搞出三层抽象。测试是不是真的在测行为。Agent 有时候会写为了通过而通过的测试断言很弱。6.3 知识沉淀的方式变了传统团队的知识沉淀靠文档和口口相传。AI Native 团队的知识沉淀很大一部分沉淀在上下文文件和任务模板里。每次 Agent 犯错就往上下文文件加一条规则每次任务定义得好就把它存成模板。这些沉淀是活的、可执行的比静态文档有用得多。我现在的习惯是每周花半小时回顾这周 Agent 犯的错把共性问题提炼成上下文规则。这个习惯坚持几个月后Agent 的低级错误率会降到很低。7. 落地路线从零到一的三阶段推进讲了这么多原理最后给一条可落地的路线。我建议分三个阶段推进每个阶段 2 到 4 周。7.1 第一阶段单点验证选一个中等复杂度的模块让一两个工程师用 Agent 完整走一遍流程。目标是验证这套方法在你们项目里行不行得通。这个阶段的产出一份初版上下文文件、几个任务模板、一套验证脚本。不要追求完美先跑通。7.2 第二阶段小范围推广选 3 到 5 个工程师在 2 到 3 个模块上推广。目标是打磨上下文文件和任务模板形成团队可复用的资产。这个阶段的产出稳定的上下文文件、成熟的验证流程、几个成功案例。同时要收集问题看看哪些地方 Agent 表现不好是上下文问题还是任务定义问题。7.3 第三阶段全面铺开全员推广同时建立配套机制上下文文件的维护责任人、任务模板的迭代机制、Agent 产出的评审规范。这个阶段最容易出问题的是形式主义——大家为了用而用任务定义随便写上下文文件没人维护。要避免这个关键是让团队看到实际收益交付周期缩短了、返工率降低了、工程师从重复劳动里解放出来了。我自己的体会是这套东西的价值不在于用了 AI而在于它强迫团队把很多平时含糊的东西想清楚了需求到底是什么、验收标准是什么、上下文够不够、验证怎么做。这些想清楚了用不用 Agent 效率都会提升用上 Agent提升会更大。最后分享一个我踩过的坑不要一开始就追求全自动。我早期试图让 Agent 端到端完成整个需求结果在需求理解、方案设计这些环节反复跑偏浪费了大量时间。后来退回到人定义、Agent 执行、人验收的模式反而稳定了。自动化程度是随着上下文质量和验证能力提升而自然提高的急不来。
