EP01. "AI-Native SDLC 实战手册：从 intent.md 到写代码（Plan / Design / Build 三阶段）"

• 传统 SDLC 的六个阶段（规划/设计/构建/测试/部署/维护）是在「写代码最耗时最贵」的年代设计出来的假设——现在 AI 几分钟内能生成大量代码，瓶颈已经转移到审批、审查、部署这些还在按人类速度运作的环节。官方这门 The AI-Native SDLC Playbook（14 节课，约 1 小时，面向大型企业的工程/安全负责人）就是重新设计这整条流程
• 这不是单一功能教学，而是一套包含 12 个模块化「play」（打法） 的实施手册，横跨六个阶段，每个 play 各自讲清楚「这阶段变了什么 / 怎么开始 / 具体步骤 / 治理考量 / 怎么衡量成效」
• 这篇笔记覆盖前半段——Plan（想法怎么被捕捉成 intent.md）、Design（需求和设计怎么合并成一次 session）、Build（写代码阶段的五个打法：Plan Mode / CLAUDE.md / Skills / 并行会话 / 反馈循环）；后半段 Test / Deploy / Maintain 见 EP02
• 前置知识：知道 Claude Code 基本操作（plan mode / CLAUDE.md / hooks / subagent 这些概念），这门课假设读者是企业里要落地治理框架的工程或安全负责人，不是纯技术上手教程

重点内容

为什么传统 SDLC 撑不住了

传统 SDLC 把软件推过规划、设计、构建、测试、部署、维护六个阶段，各阶段由不同角色（PM、架构师、工程师、QA、发布团队、运维）负责，靠文档和签核在阶段之间流转。

瓶颈转移：AI 快速生成代码后，瓶颈搬到了规划、审查、部署这些还在按人类速度运作的环节——安全审查队列变长，治理例外一堆，组织被迫在「上线没审够的代码」和「卡住进度」之间二选一。

AI-Native SDLC 的核心原则

重新设计后的流程从线性变成一个持续循环，Claude 贯穿全程。关键特征：

• 自动化交接：阶段之间的交接由提交的产物触发
• 提交的产物：每个阶段都有一份提交的产物（intent.md、spec.md、代码 diff、PR、事故记录）作为下一阶段的起点
• 人力集中在真正需要判断的决策关卡，不是重复性审查
• 治理规则在执行过程中被强制执行（靠 hooks 和审批层），不是事后补审

六阶段：传统 vs AI-Native

12 个模块化 play 组成整本手册，彼此有依赖关系（用依赖图呈现），但组织可以按自己的优先级切入。一开始每一步都要人工提示，终态是全自动循环——被接受的产物自动触发下一阶段。

Stage 1 · Plan：把想法捕捉成 intent.md

传统做法：想法要经过 backlog 条目、user story、故事点、refinement 会议好几层，每次交接所有权都换一次手，理解也跟着被稀释。

AI-native 做法：提出想法的人（不一定是工程师）直接跟 Claude 头脑风暴，整理成 intent.md——「用提出者自己的话写的 proto-spec」，包含想要什么、为什么、有什么限制条件。

需要的基础设施：给非工程背景的人用的 Claude 入口（claude.ai 或 Cowork）；约定好的 intent.md 模板；版本控管的共享仓库（通常是产品仓库里一个 intent/ 文件夹）；能代表非技术贡献者提交文件的 Git 连接器。这套基础设施由平台或工程团队负责搭建，决定 intent 存放的位置和访问权限。

执行步骤：

1. 提出者用口语化的方式跟 Claude 描述问题
2. 反复讨论到具体为止（Claude 会主动问范围、使用者、限制条件、成功标准）
3. 请 Claude 套用组织模板整理成 intent.md（这一步可以直接做成一个 skill）
4. 提出者审核并修正 Claude 的输出
5. 提交进共享仓库

范例 intent.md（claims status self-service）：

# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.
## Problem
Customers phone the contact center to ask where their claim is.
## Proposed outcome
Customers see claim status, next step and expected date in the portal.
## Affected users and systems
Claims handlers, portal team, claims-core API.
## Constraints
No new PII in the portal session. Existing authentication only.
## Open questions
Do third-party loss adjusters need access too?

治理：靠 Git 历史记录作者、时间戳、修订记录当证据；产品负责人批准决定这份 intent 要不要进 Stage 2。

衡量指标：Leading——从第一次对话到提交 intent.md 的时间（预期从数周缩短到几小时）；Lagging——存活率（有多少 intent.md 真的进了 Stage 2 vs 被关掉）和提交后被改动的频率。

