1. 从人写代码到人管AgentAI Native团队到底变了什么过去两年我参与过三个不同规模的团队从传统研发模式向 AI Native 模式迁移的过程。说实话第一次听到AI Native 团队这个词的时候我的反应和大多数人一样——不就是让程序员用 Copilot 写代码吗但真正上手之后才发现这个理解偏差得离谱。AI Native 不是给现有流程加个 AI 助手而是把整个软件开发生命周期SDLC的底层假设换掉过去我们假设写代码的是人工具是辅助现在要假设执行任务的是 Agent人是编排者和审核者。这个假设一变很多东西就跟着变了。需求拆解的方式变了——以前是拆给人做的任务现在是拆给 Agent 做的任务颗粒度、上下文依赖、验收标准都不一样。代码审查的重心变了——以前盯的是逻辑漏洞和边界条件现在更多盯的是 Agent 有没有理解偏了、有没有引入它自己编造的依赖。甚至连什么算一个合格的工程师这个定义都在变——写代码快不再是核心竞争力能把一个模糊需求翻译成 Agent 可执行的清晰指令、能设计好 Agent 之间的协作流程、能在 Agent 跑偏的时候快速定位问题这些才是。我写这份手册的出发点很简单网上关于 Claude Code、Agent 框架、AI Native SDLC 的资料太碎了要么是官方文档那种告诉你有什么功能的说明书要么是碎片化的技巧帖。但一个团队要真正落地 AI Native 研发范式需要的是一套从环境搭建、Agent 编排、上下文管理到安全管控的完整链路。这篇内容就是把我踩过的坑、验证过的方案、以及那些文档里不会写但实际会要命的细节系统地整理出来。不管你是刚接触 Claude Code 的独立开发者还是正在推动团队转型的技术负责人应该都能从里面找到能直接用的东西。2. 环境搭建Claude Code 在 Mac、Ubuntu、VS Code 里的真实安装体验2.1 为什么安装这一步就有人卡住Claude Code 的安装本身不复杂但我在帮别人配置的过程中发现卡住的人往往不是卡在命令上而是卡在几个没人告诉你的前置条件上。先说最核心的一点Claude Code 是一个跑在终端里的 Agent 工具它的工作方式是直接读写你的文件系统、执行终端命令。这意味着它对环境的要求和普通 CLI 工具不太一样——它需要 Node.js 运行时建议 18 以上需要能访问外网因为要调用模型 API还需要你对当前工作目录有完整的读写权限。Mac 上的安装相对顺滑。如果你用 Homebrew一条brew install node把 Node 装好然后通过 npm 全局安装 Claude Code 的包就行。但这里有个坑Mac 上如果之前用 nvm 管理过 Node 版本全局安装的包可能装到了某个特定版本下切换 Node 版本后就找不到了。我的建议是统一用 nvm 管理装完之后nvm alias default固定一个版本避免每次开新终端都要重新切。Ubuntu 上的情况稍微复杂一点。Ubuntu 自带的 Node 版本往往偏旧直接apt install nodejs装出来的可能是 12 或 14跑不起来。正确做法是先加 NodeSource 的源或者用 nvm 装。另外 Ubuntu 上有个权限问题很常见如果你用sudo npm install -g装的包普通用户执行时可能因为权限不够而报错。解决办法是要么配置 npm 的全局目录到用户目录下要么干脆用 nvm 装 Node这样全局包天然就在用户空间里不会有权限问题。VS Code 的集成是另一个维度。Claude Code 本身是终端工具但通过 VS Code 的终端面板使用体验会好很多——你可以一边看代码一边让 Agent 改改完直接在编辑器里 diff。配置的关键是确保 VS Code 的集成终端用的是你装好 Claude Code 的那个 shell 环境。我遇到过有人在系统终端里能用在 VS Code 终端里就报command not found原因就是 VS Code 默认用的 shell 和系统登录 shell 不一致PATH 没加载全。2.2 安装之后第一件该做的事装完 Claude Code很多人第一反应是赶紧让它写点代码试试。我的建议是先别急花十分钟做两件事。第一件是确认它到底能访问哪些目录。Claude Code 默认会在你启动它的目录下工作但它有能力读写子目录甚至通过命令访问更上层。你可以在一个测试目录里启动它让它执行pwd和ls看看它的工作范围是不是符合你的预期。第二件是配置好模型接入。Claude Code 默认走 Anthropic 的模型但实际团队使用中出于成本、合规或可用性考虑经常需要接入第三方模型。这时候就需要用到类似 cc switch 这样的工具来切换模型后端把 DeepSeek、Qwen、GLM 等模型接进来。这里要特别提醒一点接入第三方模型时模型的工具调用能力function calling和上下文窗口大小是两个硬指标。有些模型聊天很流畅但工具调用格式不稳定Claude Code 发过去的工具调用请求它返回的格式对不上Agent 就会卡住或者乱执行。我实测下来工具调用能力强的模型在 Claude Code 里的表现明显更稳。上下文窗口也很关键Claude Code 会把当前项目的大量上下文塞进 prompt窗口太小的模型会频繁触发截断导致 Agent失忆。提示安装完成后先在非生产目录里跑一个完整的读文件-改文件-执行命令闭环确认 Agent 的工具调用链路是通的再放到真实项目里用。3. CLAUDE.md 与上下文工程让 Agent 真正懂你的项目3.1 CLAUDE.md 不是 README 的替代品CLAUDE.md 这个文件是 Claude Code 体系里最被低估的东西。很多人把它当成一个项目说明随便写写结果发现 Agent 的表现时好时坏。问题出在CLAUDE.md 不是给人看的 README它是给 Agent 看的操作手册。README 可以写本项目是一个电商系统但 CLAUDE.md 要写的是本项目的订单模块在 src/order 下修改订单状态必须走 OrderStateMachine 类不要直接改数据库字段。这两者的区别在于README 描述是什么CLAUDE.md 规定怎么做和不能怎么做。Agent 在执行任务时会优先参考 CLAUDE.md 里的约束。如果你不写清楚它就会按自己的理解来——而它的理解往往和你的项目规范有偏差。我见过最典型的例子是项目里有一套自定义的错误处理规范但没写进 CLAUDE.md结果 Agent 每次改代码都按通用模式抛异常和现有代码风格完全不一致review 的时候得全部返工。写 CLAUDE.md 有几个实操要点。第一把项目的目录结构和关键模块的职责写清楚Agent 需要知道改这个功能该去哪个目录。第二把项目的编码规范和禁忌写清楚比如不要引入新的第三方依赖所有 API 调用必须走统一的 client 封装测试文件必须和源文件同目录。第三把常用的命令写清楚比如怎么跑测试、怎么构建、怎么启动本地服务这样 Agent 需要验证时会自己执行。第四把当前项目的已知问题和正在进行的重构写清楚避免 Agent 改到一半发现踩了别人正在改的代码。3.2 上下文窗口的分配策略Claude Code 工作时塞进模型上下文的内容大致分几块系统提示、CLAUDE.md、当前对话历史、被读取的文件内容、工具调用结果。这几块是共享上下文窗口的窗口就那么大怎么分配直接决定了 Agent 的表现。我的经验是CLAUDE.md 不要写太长控制在 2000 字以内。写太长会挤占文件内容的上下文空间而且 Agent 对超长文档的注意力会衰减写了等于没写。真正重要的约束放前面次要的放后面。对话历史方面如果一个任务要跑很久中间要主动清理无关的对话轮次或者开新会话。被读取的文件内容是最占空间的所以不要让 Agent 一次性读太多文件——更好的做法是让它先读目录结构定位到相关文件再读具体内容。还有一个技巧是分层上下文。把项目级的通用约束放 CLAUDE.md把模块级的约束放在各模块目录下的说明文件里Agent 进入某个模块工作时再读对应的说明。这样上下文利用率最高不会一上来就把整个项目的所有规范都塞进去。3.3 Agent 记忆跨会话保持项目认知Agent 记忆是 AI Native 研发里一个绕不开的话题。Claude Code 本身在单次会话内是有记忆的但会话结束就忘了。团队协作场景下我们希望 Agent 能记住上次这个模块改了什么这个 bug 之前排查到哪一步了。实现这个有几种思路。一种是用文件做外部记忆。在项目里维护一个NOTES.md或者.agent-memory/目录每次会话结束前让 Agent 把关键结论写进去下次会话开始时读进来。这种方式简单可靠缺点是依赖 Agent 主动写容易漏。另一种是用专门的记忆工具比如把项目知识存到向量数据库里Agent 需要时检索。这种方式更自动但引入的复杂度也高小团队不一定划算。我目前的做法是混合关键的架构决策和踩坑记录手动维护在一个DECISIONS.md里日常的任务进展让 Agent 自己写到PROGRESS.md。CLAUDE.md 里明确告诉 Agent开始任务前先读这两个文件结束任务后更新 PROGRESS.md。这样既保证了关键信息不丢又不会让 Agent 的记忆负担太重。4. Agent 编排与 Harness把单个 Agent 变成团队生产力4.1 Harness 和 Agent 到底差在哪这两个词经常被混用但它们的职责完全不同。Agent 是执行者它接收任务、调用工具、产出结果。Harness 是编排层它负责决定什么时候启动哪个 Agent给 Agent 什么上下文Agent 的输出怎么传递给下一个环节出错怎么重试。打个比方Agent 是一个熟练的工人Harness 是工头加流水线。工人再熟练如果没有工头分配任务、没有流水线传递半成品也做不出完整的产品。很多团队一开始只关注用哪个 Agent 框架忽略了 Harness 的设计结果就是单个任务跑得挺好一旦要串起需求分析-方案设计-编码-测试-审查这条链路就乱套了。Harness 的核心设计点有几个。任务路由什么类型的任务交给什么 Agent是同一个 Agent 换 prompt还是不同 Agent 各司其职。上下文传递上一个 Agent 的产出怎么变成下一个 Agent 的输入是直接传全文还是传摘要。状态管理任务跑到一半失败了怎么恢复到中间状态而不是从头再来。人工介入点哪些环节必须人工确认才能继续哪些可以全自动。4.2 多 Agent 协作的几种模式实际落地中多 Agent 协作主要有三种模式各有适用场景。第一种是流水线模式。任务按固定顺序经过多个 Agent每个 Agent 负责一个环节。比如需求 Agent 产出需求文档设计 Agent 基于需求产出技术方案编码 Agent 基于方案写代码测试 Agent 写测试用例。这种模式适合流程标准化程度高的团队优点是可控、可预测缺点是灵活性差遇到需要来回迭代的任务就不好使。第二种是主从模式。一个主 Agent 负责拆解任务和调度多个从 Agent 负责执行具体子任务。主 Agent 像一个项目经理把大任务拆成小任务分下去收集结果后决定下一步。这种模式适合任务边界不太清晰、需要动态调整的场景。Claude Code 里可以通过让主 Agent 生成子任务描述、再启动新的 Agent 会话执行来实现。第三种是对等协作模式。多个 Agent 各自有专长通过共享的工作区比如一个共享目录或消息队列交换信息。这种模式最灵活但也最难管理容易出现 Agent 之间互相等待或者重复劳动。我一般只在特定场景用比如一个 Agent 写代码、一个 Agent 同时写文档两者通过共享的接口定义文件保持同步。4.3 用 Claude Code 搭建最小可用 HarnessClaude Code 本身不是一个 Harness 框架但它的命令行能力和文件操作能力足够搭一个轻量的 Harness。我的做法是用一个 shell 脚本或者 Node 脚本做调度器核心逻辑是读取任务队列为每个任务启动一个 Claude Code 会话传入对应的 prompt 和上下文文件收集输出根据输出决定下一步。具体来说我会在项目里建一个.harness/目录里面放tasks/待执行任务、context/各任务的上下文、outputs/执行结果、state.json当前状态。调度脚本每次从 tasks 里取一个任务组装 prompt调用 Claude Code 执行把结果写到 outputs更新 state。如果任务需要人工确认就在 state 里标记为待确认暂停流水线。这个方案的好处是简单、透明、可调试。每个环节的输入输出都是文件出问题了一眼就能看到是哪一步的上下文不对。缺点是没有现成的重试、并发、监控机制任务量大了需要自己补。但对于刚开始落地 AI Native 的团队这个复杂度刚好——先用起来跑通了再考虑上更重的框架。注意Harness 设计里最容易忽略的是失败恢复。Agent 执行失败是常态如果每次失败都从头跑成本会高得离谱。一定要在任务粒度上做 checkpoint失败时从最近的 checkpoint 恢复。5. Agent 安全与权限边界别让 Agent 变成脱缰野马5.1 Agent 能做什么不该做什么Claude Code 这类工具最让人又爱又怕的地方就是它能直接执行终端命令。爱的是效率——它能自己跑测试、装依赖、改配置怕的是它可能执行你根本不想执行的命令比如rm -rf一个不该删的目录或者把敏感信息提交到不该提交的地方。安全的第一道防线是权限最小化。不要让 Agent 在你整个 home 目录或者整个代码仓库根目录下工作而是把它限制在具体的子目录里。Claude Code 启动时可以指定工作目录确保它只能访问这个目录及其子目录。对于需要访问外部资源的操作比如调用 API、访问数据库要通过环境变量或者配置文件把凭证传进去而不是让 Agent 自己去读系统的凭证文件。第二道防线是危险操作确认。Claude Code 在执行某些命令前会请求确认但默认的确认策略可能不够严。我的做法是在 CLAUDE.md 里明确列出禁止执行的操作比如不要执行任何删除操作不要修改 .env 文件不要执行 git push。同时在 Harness 层面加一层拦截对 Agent 要执行的命令做模式匹配命中危险模式的直接拒绝。第三道防线是输出审查。Agent 产出的代码、文档、配置在合并到主分支之前必须经过人工或另一个 Agent 的审查。审查的重点不是代码风格而是有没有引入不该有的依赖有没有泄露敏感信息有没有改变不该改变的行为。5.2 第三方模型接入的安全考量用 cc switch 这类工具接入第三方模型时数据流向变了——你的代码上下文会发送到第三方模型的 API。这在某些场景下是不可接受的比如涉及商业机密的项目。接入前要确认几件事第三方模型的服务条款里你的数据会不会被用于训练数据传输是不是加密的有没有数据留存策略。从技术角度可以做的是上下文脱敏。在把上下文发给模型之前把敏感信息密钥、用户数据、内部地址替换成占位符模型返回结果后再替换回来。这个在 Harness 层面实现对 Agent 透明。另一个做法是分级使用核心算法和敏感模块只用可信模型通用代码和文档可以用第三方模型。5.3 Agent 跑偏的典型信号与止损Agent 跑偏不是一下子发生的通常有一些早期信号。比如它开始反复读同一个文件却不动手改它生成的代码里出现了项目里根本不存在的类或函数它开始执行和当前任务无关的命令它的输出越来越长但越来越空。这些信号出现时不要等它自己纠正直接中断会话检查上下文重新给指令。止损的关键是保留现场。中断之前把当前的对话历史、Agent 读过的文件列表、执行过的命令记录都保存下来。这些是排查问题的依据。我见过有人一发现 Agent 跑偏就关掉重来结果同样的问题反复出现因为根本不知道是哪一步的上下文出了问题。6. 从需求到上线AI Native SDLC 的完整链路拆解6.1 需求阶段把模糊需求翻译成 Agent 可执行的任务传统 SDLC 里需求阶段产出的是给人看的需求文档。AI Native 模式下需求阶段还要多产出一份Agent 任务描述。这份描述要包含任务目标要达成什么、输入基于哪些现有代码或文档、输出产出什么文件或什么状态、约束不能做什么、验收标准怎么判断做完了。这个翻译过程本身就是一项核心能力。我总结了一个模板在 [项目/模块] 中基于 [现有实现/文档]实现 [具体功能]要求 [约束条件]完成后 [验收方式]。比如在订单模块中基于现有的 OrderService增加一个取消订单的方法要求复用现有的状态机完成后跑通 OrderServiceTest 里的取消订单用例。这样的描述Agent 基本能一次做对。6.2 设计与编码阶段Agent 主导人做关键决策设计和编码阶段是 Agent 发挥的主场。但Agent 主导不等于人不管。我的做法是架构设计由人主导Agent 辅助出方案和对比详细设计和编码由 Agent 主导人做 review 和关键决策。具体流程是人给出架构约束和关键接口定义Agent 基于这些生成详细设计文档和代码骨架人 review 骨架确认方向对了Agent 再填充具体实现。这样既利用了 Agent 的速度又保证了架构的一致性。如果让 Agent 从零设计架构它往往会选一个通用但不符合项目实际的方案后期改起来很痛苦。6.3 测试与审查阶段Agent 互审的实践测试阶段可以让 Agent 做很多事生成测试用例、跑测试、分析失败原因、修复明显的测试问题。但要注意Agent 写的测试往往过于配合自己的实现——它写的代码和它写的测试是自洽的但可能漏掉了边界情况。所以测试用例的 review 要特别关注有没有覆盖异常路径。审查阶段我推荐Agent 互审让一个 Agent 审查另一个 Agent 的产出。审查 Agent 的 prompt 里要明确审查维度逻辑正确性、边界条件、依赖引入、安全风险、与现有代码的一致性。审查结果由人做最终判断。这个模式能抓到不少 Agent 自己意识不到的问题因为审查 Agent 没有我刚写了这段代码的思维定势。6.4 上线与运维Agent 在可观测性里的角色上线之后Agent 的价值从写代码转向看系统。它可以帮你分析日志、定位异常、生成故障报告。但生产环境的 Agent 权限要收得更紧——只读权限为主任何写操作都要人工确认。我见过有团队让 Agent 自动处理告警结果 Agent 把一个正常的流量波动当成故障触发了一堆不必要的操作。生产环境的 Agent宁可保守不可激进。7. 团队落地时最容易踩的五个坑第一个坑是把 AI Native 当成工具升级。买几个账号、装几个插件就以为转型完成了。实际上 AI Native 改的是流程和分工工具只是载体。不调整流程工具再好也发挥不出来。第二个坑是CLAUDE.md 写成摆设。要么不写要么写成一堆正确的废话。CLAUDE.md 的价值在于项目特有的约束通用的编码规范模型本来就知道不用写。写那些不写 Agent 就会做错的东西。第三个坑是上下文给太多。觉得给 Agent 的信息越多它越聪明结果上下文窗口被塞满关键信息被淹没。上下文要精不要多按需加载。第四个坑是没有人工介入点。追求全自动结果 Agent 跑偏了没人发现产出物质量失控。关键节点必须有人确认尤其是架构决策和上线操作。第五个坑是忽视成本。Agent 跑起来 token 消耗很快尤其是多 Agent 协作和长会话。要在 Harness 层面做成本监控设置单任务和单日的 token 上限避免账单失控。8. 我目前的工作流长什么样说了这么多方法论最后分享一下我自己现在每天的工作流可能更直观。早上到工位先花十分钟看昨天 Agent 跑完的任务队列review 产出物把需要人工决策的标记出来。然后开一个新的 Claude Code 会话把今天的核心任务用前面说的模板写成任务描述让 Agent 先出方案。方案出来后我 review 一遍确认方向然后让 Agent 开始实现。实现过程中我会时不时看一眼它的操作发现跑偏立刻中断。下午主要是 review 和集成。Agent 产出的代码我会用另一个 Agent 会话做交叉审查然后自己再过一遍关键逻辑。测试跑通后合并。傍晚把今天没做完的任务和踩的坑更新到 PROGRESS.md 和 DECISIONS.md供明天和团队其他成员参考。这套流程跑下来我个人的编码产出大概提升了三到四倍但更重要的是重复性的、机械性的工作基本被 Agent 吃掉了我能把精力放在架构设计和关键决策上。当然这套流程不是一天建成的中间踩的坑、返工的成本、调整的反复都是真实发生过的。如果你刚开始建议从一个模块、一个任务类型开始试跑通了再扩大范围。