AI Engineering · Agentic Software Development

AI 原生 SDLC 学习手册：
用制品链重构软件交付流程

当写代码不再是瓶颈，流程本身就成了瓶颈。这本手册把 Anthropic 的六阶段 playbook 拆解为可执行的实践：每个阶段以提交一个制品结束，下一个阶段以读取它开始，而人类的注意力集中在门禁上。

AI-Native SDLCClaude Codeintent.mdCLAUDE.mdSkills · Hooks持续评估治理与审计

基于 Anthropic《The AI-Native SDLC Playbook》（2026-08-21）提炼、重组与中文实践化整理。

传统 SDLC 为何失效

组织已经能以一年前不可想象的速度用 AI 写代码，但代码周围的流程没有同步进化——审批门、评审、交接、策略都还是为人类产出设计的旧样子，agentic coding 带来的生产力收益被卡在半路。

传统 SDLC 覆盖计划、设计、构建、测试、部署、维护六个阶段，每个阶段由不同角色拥有：产品经理写需求，架构师转成设计，工程师实现，QA 验证，发布团队上线，运维监控。它为“写代码是最耗时、最昂贵环节”的时代优化——PRD、估算仪式、安全评审都是为了在数周到数季度的开发周期里强制对齐。当构建阶段坍缩为几个小时，三件事同时发生：

构建不再是约束之后，什么坏了

01 · 瓶颈转移

构建左右两侧的环节——计划、评审/测试、部署——仍以人类速度运行。人类速度的阶段保持原长，构建却坍缩为数小时，前者成为新约束。

02 · 控制与现实失配

逐行人审在“代码由人写”的前提下合理；一旦 diff 的大部分由 agent 产出，这套控制就追不上现实，变得难以执行。

03 · 治理成本上升

例外仍然要经过每周或每月开会的委员会与审批流程，排队时间随产出线性增长。

以安全评审为例：安全团队按人类产出配置人力。当 agent 让代码产出成倍增长，要么评审队列堆积，要么代码带病上线——受监管的组织两者都不能接受。所以结论是：SDLC 流程本身需要一场与实现阶段同等级别的变革。

AI 原生 SDLC 全景：从线性流程到制品驱动的闭环

AI 原生 SDLC 不是给旧流程加装插件，而是保留旧的控制目标（问责、可审计、风险可控），换上新的执行方式。最根本的结构变化有两个：流程从线性变成闭环，AI 嵌入每个点；阶段之间的交接由“制品提交”自动触发，消除传统 SDLC 手工、笨重的 handoff。你也可能听到 agentic SDLC、AI SDLC 等叫法——它们描述的是同一件事。

阶段	传统 SDLC	AI 原生 SDLC
Plan	委员会收集需求，经工作坊与签字提炼，手工撰写成文	Claude 直接从源头综合痛点，捕获进 `intent.md`——人可读、机器可执行
Design	分析师写 spec，设计师再解析 spec	需求与设计压缩为与 agent 的一次工作会话，由编码为 skills 的标准引导，版本控制于 git
Build	测试与代码手写，文档在开发结束后补	测试与代码由 AI 生成，制度知识维护为版本控制的机器可读 `CLAUDE.md` 与 skills
Test	阶段边界上的 QA 门	持续评估（evals）编织进实现过程
Deploy	人审每一行代码；治理在评审周期中进行，且常常不一致	多层 agent 评审，人类评审保留给受监管与关键代码；治理随 agent 行动实时执行，hooks 即审批门
Maintain	人盯着生产环境找 bug	agent 监视线上部署；控制带宽被击穿即被诊断，并回写为新的 `intent.md`

贯穿全程的线索：被提交的制品

右列的共同点是被提交的制品（committed artifact）：每个阶段以向版本控制提交一个制品结束，下一个阶段以读取它开始。早期阶段以 .md 文件为主，因为产品负责人和 agent 能读同一个文件并各自行动；从 Build 起，制品变成代码及其记录。提交链同时就是审计链：谁要了什么、agent 产出了什么、谁批准了什么。

SDLC 闭环 · 每阶段提交一个制品，触发下一阶段

├─ Plan → intent.md（意图：想要什么、为什么、什么约束）

├─ Design → spec.md（需求 + 设计：在组织 skills 约束下生成）

├─ Build → plan.md → diff 与测试（计划先于实现，diff 对照计划）

├─ Deploy → PR + 评审记录（人类审批在门禁处发生）

└─ Maintain → 事件记录 → 回写为新的 intent.md，回到起点

与遗留系统共存：先定“事实来源”

现有流程多半已经在 Jira、带监管追溯的需求工具、Figma、变更委员会里跟踪这些制品。这些系统难以取代——审计方已经接受它们，其他团队依赖它们。规则是：为每个制品指定唯一的事实来源，其余系统只保存副本或链接。