Stage 2 · Design：需求和设计合并成一次 session

不再把需求和设计拆成两个团队接力做，而是在一次 prompted session 里，Claude 拿着 intent.md，套用组织的 skills（品牌、安全、合规、UX 标准），同时产出 spec.md 并标注出需要关注的疑虑点。

核心 prompt 模板：「Apply the skills available to you so the plan conforms to our brand guidelines, security policies and UX standards. Document the spec fully as spec.md, ready to hand to the engineering team.」

执行步骤：

1. 产品负责人开一个已经载入组织 skills 的 session，附上 intent.md
2. prompt 引导 Claude 产出 spec.md 并标出疑虑
3. 产品负责人对照原始 intent 审核 spec
4. 团队跟对应的政策负责人处理被标出的疑虑
5. spec.md 跟 intent.md 一起提交，成对留档
6. 人工决策者批准 spec 后才能进 build 阶段

衡量指标：Leading——intent.md 到 spec.md 提交之间的时间；Lagging——build 开始后 spec.md 又被改了几次。

Stage 3 · Build：五个让「写代码」阶段变 AI-native 的打法

打法一：Claude Code Plan Mode 当默认起点

传统：工程师自己看设计就开始写代码，实作策略没有留下文档，或者只藏在 ticket 留言里，审查者看不到，直到最后看到完成的 diff。

AI-native：工作从一份 Claude 在 plan mode（只读，不改动代码库）产出的书面计划开始，工程师打磨这份计划，批准版本变成一份提交的产物。

执行步骤：

1. 用 plan mode（只读）开始 session
2. 提供 intent.md 和 spec.md
3. 请 Claude 列出实作计划——哪些文件受影响、工作顺序、验证用的测试
4. 仔细盘问这份计划：哪里可能出问题、风险点在哪、被否决的替代方案是什么
5. 反复打磨，打磨到「一个完全没参与过讨论的人光看这份计划就能照着做」
6. 批准后存成 plan.md 留档，供之后审计/验证用
7. 让 Claude 实作，计划够扎实通常一次就能做完
8. 如果实作跟计划有落差就更新 plan.md，可以考虑上 hook 强制这条规则

范例 plan.md 结构：Files Affected（具体改哪些模块/组件）、Work Sequence（有序的实作步骤）、Risk Assessment（潜在的破坏点，比如 rate-limiting 限制需要加缓存）、Validation Proof（测试覆盖细节、验收标准要对上批准过的设计）。

治理：靠 plan mode 的只读限制，让设计决策在真正生成代码之前先过一轮审查；plan 的批准要记录谁负责；标准改动由工程师自己批准，风险较高的要升级给技术主管或架构师。

衡量指标：Leading——第一次实作就能合并的改动比例、从 plan 批准到 PR 合并的时间；Lagging——每个改动要返工几次、已合并的 diff 还跟提交的 plan.md 一致的频率。

打法二：CLAUDE.md——把组织知识变成文件

核心作用：给 Claude 一个新人需要的上下文——约定、指令、架构、团队最常踩的坑。

前置条件：不需要，只要有仓库、装了 Claude Code、一个熟悉代码库的工程师。

执行步骤：

1. 在 repo 里跑 /init，让 Claude 根据发现的代码模式自动生成初版
2. 把生成的内容精简到「第一天上手真正需要的东西」——保留 build/test/lint 指令、关键约定、常踩的坑
3. 提交进 Git，放在 repo 根目录，共享 + 走 code review 式的治理
4. 持续改进的工作原则：「Claude 犯同一个错误两次，这个修正就该写进 CLAUDE.md」
5. 控制长度在一页以内，保持上下文效率

范例结构（一个 payments service）：

• Commands：build/test/lint 指令
• Conventions：Java 21 + Spring Boot 3、不新增 Lombok、金额一律用 BigDecimal 不用 double、每个 endpoint 都要在 src/itest 有集成测试
• Architecture：api/ 放 REST controller、core/ 放 domain 逻辑、adapters/ 管外部系统整合、Kafka 事件在 schemas/（生成的 class 不能手改）
• Known Issues：不要升依赖版本（归平台团队管）；legacy 的 v1/ 包冻结了，改动都进 v2/

治理：版本控管确保「agent 照着做的指令可审查、可审计」；团队约定集中在一份文件，Git 历史追踪全部改动，PR 审查时要 code owner 批准。

衡量指标：Leading——Claude 重复犯 CLAUDE.md 本该覆盖的错误的频率（靠 Git 历史追踪修正）；Lagging——新成员加入到第一次 PR 合并的时间。

