1. 从“人写代码”到“人管意图”AI Native 团队到底在做什么这两年“AI Native”这个词被喊得震天响但真正落到一个研发团队里它到底改变了什么我自己的体感是变化不在于“用不用 AI 写代码”而在于整个软件开发生命周期SDLC的骨架被重新排列了。传统 SDLC 是需求、设计、编码、测试、部署、运维一条线人负责每一个环节的产出AI Native 的 SDLC 里人负责的是“定义意图、约束边界、验收结果”中间大量的执行动作交给 Agent 去跑。我带的团队从去年开始做这套转型踩了不少坑也沉淀出一套能跑通的落地手册。这篇就把我们实际在用的东西完整拆开讲CLAUDE.md 这类上下文契约文件怎么写、Plan Mode 怎么用、Agent 怎么编排、并发怎么扛、记忆怎么存、安全边界怎么划。适合两类人看一类是正在推动团队往 AI Native 转的技术负责人另一类是想搞清楚“Agent 到底怎么落地到真实项目里”的一线开发。不管你现在是纯手工开发还是已经半自动化这里面的东西都能直接抄。先说一个最容易被误解的点AI Native 不等于“让 AI 帮你补全代码”。补全代码只是最浅的一层真正的 AI Native 团队是把 Agent 当成一个有记忆、有工具、有边界、可编排的“虚拟同事”来用。它要能读你的项目规范、能进沙盒跑命令、能自己规划任务、能在失败后重试最后把结果交回给人验收。这套东西跑起来之后团队的产出节奏和协作方式会发生质变。2. AI Native SDLC 的整体设计与思路拆解2.1 为什么传统 SDLC 在 Agent 时代会“卡壳”传统 SDLC 的假设是执行者是人人的上下文是连续的。一个开发看了需求文档脑子里就记住了约束写代码时自然遵守。但 Agent 没有这种“连续记忆”它每次执行都是一次相对独立的推理你不在上下文里明确告诉它“这个项目用 pnpm 不用 npm”“测试必须跑 vitest 不用 jest”它就可能按训练数据里的默认习惯来。这就是为什么很多团队一开始让 Agent 写代码结果生成的东西“看着对但跑不起来”——不是模型不行是上下文契约缺失。传统 SDLC 里那些“约定俗成”的东西在 Agent 面前必须显式化、文件化、可检索化。CLAUDE.md 这类文件本质上就是干这个的把团队的隐性规范变成 Agent 每次都能读到的显性契约。另一个卡壳点是验收环节。人写代码review 的时候看逻辑就行Agent 写代码你得看它有没有偷偷改依赖、有没有绕过测试、有没有在沙盒里执行危险命令。所以 AI Native SDLC 必须把“可观测性”和“边界控制”前置而不是等出事再补。2.2 我们最终选定的四层架构试过几种方案之后我们稳定在这样一套四层结构上契约层CLAUDE.md、AGENTS.md、项目级 rules 文件负责把规范、技术栈、禁忌、验收标准写清楚。规划层Plan Mode让 Agent 先出计划再动手人审计划而不是审代码。执行层Agent 工具文件读写、终端、浏览器、检索在沙盒里跑。记忆层working memory当前任务上下文 长期记忆项目知识库、历史决策。这四层里契约层是最容易被低估但收益最大的。我们内部做过对比同一个任务没有 CLAUDE.md 的 Agent 平均要 3 轮返工有清晰契约的平均 1.2 轮就能过。原因很简单Agent 不用猜了。2.3 方案选型背后的取舍逻辑有人会问为什么不直接用一个全能 Agent 框架非要自己搭这套我的经验是通用框架解决的是“能不能跑”团队落地解决的是“跑得稳不稳、可不可控”。我们评估过市面上的 Agent 框架和编排平台最后的选择逻辑是这样的维度通用框架自建契约编排我们的选择上手速度快慢前期慢后期快可控性低高自建团队规范沉淀难易自建并发与隔离依赖框架自主可控自建迁移成本高绑定框架低自建核心判断是Agent 框架会变但团队的规范契约和验收标准是长期资产。把资产绑在框架上框架一换全白干。所以我们把契约层和记忆层做成框架无关的纯文件执行层才对接具体框架。3. 核心细节解析契约、规划、执行、记忆怎么落地3.1 CLAUDE.md 到底该写什么不该写什么CLAUDE.md 是 Anthropic 系工具链里约定俗成的项目上下文文件但它的价值不限于某个工具。我们把它当成**“Agent 进项目前必读的入职手册”**。写得好不好直接决定 Agent 的输出质量。我见过太多团队把 CLAUDE.md 写成 README 的复制粘贴这是浪费。它应该只写Agent 会犯错、且必须纠正的东西。我们内部模板大致分这几块# 项目上下文 ## 技术栈强制 - 包管理器pnpm禁止 npm/yarn - 测试框架vitest禁止 jest - 语言TypeScript strict 模式 - Node 版本20.x ## 目录约定 - 业务代码src/ - 测试src/**/*.test.ts - 禁止在根目录创建临时文件 ## 编码禁忌 - 禁止 any用 unknown 类型守卫 - 禁止 console.log用 logger - 禁止直接改 package.json 依赖版本 ## 验收标准 - 提交前必须 pnpm test 全绿 - 必须 pnpm lint 无 error - 新增函数必须有对应测试 ## 常用命令 - 开发pnpm dev - 测试pnpm test - 构建pnpm build关键心得禁忌部分比规范部分更重要。Agent 天然倾向于“多做”你不明确禁止它就会自作主张装依赖、改配置、加 console。把禁忌写死能省掉大量返工。注意CLAUDE.md 不要写太长。超过 200 行Agent 的注意力会被稀释关键约束反而被忽略。我们控制在 80-120 行超出的内容拆到子目录的 rules 文件里按需加载。3.2 Plan Mode先审计划再审代码Plan Mode 是我认为 AI Native 团队最该养成的习惯。它的逻辑很简单让 Agent 先输出一份执行计划人确认后再动手。听起来多了一步实际上省了大量返工。为什么有效因为 Agent 最容易犯的错不是“代码写错”而是“方向跑偏”。比如你让它“优化登录接口”它可能直接去重构整个认证模块。等它写完你才发现方向错了返工成本极高。但如果先出计划你一眼就能看出“它理解错了”改计划比改代码便宜得多。我们的 Plan Mode 实操流程人给出任务描述明确目标和边界。Agent 输出计划要改哪些文件、分几步、每步验证方式。人审计划重点看范围是否越界、验证是否充分。确认后 Agent 执行每完成一步汇报。人验收结果不通过则回到计划调整。提示Plan Mode 的计划里必须包含“验证方式”。如果 Agent 的计划里没有“怎么证明这步做对了”直接打回。这是防止它“假装完成”的关键。3.3 Agent 执行沙盒为什么必须隔离Agent 执行层最大的风险是它真的会执行命令。我们早期就出过一次事故Agent 为了“清理临时文件”执行了一条删除命令把不该删的东西删了。从那以后所有 Agent 执行一律进沙盒。沙盒的核心要求文件系统隔离Agent 只能访问项目目录不能碰系统目录。网络受限默认禁止外网访问需要时白名单放行。命令白名单只允许预定义的安全命令危险命令直接拦截。资源限制CPU、内存、执行时长都有上限防止跑飞。我们用容器做隔离每个 Agent 任务起一个独立容器任务结束即销毁。这样即使 Agent 行为异常影响范围也被限制在容器内。3.4 记忆层working memory 和长期记忆怎么分工Agent 的“记忆”分两种混在一起用会出问题working memory当前任务的上下文任务结束就清空。比如“我正在改哪个文件、上一步做了什么”。长期记忆跨任务的知识比如“这个项目历史上为什么选了某个方案”。我们的做法是working memory 放在 Agent 的上下文窗口里长期记忆放在项目内的docs/decisions/目录用 Markdown 记录关键决策。Agent 需要时通过检索工具去查而不是全塞进上下文。这样做的理由上下文窗口是稀缺资源。把长期记忆全塞进去会挤占当前任务的推理空间反而让 Agent 变笨。按需检索才是正解。4. 实操过程从零搭一个能跑的 AI Native 工作流4.1 第一步把项目规范文件化这是所有工作的起点。具体操作在项目根目录创建CLAUDE.md按 3.1 的模板填。在.agent/rules/下按模块拆分细则比如frontend.md、backend.md。在docs/decisions/下建决策记录每条决策写清楚“背景、选项、选择、理由”。这一步的验收标准新来的 Agent 只读这些文件就能知道项目该怎么写代码。你可以拿一个真实任务测试看 Agent 是否还会犯“用错包管理器”这类低级错误。4.2 第二步配置 Plan Mode 工作流Plan Mode 不是某个工具的专属功能而是一种协作约定。我们把它固化成流程# 伪代码示意实际用你团队的工具链 agent plan --task 给用户列表加分页 --context CLAUDE.md # Agent 输出计划人审 agent execute --plan plan-001 --sandbox container # 每步执行后汇报 agent status --plan plan-001关键参数说明--context指定契约文件确保 Agent 读到规范。--sandbox指定隔离环境必填。--max-steps限制最大步数防止 Agent 无限循环。注意--max-steps一定要设。我们遇到过 Agent 陷入“改-测-失败-再改”的死循环跑了 40 多步还没收敛。设个上限超了就人工介入。4.3 第三步搭执行沙盒容器化沙盒的最小配置FROM node:20-slim WORKDIR /workspace # 只挂载项目目录 VOLUME [/workspace] # 非 root 用户运行 USER node # 限制资源 # docker run 时加 --memory2g --cpus2 --networknone启动命令docker run --rm \ --memory2g \ --cpus2 \ --networknone \ -v $(pwd):/workspace \ agent-sandbox:latest参数解释--memory2g内存上限防止 Agent 跑飞吃满宿主机。--cpus2CPU 上限保证宿主机其他任务不受影响。--networknone默认断网需要联网时再单独放行。--rm任务结束自动销毁不留残留。4.4 第四步接入记忆检索长期记忆用简单的文件检索就够不必上向量数据库。我们的做法# 检索决策记录 def search_decisions(query): results [] for f in Path(docs/decisions).glob(*.md): content f.read_text() if query.lower() in content.lower(): results.append({file: str(f), content: content}) return results为什么不上向量库因为项目决策记录通常就几十条关键词检索足够。上向量库反而增加维护成本和不确定性。等记录超过几百条再考虑升级。4.5 第五步跑通一个完整任务拿“给用户列表加分页”举例完整流程人写任务描述附上 CLAUDE.md 路径。Agent 出计划改UserList.tsx、加usePaginationhook、补测试。人审计划确认范围没越界。Agent 在沙盒执行每步汇报。执行完跑pnpm test全绿。人验收合并。整个过程人只做了两件事审计划、验收。中间执行全交给 Agent。这就是 AI Native 的节奏。5. 常见问题与排查技巧实录5.1 Agent 跑飞了怎么办现象Agent 执行步数暴涨或者开始改不该改的文件。排查思路先看--max-steps有没有设没设立刻停。看 Agent 的 working memory判断它是不是“理解偏了”。检查 CLAUDE.md 的禁忌部分是否覆盖了当前场景。解决停掉任务补充契约文件里的禁忌重新跑。我们内部统计80% 的跑飞都是契约缺失导致的。5.2 Agent 说“完成了”但实际没完成现象Agent 汇报任务完成但测试没过或功能缺失。根因Agent 的“完成”定义和人的不一样。它可能觉得“代码写了”就是完成不管测试。解决在 CLAUDE.md 的验收标准里写死“必须测试全绿才算完成”。并且在 Plan Mode 的计划里强制要求每步有验证方式。5.3 并发任务互相干扰现象多个 Agent 同时跑改了同一个文件冲突。解决任务分配时做文件级锁。我们的做法是维护一个任务-文件映射表同一文件同一时间只允许一个 Agent 改。跨文件的任务可以并行同文件的任务串行。问题根因解决跑飞契约缺失补禁忌设 max-steps假完成验收标准模糊写死测试要求并发冲突无文件锁任务-文件映射记忆混乱working/长期混用分离按需检索沙盒逃逸隔离不足容器 非 root 断网5.4 独家避坑技巧契约文件要版本化CLAUDE.md 改动要进 git这样能追溯“哪次改动导致了 Agent 行为变化”。Plan Mode 的计划要存档好的计划可以复用下次类似任务直接调出来改。沙盒镜像要固定版本别用 latest用具体 tag保证行为可复现。定期清理长期记忆过时的决策记录要标记废弃否则 Agent 会参考旧决策。6. 团队协作与规模化从一个人用到一群人用6.1 角色怎么重新划分AI Native 团队里角色会发生迁移原开发从“写代码”转向“写契约 审计划 验收”。原测试从“写用例”转向“定义验收标准 设计验证流程”。原架构从“画图”转向“设计 Agent 编排 边界控制”。这不是裁员是能力重心转移。我们团队转型后人均产出提升了但要求每个人都能清晰表达“我要什么”和“怎么算做对了”。6.2 规模化时的编排策略单 Agent 跑单任务简单多 Agent 跑多任务就复杂了。我们的编排策略任务分解大任务拆成独立子任务每个子任务一个 Agent。依赖管理有依赖的子任务串行无依赖的并行。结果汇总所有子任务完成后一个汇总 Agent 做集成验证。编排的核心是依赖图。我们用一个简单的 DAG 描述任务依赖编排器按拓扑序调度。6.3 评测与持续改进Agent 的输出质量要可度量。我们的评测维度一次通过率任务一次验收通过的比例。返工轮次平均返工几次。契约命中率Agent 犯错时是否是因为契约没覆盖。每周复盘这些指标针对性补契约。契约越完善一次通过率越高这是正循环。7. 安全边界Agent 能做什么绝对不能做什么7.1 权限最小化原则Agent 的权限按“最小必要”给只读项目目录不碰系统目录。默认断网需要时白名单。命令白名单危险命令拦截。敏感操作如删除、发布必须人工确认。7.2 审计与可追溯每个 Agent 任务都要留痕任务描述、计划、执行日志、结果全部存档。关键操作改文件、跑命令记录时间戳和操作者。出问题能回溯到具体哪一步。7.3 人工兜底再完善的自动化也要有人工兜底。我们的原则Agent 可以提议但关键决策必须人拍板。比如发布上线、改数据库 schema、动生产配置一律人工确认。8. 我踩过的坑和现在的日常说几个真实的坑。第一个是过早追求全自动。我们一开始想让 Agent 从需求到上线全包结果发现中间任何一环出错都会连锁反应。后来改成“人在关键节点介入”反而更稳。第二个是契约文件写太细。有段时间 CLAUDE.md 写到 300 多行Agent 反而抓不住重点后来砍到 100 行以内效果立竿见影。第三个是忽视沙盒。早期图省事直接在宿主机跑出过一次误删事故之后所有执行一律进容器再没出过事。现在的日常是这样的早上人写任务描述和验收标准Agent 跑计划人审完放行Agent 执行人验收。一天下来人能同时推进的任务数量翻了几倍但脑子反而更轻松因为不用再纠结“这行代码怎么写”只需要想清楚“我要什么”。如果让我给刚起步的团队一个建议别一上来就搞复杂编排先把 CLAUDE.md 写好把 Plan Mode 用起来把沙盒搭起来。这三件事做完你就已经比 80% 的团队更 AI Native 了。剩下的编排、并发、记忆都是在这三件事基础上的自然延伸。