配置	做法	适用
仓库为准	markdown 制品是权威记录，遗留系统引用 commit 中的文件	工程主导型组织最干净：所有记录在同一工具、同一时间戳权威下
遗留系统为准	Jira / ServiceNow / 需求工具持有权威记录，markdown 是工作副本；Claude 会话开始时读取记录，结束时经 MCP 连接器写回	审计与合规强依赖既有工具的组织
链接（最低标准）	所有制品标注记录 ID，所有遗留记录包含 markdown 文件的 commit SHA	过渡起步阶段：接受两个事实来源并存，但必须互联

人类的角色没有被削弱：每个需要判断的决策仍由人负责。变化的是注意力的位置——从“逐行检查产出”上移到“在门禁处审查 agent 标记出来的东西”。循环持续运转，人类判断保持在它之上。

Plan：想法不再等待别人来写文档

意图被一次性捕获——用发起人自己的语言——作为版本控制中的制品，供下一阶段直接使用。intent.md 有三个入口：人有想法、工单被提交、告警触发的事件（见第 08 节 Maintain）。无论入口是人、事件触发还是 agent，规则相同：产品负责人在提交前评审并修正 agent 写的 intent.md。

传统

想法要排队翻译

一个想法要经过 backlog 条目、用户故事、故事点、refinement 会议才能被行动。每次交接都在转移所有权，到达工程的东西与发起人的本意已隔了数层。

AI 原生

发起人直接产出 proto-spec

发起人与 Claude 头脑风暴，把结果用自己的语言写成 intent.md：想要什么、为什么、在什么约束之下。重复流程编码为 skills。不再需要说服产品团队替你写文档。

基础设施

给非工程师的 Claude 访问（claude.ai 或 Cowork）；一份约定的 intent.md 模板。
共享的版本控制“意图之家”：单一产品最简单是产品仓库里的 intent/ 目录，让制品链紧邻由它派生的代码；跨多仓库才值得独立 intent 仓库。
不会用 git 的贡献者不必直接碰 git——通过版本控制系统的连接器（如 GitHub），Claude 可以在 claude.ai / Cowork 里代表他们提交 markdown 文件。

执行步骤

发起人用自己的话向 Claude 描述问题：今天做不了什么、谁受影响、更好是什么样、什么不在范围内。不需要任何正式语言。
头脑风暴直到想法具体。Claude 会问分析师该问的问题：范围、用户、约束、成功标准。
让 Claude 按组织模板把结果写成 intent.md（模板可由技术成员编码为 skill 并由负责人签字）：问题、建议结果、受影响的用户与系统、约束、开放问题。
发起人修正 Claude 理解错的地方。
提交 intent.md 到共享之家。作者与时间戳进入记录，产品负责人从这里接手。

# Intent：理赔状态自助查询
Author：J. Ortiz（理赔运营）。Status：draft。

## Problem
客户打电话到客服中心询问理赔进度。
话务员约三分之一的通话时间花在“仅查状态”的来电上。

## Proposed outcome
客户在门户中看到理赔状态、下一步动作与预期完成日期。

## Affected users and systems
理赔话务员、门户团队、claims-core API。

## Constraints
门户会话不引入新的 PII。仅使用现有认证方式。

## Open questions
第三方公估人是否也需要访问？

治理与度量

治理证据就是被提交的 intent.md 本身：作者、时间戳与完整修订史都在意图之家的 git 历史里。接受或拒绝、把意图送进 Design 的决定，记录为该制品的 merge 或关闭的评审。

先行指标

从首次对话到 intent.md 提交的耗时

从意图之家的 git 历史读取。预期从数周的需求引导与 refinement 周期降到数小时。

滞后指标

存活率

被产品主人接受进入 Design 的 intent.md 占比（merge 或关闭的评审即决定记录）；以及同一变更的 spec.md 首次提交之后，intent.md 还被改了多少次。

Design：需求与设计坍缩为一次会话

策略在 spec 写作时就被应用，而不是数周后在评审里才被发现。产品负责人把已接受的 intent.md 交给 Claude，产出一份需求与设计 spec——受组织 skills（品牌、安全、合规、UX）约束。产品负责人评审 spec，但不撰写它；目标是产出工程团队可以直接做计划的 spec，且关注点已被标记出来。

前端工作是最清晰的例子：intent.md 被接受后，产品负责人在 Claude Design（beta）里从 intent 出发做设计稿、迭代 mock，然后导出到 Claude Code 实现。

传统

两个团队、两个阶段

分析师把想法形式化为需求，设计师再把需求解析回设计。分离是为了问责，但既慢又有损——每次转译都在丢失信息。

AI 原生

一次提示会话

Claude 读取 intent.md，在组织 skills 的约束下产出需求与设计 spec，并标记出关注点——尤其是无法同时满足相互冲突策略的地方。

执行步骤