打法三：Skills 当组织知识的可执行版本

核心定义：「Skills 是组织把机构知识变成可执行的方式——指令是明确的、版本控管的、广泛套用的、政策一变就能集中更新。」

判断原则：需要一致套用的知识做成 skill；组件相关的指引留在 CLAUDE.md；其他内容用 prompt。

前置条件：不强制要求，有 CLAUDE.md 会更有帮助；需要一条有明确负责人、有文档来源的政策。

执行步骤：

1. 挑一个目前执行不一致的组织知识（安全标准/API 约定/品牌指南）
2. 写成一个 skill（文件夹 + SKILL.md，frontmatter 定触发条件，正文写具体该做的动作），由工程师根据政策负责人的权威来源开发
3. 放进仓库的 .claude/skills/<名字>/，或做成 plugin 全组织分发
4. 用几种不同问法请 Claude 做相关任务，验证 skill 真的会稳定触发
5. 政策改了就更新 skill，上线前要拿到政策负责人批准
6. 工程师之后的 session 会自动拿到更新版本

范例：secure-api-review 这个 skill，涵盖认证要求（gateway JWT；除了 /health 都不能匿名）、对照 OpenAPI schema 做输入校验（拒绝未知字段）、审计日志（谁、做了什么、对什么实体、什么时间）、数据分类（PII 字段不能出现在 log/error 里）、脚本执行校验。

衡量指标：Leading——政策负责人批准到 skill 文件夹 PR 合并之间的时间；Lagging——PR 里引用该政策的发现数量应该趋近于零，如果持续出现，代表 skill 没有稳定触发或者内容跟官方政策已经脱节。

Build 阶段的硬性护栏 hooks：在 Claude 实际编辑文件/跑 shell 指令的 build 阶段特别重要——能力包括挡住对受保护路径（生成文件/冻结的 package）的编辑、编辑完自动跑 formatter/linter、防止凭证外泄、无例外地强制执行政策。设计原则：每次匹配到动作就要执行，所以要求速度快、范围限定在单一文件；重量级检查（完整测试套件）留给 commit 或 PR 阶段做；审批类的提示要放在 Stage 5 部署关卡，不要放在 build 阶段，否则会卡住并行的 session。

打法四：并行 Session 与 Subagent

Parallel Sessions：各自独立的 Claude Code 实例，在自己的 Git worktree 里做互不相关的任务，彼此互不知道对方存在，只靠盯着全局的工程师协调。

Subagents：在单一 session 里的范围受限的帮手，有自己的 context 窗口和工具限制，适合会在多个任务里重复出现的工作（比如验证应用）。

核心原则：「一个工程师同时跑好几个 Claude session，各自在自己的 worktree 里做自己的任务」——增加并行工作量，同时让每个 session 专注在单一职责上。

前置条件：所有 session 都要能参照同一份 CLAUDE.md；有反馈循环（下面打法五）能减少盯着看的需要；Git 仓库提供 worktree 隔离；权限设置好，安全指令不用每次都停下来问。

执行步骤：

1. 用 plan mode 得到的洞察，把工作拆成互不干扰、各自动不同文件的任务；会共享文件的任务留在同一个 session 里按顺序做
2. 用 claude --worktree feature-auth 这种格式各自开独立 session，各自的 worktree 对应各自的分支
3. session 数量先从 2-3 个开始，审查质量维持得住才扩大
4. 把重复出现的任务转成 .claude/agents/ 底下用 Markdown 定义的 subagent，写清楚名字、用途描述、允许用的工具

治理：基于配置的仓库级 hooks 和权限对所有 session 一视同仁地生效，动作记录都会归到发起的工程师身上。

衡量指标：Leading——每个工程师同时开几个并行 session（靠 OpenTelemetry 追踪）、花在「引导」vs「等待」上的时间比例；Lagging——每周每个工程师合并的改动数量 vs PR 历史里的返工率。

打法五：给 Claude 一个反馈循环

核心区别：反馈循环贯穿整个任务、需要跑几次就跑几次；verifier subagent 则是任务做完之后，开一个全新 context 窗口做一次性的最终检查——两者是不同的东西，不能互相替代。

传统做法：验证信号来得很晚——CI 要等几分钟、测试要等几天、生产环境要等几周，信号越晚，工程师就得审查 agent 的全部输出。

AI-native 做法：session 里就能立即验证，Claude 会自己反复迭代到检查通过，工程师才看到结果。

执行步骤：

