1. 从AI辅助到AI原生团队开发范式的分水岭大多数团队对AI的使用还停留在辅助层面——写代码时开个补全插件写文档时让模型润色一下测试时用AI生成几条用例。这种模式的天花板很明显AI始终是一个外挂工具人还是流程的中心所有上下文靠人脑传递所有决策靠人拍板。而AI Native的核心区别在于AI不再是工具而是团队的一等公民——它有自己的工作空间、自己的上下文文件、自己的任务队列甚至自己的记忆。这个转变听起来抽象落到工程上其实非常具体。传统SDLC里需求从产品经理传到开发开发传到测试测试传到运维每一环都有信息损耗。AI Native SDLC要做的事情是把这条链路上所有可结构化的上下文沉淀成AI能直接读取和执行的资产。CLAUDE.md这类文件就是典型代表——它不是给人看的文档而是给Agent看的项目宪法里面写清楚了这个仓库的技术栈、目录约定、代码风格、禁止事项、常用命令。Agent每次启动都会先读它相当于新员工入职先看员工手册。我见过太多团队在这一步走偏把CLAUDE.md写成给领导汇报的PPT堆满了赋能闭环抓手这类词结果Agent读完一脸懵该干嘛还是干嘛。正确的做法是把它当成一份给一个聪明但完全不了解你项目的工程师看的交接文档——具体、可执行、有边界。比如不要写遵循良好的代码规范而要写所有新函数必须带类型注解Python用mypy检查提交前跑make lint。Plan Mode是另一个容易被低估的机制。很多人觉得让AI先出计划再执行是浪费时间直接让它干活不香吗实测下来恰恰相反。在Plan Mode下Agent会先把任务拆解成步骤、列出要改的文件、说明每步的意图人确认后再执行。这个确认环节省下的返工时间远超多花的那几十秒。尤其是涉及多文件改动的重构任务没有Plan Mode的Agent就像没有图纸就开工的装修队干到一半发现水电走错了拆了重来。Agent这个概念在AI Native语境下和传统的脚本有本质区别。脚本是确定性的输入A必然输出BAgent是有自主决策能力的它会根据环境反馈调整策略。这就引出了一个关键问题如何给Agent划定安全边界。一个能自主执行命令、读写文件、调用API的Agent如果边界没划好轻则改错文件重则删库跑路。所以Agent沙箱、权限控制、操作审计这些机制在AI Native团队里不是可选项而是基础设施。2. CLAUDE.md的写法决定了Agent的上限2.1 为什么这个文件比你想的重要CLAUDE.md以及类似的AGENTS.md、.cursorrules等本质上是Agent的持久化上下文。Agent的上下文窗口是有限的每次对话能塞进去的信息就那么多。如果项目约定不沉淀成文件每次都要人在对话里重复交代既浪费token又容易遗漏。更关键的是人会在不同会话里给出不一致的指令导致Agent的行为飘忽不定。我自己的做法是把CLAUDE.md分成几个固定区块项目概览、技术栈与版本、目录结构说明、开发命令、代码规范、测试要求、禁止事项、常见陷阱。每个区块都写具体的、可验证的内容。比如技术栈部分不写使用现代前端框架而写React 18 TypeScript 5.3 Vite 5状态管理用Zustand样式用Tailwind CSS 3.4。2.2 一个可复用的CLAUDE.md骨架下面是我在多个项目里迭代出来的结构你可以直接拿去改# 项目名称 ## 项目概览 一句话说明这个项目是干什么的目标用户是谁。 ## 技术栈 - 语言与版本Python 3.11 - 框架FastAPI 0.110 - 数据库PostgreSQL 16 SQLAlchemy 2.0 - 测试pytest httpx - 包管理uv ## 目录结构 - src/api/路由层只做参数校验和响应组装 - src/services/业务逻辑层所有核心逻辑写在这里 - src/models/SQLAlchemy模型 - tests/测试文件与src结构镜像 ## 常用命令 - 安装依赖uv sync - 启动开发服务uv run uvicorn src.main:app --reload - 跑测试uv run pytest -xvs - 类型检查uv run mypy src/ - 格式化uv run ruff format . ## 代码规范 - 所有函数必须有类型注解 - 禁止在路由层写业务逻辑 - 数据库操作必须通过service层 - 异常统一用自定义的AppError体系 ## 禁止事项 - 不要修改alembic/versions/下的历史迁移文件 - 不要在代码里硬编码密钥用环境变量 - 不要跳过测试直接提交 ## 常见陷阱 - 本地开发连的是docker里的PG端口5433不是5432 - 修改模型后必须生成迁移uv run alembic revision --autogenerate -m 描述这个骨架的关键在于可执行性。Agent读完就知道该跑什么命令、该把代码放哪、什么不能碰。我实测下来有了这份文件Agent首次生成代码的可用率能从大概四成提到七成以上。2.3 维护CLAUDE.md的节奏很多人写完CLAUDE.md就扔那不管了结果项目演进半年文件里写的命令早就失效了。我的习惯是把它纳入代码评审——每次PR如果引入了新的约定、新的命令、新的目录必须同步更新CLAUDE.md。这跟维护README是一个道理但优先级更高因为README是给人看的CLAUDE.md是给Agent看的Agent不会像人一样猜你的意图。还有一个技巧把CLAUDE.md拆成主文件和子目录文件。根目录放全局约定各个子模块目录放该模块特有的说明。Agent在处理某个模块的任务时会优先读取该模块的说明文件这样上下文更聚焦token利用效率更高。3. Plan Mode不是可选项任务拆解的质量决定交付质量3.1 Plan Mode到底在做什么Plan Mode的本质是强制Agent先做任务分解再执行。在没有Plan Mode的情况下你给Agent一个给用户模块加个导出功能的任务它可能直接就开始改代码了改到一半发现需要先加个依赖加完依赖发现数据库要加字段加完字段发现前端要改接口……整个过程像打地鼠改一处崩一处。Plan Mode下Agent会先输出一份计划要改哪些文件、每个文件改什么、按什么顺序改、有没有依赖关系、有没有风险点。人看完这份计划可以提前发现哎这个方案会影响另一个模块或者这个顺序不对应该先改数据库直接在计划阶段纠正而不是等代码写完再返工。3.2 一份好的Plan长什么样我拿一个真实任务举例给一个FastAPI项目加用户头像上传功能。Agent在Plan Mode下输出的计划应该是这样的## 任务计划用户头像上传 ### 步骤1数据库变更 - 修改 src/models/user.py给User模型加 avatar_url 字段String, nullable - 生成迁移文件uv run alembic revision --autogenerate -m add avatar_url to user ### 步骤2存储层 - 新增 src/services/storage.py封装对象存储的上传逻辑 - 需要新增依赖boto3或项目已有的存储SDK - 配置项从环境变量读取 STORAGE_BUCKET、STORAGE_REGION ### 步骤3业务逻辑 - 修改 src/services/user.py新增 update_avatar(user_id, file) 方法 - 校验文件类型只允许jpg/png、大小限制2MB ### 步骤4API层 - 修改 src/api/user.py新增 POST /users/{user_id}/avatar 路由 - 接收multipart/form-data调用service层方法 ### 步骤5测试 - 新增 tests/services/test_storage.py - 新增 tests/api/test_user_avatar.py - 用mock替换真实存储调用 ### 风险点 - 对象存储的凭证管理需要确认现有方案 - 文件大小限制需要和产品确认具体数值这份计划的价值在于它把一个功能拆成了五个可独立验证的步骤每一步都有明确的产出物。人审计划的时候可以快速判断存储方案用现有的还是新引入大小限制合不合理测试覆盖够不够这些问题在计划阶段解决成本是分钟级等代码写完再发现成本是小时级。3.3 什么任务适合Plan Mode不是所有任务都需要Plan Mode。改个typo、调个日志级别直接干就行。我的判断标准是涉及三个以上文件或者涉及数据库/接口/依赖变更的任务必须走Plan Mode。这类任务的共同特点是牵一发动全身计划阶段多花两分钟执行阶段省半小时。还有一个经验Plan Mode下不要一次给太大的任务。你给Agent一个重构整个认证模块的任务它出的计划会非常粗因为细节太多它顾不过来。正确的做法是把大任务切成小任务每个小任务单独走Plan Mode。比如重构认证模块可以切成把session认证换成JWT把密码哈希从bcrypt换成argon2加refresh token机制三个独立任务。4. Agent的边界设计能干什么和不能干什么4.1 Agent沙箱的必要性Agent沙箱这个词听起来很重其实核心就一件事限制Agent能触碰的资源范围。一个没有沙箱的Agent理论上可以读写你机器上的任何文件、执行任何命令、访问任何网络。这在开发环境可能还好在生产环境就是灾难。沙箱的实现层次有好几种。最轻的是文件系统层面的限制比如让Agent只能在一个指定的工作目录里操作出了这个目录就拒绝。中等的是进程层面的限制用容器把Agent跑起来限制它能用的CPU、内存、网络。最重的是权限层面的限制Agent的每个操作都要经过一个策略引擎审批比如读文件可以写文件需要确认执行shell命令需要白名单。我自己的实践是分环境处理本地开发用文件系统限制就够了Agent只能碰项目目录CI环境用容器隔离Agent跑在一次性容器里跑完就销毁生产环境基本不让Agent直接操作只让它生成变更建议由人来执行。4.2 权限白名单的具体设计Agent能执行shell命令这件事风险最大。我的做法是维护一个命令白名单只有白名单里的命令允许直接执行其他命令需要人工确认。白名单大概长这样命令类别允许的命令说明包管理uv,npm,pnpm只允许install/sync/add不允许publish测试pytest,vitest,jest只读操作安全构建make build,vite build只读操作安全格式化ruff,prettier,eslint只读操作安全数据库alembic upgrade,alembic revision需要确认因为会改数据库Gitgit status,git diff,git log只读操作安全Git写操作git commit,git push需要确认危险命令rm,curl,wget,chmod默认禁止这个白名单不是一成不变的随着项目演进会调整。关键是默认拒绝显式允许而不是反过来。4.3 Agent记忆的管理Agent记忆是个双刃剑。好的记忆让Agent越用越懂你的项目坏的记忆让Agent把过时的、错误的经验一直带下去。我的做法是把记忆分成两类项目级记忆和会话级记忆。项目级记忆就是CLAUDE.md这类文件是持久的、经过评审的、可信的。会话级记忆是Agent在单次任务中积累的上下文任务结束就丢弃。两者之间有一个晋升机制如果某个会话级的经验被证明是通用的、有价值的就把它沉淀到项目级记忆里。具体操作上我会在任务结束后问Agent这次任务里有没有什么经验值得记到CLAUDE.md里Agent会给出几条建议我筛选后手动加进去。这个习惯坚持下来CLAUDE.md会越来越厚但每一条都是实战验证过的。5. 多Agent协作什么时候需要怎么编排5.1 单Agent的天花板单Agent做任务上下文窗口是硬约束。一个复杂任务涉及的文件、日志、文档加起来可能几十万字塞不进一个上下文窗口。这时候要么做摘要丢信息要么分多次对话丢上下文连贯性。多Agent协作就是为了解决这个问题把任务拆给多个Agent每个Agent负责一块各自维护自己的上下文。但多Agent不是银弹。我见过不少团队一上来就搞多Agent结果协调开销比任务本身还大。判断标准很简单如果单Agent加Plan Mode能搞定就不要上多Agent。多Agent适合的场景是任务天然可并行、且各子任务之间耦合度低。比如给十个微服务各加一个健康检查接口这种任务十个Agent并行做比一个Agent串行做快得多。5.2 编排模式的选择多Agent编排有几种常见模式各有适用场景主管模式一个主管Agent负责任务分解和结果汇总多个工作Agent负责执行。适合任务可以清晰分解、子任务之间独立性强的场景。主管Agent的prompt要写清楚你负责分解任务不要自己执行。流水线模式Agent按顺序排列前一个的输出是后一个的输入。适合有明确阶段划分的任务比如需求分析→设计→编码→测试。每个Agent专注自己那一环prompt可以写得很专。对等模式多个Agent平级通过共享的工作区协作。适合探索性任务比如调研三个技术方案并给出对比。每个Agent调研一个方案最后汇总。我自己的项目里用得最多的是主管模式因为它最可控。主管Agent的prompt大概长这样你是一个任务协调者。你的职责是 1. 把用户的任务分解成3-5个子任务 2. 为每个子任务生成一个工作Agent的prompt 3. 收集工作Agent的结果并汇总 4. 如果子任务之间有依赖调整执行顺序 你不需要自己执行任何子任务只负责协调。5.3 Agent之间的通信协议多Agent协作最容易出问题的地方是通信。Agent A的输出格式Agent B读不懂或者Agent A以为自己在汇报Agent B以为自己在接收指令。解决办法是定义统一的消息格式。我的做法是用JSON schema约束Agent之间的消息{ from: agent_name, to: agent_name, type: task_assignment | result_report | question | answer, payload: { task_id: uuid, content: ..., artifacts: [file_path_1, file_path_2], status: pending | in_progress | done | failed } }这个格式看起来简单但能避免大量沟通歧义。每个Agent的prompt里都写清楚你发送消息必须符合这个格式接收消息时按这个格式解析。6. 落地过程中踩过的坑和应对6.1 Agent执行中断的排查思路agent execution terminated due to error这个报错我踩过不下十次。原因五花八门但排查路径可以标准化第一步看Agent的最后一条输出。如果它停在某个命令执行后大概率是那个命令失败了。第二步看命令的退出码和stderr。第三步如果命令本身没问题看是不是上下文超限了——Agent的上下文窗口满了它会静默截断然后行为变得奇怪。第四步看是不是权限问题——Agent试图访问沙箱外的资源被拒绝了。我遇到最多的是上下文超限。解决办法是把大任务拆小或者把不必要的信息从上下文里剔除。比如Agent读了一个巨大的日志文件把上下文撑爆了这时候应该让它先grep出关键行而不是读全文。6.2 Agent自作主张的预防Agent有时候会做一些你没让它做的事比如顺手重构了一个它觉得不优雅的函数或者删了一个它觉得没用的文件。这种自作主张在开发环境可能只是烦人在生产环境就是事故。预防措施有三层。第一层是prompt约束在CLAUDE.md里明确写只做被要求的事不要顺手改其他代码。第二层是Plan Mode让Agent先说要做什么你确认了再执行。第三层是操作审计Agent的每个写操作都记日志事后可以追溯。我自己的习惯是对Agent的写操作保持最小惊讶原则——如果Agent要改的文件不在我预期的范围内我会先问它为什么。这个习惯帮我拦下过好几次Agent觉得这个文件该删的情况。6.3 Token成本的控制Agent跑起来token消耗是很快的。一个复杂任务Agent读文件、思考、执行、读结果、再思考来回几轮几十万token就没了。控制成本有几个实用技巧精简上下文CLAUDE.md不要写废话只写Agent真正需要的信息。我见过有人把整个API文档贴进去几万字Agent每次启动都读一遍纯浪费。用grep代替全文读取让Agent先grep定位再读具体行而不是读整个文件。缓存常用信息有些信息Agent每次都要用比如数据库schema可以做成一个精简的摘要文件而不是让它每次去读模型定义。设置token预算在Agent的配置里设一个单任务token上限超了就停下来让人介入避免一个任务烧掉一天的额度。6.4 Agent Skill的沉淀Agent Skill是指把一类任务的执行方法固化下来让Agent下次遇到同类任务可以直接调用。比如给一个API加新端点这个任务涉及改路由、改service、加测试、更新文档步骤是固定的。把这个流程写成一个skill文件Agent下次遇到加端点的任务直接按skill执行不用重新规划。Skill的写法没有统一标准我的做法是用markdown写清楚适用场景、前置条件、执行步骤、验证方法、常见问题。放在项目的.agent/skills/目录下CLAUDE.md里引用一下。这样Agent在处理任务时会先查有没有对应的skill有就直接用没有才自己规划。这个机制的价值在于把人的经验固化成Agent的能力。团队里资深工程师知道加端点要记得更新OpenAPI文档新人可能不知道Agent也不知道。但把这个经验写成skillAgent就知道了新人通过Agent也间接知道了。7. 从零搭建AI Native工作流的实操路径7.1 第一周把CLAUDE.md写起来不要一上来就搞复杂的Agent编排。第一周就做一件事给现有项目写一份CLAUDE.md。内容按我前面给的骨架来重点是技术栈、命令、目录结构、禁止事项这四块。写完让Agent跑一个简单任务试试比如给某个函数加个参数校验看它能不能按你的约定来。根据Agent的表现迭代CLAUDE.md把Agent做错的地方补进去。这一周的目标是让Agent懂你的项目。判断标准是Agent生成的代码你不需要大改就能用。7.2 第二周引入Plan Mode第二周开始所有涉及多文件的任务都走Plan Mode。一开始你可能会觉得慢但坚持一周你会发现返工率明显下降。这一周的重点是练习审计划——Agent出的计划你要能快速判断哪里有问题。常见的计划问题包括步骤顺序不对、遗漏了测试、风险点没识别出来。审多了你就有感觉了。这一周还要开始建立命令白名单。把Agent常用的命令列出来分类成直接允许和需要确认。这个白名单会随着使用不断调整。7.3 第三周沉淀Skill第三周开始把重复出现的任务模式沉淀成Skill。判断标准是如果一类任务你让Agent做了三次以上就该写Skill了。Skill不用写得很完美先写个初版用的时候发现哪里不对再改。Skill的价值在于复用写得越多Agent能独立处理的任务就越多。这一周还要开始做操作审计。Agent的写操作记日志每周review一次看有没有异常操作。这个习惯能帮你及早发现Agent的行为偏差。7.4 第四周多Agent试点如果前三周跑得顺第四周可以试点多Agent。选一个天然可并行的任务比如给五个模块各加一个日志埋点用主管模式跑一次。重点观察主管Agent的任务分解合不合理、工作Agent之间的通信有没有歧义、汇总结果的质量如何。根据观察结果调整编排策略。如果前三周跑得不顺第四周不要急着上多Agent继续打磨单Agent的工作流。多Agent是放大器单Agent的问题在多Agent里会被放大不会自动消失。7.5 持续迭代的节奏AI Native工作流不是搭完就完事的它需要持续迭代。我的节奏是每周花半小时review Agent的表现把新的经验补进CLAUDE.md或Skill每月花两小时做一次全面review看有没有结构性的问题需要调整每季度重新评估一次工具链看有没有新的工具值得引入。这个节奏听起来不重但坚持下来效果很明显。我自己的项目跑了半年Agent首次生成代码的可用率从四成提到了八成以上返工率降了一半多。这些数字不是靠某个神奇的工具而是靠持续的小迭代积累出来的。最后分享一个我自己的体会AI Native落地最大的障碍不是技术是习惯。人习惯了自己动手很难信任Agent去干活。但一旦你跨过那个信任门槛把重复性的、模式化的任务交给Agent你会发现自己能腾出大量时间做真正需要人判断的事——架构设计、技术选型、和产品吵架。这才是AI Native的真正价值不是让AI替代人而是让人做人该做的事。