1. 为什么“AI-Native SDLC”不是给旧流程贴标签1.1 从“用AI辅助”到“以AI为原生”的分水岭很多团队嘴上说着 AI-Native实际干的事还是老一套需求文档写完丢给 AI 润色代码写完让 AI 补两行注释测试用例让 AI 生成一批再人工挑。这不叫 AI-Native这叫“AI 打杂”。真正的 AI-Native SDLC核心判断标准只有一条流程里的每一个环节是否默认有一个智能体在参与并且这个参与是可配置、可审计、可复现的。我见过太多团队卡在这个认知门槛上。他们把 Claude Code 当成一个更聪明的代码补全工具装完插件就开始用结果用了两周发现“也就那样”。问题不在工具在于他们仍然用“人写代码、AI 帮忙”的旧范式去套。AI-Native 的范式是反过来的人负责定义意图和验收标准智能体负责执行和迭代人只在关键决策点介入。这个转变带来的直接后果是你的项目结构、文档组织、甚至 Git 提交习惯都要跟着变。举个最直观的例子传统项目里 README 是给人看的AI-Native 项目里CLAUDE.md这类文件是给智能体看的它的写法、粒度、更新频率直接决定了智能体干活的质量。这就是为什么我把“项目上下文文件”放在整个实践手册的第一位来讲——它是地基。1.2 一个典型 AI-Native 项目的目录长什么样先看结构再讲道理。下面是我在实际项目中反复打磨后稳定下来的目录骨架适用于大多数中大型代码仓库project-root/ ├── CLAUDE.md # 智能体主上下文项目级规则 ├── .claude/ │ ├── commands/ # 自定义斜杠命令 │ ├── agents/ # 子智能体定义 │ └── settings.json # 权限与工具配置 ├── docs/ │ ├── adr/ # 架构决策记录 │ └── specs/ # 需求规格供智能体读取 ├── src/ ├── tests/ └── scripts/ └── verify.sh # 智能体可调用的验证脚本这个结构里CLAUDE.md和.claude/目录是 AI-Native 的“新基建”。传统项目里没有它们照样跑但在 AI-Native 流程里缺了它们智能体就像一个没有入职培训的新员工你得每次从头解释一遍项目背景效率极低且结果不稳定。注意不要把所有规则都塞进一个巨大的CLAUDE.md。我踩过的坑是文件超过 500 行后智能体对规则的遵循度明显下降而且每次对话都要消耗大量上下文预算。正确做法是主文件只放“全局铁律”细节规则拆到.claude/commands/里按需加载。1.3 智能体在 SDLC 各阶段的角色分工把 SDLC 拆成需求、设计、编码、测试、评审、部署六个阶段每个阶段智能体的介入方式完全不同。我用一张表说清楚阶段智能体角色人的角色关键产物需求需求澄清、边界追问定义业务意图specs/*.md设计方案生成、权衡分析拍板选型docs/adr/*.md编码主力实现定义接口与约束可运行代码测试用例生成、边界覆盖验收标准制定tests/*评审静态检查、逻辑审查最终把关review 记录部署脚本生成、回滚预案审批上线scripts/*这张表的价值在于它逼你回答一个问题每个阶段智能体的输入是什么、输出是什么、人从哪里介入。回答不清楚AI-Native 就是一句空话。我建议你把这张表打印出来贴在工位上每引入一个新智能体就问它落在哪个格子。2. Claude Code 的安装与项目接入实操2.1 安装路径选择桌面版还是命令行Claude Code 目前主要有两种形态命令行版本和桌面版。选哪个不是喜好问题而是工作流问题。命令行版本适合已经习惯终端操作的开发者它的优势是可脚本化、可组合。你可以把它嵌进 Makefile、CI 流程、Git hook 里。桌面版适合需要图形化界面管理多个会话的场景比如同时开三个智能体分别处理前端、后端、测试。安装命令行版本Node.js 环境是前提。我实测下来Node 18 和 Node 20 都稳定Node 16 会有兼容问题。安装命令npm install -g anthropic-ai/claude-code装完后验证claude --version如果提示命令找不到八成是 npm 全局路径没进 PATH。Linux 和 macOS 下通常是~/.npm-global/bin或/usr/local/binWindows 下是%APPDATA%\npm。这个坑我见过太多人踩装完以为失败了其实只是路径问题。提示如果你在公司网络环境下遇到订阅权限相关的报错先确认账号的订阅状态和组织策略这类问题通常不是安装本身导致的而是账号权限配置问题。具体排查方向是检查组织管理员是否开放了对应工具的访问权限。2.2 在 VS Code 里接入 Claude CodeVS Code 接入有两种方式我推荐第二种。第一种是装官方扩展在扩展市场搜 Claude Code装完在侧边栏就能用。优点是开箱即用缺点是它和终端里的会话是隔离的你在终端里积累的上下文扩展里看不到。第二种是在 VS Code 内置终端里直接用命令行版本。这样你的会话、上下文、自定义命令全部统一。具体做法是在 VS Code 的settings.json里加一个终端配置{ terminal.integrated.profiles.linux: { claude: { path: bash, args: [-c, claude] } } }这样你新建终端时选 claude 配置直接进入智能体会话。Windows 下把linux换成windowspath 换成powershell.exe即可。我为什么推荐第二种因为 AI-Native 流程里上下文连续性比界面美观重要得多。你在终端里跑测试、看日志、调智能体全在同一个会话里智能体能感知到你的操作历史给出的建议质量明显更高。2.3 接入本地模型以 LM Studio 为例有些场景下你不想把代码发到云端比如处理敏感业务逻辑。这时候可以把 Claude Code 指向本地模型。LM Studio 启动本地服务后默认监听http://localhost:1234在 Claude Code 的配置里指定 base URL 即可。具体配置在.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:1234/v1, ANTHROPIC_API_KEY: local } }这里有个关键点本地模型的上下文窗口通常比云端小所以你的CLAUDE.md要写得更精简把非必要规则移到按需加载的命令文件里。我实测下来本地模型处理单文件重构任务没问题但跨十几个文件的架构级改动还是得用云端模型。注意本地模型的能力差异很大同一个提示词在不同模型上效果可能天差地别。建议你先用一个小任务做基准测试确认模型在你的场景下够用再全面切换。3. CLAUDE.md 的写法决定智能体干活质量的关键文件3.1 一份合格 CLAUDE.md 的四个必备模块CLAUDE.md不是项目介绍文档它是给智能体的操作手册。我总结下来一份合格的CLAUDE.md必须包含四个模块缺一个都会导致智能体行为不稳定。第一个模块是项目定位。用三到五句话说清楚这个项目是干什么的、技术栈是什么、核心模块有哪些。不要写“本项目是一个优秀的……”这种废话直接写“这是一个基于 FastAPI 的订单服务依赖 PostgreSQL 和 Redis核心模块是 order、payment、notification”。第二个模块是编码规范。这里要具体到可执行的程度。不要写“代码要清晰”要写“函数不超过 50 行参数不超过 4 个所有公开函数必须有类型注解”。智能体对量化规则的遵循度远高于模糊描述。第三个模块是常用命令。把构建、测试、lint、部署的命令列出来智能体需要执行验证时会直接调用。比如# 运行测试 pytest tests/ -v # 代码检查 ruff check src/ # 类型检查 mypy src/第四个模块是禁区与约束。明确告诉智能体哪些事不能做。比如“不要修改 migrations 目录下的历史文件”、“不要直接操作生产数据库”、“提交前必须跑通全部测试”。这一块是防止智能体“好心办坏事”的关键。3.2 规则粒度为什么“越具体越听话”我做过一个对比实验。同一批任务用两版CLAUDE.md分别跑。A 版写“请遵循良好的代码风格”B 版写“使用 4 空格缩进字符串用双引号导入按标准库、第三方、本地分组”。结果 B 版的代码一次通过率比 A 版高出将近一倍。原因很简单智能体没有“常识”它只有“指令”。你脑子里的“良好风格”对它来说是不存在的你必须把它翻译成可判定的规则。这就像带新人你说“注意代码质量”他一脸茫然你说“每个函数写单元测试覆盖率不低于 80%”他就知道怎么干了。所以写CLAUDE.md的心法是假设读者是一个能力很强但完全不了解你项目的外包工程师。你要把那些“不言自明”的约定全部显式写出来。项目里用 pnpm 不用 npm用 vitest 不用 jest用 dayjs 不用 moment这些都要写。3.3 动态维护让 CLAUDE.md 跟着项目一起长大CLAUDE.md不是写完就扔那儿的。我建议你把它当成代码一样维护每次发现智能体犯了重复性错误就往里加一条规则。具体做法是建一个习惯每次智能体输出不符合预期先问自己“这是不是因为我没在 CLAUDE.md 里说清楚”。如果是立刻补规则。这样跑一个月你的CLAUDE.md会变成一份极其精准的项目操作手册新来的智能体或者新人读一遍就能上手。我自己的项目里CLAUDE.md从最初的 30 行涨到了 200 多行每一条都是踩坑换来的。比如“修改 API 响应结构时必须同步更新 docs/api.md”、“新增环境变量必须同时更新 .env.example 和部署配置”这些都是被智能体坑过之后加上的。提示CLAUDE.md建议纳入版本控制每次修改都提交。这样你能追溯“哪条规则是什么时候因为什么加的”团队协作时也能避免规则冲突。4. 自定义命令与子智能体把重复劳动固化下来4.1 斜杠命令把高频操作变成一键触发Claude Code 支持自定义斜杠命令放在.claude/commands/目录下每个命令是一个 Markdown 文件。文件名就是命令名文件内容是提示词模板。举个我天天用的例子.claude/commands/review.md请审查当前 git diff 中的改动重点关注 1. 是否有未处理的边界条件 2. 是否有硬编码的配置值 3. 错误处理是否完整 4. 是否有性能隐患如循环内查询数据库 输出格式按文件分组每个问题标注严重程度高/中/低。之后在会话里输入/review智能体就会自动执行这套审查逻辑。这个命令帮我省下的时间保守估计每周好几个小时。再比如.claude/commands/test-gen.md专门用来给指定文件生成测试为 $ARGUMENTS 生成单元测试要求 - 覆盖正常路径、边界值、异常路径 - 使用项目现有的测试框架和断言风格 - mock 外部依赖不发起真实网络请求 - 每个测试函数名用中文描述测试意图$ARGUMENTS是参数占位符输入/test-gen src/order/service.py就能针对指定文件生成测试。4.2 子智能体让专业的事交给专业的“人”子智能体是 Claude Code 里被严重低估的功能。你可以定义多个子智能体每个有自己的系统提示词和工具权限主智能体在需要时把任务派发给它们。在.claude/agents/下定义比如一个专门做数据库迁移审查的子智能体db-reviewer.md--- name: db-reviewer description: 审查数据库迁移脚本的安全性 tools: Read, Grep, Glob --- 你是数据库迁移审查专家。审查迁移脚本时检查 1. 是否有锁表风险大表加索引、改列类型 2. 是否有数据丢失风险删列、改类型 3. 回滚方案是否完整 4. 是否考虑了并发写入场景 只读不写输出审查报告。注意tools字段我只给了读权限没给写权限。这是最小权限原则的体现审查类智能体不需要改代码就不给它改代码的能力避免它“顺手”帮你改了反而引入问题。子智能体的价值在于上下文隔离。主智能体的上下文窗口是有限的如果所有任务都在主会话里做很快就会被各种细节塞满。子智能体处理完任务只返回结论不把中间过程带回主会话这样主会话能保持清爽处理更长的任务链。4.3 权限配置给智能体划好活动边界.claude/settings.json里的权限配置是 AI-Native 流程的安全阀。我建议按“默认拒绝、按需开放”的原则配置。{ permissions: { allow: [ Read, Grep, Glob, Bash(pytest:*), Bash(ruff:*), Bash(git diff:*), Bash(git status:*) ], deny: [ Bash(rm:*), Bash(git push:*), Bash(curl:*), Write(./migrations/**) ] } }这份配置的含义是读操作全放开测试和检查命令放开但删除、推送、网络请求、修改迁移文件全部禁止。这样即使智能体判断失误也造不成不可逆的破坏。我踩过的一个坑是早期没配 deny 列表智能体为了“清理临时文件”执行了rm -rf虽然只是删了构建产物但那一刻我后背发凉。从那以后所有破坏性命令一律进 deny 列表。注意deny 列表的优先级高于 allow。如果一条命令同时匹配两个列表以 deny 为准。这个设计很合理但配置时容易忽略建议配完后用几个边界命令测试一下。5. 智能体工作流搭建从单点工具到流水线5.1 需求到代码一条可复现的链路AI-Native SDLC 的核心价值是把“需求到代码”这条链路变成可复现的流水线。我实际跑通的链路是这样的第一步人写一份docs/specs/feature-x.md描述业务意图和验收标准。这份文档不需要很正式但必须包含“输入是什么、输出是什么、异常情况怎么处理”三要素。第二步让智能体读这份 spec生成技术方案输出到docs/adr/。提示词大概是“阅读 specs/feature-x.md生成技术方案包含数据模型、接口设计、关键流程列出至少两个备选方案并说明取舍”。第三步人审方案拍板选型把决策写回 ADR。第四步让智能体按 ADR 实现代码同时生成测试。第五步跑/review命令做自动审查人做最终把关。这条链路跑顺之后一个中等复杂度的功能从需求到可合并的代码时间能压缩到原来的三分之一左右。但前提是每一步的产物都要落盘不能只在对话里聊完就完。落盘是为了可追溯、可复现、可回滚。5.2 测试与验证让智能体自己证明自己智能体写完代码怎么知道它对不对答案是让它自己跑验证。这就是为什么CLAUDE.md里要写清楚测试命令。我的做法是在.claude/commands/verify.md里定义一套完整验证流程执行以下验证全部通过才算完成 1. ruff check src/ —— 代码风格 2. mypy src/ —— 类型检查 3. pytest tests/ -v —— 单元测试 4. pytest tests/ --covsrc --cov-fail-under80 —— 覆盖率 任何一步失败修复后重新执行全部步骤。这样智能体在提交代码前会自己跑一遍把低级错误挡在人工审查之前。我统计过加了这一步之后人工审查发现的问题数量下降了大约六成审查者可以把精力放在逻辑和架构层面而不是格式和拼写。5.3 多智能体协作什么时候需要什么时候不需要多智能体协作是个热门话题但我要泼一盆冷水大多数场景不需要多智能体。一个配置良好的主智能体加几个专用子智能体足够应付 90% 的任务。什么时候真的需要多智能体当任务可以明确切分且互不依赖时。比如前端和后端同时开发两个智能体各管一摊通过接口契约对齐。或者一个智能体写代码另一个智能体专门写测试形成对抗关系测试智能体会更努力地找边界情况。什么时候不需要任务有强顺序依赖时。比如“先设计数据库再写 API 再写前端”这种链路用一个智能体串行做比多个智能体来回传递上下文效率高得多。多智能体的通信成本很高切分不当反而拖慢速度。我个人的经验法则是如果一个任务你能清楚地画出 DAG有向无环图且图中有并行分支才考虑多智能体。画不出来就老老实实用单智能体。6. 常见问题与排查技巧实录6.1 智能体“不听话”的三种典型表现与对策第一种表现是忽略 CLAUDE.md 里的规则。原因通常是规则太多太杂或者规则之间互相矛盾。对策是把规则按优先级分层铁律放最前面用加粗标注细节规则拆到命令文件里按需加载。第二种表现是反复犯同一个错误。原因是你只在对话里纠正了它没把纠正写进CLAUDE.md。对策是建立“纠错即更新”的习惯每次纠正都落盘成规则。第三种表现是过度发挥改了不该改的地方。原因是权限配置太宽松。对策是收紧 allow 列表把非必要权限全部移除用 deny 列表兜底。下面这张表是我整理的常见问题速查现象可能原因排查方向解决动作规则不生效规则太模糊或太多检查 CLAUDE.md 行数与具体度拆分规则量化描述重复犯错纠正未落盘回顾历史对话把纠正写成规则改动范围过大权限过宽检查 settings.json收紧 allow补充 deny上下文丢失会话过长查看会话轮次拆分会话用子智能体命令执行失败环境路径问题手动跑一遍命令修正 CLAUDE.md 中的命令6.2 上下文窗口管理长任务不崩的技巧上下文窗口是智能体的“工作记忆”用满了就会开始遗忘早期内容。管理它的核心技巧是主动清理和分层。主动清理的做法是一个任务完成后开新会话做下一个任务不要在一个会话里连续做十个不相关的任务。分层则是把信息按重要性分三档铁律放CLAUDE.md常驻任务相关放 spec 文件按需读临时信息放对话用完即弃。我实测下来一个会话处理三到五个相关任务是比较舒服的区间。超过这个数智能体开始出现“忘记前面说过什么”的情况输出质量明显下滑。6.3 智能体行为审计出了事怎么追溯AI-Native 流程里智能体的每一步操作都应该可追溯。Claude Code 的会话记录默认会保存但光有记录不够你还需要一套审计习惯。我的做法是所有智能体产出的代码改动必须通过 Git 提交提交信息里标注是哪个智能体、执行了什么命令。这样出问题时git log就是审计日志。另外关键决策比如选型、架构变更必须由人写进 ADR不能只存在于对话里。提示如果你的团队对合规性要求高建议把智能体的操作日志定期归档并建立“智能体改动需人工复核”的强制流程。这不是不信任智能体而是工程上必要的冗余。7. 我踩过的坑与几条硬核经验7.1 不要指望智能体一次做对复杂任务这是我最大的教训。早期我总想用一个提示词让智能体完成整个功能结果它要么漏掉细节要么在某个环节跑偏。后来我改成任务切片把大任务拆成“设计接口、实现核心逻辑、补边界处理、写测试”四个小任务每个任务单独对话完成一个再进下一个。虽然对话次数多了但总时间反而更短因为返工少了。7.2 验证脚本是智能体的“安全带”scripts/verify.sh这个文件看起来不起眼但它是我整个流程里最重要的基础设施之一。它把“什么叫做对了”这件事变成了可执行的代码。智能体不需要理解你的验收标准它只需要跑脚本看退出码是不是 0。我建议每个项目都维护一个这样的脚本内容就是CLAUDE.md里那些验证命令的集合。智能体每次提交前跑一遍人审查前也跑一遍两边用同一套标准避免扯皮。7.3 把智能体当同事而不是工具最后说一个心态层面的经验。把智能体当工具你会不停地“使唤”它然后抱怨它不好用。把智能体当同事你会想“我需要给它什么信息它才能把活干好”。这个心态转变之后你会发现CLAUDE.md写起来顺了任务拆解清晰了协作效率也上来了。具体到操作上就是每次派任务前问自己三个问题它需要知道什么背景它的产出要满足什么标准它遇到不确定时该问谁把这三个问题的答案准备好再开口。这个习惯养成后你和智能体的协作质量会有质的提升。这套实践手册里的每一条都是我在真实项目里反复验证过的。工具会迭代模型会升级但“把意图翻译成可执行规则、把流程固化成可复现链路”这个内核不会变。你先从CLAUDE.md和验证脚本这两件事做起跑通一个小项目再逐步扩展到整个 SDLC。别一上来就追求全流程自动化那大概率会翻车。