1. 把验证包成单一指令，比如 make test 或 npm test，失败要回传非零状态码
2. 写进 CLAUDE.md，列出指令，附上「正常输出长什么样」的范例
3. 目标要可量化，比如「test_status.py 里的测试全部通过」或「endpoint 要回 200 并带上新字段」
4. 修 bug 的场景：先写一个会失败的测试，让 Claude 把 bug 重现成一条测试、确认真的失败，再动手修，过程中不能改测试本身
5. UI 相关的工作：提供截图工具和设计稿，预期要来回 2-3 轮
6. 把验证写进「完成」的判定标准里——指令要求 Claude 报告完成前必须先跑过测试
7. 用 hook 保护这条循环，防止 agent 在修 bug 过程中顺手把测试文件也改了

范例 CLAUDE.md 验证区块该包含：build 指令要求、测试执行标准（绝不能跳过/删掉失败的测试）、lint 要求零警告、报告完成前要贴出实际输出、明确指令「改代码，不要改测试」。

治理：强制执行的项目是「完成前必须验证」+ 用 hook 限制测试文件被修改；证据来源是 build 工具/测试跑分器/截图比对的原始输出；记录在 session 记录（透过 OpenTelemetry 导出）和 PR check run 里；code owner 审查 PR 时能专注在「意图对不对」，因为机械性的验证证据已经附上了。

衡量指标：Leading——agent 写的改动第一次跑 CI 就成功的比例；Lagging——每个 PR 的审查时间、事故追踪系统里的 change failure rate。

学完你会

• ✅ 讲得清传统 SDLC 的假设为什么在 AI 时代站不住脚，瓶颈实际转移到哪里
• ✅ 知道 intent.md/spec.md/plan.md 这三份产物分别在哪个阶段产生、谁负责批准、怎么留档
• ✅ 会用 Plan Mode 当每个实作任务的默认起点，而不是直接跳进去写代码
• ✅ 分得清 CLAUDE.md（组件级上下文）、Skills（需要一致套用的政策）、Hooks（硬性强制）三者各自该放什么内容
• ✅ 知道怎么把工作拆成能并行跑的 Session，什么时候该转成 Subagent
• ✅ 会给 Claude 设计一个贯穿任务的反馈循环，而不是等事后再人工审查全部输出

常见错误

• ❌ 把治理全部押在「事后人工审查」上，不设计任何贯穿执行过程的护栏——AI-native SDLC 的核心是把治理规则透过 hooks 和批准关卡嵌进执行过程本身，而不是事后靠人力补审
• ❌ Skills 写完就以为政策已经强制生效了——Skills 是「建议型」控制，只是让合规更容易发生，不是保证；真正的强制要靠 hooks 挡、PR 阶段 review pass 再查一次
• ❌ CLAUDE.md 越写越长，把整个项目文档都塞进去——控制在一页以内，只留新人第一天真正需要的：指令、关键约定、常踩的坑
• ❌ 反馈循环跟 verifier subagent 搞混——反馈循环要贯穿整个任务反复跑；verifier subagent 是做完之后另开一个新 context 做单次最终检查，两者不能互相替代
• ❌ 修 bug 时让 Claude 顺手把不通过的测试改掉或删掉——反馈循环要设 hook 保护，过程中不允许碰测试文件，只能改代码本身
• 💡 并行 Session 一开始别贪多，从 2-3 个开始，确认审查质量维持得住（不会因为盯不过来而漏审），才逐步往上加

Sources

官方文档：

1. The AI-Native SDLC Playbook（课程总览）— https://academy.claude.com/courses/ai-native-sdlc-playbook
2. Introduction — https://academy.claude.com/courses/ai-native-sdlc-playbook/introduction
3. Capture as intent.md — https://academy.claude.com/courses/ai-native-sdlc-playbook/capture-intent
4. Requirements and design — https://academy.claude.com/courses/ai-native-sdlc-playbook/requirements-and-design
5. Claude Code plan mode as the default starting point — https://academy.claude.com/courses/ai-native-sdlc-playbook/plan-mode
6. The CLAUDE.md — https://academy.claude.com/courses/ai-native-sdlc-playbook/claude-md
7. Skills as institutional knowledge — https://academy.claude.com/courses/ai-native-sdlc-playbook/skills-as-institutional-knowledge
8. Parallel sessions and subagents — https://academy.claude.com/courses/ai-native-sdlc-playbook/parallel-sessions-and-subagents
9. Give Claude a feedback loop — https://academy.claude.com/courses/ai-native-sdlc-playbook/give-claude-a-feedback-loop