产品负责人打开加载了组织 skills 的会话，附上 intent.md。
提示词指向 intent、点名约束、要求标记关注点。先手工运行；再固化为组织级 slash command；最终让 intent 之家的 merge 事件触发一个非交互 job——加载 skills 跑同一遍流程，把 spec.md 作为 PR 提交。此后产品负责人的首次介入就是评审本身。
同一产品负责人对照想法评审 spec：它是否解决了陈述的问题？intent 里的开放问题被回答还是被延续？
优先处理被标记的关注点——它们就是分析师本会升级的问题。每个关注点在其策略负责人那里解决，之后 spec 才能见到工程。
spec.md 与 intent.md 一起提交。这对文件记录了“要什么”与“决定了什么”。
产品负责人决定 spec 与 intent 是否进入 build（组织定义为高风险的事项咨询技术负责人）。这个决定永远由人做，接受 spec 即触发 Build 的计划模式。

提示词示例

阅读附带的 intent.md，为把它集成进现有代码库产出一份需求与设计 spec。
运用你可用的 skills，使方案符合我们的品牌指南、安全策略与 UX 标准。
将 spec 完整写成 spec.md，可直接交给工程团队。
清晰描述所有关注点，尤其是无法同时满足相互冲突策略的地方。

治理与度量

活的策略在 spec 写作的同时被读取并应用；组织 skills 作为 spec 的约束生效。spec、产生它的提示词、生效中的 skill 版本全部进入版本控制。产品负责人签署 spec，并把标记的关注点路由到具名的策略负责人。

先行指标

intent 提交 → spec 提交的间隔

同一变更的两个 git 时间戳之差，与旧的需求 + 设计周期对比。

滞后指标

build 开始后的需求返工

统计同一变更中日期晚于首个 plan.md 提交的 spec.md 提交次数——git log 直接给出。

Build：没有已接受的计划就没有实现

制度知识变成 agent 读取的文件，护栏以代码而非习惯运行。这一阶段集中了 playbook 最多的小玩法：计划模式、自动模式、CLAUDE.md、skills、hooks、并行会话。

计划模式（plan mode）作为默认起点

工程师以 plan mode 开始 Claude Code 会话，交给 Claude 已批准的 spec.md，让它反过来“面试”工程师，迭代计划直到满意。计划模式下 Claude 只能读代码不能改；被批准的计划提交为 plan.md——Deploy 阶段的 PR 评审会检查最终 diff 是否符合它。设计评审因此发生在任何代码生成之前，此时改方向只是编辑一份文档。

工程师在 plan mode 中开始会话，给出 intent.md 与 spec.md，要一份实现计划：点名哪些文件会变、工作顺序、证明它的测试。
审问计划：这个变更可能破坏什么？哪一步最险？Claude 放弃了哪些别的选项？
迭代到一个从未见过这段对话的工程师也能仅凭计划实现这个变更。
提交被批准的计划为 plan.md。计划加入审计链；接受计划后让 Claude 实现——有扎实的计划时，实现往往一遍过。
实现偏离计划时，在同一 commit 里更新 plan.md；可以用 hook 强制两者同步。

# Plan：理赔状态自助查询（源自 intent.md 2026-06-02）

## Files that change
portal/src/claims/StatusPanel.tsx（新增）、claims-api/routes/status.py、
claims-api/tests/test_status.py

## Order of work
1. 在现有认证之后新增 status 端点。
2. 面向该端点实现面板。
3. 接入门户导航。

## Risks
claims-core API 限流 50 rps；面板必须做缓存。

## Proof
test_status.py 覆盖四种理赔状态；截图与已批准的设计稿一致。

自动模式与并行推进

Claude Code 还可以跑在 auto mode：工程师批准计划后，Claude 无需逐次编辑确认地应用每个变更。随着后续护栏成熟——调教过的 CLAUDE.md、编码策略的 skills、阻断危险动作的 hooks、Claude 能自己跑的测试套件——auto-accept 成为常规工作的默认：精炼的 spec、小爆炸半径、测试已覆盖的代码。重心的转移是从“盯着 agent 的每次编辑”变成“长自主会话之后评审制品”；配合 worktrees，它也是团队级并行与最终闭环自治的基础。

并行会话

一个工程师驱动多条工作流

并行会话是另一个完整的 Claude Code 实例，在独立的 git worktree 里做独立任务；彼此一无所知，唯一共享的是指挥它们的工程师。按计划拆分互不触碰文件的任务，共享文件的任务放进同一会话顺序执行。两三个会话是合理起点——实际上限是一个人能认真评审多少条流。

子代理

会话内的 scoped 助手

子代理跑在单个会话内部，有自己的上下文窗口与工具限制，适合在多个任务里重复出现的工作：精简代码、验证应用行为、探索代码库并汇报而不淹没主上下文。定义放在 .claude/agents/ 并提交进 git，全团队共享。

