1. 从“人写代码”到“人管意图”AI Native 团队到底在改什么先说一个我观察到的现象。很多团队嘴上喊着“我们要做 AI Native”实际干的事只是给每个人发了个 AI 编程助手的账号然后继续用原来的方式拆需求、写文档、排期、Code Review。结果呢效率提升了个位数百分比大家还觉得“AI 也就那样”。问题出在哪出在把 AI 当工具而不是把 AI 当“团队成员”。传统软件开发生命周期SDLC的底层假设是人是唯一的执行主体工具只是辅助。所以流程设计围绕“人怎么协作”展开——需求评审会、设计文档、任务拆分、代码评审、测试用例、发布检查单。而 AI Native 的底层假设变了AI 是执行主体之一人的角色从“生产者”变成“意图定义者与质量守门人”。这个转变听起来简单落地时几乎每个环节都要重新设计。我见过最典型的翻车场景是这样的团队引入 AI 编码助手后让 AI 直接根据一句话需求生成整个模块。结果 AI 产出的代码结构混乱、命名随意、边界条件缺失Review 的人花的时间比手写还多。根因不是模型不行而是没有给 AI 建立“上下文契约”——它不知道这个项目的架构约定、命名规范、错误处理模式、依赖边界。你让它自由发挥它就只能给你一个“能跑但没法维护”的东西。所以 AI Native 团队开发落地手册的核心不是教你用哪个模型、哪个插件而是回答三个问题意图如何被结构化地传递给 AIPlan Mode、CLAUDE.md、Skill 定义AI 的执行如何被约束和验证Agent 沙盒、Harness、测试门禁多个 AI 与多个人如何编排协作多 Agent 分工、任务路由、记忆管理这三个问题贯穿整个 SDLC。下面我按实际落地顺序把每个环节拆开讲。2. 意图层CLAUDE.md 与 Plan Mode 如何把“一句话需求”变成可执行契约2.1 为什么“提示词工程”在团队协作里基本失效个人用 AI 写代码提示词写得好确实能出活。但团队协作场景下提示词工程有个致命问题它不可复用、不可审计、不可传承。张三今天写了一段精妙的提示词让 AI 生成了正确的模块明天李四接手他不知道张三当时是怎么“哄”AI 的只能重新试。这跟“代码没有注释、没有文档”是一样的病。AI Native 团队的解法是把“提示词”升级为“契约文件”。契约文件是版本化的、进代码仓库的、所有人共享的。它不描述“怎么问 AI”而是描述“这个项目的规则是什么”。AI 每次执行任务前先读契约再干活。2.2 CLAUDE.md 的本质给 AI 的项目宪法CLAUDE.md 这类文件不同工具叫法不同有的叫 rules 文件、有的叫 context 文件的核心作用是把隐性的团队约定显性化。我建议至少包含以下几块内容# 项目契约 ## 技术栈与版本 - 语言TypeScript 5.x严格模式 - 框架Next.js 14 App Router - 数据库PostgreSQL Prisma - 测试Vitest Playwright ## 目录结构约定 - src/app/ 路由与页面 - src/lib/ 纯函数与工具 - src/server/ 服务端逻辑禁止被客户端直接引用 - src/components/ UI 组件必须有 Storybook 用例 ## 编码规范 - 禁止 any必要时用 unknown 类型守卫 - 所有异步函数必须处理错误禁止裸 await - 命名文件名 kebab-case组件 PascalCase常量 UPPER_SNAKE ## 禁止事项 - 禁止引入新的第三方依赖除非在 PR 描述中说明理由 - 禁止在组件内直接调用数据库 - 禁止提交 console.log ## 验证命令 - 类型检查pnpm typecheck - 单测pnpm test - 构建pnpm build这份文件看起来平平无奇但它是 AI 能否产出“可合并代码”的分水岭。我实测过一个对比同一个需求没有契约文件时 AI 产出的代码需要人工修改约 40% 的内容有了契约文件后修改量降到 10% 以内。差距主要来自命名、错误处理、目录归属这些“约定类”问题。注意契约文件不是写一次就完事。每次 Code Review 发现 AI 反复犯同一类错误就应该把这条规则补进契约。它应该像代码一样持续演进。2.3 Plan Mode先让 AI 交方案再让它写代码Plan Mode有的工具叫“规划模式”“思考模式”是我认为 AI Native 流程里最被低估的环节。它的逻辑很简单在 AI 动手写代码之前强制它先输出一份执行计划包括要改哪些文件、每个文件改什么、依赖关系是什么、风险点在哪。为什么这一步关键因为 AI 直接写代码时一旦方向错了你要读几百行代码才能发现。而读一份 20 行的计划10 秒就能判断方向对不对。这是把纠错成本从“代码级”前移到“意图级”。我通常这样用 Plan Mode把需求描述 相关文件路径 契约文件一起给 AI要求它输出改动清单、每个改动的理由、潜在影响范围、需要新增的测试人工审核计划确认或修正确认后再让 AI 按计划执行这里有个实操技巧计划里要求 AI 标注“不确定项”。比如“我不确定这个函数是否被其他地方调用需要确认”。这些不确定项往往就是隐藏的坑人工重点看这几条效率最高。2.4 Skill 定义把重复性任务封装成可调用单元Agent Skill 这个概念最近很热但很多人理解偏了。Skill 不是“更复杂的提示词”而是把一类任务的完整执行逻辑封装起来让 AI 可以按需调用。举个例子团队经常需要“把某个网页内容整理成 Markdown 存进知识库”。这件事如果每次都用自然语言描述AI 每次执行方式都不一样。但如果封装成一个 Skill# Skill: web-to-markdown ## 触发条件 用户要求将网页内容保存为 Markdown 时 ## 执行步骤 1. 获取目标 URL 内容 2. 提取正文去除导航、广告、页脚 3. 保留标题层级、代码块、表格 4. 图片转为占位符并记录原始链接 5. 输出到指定目录文件名用页面标题的 kebab-case ## 输出格式 标准 Markdown首行是 H1 标题 ## 禁止事项 - 禁止编造原文没有的内容 - 禁止修改代码块内的代码Skill 的价值在于一致性。同一个 Skill 被调用一百次产出一百次结构相同的结果。这对团队协作至关重要——下游处理这些 Markdown 的人不需要每次猜格式。3. 执行层Agent 沙盒、Harness 与并发扛压的真实边界3.1 Agent 沙盒不是“安全措施”是“执行环境”很多人把 Agent 沙盒理解成安全隔离这只是一半。沙盒更重要的作用是给 AI 一个可预测、可重置、可并行的执行环境。我踩过的一个坑早期让 AI 直接在开发机上执行命令结果它装了一堆全局依赖改了系统配置还把某个服务的端口占了。排查了半天才发现是 AI 干的。后来改成沙盒方案——每个 Agent 任务在独立的容器里跑有独立的文件系统、独立的依赖、独立的网络策略。任务结束容器销毁不留痕迹。沙盒的关键配置项配置项建议值理由文件系统只挂载项目目录只读挂载系统目录防止 AI 改坏系统文件网络默认关闭按需白名单防止 AI 拉取不可信依赖资源限制CPU 2 核、内存 4G、超时 10 分钟防止单个任务拖垮整机快照任务前打快照失败可回滚出问题不用手动清理提示沙盒里要预装项目所需的运行时和依赖。如果每次任务都从头装依赖光装包就耗掉一半时间。我的做法是做一个基础镜像把不常变的依赖层固化进去。3.2 Harness 和 Agent 的区别一个管“怎么跑”一个管“跑什么”这两个词经常被混用我按自己的理解给个区分Agent是“执行者”它理解任务、做决策、调用工具、产出结果。它关心的是“这个任务怎么完成”。Harness是“执行框架/脚手架”它负责给 Agent 提供运行环境、注入上下文、管理生命周期、收集结果、处理异常。它关心的是“Agent 怎么被可靠地跑起来”。打个比方Agent 是司机Harness 是车 调度系统。司机决定怎么开车和调度系统决定司机能不能安全、高效、可监控地把车开出去。一个成熟的 Harness 至少要做这几件事上下文注入把契约文件、相关代码、历史对话按需喂给 Agent工具注册告诉 Agent 它能用哪些工具读文件、写文件、执行命令、调 API生命周期管理启动、超时、重试、终止、清理结果收集把 Agent 的产出结构化地返回给上层可观测性记录每一步的输入输出方便排查很多团队自己写 Harness写着写着就写成了一个“任务队列 容器管理 日志系统”。这没错但要注意别过度工程化。初期用现成的 Agent 框架 简单的脚本编排就够了等流程跑顺了再抽象。3.3 AI Agent 怎么扛并发不是加机器那么简单“AI Agent 怎么扛并发”是个高频问题。我的经验是并发瓶颈通常不在模型调用而在上下文管理和状态同步。模型调用本身可以水平扩展加 API 配额就行。真正难的是多个 Agent 同时改同一个代码仓库怎么避免冲突多个 Agent 共享一份记忆/知识库怎么保证读到的是最新版本一个任务依赖另一个任务的产出怎么编排依赖关系我的实践方案是分三层处理第一层任务隔离。每个 Agent 任务在独立的 Git 分支或独立的 worktree 里操作。任务完成后通过 PR 合并冲突在合并时解决。这样 Agent 之间不需要实时同步各自干活就行。第二层状态外置。Agent 的中间状态比如“我已经读了哪些文件”“我做了哪些决策”不放在 Agent 内存里而是写到外部存储Redis、数据库、文件。这样 Agent 崩溃重启后能恢复也方便多个 Agent 共享。第三层依赖编排。用 DAG有向无环图描述任务依赖。A 任务完成后触发 B 任务B 和 C 可以并行。编排层负责调度和重试。这块可以用现成的工作流引擎也可以自己写个简单的调度器。实测下来一个中等规模的团队10 人左右用这套方案可以同时跑 20-30 个 Agent 任务而不混乱。再往上就要考虑更细粒度的资源隔离和优先级调度了。3.4 Agent 安全不是防黑客是防“好心办坏事”Agent 安全这个话题容易被带偏到“防恶意攻击”。但在团队内部使用场景下更大的风险是Agent 在正常执行任务时造成的意外破坏。我遇到过的真实案例Agent 为了“清理无用文件”删掉了一个它认为没用的目录结果那是测试数据Agent 为了“修复构建错误”改了一个它不该改的配置文件导致其他环境出问题Agent 为了“优化性能”把一个有副作用的函数改成了纯函数逻辑错了这些都不是恶意攻击是 Agent 在“努力完成任务”时越界了。防范措施最小权限Agent 只能访问完成任务必需的文件和工具危险操作二次确认删除、覆盖、执行系统命令等操作要求人工确认变更审计Agent 的每一次文件修改都记录 diff可追溯回滚机制任何 Agent 的产出都可以一键回滚注意不要指望通过提示词让 Agent“不要做危险操作”。提示词是软约束权限和沙盒是硬约束。安全要靠硬约束。4. 协作层多 Agent 分工与记忆管理的落地细节4.1 什么时候该用多 Agent什么时候不该多 Agent 不是越多越好。我见过一个团队搞了七八个 Agent 互相协作结果调试成本比收益还高。判断标准很简单如果一个任务能被清晰地拆成几个独立子任务且子任务之间接口明确那就适合多 Agent。如果子任务之间需要频繁来回沟通那单 Agent 反而更高效。适合多 Agent 的场景一个负责写代码一个负责写测试一个负责 Review一个负责前端一个负责后端接口提前约定好一个负责实现一个负责文档不适合多 Agent 的场景需要反复讨论才能确定方案的设计任务强依赖上下文连续性的调试任务需求本身还很模糊的探索性任务4.2 Agent 记忆短期、长期、共享三层Agent 记忆是另一个高频话题。我把它分成三层短期记忆当前任务的对话历史。这个由 Harness 管理任务结束就丢弃。关键是控制长度太长会拖慢推理、增加成本。我的做法是超过一定轮次后做摘要压缩。长期记忆跨任务的知识积累。比如“这个项目的某个模块历史上出过什么 bug”“某个 API 的调用注意事项”。这些存在外部知识库里Agent 按需检索。共享记忆多个 Agent 之间共享的状态。比如“当前代码仓库的最新 commit”“某个任务的最新产出”。这层要特别注意一致性避免 Agent A 读到的是旧版本。实操中长期记忆和共享记忆最容易出问题。我的建议是长期记忆用向量检索 结构化标签共享记忆用版本号 乐观锁。别搞太复杂先跑起来再优化。4.3 多 Agent 协作的接口设计多 Agent 协作的核心是接口设计。每个 Agent 的输入输出要定义清楚就像微服务之间的 API 一样。一个典型的接口定义agent: code-writer input: task_description: string target_files: list[string] contract_file: string output: changed_files: list[{path, diff}] test_results: {passed, failed, errors} notes: string constraints: max_files_changed: 10 must_pass_typecheck: true有了这样的接口定义Agent 之间就可以像搭积木一样组合。上游 Agent 的 output 直接作为下游 Agent 的 input中间不需要人工干预。4.4 人在多 Agent 流程中的位置AI Native 不等于“人不管了”。人的位置从“执行者”变成了“意图定义者 质量守门人 异常处理者”。具体来说人要做这几件事定义意图把模糊需求转化为清晰的、AI 可执行的契约审核计划在 Plan Mode 阶段确认方向守门质量Review AI 的产出决定是否合并处理异常AI 搞不定的问题人来兜底优化契约把反复出现的问题沉淀成规则我观察到的高效团队人的时间分配大概是30% 定义意图和契约20% 审核计划30% Review 产出20% 处理异常和优化流程。写代码的时间反而很少了。5. 落地路线图从单点试用到全流程 AI Native 的四步走5.1 第一步单点验证选一个低风险模块别一上来就全流程改造。选一个低风险、边界清晰的模块先试。比如一个内部工具、一个独立的小服务。目标是跑通“契约文件 Plan Mode 沙盒执行 人工 Review”这个最小闭环。这个阶段的关键是建立信心和手感。让团队看到 AI 确实能产出可用的东西同时暴露流程中的问题。5.2 第二步沉淀契约把踩过的坑变成规则第一个模块跑完后一定会积累一堆“AI 又犯了这个错”的案例。把这些案例整理成契约规则。这个过程本身就是团队对“什么是好代码”的重新梳理。我建议每周花半小时做一次“契约回顾”这周 AI 犯了哪些错哪些可以变成规则哪些需要人工介入5.3 第三步扩展场景从编码扩展到测试、文档、运维编码跑通后把同样的模式复制到其他环节测试AI 根据代码生成测试用例人工审核覆盖度文档AI 根据代码变更自动更新文档运维AI 分析日志、定位问题、生成修复建议每个环节的契约文件不同但方法论是一样的。5.4 第四步编排多 Agent形成流水线当单个环节都跑顺了开始编排。比如需求 Agent 产出任务描述 → 编码 Agent 实现 → 测试 Agent 验证 → Review Agent 检查 → 人工终审。这个阶段最大的挑战是异常处理。流水线跑通容易跑稳难。要设计好每个环节失败后的重试、回滚、人工介入机制。6. 那些没人告诉你但一定会踩的坑6.1 模型不是越强越好匹配任务最重要我试过用最强的模型做所有事结果成本高、速度慢很多简单任务根本不需要那么强的模型。后来改成按任务复杂度路由简单任务用轻量模型复杂任务用强模型。成本降了一半速度还快了。6.2 上下文不是越多越好精准比全面重要早期我恨不得把整个代码仓库都塞给 AI结果它反而抓不住重点。后来改成按需检索根据任务描述只喂相关的文件片段。效果反而更好。6.3 Agent 的“自信”是最大的风险AI 会用非常自信的语气说出错误的东西。所以任何 AI 的产出尤其是涉及事实、数据、API 用法的都要验证。我的习惯是AI 说的每一句“这个函数是这样用的”我都要去源码里确认一遍。6.4 别指望 AI 理解“潜规则”团队里有很多没写下来的约定比如“这个模块虽然叫 utils 但其实是核心逻辑不能随便改”“这个接口虽然文档说废弃了但还有人在用”。这些潜规则 AI 不知道必须显性化到契约文件里。6.5 流程改造的阻力主要来自人不是技术技术方案再完美如果团队成员不习惯新流程也推不动。我的经验是先让一两个人用起来产出可见的成果再逐步推广。别搞强制推行会反弹。7. 我个人的几条实操心得第一契约文件要短。我见过有人写了 500 行的契约文件AI 根本读不完读了也记不住。核心规则控制在 100 行以内细节放到子文件里按需加载。第二Plan Mode 的计划要可执行。不要接受“我会优化这个模块”这种模糊计划。要求 AI 具体到“改哪个文件的哪个函数改成什么样”。第三沙盒要快。如果启动沙盒要等两分钟没人愿意用。我的目标是沙盒启动在 10 秒内这需要提前做好镜像和缓存。第四Review 要聚焦。AI 产出的代码重点看逻辑正确性和边界条件格式和命名问题让自动化工具去管。第五保留人工兜底通道。再好的流程也会有 AI 搞不定的情况。要有一个清晰的“转人工”机制别让任务卡死。第六度量要真实。别只看“AI 生成了多少代码”要看“合并了多少代码”“返工率多少”“Review 时间变化”。这些才是真实收益。这套东西我前后折腾了大半年中间推翻重来了好几次。现在回头看最大的体会是AI Native 不是把 AI 塞进旧流程而是围绕 AI 的能力边界重新设计流程。哪些事 AI 擅长、哪些事 AI 容易出错、哪些事必须人来把关想清楚这些流程自然就出来了。技术选型反而是最后一步用哪个框架、哪个模型都是可以替换的。