---
name: verifier
description: 在会话报告完成前运行应用并检查变更是否生效
tools: Bash, Read
---
用 make run 启动应用。执行被变更的行为以及最相邻的两个流程。
报告你运行了什么、看到了什么，以及任何与 plan.md 不符的行为。
不要修复任何东西；只报告。

CLAUDE.md：新同事入职第一天需要的一切

CLAUDE.md 给 Claude 一个新加入者需要的上下文：约定、命令、架构、团队最常见的错误。过去放在人脑和 wiki 里的知识，变成 agent 在每个会话开始时读取的文件——由全团队维护，每次犯错就迭代一次。

在仓库里跑 /init，Claude 从它看到的东西生成初稿。
把生成物裁剪到“新同事第一天需要的”：构建/测试/lint 命令、真正要紧的约定、Claude 反复出错的地方。
提交到仓库根目录，全团队共享一个版本，像代码一样评审变更。
一条工作经验：同一个错误犯第二次，修正就进 CLAUDE.md。
保持一页以内——Claude 每次会话都全文读取，过期内容在白白消耗上下文。

# Payments service

## Commands
- 构建：make build
- 测试：make test（单元）、make itest（集成，需要 docker）
- Lint：make lint（CI 会跑；推送前修掉）

## Conventions
- Java 21、Spring Boot 3。不新增 Lombok。
- 金额一律 BigDecimal，绝不用 double。
- 每个端点在 src/itest 有对应的集成测试。

## Architecture
- api/ 放 REST 控制器，core/ 放领域逻辑，adapters/ 对接外部系统。
- Kafka 事件定义在 schemas/；不要编辑生成类。

## Things Claude gets wrong
- 不要升级依赖版本；由平台团队负责。
- 遗留的 v1/ 包已冻结；改动进 v2/。

Skills：可操作的制度知识

skills 是组织把制度知识变得可执行的方式：指令显式、版本控制、被广泛应用、策略变化时集中更新。经验法则：必须被一致应用的制度知识写成 skill；属于组件级别的信息放 CLAUDE.md 或提示词。skill 是一个文件夹，内含 SKILL.md——frontmatter 声明何时触发，正文说明做什么。放在 .claude/skills/<name>/ 随代码交付，或通过 plugin 全组织分发。策略变更时改 skill 并由策略负责人签收，工程师在下次会话自动拿到新版本。

---
name: secure-api-review
description: 应用 API 安全标准。凡是创建或修改对外端点、
  评审 API 代码、生成 OpenAPI spec 时使用。
---
# Secure API review

创建或修改 API 端点时：
1. 认证：每个端点都要求网关 JWT；除 /health 外不允许匿名路由。
2. 输入校验：请求体按 OpenAPI schema 校验，拒绝未知字段。
3. 审计：每个改状态的端点发出审计事件，含 actor、action、
   entity 与 timestamp。
4. 数据分级：schema 中标记为 pii 的字段绝不出现在日志或报错中。

运行 scripts/check-endpoints.sh，并把输出附进你的总结。

skill 是“咨询性控制”：它让 Claude 很可能在写代码时就应用策略，但没有任何东西强制会话服从。必须永远成立的策略要有确定性层兜底——hook 阻断动作，或 PR 处的复检 pass。skill 让违规变稀有，hook 让违规接近不可能。skill 调用记录在会话 trace 里，策略负责人像评审代码一样评审 skill 变更。

Hooks：构建期护栏

Claude 在实现期的动作大多是文件编辑与 shell 命令，所以构建阶段是 hooks 触发最频繁的地方。构建期 hooks 可以：阻断对受保护路径的编辑（生成代码、冻结的包）；每次编辑后自动跑 formatter 与 linter，让漂移永不累积；把凭据挡在 diff 之外。hook 在每个匹配的动作上都会运行，因此要快、且限定在变更的文件上；更重的检查（全量测试）属于 commit 或 PR。需要人批准的 hook 属于 Deploy 阶段的门禁——构建期弹批准提示，会把人放回所有并行会话的关键路径上。

仓库里的配置全景

repo/（引导 agent 的一切都版本控制在这里）

├─ CLAUDE.md —— 每次会话读取的团队工作知识

├─ REVIEW.md —— PR 评审策略（Deploy 阶段）

└─ .claude/

├─ skills/<name>/SKILL.md —— 编码为技能的组织策略

├─ agents/verifier.md —— 子代理定义（名字、触发条件、可用工具）

└─ settings.json —— hooks 与权限（团队级；不可协商的进托管设置）

* 以上全部随代码评审、随 git 留痕，构成可审计的“agent 行为配置层”

先行指标

首过合并率与计划到合并耗时

从首次实现就直接合并的变更占比；计划批准 → PR 合并的时间（PR 元数据可得）。

滞后指标

返工与计划一致性

每个变更的返工周期数；合并的 diff 与提交的 plan.md 仍然吻合的频率。CLAUDE.md 另看两条：Claude 重复犯已知错误的频率（先行），新成员首个合并 PR 的时间（滞后）。

Test：会话先自检，配置也做回归

两个原则：每个会话在人类看到之前先检查自己的工作；引导 agent 的配置（CLAUDE.md、skills、hooks）像代码一样接受回归测试。

给 Claude 反馈回路

永远给 Claude 一种验证自己工作的方式——测试、构建或截图 diff。会话自检并修复自己的错误，工程师看到的产物已经通过检查。注意区分两个概念：反馈回路贯穿整个任务反复运行；verifier 子代理是会话认为完成后、用全新上下文窗口做的一次最终检查——裁决不被产生代码的那套假设污染。

如果检查工作今天需要一串命令加环境知识，把它封装成单一目标：make test 或 npm test，失败时非零退出。
在 CLAUDE.md 的 Commands 区列出每条命令与健康输出的示例。
目标要可量化，让 Claude 不用问你就能判定：“test_status.py 全绿”“截图与附带的 mock 一致”“端点返回 200 且带新字段”。
修 bug 先写失败的测试：让 Claude 把 bug 复现成测试，运行并确认按预期失败，提交这个测试；然后才让 Claude 在不许编辑测试的前提下修到通过（test-file hook 强制这一限制）。先于修复存在、且 agent 改不动的测试，才是 bug 已死的证明。
UI 工作用视觉检查闭环：给 Claude 浏览器或截图工具、给 mock，让它“实现 → 截图 → 对比 → 调整”。两三轮很正常，每轮都应更好。
把验证写进“完成”的定义：CLAUDE.md 指示——报告任务完成前跑齐三项并粘贴输出。
保护回路本身：修代码的 agent 不能弱化对该代码的检查——用 hook 阻止 fix 任务中编辑测试文件；或者在评审里拒绝任何触碰测试的变更。

## Verifying your work

- 构建：make build（必须以 “Build succeeded” 结束）
- 测试：make test（全绿；绝不跳过或删除失败的测试）
- Lint：make lint（零告警）

报告任何任务完成前运行以上三项，并粘贴输出。
测试失败时，修代码，而不是修测试。

CI 中的持续评估（continuous evals）

evals 是 AI 原生世界里阶段门 QA 的等价物：当换入新模型、改写提示词、修改 CLAUDE.md / skills / hooks 时，评估套件回答“agent 是否仍按同样标准工作”。把它当活套件维护——模型进步后，曾经能区分好坏的用例会失效，需要从持续监控中补充新用例。

平台工程师从近期工作中收集 20–50 个真实任务及其可接受结果。
每个任务写成一个 eval：提示词 + 定义“可接受”的检查（测试通过、lint 干净、行为不变、策略被遵守）。
套件在 CI 中非交互运行：按计划，以及在 CLAUDE.md、skills、hooks 任何变更时——这些配置引导 agent，值得获得代码级别的回归测试。
以结果门禁配置变更：一个让通过率下降的 skill 变更，先评审再合并。
每个生产事故都变成一条 eval，由负责该事故的团队编写，并作为回归测试留在套件里。

name: Agent evals
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**']
  schedule:
    - cron: '0 2 * * *'
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - name: Run eval suite
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          for eval in evals/*.json; do
            claude -p "$(jq -r '.prompt' $eval)" \
              --allowedTools "Read,Edit,Bash(make test)" \
              --output-format json > result.json
            ./evals/check.sh "$eval" result.json
          done

治理上，evals 给了 QA 一个追得上 agent 产出的门：通过率阈值作为 merge 检查执行，运行被记录以便跨时间对比，配置变更由拥有它的团队批准。

先行指标

CI 首过通过率

agent 所写变更的首次 CI 成功率（CI 系统原生支持）；eval 侧看通过率趋势与“事故变成永久 eval”的耗时。

滞后指标

评审时间与逃逸回归

每 PR 评审时间（应随测试接住评审员曾接住的问题而下降）、变更失败率；CI 拦下的回归 vs 生产发现的回归。

Deploy：双向评审，治理随行动执行

评审双向运行：Claude 按组织策略评审进站 PR，也处理自己 PR 上的评审意见。工程师的评审注意力上移一层——判断意图与风险。agent 做到生产门禁为止的一切，不越雷池一步。

PR 评审回路中的 AI

托管 Code Review 服务最快起步：管理员启用并选择仓库。需要自控管线时，用自己的 CI 跑 claude-code-action，模型调用可经 Bedrock / Vertex / Foundry 走自有云协议。
技术负责人把评审策略写成仓库根目录的 REVIEW.md：组织关心的 passes（bug 与逻辑错误、安全与漏洞、对照 spec.md / plan.md 与设计原则的合规）、Important 与 Nit 的分界、跳过项。
设置人类阈值：findings 本身不批准也不阻塞 PR；分支保护仍要求 code owner 批准。需要以 findings 门禁合并的平台，可以读 check run 发布的严重度计数（机器可读）。
评审者或作者在意见上 tag @claude，Claude 处理意见并推送修复；PR 线程同时记录请求与变更。对 Claude 自己开的 PR 可以更进一步：用自定义 slash command 让它“看护”PR——扫未解决意见与失败检查、修复、推送，直到全绿只剩 code owner 批准。
评审发现回馈 CLAUDE.md：同类错误第二次被标出，修正就随这次评审写进 CLAUDE.md——评审也读 CLAUDE.md，于是从下一个 PR 起就能拦住。评审同时标记 CLAUDE.md 已被变更弄过期的情况。
每月由技术负责人调优：给 findings 评级让评审者变好、在 REVIEW.md 里限制 nit 量、排除生成路径与 CI 已强制的内容。

# Review instructions

## Passes
跑三个 pass，每个 finding 标注所属 pass：
- Bugs：逻辑错误、边界破坏、隐性回归
- Security：注入风险、认证缺口、日志中的 PII
- Compliance：变更符合 spec.md、plan.md 与我们的设计原则

## Important 在这里的含义
Important 只留给会破坏行为、泄露数据或违反策略的 finding。
风格与命名是 nit。

## Nit 上限
每次评审最多报 5 个 nit；其余汇总为计数。

## 不要报告
src/gen/ 下的生成文件，以及 CI 已强制执行的任何内容。

职责分离得以保留：写代码的 agent 没有任何批准它的路径。REVIEW.md 的策略作用于所有 PR；findings、修复、评级与批准都记录在 PR 历史里——PR 即审计记录。

Hooks 作为审批门禁

Build 阶段的 hook 无人参与，只 allow / block；hook 还可以 ask——暂停动作直到指定的人批准，这正是发布门禁需要的。它并不只属于部署：Build 期阻止无变更工单的迁移与基础设施编辑、Test 期阻止改测试文件，都是同一机制。

工程领导层会同变更管理与合规，列出必须保留的人工审批门：变更签字、发布授权、受保护路径编辑。
平台工程师把每个门表达为 hook——在 Claude 行动前运行的脚本，可以 allow、ask 或 block。
团队 hooks 进 git 里的 .claude/settings.json；不可协商的 hooks 进平台 / IT 管理员拥有的托管设置，个人工程师关不掉。
block 要自我解释：hook 拦下动作时，原因与获得批准的路径要出现在 Claude 的输出里。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
# 生产部署需要具名的发布授权
cmd=$(jq -r '.tool_input.command' < /dev/stdin)
if [[ "$cmd" == *"deploy"* && "$cmd" == *"production"* ]]; then
   if [ -z "$RELEASE_APPROVAL" ]; then
     echo "Production deploys need a release authorization." >&2
     exit 2  # exit 2 阻止动作；消息会传给 Claude
   fi
fi
exit 0

受监管企业的托管设置：每行买到什么控制

permissions.deny 把密钥挡在 agent 上下文之外、封死工具级网络出口；allow 预批安全内循环，别让 deny 清单变成提示疲劳。
disableBypassPermissionsMode + allowManagedPermissionRulesOnly：任何工程师、项目文件或命令行参数都无法放宽规则。
sandbox 补上权限管的空白：工具级 deny 拦不住 shell 命令联网，OS 级域名白名单直接封死出站；failIfUnavailable 让沙箱成为门——初始化不了就拒绝启动，沙箱内失败也不许在沙箱外重试。
credentials 拦截沙箱内 shell 对 ~/.ssh、~/.aws/credentials 的读取，并从每个沙箱命令的环境里剥离具名密钥。
allowManagedHooksOnly：本节的审批门是唯一运行的 hooks，本地加不了也换不掉；插件市场白名单与最低版本门槛保证每个 skill、hook、MCP 服务器都来自组织批准的渠道与经过评估的构建。

把它当裁剪的起点，而不是照抄的模板：每个 deny 都在换掉一部分能力，正确的平衡取决于仓库的数据分级。

CI/CD 集成与部署

在管线内非交互地运行 Claude Code，沙箱化执行让长时 agent 安全运行，部署能力经 MCP 暴露，并在 agent 需要回滚之前就把回滚路径演练到熟。

从只读的判断步骤起步：用 claude -p 分诊失败构建、总结 flaky 测试、起草 changelog。
在既有门禁之后加写步骤（修 lint、更新生成文档、处理 @claude 意见）。agent 写的一切以 PR 到达——没有直推 main 的路径。
执行沙箱化：agent 任务跑在容器与网络策略下，持短生命周期 scoped token，默认不持任何生产凭据。
经 MCP 暴露部署：deploy、status、rollback 成为按环境限定的工具——agent 的部署能力是一份白名单，而不是一个带凭据的 shell 脚本。
按环境分层自治：开发环境自由部署；staging 居中；生产由 agent 准备发布、发布经理授权、hook 强制生产门。
回滚是管线里演练最充分的路径：一条 agent 能跑的单一命令，且在 staging 定期演练——Maintain 阶段的闭环会调用它，所以必须提前证明可用。

- name: Triage failed build
  if: failure()
  run: >
    claude -p "读取构建日志 out/build.log。找出最可能的原因，
    判断失败看起来是 flaky 还是真实回归，并为 PR 线程写一段
    三行总结。" >> triage.md

先行指标

首次评审时间

应降到分钟级；以及无需人触碰分支即解决的意见占比。hooks 侧看每个审批门的等待耗时（OTel 导出带时间戳与 allow/block 裁决）。CI/CD 侧看无需呼人的失败分诊占比。

滞后指标

拦截 vs 逃逸

合并前拦住的缺陷与漏洞，对比逃逸到生产的（PR 历史 + 事故跟踪器）；门禁违规到达生产的前后变化；DORA 指标。

Maintain：闭环合拢，无人启动的回路

前五个阶段都由人启动初始步骤；这一阶段把焦点转向自主运行：触发器在没有任何人参与调用路径的情况下唤起 Claude，它的发现以 intent.md 重新进入管线。回路头部无人，阶段之间设独立的置信门——确定性检查或对抗性评审 agent——决定上一阶段的产出是继续还是升级给人。

关闭回路：确定性检测 + 分层响应

一个确定性脚本监视生产，在控制带宽（control band）被击穿时调用 Claude。检测完全确定性、无模型参与：滚动窗口的均值与标准差，配合 Western Electric 类规则，让带宽既抓尖峰也抓缓慢漂移；脚本本身版本控制且带单测。响应分层定义在版本控制的配置里：

1σ：只记录日志。
2σ：调用 Claude 做只读诊断（工具限定为 Read、Grep、查看 CI 运行）。
3σ：Claude 可以行动——但只能开 PR 进评审门，或触发预批准的 runbook（如回滚部署）。

服务负责人或平台工程师选一个有稳定滚动基线的指标：CI 测试失败率、部署后 5xx 率、PR 周期时间。
写检测脚本（均值 + 标准差 + 规则），版本控制、单元测试。
在版本控制的配置（bands.yaml）里定义响应分层。
触发层可以是定时 workflow、监控栈的 webhook 或网络内 Cron。Claude 无状态非交互运行——CI runner 上的一步或沙箱容器里的 Agent SDK 服务。因为运行无状态且非交互，回路可以在无人启动的情况下开始和结束。
agent 把诊断写成 Plan 阶段格式的 intent.md：异常与证据、建议结果、受影响系统、开放问题。从此这条发现像任何变更一样走管线。
服务负责人或值班工程师分诊队列：立即修、排期、驳回。驳回用于调带宽、降噪声。
修复上线后，为该事故类加一条 eval（持续评估玩法），此后对这类问题持续设防。

metric: ci_test_failure_rate
baseline: rolling_30d
rules: western_electric
tiers:
  1sigma: { action: log }
  2sigma: { action: diagnose,
            tools: "Read,Grep,Bash(gh run view *)" }
  3sigma: { action: propose,
            routes: [pull_request, runbook:rollback-deploy] }

回路的三个实例

CI 测试失败率破 3σ：agent 隔离 flaky 测试或开 revert PR，由评审门裁决。
部署后 5xx 率破 3σ 且窗口内有部署：agent 触发既有的回滚管线。
PR 周期时间触发漂移规则：agent 给工程领导层写报告——这套 harness 对流程指标同样有效。

周期性代码库扫描

一次安全扫描是“特定模型对特定时点代码库”的陈述，而两半都会过期：代码每周都在变，每一代模型都能发现上一代漏掉的漏洞。AI 原生的答案是按计划运行扫描、调用路径中无人，发现走与其他变更相同的门禁。Claude Security 是其托管形式：连接 GitHub 仓库后在 Anthropic 基础设施上按计划扫描，每个发现在报告前先被验证并附置信度；能装进一个 PR 的修复经 Claude Code on the Web 走 PR 评审门，更大的问题（架构弱点、跨服务重复的模式）写成 intent.md 从 Plan 走起。覆盖率从最近一次运行算起，而不是从第一次。确定性检查留在 CI，模型驱动的扫描补上它们不擅长的、依赖上下文的漏洞。

Claude Tag：值班频道里的第一响应者

事故也会从沟通工具抵达——晚上十点事故频道里的一条紧急修复请求。Claude Tag（公开 beta，现于 Slack）让 Claude 以自己的身份成为频道成员：每次事故都有第一响应者，响应本身成为未来事故的回路与记忆。对话与制度知识留在频道里，任何成员都能实时引导与求证；频道历史本身增加可审计性。通过 MCP，Claude 验证指标回到基线并在线程里确认，把 post-mortem 写进版本控制的 lessons 文件供未来调查读取。被 tag 的工单同样处理：小而边界清晰的修复以 PR 过评审门，更大的写成 intent.md 进入 Plan——回路开始自喂养。

先行指标

击穿 → 入队耗时

从带宽击穿到 intent.md 出现在分诊队列的时间（检测脚本日志含击穿时间戳与层级），对比旧流程从事故到 post-mortem 行动的时间。

滞后指标

修复转化与重复事故

分诊队列中变成合并修复的发现占比；同类重复事故应随修复与 eval 积累而下降。扫描侧另看：计划内仓库占比、扫描发现 vs 生产/外部报告、多次扫描后单次发现数的下降趋势。

度量与落地路线

每个玩法都定义了先行指标（方向是否正确）与滞后指标（是否真的有效），且几乎全部来自已有的数据源：git 历史、PR 元数据、CI 日志、事故跟踪器、OTel 导出——不需要新建度量体系。

各玩法度量总表

阶段 · 玩法	先行指标	滞后指标
Plan · intent 捕获	首次对话 → intent.md 提交耗时	存活率；spec 首提后 intent 的改动数
Design · 需求设计会话	intent 提交 → spec 提交间隔	build 开始后的 spec 返工次数
Build · 计划模式	首过即合并的比例；计划批准 → 合并耗时	每变更返工周期；diff 与 plan.md 一致率
Build · CLAUDE.md	重复犯已知错误的频率（git 历史可查）	新成员首个合并 PR 的时间
Build · 并行会话	人均并发会话数（评审质量保持前提下）	人均周合并数 + 返工率
Test · 反馈回路	agent 变更的 CI 首过成功率	PR 评审时间；变更失败率
Test · 持续评估	eval 通过率趋势；事故 → eval 的耗时	CI 拦截 vs 生产发现的回归
Deploy · PR 评审	首次评审时间；无人触碰即解决的意见占比	合并前拦截 vs 生产逃逸的缺陷与漏洞
Deploy · 审批门	每个门的等待耗时（OTel 导出）	到达生产的门禁违规数
Deploy · CI/CD	无需呼人的失败分诊占比	DORA 指标
Maintain · 闭环	带宽击穿 → intent 入队耗时	发现 → 合并修复占比；同类重复事故
Maintain · 周期扫描	接入排期仓库占比；发现 → patch 进门耗时	扫描发现 vs 生产/外部报告；单次发现数趋势

采用路径：从手工提示到自动闭环

玩法是模块化的，可以按组织的独特需求在不同时间优先改造不同阶段；每个玩法在“先决条件”里列出依赖。演进的方向是确定的：

01 · 手工提示每一步

先让每个玩法以手工提示的方式跑通：人发起 intent 会话、人跑设计 pass、人开 plan mode。终局不是这样，但起点必须是。

02 · 固化为配置

把重复出现的流程写成 skills、组织级 slash command、CLAUDE.md 条目与 hooks——组织知识从人脑迁入仓库，agent 行为开始被版本控制。

03 · 制品触发制品

让被接受的制品自动触发下一阶段：intent merge 触发设计 pass，spec 接受触发 plan mode，PR 合并触发管线。人的注意力集中到门禁，评审 agent 标记的东西，而不是从零开始每个阶段。

04 · 闭环自运行

确定性检测监视生产，击穿控制带宽即回写新的 intent.md，回路在无人启动的情况下持续运转。人类判断保持在循环之上。

落地检查清单

每个阶段结束都提交一个制品，下一阶段以读取它开始（Build 之前以 .md 为主）。
每个制品有唯一的事实来源；遗留系统保存链接或副本，或被显式声明为准。
写代码的 agent 没有任何批准代码的路径——职责分离贯穿始终。
“绝不发生”的策略都有确定性层（hook / CI）兜底；skill 只负责让违规变稀有。
fix 任务中 agent 不能编辑测试文件（hook 强制）；bug 修复先提交失败的测试。
agent 的一切写入以 PR 到达，没有直推 main 的路径；生产门禁处必须具名人类授权。
回滚是管线里演练最充分的路径，并在闭环调用它之前已经过验证。
引导 agent 的配置（CLAUDE.md / skills / hooks）变更被 eval 套件门禁。
每个生产事故最终变成一条留在套件里的 eval。
评审发现的同类错误第二次出现时，修正已进入 CLAUDE.md。

最终判断：AI 原生 SDLC 不是把人移出流程，而是把人的注意力从“检查每一行”重新部署到“在门禁处做判断”。循环持续运转，人类判断保持在它之上——问责、治理与监管要求在这个过程中被加固，而不是被绕过。