SDLC · Agentic Engineering

AI 原生 SDLC 全景拆解

当代码不再是瓶颈,软件开发生命周期必须围绕智能体重建。本文逐节点拆解 Anthropic《The AI-Native SDLC Playbook》提出的六阶段闭环,每个节点配手绘 SVG 结构图。

原文:The AI-Native SDLC playbook 作者:Louis Claxton 来源:claude.com/blog 6 阶段 · 11 张节点图

00核心论断

只读这一节,也应该能拿到这份 playbook 的全部骨架。以下八条,是后面每一章的论点来源。

① 瓶颈已经迁移

Build 阶段压缩到小时级之后,约束变成了它左右两侧的人类速度节点:Plan、Review/Test、Deploy。这三个阶段长度不变,于是整条流水线的节拍由它们决定。

② 控制开始失效

为「一人写代码」设计的逐行人工评审,在智能体产出大部分 diff 之后赶不上趟。安全团队按人类产出规模配置,产出翻倍后要么队列堆积,要么审查不足就上线——受监管组织两者都不能接受。

③ 线性流变成闭环

六个阶段不再靠人推动交接,而是阶段提交工件 → 工件触发下一阶段。被接受的 intent.md 触发设计,被批准的 spec.md 触发 plan mode,合并的 PR 触发流水线,被突破的控制带写回新的 intent.md。

④ 工件即审计追踪

每一阶段以一个提交进版本控制的工件收口:intent.md → spec.md → plan.md → diff 及其测试 → 带评审发现的 PR → 事件记录。这条提交链本身就是「谁要求了什么、智能体产出了什么、谁批准了」的审计追踪。

⑤ 控制分两层

Skill 是建议性控制(让违规罕见),hook 是确定性控制(让违规几乎不可能)。必须无条件成立的策略,要在 skill 后面再加 hook、权限或沙箱。原文的判据一句话:skill 使违规罕见,hook 使它们几乎不可能。

⑥ 智能体的行动边界

核心治理原则:智能体可以做直到生产关卡的一切,不能做超过它的任何事。环境分层自治——dev 自由部署、staging 居中、production 必须由发布经理授权且由 hook 强制。

⑦ 度量必须成对

每个阶段都同时给出前置指标(leading,快反馈、来自 git/CI 元数据)与后置指标(lagging,结果验证、来自 PR 历史与事件追踪器)。只给前置会优化过程不优化结果,只给后置则反馈太慢。

⑧ 人的位置

人类对每一个需要判断的决定保持负责。转变的不是「人是否在环内」,而是人的注意力落点:从逐行读代码,移到审阅工件、裁决关卡、处理智能体标记出的内容。

一句话总结

AI 原生 SDLC = 旧的控制目标 + 新的执行方式。流程从线性变为循环,AI 嵌入每一个点,人在每一个需要判断的关卡上做裁决。

01核心命题:代码不再是瓶颈

组织已经在用 AI 以一年前无法想象的速度写代码,但围绕代码的流程没有以同样的速度改变。许多团队仍然保留着同样的审批关卡、评审、交接和策略——这些正是用来抑制 Claude Code 之类智能体编码方案生产力提升的东西。

传统 SDLC 之所以流程繁重,是因为它被设计出来的那个年代,编写和实现代码是最耗时、最昂贵的阶段。PRD、估算仪式、产品安全评审的存在,是为了在可能长达数周、数月甚至数季度的开发工作中强制对齐;而它隐含的另一个假设是——每一步都由人执行,所以控制手段也是按人设计的。

当代码不再是瓶颈、Build 阶段运行得比传统 SDLC 允许的更快时,三件事同时成为现实:

① 瓶颈迁移

约束移到 Build 左侧和右侧的步骤——主要是 Plan、Review/Test 和 Deploy,它们仍然以人类速度运行。

② 控制失配

当一个人写代码时,逐行人工评审是合理的;一旦智能体写了大部分 diff,人工评审就赶不上了。

③ 治理成本上升

例外情况仍然通过每周或每月开会的委员会来路由,治理开销随产出增长而非下降。

以安全瓶颈为例:安全团队的规模是按人类产出配置的。当智能体把代码产出倍增时,要么审查队列堆积,要么代码在审查不足的情况下发布。受监管的组织不能接受这两种结果——所以安全和策略检查必须跟得上智能体。

传统 SDLC —— 每个阶段都由人推动 Plan Design Build Test Deploy Maintain 旧约束:Build(写代码本身最耗时) AI 原生 SDLC —— 只有 Build 被压缩到小时级 被压缩掉的时间 Plan Design Build Test Deploy Maintain 人类速度:Plan + Design 人类速度:Review / Test + Deploy 总时长缩短

图 1 · 瓶颈迁移。传统 SDLC 六阶段长度相当,Build 是约束;AI 原生 SDLC 中 Build 压缩到小时级,而 Plan、Review/Test、Deploy 这些人类速度阶段长度不变——于是约束从「写代码」迁移到 Build 左右的关卡上,总时长下降但节拍由关卡决定。

为了真正拿到智能体 AI 的生产力提升并保护它,传统 SDLC 生命周期需要经历与实现阶段同等程度的转型。

02什么是 AI 原生 SDLC

AI 原生 SDLC 是一个重新构想的流程:保留旧的控制目标,换上新的执行方式。流程从线性流变成一个循环,AI 嵌入每一个点。

这个转变在不同组织里有不同叫法——agentic SDLC、AI SDLC、agentic software development——标签不同,描述的是同一件事。

关键差异:交接由谁推动

传统 SDLC

工作通过文档、工单和签核在阶段之间移动。产品经理写需求,技术架构师把它转成设计,工程师构建设计,QA 团队验证它,发布团队发布它,运维监控运行中的东西。

每次交接都手动且笨拙,所有权在交接时转移——到达工程的内容可能已经离源头者的本意差了好几步。

AI 原生 SDLC

阶段之间靠工件的自动交接驱动:被接受的 intent.md 触发 Design,被批准的 spec.md 触发 plan mode,合并的 PR 触发流水线,被突破的控制带写出下一个 intent.md。

人类注意力集中在关卡上——审阅智能体标记出的内容,而不是从头启动每个阶段。

传统:线性流 · 靠人推动交接 Plan PRD · 用户故事 · 故事点 · 精炼会 Design 需求文档 → 设计稿,跨团队解析 Build 代码与测试手写,文档事后补 Test QA 关卡设在阶段边界 Deploy 人工逐行评审 · 发布 runbook Maintain 所有工单与事件都等人来启动 → AI 原生:闭环 · 工件触发下一阶段 ⟲ 新的 intent.md intent.md spec.md plan.md · diff 合并的 PR 测试证据 · evals Plan 规划 Design 设计 Build 构建 Test 测试 Deploy 部署 Maintain 维护 工件即触发 提交链 = 审计追踪

图 2 · 线性 → 闭环。左侧每个阶段之间都需要一次人为发起的交接;右侧每个箭头都是一次工件提交——intent.md → spec.md → plan.md + diff → 测试证据 → 合并的 PR。橙色的闭环边(Maintain → Plan)是整套机制的收口:被突破的控制带写回新的 intent.md,循环自我续跑。

六个阶段的两端对照

下表列出传统 SDLC 与 AI 原生 SDLC 的两个极端。大多数组织位于两列之间的某个位置。

阶段传统 SDLCAI 原生 SDLC
Plan 需求由委员会收集,通过研讨会和签核提炼,手工编写 Claude 直接从源头综合痛点,捕获在 intent.md 中——人类可读且机器可操作
Design 规格由分析师编写,再由设计师解析 需求与设计压缩到与智能体的一次工作会话中,由编码为 skills 的标准指导,在 git 中版本化
Build 测试和代码手写,文档在主要开发之后编写 测试和代码由 AI 生成,机构知识作为版本化的机器可读 CLAUDE.md 与 skills 维护
Test QA 关卡位于阶段边界 持续评估贯穿实现——每个会话在人类看到之前自检
Deploy 人类审查每一行代码,治理在评审周期中发生,通常不一致 多层智能体评审,人类评审保留给受监管与关键代码;治理在 AI 行动时强制执行,hooks 作为审批关卡
Maintain 人类监视生产中的 bug 智能体监控实时部署,任何被突破的控制带被诊断并作为新的 intent.md 写回循环
贯穿右列的线索

是承诺的工件(committed artifact)。每个阶段以「写入版本控制的一个工件」结束,下一个阶段通过读取它开始。在早期阶段,.md 文件是主要工件,因为产品负责人和智能体可以读、可以操作同一个文件;从 Build 开始,工件是代码及其记录。提交链同时也是审计追踪:谁要求了什么、智能体产出了什么、谁批准了它。

03生命周期总览:六阶段闭环

Plays 是 playbook 的核心,分为六个非线性阶段。它们一起覆盖完整生命周期,但采纳顺序 ≠ 阶段顺序——你可以从任何一个没有前置依赖的阶段开始。

每个 play 都覆盖同样的五件事:什么改变、如何开始、具体实现步骤、治理考虑、以及如何衡量它是否有效。步骤是模块化的,组织可以按自身需求在不同时间优先转型不同阶段。

intent.md spec.md plan.md + diff 测试证据 + evals 合并的 PR ⟲ 新的 intent.md 人类判断 留在每一个需要判断的关卡上 裁决 · 审批 · 定责 01 Plan 规划 02 Design 设计 03 Build 构建 04 Test 测试 05 Deploy 部署 06 Maintain 维护 闭环边:自动续跑,无需人启动 工件交接边

图 3 · 生命周期总图。六个阶段首尾相接成环,环上的每一段标注了该次交接所提交的工件。前三段(intent.md、spec.md、plan.md)是 markdown,因为产品负责人与智能体需要读、写同一个文件;从 Build 起,工件变成代码及其证据记录。橙色边是闭环:Maintain 检测到的控制带突破写回一个新的 intent.md,流水线无需人启动即可重启。

六阶段速查

#阶段收口工件核心机制触发下一阶段的条件
01Plan 规划 intent.md 源头者与 Claude 头脑风暴,用自己术语写下原型规格 产品负责人接受该 intent(记录为合并的评审)
02Design 设计 spec.md 需求与设计压缩到一次会话,由组织的 skills 约束 产品负责人批准 spec,启动 plan mode
03Build 构建 plan.md + diff plan mode 先出书面计划;CLAUDE.md、skills、hooks 三层配置 计划被接受 → 实施 → PR 提交
04Test 测试 测试证据 + evals 自检反馈回路;evals 在 CI 中对智能体配置做回归测试 CI 全绿且证据粘贴进 PR
05Deploy 部署 带评审发现的 PR 三层智能体评审;hooks 作为审批关卡;按环境分层自治 代码所有者批准(分支保护)→ 合并
06Maintain 维护 事件记录 → 新的 intent.md 确定性检测脚本(σ 分层)→ 无头调用 Claude 诊断 诊断写成 intent.md,回到 01
为什么是闭环而不是流水线

因为「一个阶段以提交一个工件结束,该提交启动下一个阶段」。一旦这条链成立,人类注意力的落点就变了:不再是「从头启动每个阶段」,而是审阅智能体标记出的内容、在关卡上做裁决。第一步你手动提示每一步;最终状态是每个被接受的工件自动触发下一个关卡。

01
Stage 1 · Plan

规划:把意图一次捕获成版本化工件

核心理念

想法不再等待有人把它们写下来。意图在来源者自己的话语中一次捕获,作为一个版本控制工件,下一个阶段可以直接对其操作。

节点结构

Plan 阶段有三个进入路径,但无论从哪条路径进入,流程是同一套:头脑风暴 → 起草 → 人工审阅更正 → 提交。

前置依赖:无 有人有想法 工单被提交 事件经告警浮现 步骤 1–2 与 Claude 头脑风暴 步骤 3 起草 intent.md 步骤 4 审阅 · 更正 步骤 5 · 收口 提交到归属地 来源者本人,不需要 git 经验 组织 intent 模板编码为 skill 产品负责人 repo 的 intent/ 目录 同为入口: Stage 6 的事件告警也会生成 intent.md,经由同一条链——差别只在「谁先写下第一版」。 关键分工: Claude 写草稿,人做更正。产品负责人对提交前的 intent.md 负最终责任。

图 4 · Plan 阶段节点图。三条入口(想法 / 工单 / 事件告警)在头脑风暴处汇合,此后是固定四步:与 Claude 头脑风暴具体化 → 按组织模板起草 intent.md → 来源者更正误解 → 提交到共享归属地。作者与时间戳随提交进入记录,产品负责人从这里接手。

传统 vs AI 原生

传统

想法在任何人能对其采取行动之前,要通过 backlog 条目、用户故事、故事点和精炼会议。每次交接时所有权转移,所以到达工程的内容与来源者本意相差好几步。

AI 原生

来源者与 Claude 头脑风暴,把结果写成 intent.md——一份用来源者自己术语写的原型规格,包含想要什么、为什么、在哪些约束下。重复流程通过 skills 编码。

基础设施(一次性搭建)

搭建由平台或工程团队完成,需要决定谁可以写入,因为许多贡献者会来自整个组织。一旦仓库存在,没有 git 经验的贡献者不需要直接使用 git——通过到版本控制系统(如 GitHub)的连接器,Claude 可以代表他们从 claude.ai 或 Cowork 提交 markdown 文件。

执行步骤

  1. 来源者用自己的话描述问题。可以描述今天不能做什么、谁受这个想法影响、更好是什么样子、什么超出范围。不需要正式语言。
  2. 头脑风暴直到想法具体化。Claude 问分析师会问的问题:范围、用户、约束、成功是什么样子。
  3. 让 Claude 按组织模板写为 intent.md。模板覆盖:问题、提议结果、受影响的用户和系统、约束、开放问题。
  4. 来源者更正 Claude 误解的内容。
  5. 提交到共享归属地。作者与时间戳进入记录,产品负责人从这里接手。

示例 · intent.md

# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.

## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.

## 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?
# 意图:理赔进度自助查询
作者:J. Ortiz(理赔运营团队)。状态:草案。

## 问题描述
客户拨打客服中心电话询问其理赔进度。
处理人员大约将三分之一的通话时间用于解答仅针对进度的查询。

## 预估效果 / 方案目标
客户可在门户网站中查看理赔进度、下一步流程及预计完成日期。

## 受影响的用户与系统
理赔处理人员、门户网站团队、理赔核心 API。

## 约束条件
门户网站会话中不得引入新的个人身份信息(PII)。仅使用现有的身份验证机制。

## 待解决问题
第三方公估人(损失评估师)是否也需要访问权限?
治理

证据是已提交的 intent.md:它列出作者、时间戳和完整修订历史,记录在 intent 归属地的 git 历史中。产品负责人的接受或拒绝决策,记录为工件的合并或关闭的评审。

本阶段产出的控制证据

提交 SHA · 作者 · 时间戳 · 修订历史 · 合并/关闭的评审。这一组构成了后面所有审计链条的起点——谁要求了什么从这里开始可追。

前置指标 · Leading

从第一次对话到提交 intent.md 的时间。从 intent 归属地的 git 历史读取。期望从多周的引导与精炼周期下降到数小时。

后置指标 · Lagging

存活率:产品负责人接受到 Stage 2 而不是关闭的 intent.md 文件份额。此外统计同一变更在首次 spec.md 提交之后对 intent.md 的改动次数——它衡量意图是否真的稳定了。

02
Stage 2 · Design

设计:需求与设计压缩成一次会话

核心理念

需求和设计合并为一次会话。策略在规格编写时就被应用,而不是几周后才在评审中被发现。

组织 skills 约束:品牌 · 安全 · 合规 · UX(在 git 中版本化) 输入(已接受) intent.md 一次提示会话 需求 + 设计规格 输出工件 spec.md + 关注点 审阅 · 裁定 产品负责人 决策(必须由人做) 推进 Build 关注点 → 策略负责人 并行路径 · 前端工作 Claude Design (beta) 依 intent.md 出模拟 迭代模拟 → 导出到 Claude Code 构建 治理要点 规格、产生它的提示、以及生效的 skill 版本,全部在版本控制中记录。 被标记的关注点是分析师会升级的点,必须先与策略负责人解决,再让工程看到规格。

图 5 · Design 阶段节点图。注意两点:一是 skills 是横向的约束层,在会话进行时就把品牌/安全/合规/UX 策略烧进规格,而不是等评审时才发现冲突;二是「推进 Build」这个决策永远由人做——产品负责人咨询技术负责人处理高风险内容,人类团队成员始终是决定者。

传统 vs AI 原生

传统

需求和设计是由不同团队运行的独立阶段。分析师把想法形式化为需求,设计师再把这些解析回设计。分离是为责任而存在的,但它缓慢且有损。

AI 原生

两个阶段在一次提示会话中发生。Claude 获取 intent.md 并产生需求与设计规格,受组织的 skills 约束,并主动标记关注领域。

执行步骤

  1. 产品负责人打开一个会话,挂载组织的 skills,并附上 intent.md。
  2. 提示指向 intent.md、命名约束、要求标记关注点。先手动跑,然后编码为组织级 slash command。从那里进一步:把「intent 归属地中 intent.md 被接受」作为触发器,用非交互式作业在合并时触发,自动把 spec.md 作为 pull request 提交——产品负责人的第一次参与就是评审。
  3. 同一个产品负责人对照想法审查规格:规格是否解决了陈述的问题?intent.md 中的开放问题是被回答还是被结转?
  4. 先处理被标记的关注点,因为它们是分析师会升级的点。产品负责人在工程看到规格之前,先与策略负责人解决每一个问题。
  5. 把 spec.md 与 intent.md 一起提交。这对文件记录了要求了什么和决定了什么。
  6. 产品负责人决定规格和意图是否推进到构建;对组织归类为更高风险的内容,咨询技术负责人。这个决定永远由人类做——接受规格就是启动 Stage 3 的 plan mode。

示例 · 提示词

Read the attached intent.md and produce a requirements and design spec for
integrating it into our existing codebase. 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. Describe clearly any areas of concern, especially where you
cannot satisfy contradicting policies.
阅读附加的 intent.md 并生成一份需求与设计规范,用于将其集成到我们现有的代码库中。
运用你可用的技能,使该计划符合我们的品牌指南、安全策略和 UX 标准。
将该规范完整记录为 spec.md,以便随时交付给工程团队。
清晰说明所有需要关切的领域,尤其是你无法满足互相冲突的策略之处。
治理

实时策略在规格编写时被读取和应用,而不是几周后在评审中发现。组织的 skills 作为规格的约束生效。规格、产生它的提示、生效的 skill 版本都在版本控制中记录。产品负责人签核规格,并把被标记的关注点路由给指定的策略负责人。

风险分级

常规变更由产品负责人单独决定;组织归类为更高风险的内容必须先咨询技术负责人。这个分级是「人在环内」的具体落地方式,而不是一句口号。

前置指标 · Leading

同一变更的 intent.md 提交与 spec.md 提交之间的经过时间(两个 git 时间戳之差),与旧的需求加设计周期相比。

后置指标 · Lagging

构建开始后的需求返工:统计日期在首次 plan.md 提交之后的、同一变更的 spec.md 提交。git log 会直接给出这个数。

03
Stage 3 · Build

构建:没有已接受的计划就不实现任何东西

核心理念

没有已接受的计划就不实现任何东西。机构知识成为智能体读取的文件,护栏作为代码运行而不是作为习惯。

节点结构:一条主链 + 一个横跨全阶段的配置层

Build 阶段的结构与其他阶段不同——它有一条顺序主链(plan mode → 审问 → 提交计划 → 实施),以及一层作用于每一个会话的配置(CLAUDE.md、skills、hooks、权限)。配置层不参与顺序,它决定主链上每一次行动的行为。

配置层 —— 决定所有会话的行为,随代码一起版本化并由 PR 评审 CLAUDE.md · 约定与命令 .claude/skills/ · 建议性 hooks · 确定性护栏 permissions · 权限与沙箱 输入工件 intent.md + spec.md 步骤 1–2 plan mode 出计划 步骤 3–4 工程师审问计划 步骤 5 · 收口 提交 plan.md 步骤 6–7 实施 · 一次通过 plan mode 的强制力:工程师接受计划之前,Claude 无法编辑文件 并行会话与子智能体 —— 工程师的工作从「写」转向「编排 + 审查」 并行会话 2–3 个(合理起点) git worktree 隔离,各占分支 子智能体 .claude/agents/ 上限 = 一个人能正确审查的流数 风险分级:常规变更由工程师批准;组织归类为更高风险的内容交给技术负责人或架构师。 计划偏离现实时,在同一提交中更新 plan.md;可用 hook 强制两者保持同步。

图 6 · Build 阶段节点图。上层配置贯穿每一次行动,中层是 plan mode 主链,下层是并行化。关键点:plan mode 自带强制力——在工程师接受计划之前 Claude 无法编辑文件,于是「设计评审发生在任何代码生成之前」不再依赖自觉,而是机制。当实现偏离计划时,plan.md 必须在同一提交里更新。

传统 vs AI 原生(plan mode)

传统

工程师读设计就开始写代码。变更将如何进行、精确到哪些文件和哪些测试,留在工程师的头脑里或充其量是工单评论里。别人无法审查它。评审者看到的第一件事是完成的 diff,到那时返工已经缓慢了。

AI 原生

工作从 Claude 在 plan mode 下产生的书面计划开始——它能在不改变任何东西的情况下读代码库。工程师在写代码之前就修正计划,批准的版本作为 plan.md 提交,供后续阶段检查。

示例 · plan.md

# Plan: claims status self-service (from intent.md 2026-06-02)

## Files that change
portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py,
claims-api/tests/test_status.py

## Order of work
1. Add the status endpoint behind existing auth.
2. Panel against the endpoint.
3. Wire into the portal nav.

## Risks
The claims-core API rate-limits at 50 rps; the panel must cache.

## Proof
test_status.py covers the four claim states; screenshot matches the
approved mock.
# 计划:理赔状态自助服务(来自 intent.md 2026-06-02)

## 变更文件
portal/src/claims/StatusPanel.tsx(新建)、claims-api/routes/status.py、
claims-api/tests/test_status.py

## 工作顺序
1. 在现有身份验证后添加状态端点(status endpoint)。
2. 基于该端点开发面板组件(Panel)。
3. 接入 Portal 导航。

## 风险
claims-core API 的速率限制为 50 rps;面板必须进行缓存。

## 验证依据
test_status.py 覆盖了四种理赔状态;截图与已批准的原型图匹配。

三个子 play:机构知识怎么变成配置

CLAUDE.md · 团队共享的上下文

给 Claude 提供新加入者需要的上下文:约定、命令、架构、团队最常看到的错误。曾被放在人们头脑和 wiki 里的知识,变成每个会话开始时读取的一个文件。

工作规则:当 Claude 两次犯同一个错误时,更正进入 CLAUDE.md。保持在一页以内——任何过时的内容都在无收益地占用上下文。

Skills · 机构知识可操作化

指令明确、版本控制、广泛应用,策略变化时集中更新。经验法则:为「必须一致应用的机构知识」写 skill;不要为属于 CLAUDE.md 或提示的组件写 skill。

放置位置:repo 的 .claude/skills/<name>/ 随代码发布,或通过 plugin 组织范围内分发。

Hooks · 确定性护栏

Skill 是建议性控制,hook 是背后的确定性层。Claude 的操作在实现期间大多是文件编辑和 shell 命令,所以构建阶段是 hooks 最频繁触发的地方。

典型用途:阻止编辑受保护路径(生成类、冻结包)→ 编辑后跑格式化与 lint → 把凭证排除在 diff 之外。要求人工批准的 hook 应归入 Deploy 阶段的关卡。

示例 · CLAUDE.md

# Payments service

## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)

## Conventions
- Java 21, Spring Boot 3. No new Lombok.
- Money is always BigDecimal, never double.
- Every endpoint needs an integration test in src/itest.

## Architecture
- api/ holds REST controllers, core/ holds domain logic,
  adapters/ talks to external systems.
- Kafka events are defined in schemas/; never edit generated classes.

## Things Claude gets wrong
- Do not bump dependency versions; the platform team owns them.
- The legacy v1/ package is frozen; changes go in v2/.
# 支付服务

## 命令
* 构建:`make build`
* 测试:`make test`(单元测试),`make itest`(集成测试,需要 Docker)
* 代码检查(Lint):`make lint`(在 CI 中运行;推送前请先修复问题)

## 规范 / 约定
* 使用 Java 21、Spring Boot 3。禁止新增 Lombok 依赖。
* 金额一律使用 `BigDecimal`,绝对不能用 `double`。
* 每个 API 接口都必须在 `src/itest` 中编写集成测试。

## 架构
* `api/` 存放 REST 控制器(Controllers),`core/` 存放领域核心逻辑,`adapters/` 用于与外部系统对接。
* Kafka 事件定义在 `schemas/` 目录下;切勿直接修改自动生成的类。

## Claude 容易弄错的地方
* **请勿**升级依赖包的版本;这些由平台团队(Platform team)统一维护。
* 遗留的 `v1/` 包已被冻结;所有新修改必须在 `v2/` 中进行。

示例 · .claude/skills/secure-api-review/SKILL.md

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review

When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.

Run scripts/check-endpoints.sh and include its output in your summary.
---
name: secure-api-review
description: 应用 API 安全标准。在创建或修改对外接口、审查 API 代码或生成 OpenAPI 规范时使用。
---
# API 安全审查

当你创建或修改 API 接口时:
1. 身份认证:每个接口都需要网关 JWT;除了 /health 外,不得设置匿名路由。
2. 输入校验:根据 OpenAPI 规范校验请求体(Request Body),并拒绝未知字段。
3. 审计:每个改变状态的接口都要触发审计事件,记录操作者(actor)、操作(action)、实体(entity)和时间戳(timestamp)。
4. 数据分类:规范中标记为 PII(个人身份信息)的字段绝不能出现在日志或错误信息中。

运行 scripts/check-endpoints.sh 并将其输出结果包含在你的总结中。
skill 与 hook 的分工判据

Skill 是一个控制,但是一个建议性的控制——它让 Claude 在写代码时可能应用策略,但没有什么强制会话遵守它。必须始终成立的策略,需要在 skill 后面再加确定性的东西:阻止操作的 hook,或在 PR 上重新检查策略的评审通过。skill 使违规罕见,hook 使它们几乎不可能。

并行会话与子智能体

实践建议:把工作切成不碰同一批文件的任务;每个并行任务获得自己的 worktree(如claude --worktree feature-auth)。两到三个会话是合理起点——实际上限是一个人能正确审查多少流,只有在评审跟得上时才增加会话。将重复工作变成 .claude/agents/ 下的 markdown 定义并检入 git。

示例 · .claude/agents/verifier.md

---
name: verifier
description: Runs the app and checks the change works before the session
  reports done
tools: Bash, Read
---
Start the app with make run. Exercise the changed behavior and the two
nearest neighboring flows. Report what you ran, what you saw, and any
behavior that does not match plan.md. Do not fix anything; report only.
---
name: verifier
description: 在会话报告完成之前,运行应用并检查修改是否正常生效
tools: Bash, Read
---
使用 make run 启动应用。测试本次修改的功能以及与之最相邻的两条业务流程。
报告你所运行的命令、看到的结果,以及任何与 plan.md 不符的行为。
不要进行任何修复,仅作报告。
治理

设计评审在任何代码生成之前发生,当改变方向仍然只是编辑文档的事情。计划及其修订与「谁接受它」一起记录。常规变更由工程师批准;更高风险内容交给技术负责人或架构师。更多会话意味着更多输出,所以控制必须来自 repo 中的配置——那里的 hooks 和权限设置适用于所有会话。

Sidebar · 遗留系统的真相来源

现有流程可能已经跟踪工件,只是在 Jira / Figma / 变更委员会里。对每个工件,命名一个系统为真相来源,其他一切都持有副本或链接。三种可选配置:仓库为真相来源(markdown 权威,遗留系统引用提交中的文件)、遗留系统为真相来源(Jira/ServiceNow 权威,markdown 是工作副本,通过 MCP 读写)、链接作为最低标准(所有工件注明记录 ID,所有遗留记录含 markdown 提交 SHA)。

前置指标 · Leading

从第一次实现通过就合并的变更份额,以及从计划批准到合并 PR 的时间。两项数据都在 PR 元数据中直接可取。

后置指标 · Lagging

每个变更的返工周期(同样来自 PR 元数据),以及合并的 diff 仍然匹配已提交 plan.md 的频率——后者衡量计划是否真的约束了实现,而不只是走个流程。

04
Stage 4 · Test

测试:让每个会话在人类看到它之前检查自己的工作

核心理念

每个会话在人类看到它之前检查自己的工作,指导智能体的配置像它编写的代码一样被回归测试。

节点结构:会话内自检循环 + CI 里的 evals

Test 阶段有两个独立的机制,容易混淆:反馈回路贯穿整个任务,让 Claude 边做边自检;验证器子智能体则是在会话认为工作完成后,用全新的上下文窗口做最后打包检查——这样裁决不会被产生代码时的假设着色。

三种反馈通道 —— 会话必须能自己验证工作,否则工程师成为瓶颈 make test · 失败时非零退出 make build · 构建成功 浏览器 / 截图 diff · UI 工作 会话内自检循环 —— 在人类看到之前把错误修掉 步骤 3 陈述可量化目标 步骤 6 Claude 迭代修改 步骤 4–5 跑测试 / 构建 / 截图 判据 目标全部成立? 是 报告完成 · 粘贴输出 否 → 修复代码,不改测试(hook 阻止对测试文件的编辑) CI 中的持续 evals —— 阶段关卡 QA 的 AI 原生等价物 20–50 个真实任务 配置变更时非交互式运行 通过率对合并设关卡 每个生产事件 → 一个 eval 套件在 CI 中按计划运行,并且在 CLAUDE.md / skills / hooks 发生任何变更时运行 evals 是活的套件:随着模型改进,曾经有区分度的案例会失去区分度,必须从持续监控中补充新案例。

图 7 · Test 阶段节点图。上半是会话内循环:Claude 被给予可量化目标("test_status.py 中的所有测试通过"、"截屏匹配附加的模拟"),自己迭代直到通过,所以到达工程师的东西已经通过了它自己。下半是 evals:它把「指导智能体的配置」当作需要回归测试的生产代码——配置变了就跑套件,通过率下降就拦住合并。

传统 vs AI 原生

传统

代码工作的信号到达得很晚:CI 几分钟后,测试者几天后,生产几周后。当智能体产生代码时,晚到的信号意味着一个人必须检查它的全部输出——那个人就成了瓶颈。

AI 原生

会话被给予一种在人类看到之前检查自己工作的方式。运行测试、运行构建、截图。Claude 迭代直到检查通过。设置循环这件事落在运行会话的工程师身上,而不是 QA 团队。

执行步骤要点

  1. 如果今天检查工作需要一串命令和环境知识,把它包装成单一目标如 make test 或 npm test,失败时以非零退出。
  2. 在 CLAUDE.md 的 Commands 部分列出每个命令,并给出健康输出的例子。
  3. 陈述目标时使其可量化,以便 Claude 能自己检查而不必问你。
  4. 修 bug 时先写失败的测试。让 Claude 把 bug 复现成测试、运行它、确认它因你期望的原因失败——然后提交那个测试。只有这样才让它在不编辑测试的前提下通过。一个在修复之前就存在、且智能体无法重写的测试,是 bug 已消失的证明。
  5. UI 工作用视觉检查关闭循环:实现 → 截屏 → 比较 → 调整。两到三轮是正常的,结果应该每轮改善。
  6. 把验证作为「完成」的一部分:在报告任务完成之前跑测试并显示输出。
  7. 循环本身也需要保护——修复代码的智能体不能削弱对该代码的检查。一个在修复任务期间阻止编辑测试文件的 hook 做到这一点;替代方案是在评审中检查 diff 并拒绝任何触及测试的变更。

示例 · CLAUDE.md 的验证区块

## Verifying your work

- Build: make build (must finish with "Build succeeded")
- Test: make test (all green; never skip or delete a failing test)
- Lint: make lint (zero warnings)

Run all three before reporting any task complete, and paste the output.
If a test fails, fix the code, not the test.
## 验证你的工作

- 构建:make build(必须以“Build succeeded”结束)
- 测试:make test(全部通过;绝不跳过或删除失败的测试)
- 代码检查:make lint(零警告)

在报告任何任务完成之前运行上述全部三项,并粘贴输出结果。
如果测试失败,请修复代码,而不是修改测试。

示例 · .github/workflows/agent-evals.yml

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
治理

强制的是什么:任务报告完成前必须验证,以及修复期间阻止智能体编辑测试文件——两者都在组织想要保证的地方实现为 hooks。
证据是什么:Claude 运行并粘贴的 make test 字面输出、构建日志或截屏 diff——证据来自工具链,不是自述。
记录在哪:会话记录 + OpenTelemetry 导出到组织的可观测性栈,以及 PR 的检查运行中。
谁批准:评审 PR 的代码所有者,可以专注意图和风险,因为机械证据已经附加。

Evals 怎么建

1. 平台工程师从最近工作中收集 20 到 50 个真实任务及其预期/接受的结果。
2. 每个任务写成一个 eval:提示 + 可接受的检查(测试通过、lint 干净、行为不变、策略遵循)。
3. 套件在 CI 中按计划、并在 CLAUDE.md/skills/hooks 变更时运行——因为该配置指导智能体,值得得到代码级别的回归测试。
4. 对降低通过率的配置变更设关卡。
5. 每个生产事件获得一个 eval,由拥有该事件的团队编写,并留在套件里作为回归测试。

前置指标 · Leading

智能体编写变更的第一次 CI 成功率(CI 系统已经支持),以及随时间变化的 eval 通过率与生产事件变成永久 eval 所需的时间。

后置指标 · Lagging

每个 PR 的评审时间——一旦测试捕获了评审者过去捕获的东西,应该下降;以及CI 中捕获的回归 vs 生产中发现的回归,从事件追踪器导出。

05
Stage 5 · Deploy

部署:评审双向运行,治理在智能体行动时执行

核心理念

评审在两个方向运行:Claude 既评审传入的 PR,也处理自己 PR 上的评审评论。治理在智能体行动时强制执行。智能体做直到生产关卡的所有事情,而不做超过它的任何事。

节点结构:三通过集评审 → 人类关卡 → 分层自治

评审链 —— 所有 PR 获得同一套评审通过集,发现按严重性排名 PR 提交 Pass 1 · Bugs 逻辑与回归 Pass 2 · Security 安全与注入 Pass 3 · Compliance 对照 spec 发现分级 Important vs Nit · 上限 5 个 人类批准(分支保护) 发现本身不批准、不阻止 合并 → CI/CD 审批关卡 —— hooks 不只能阻止,也能「询问」 .claude/hooks/production-gate.sh —— 命令含 deploy 且含 production 时,若 RELEASE_APPROVAL 为空则 exit 2 阻止, 原因与批准路线出现在 Claude 的输出中。不可协商的 hooks 放在托管设置里,个别工程师无法关闭。 按环境分层自主性 —— 自治性越靠近生产越低 Dev · 智能体自由部署 Staging · 居中 Production · 需具名授权 智能体可自由执行 自动部署,生产变更需授权 准备就绪 → 发布经理授权 → hook 强制 核心原则:智能体可以行动直到生产关卡,不能通过它。回滚是流水线中排练最多的路径,必须提前被证明。

图 8 · Deploy 阶段节点图。三个通过集(Bugs / Security / Compliance)并行运行、各自打标签,然后汇聚到统一的分级与人类关卡。关键设计:发现本身不批准也不阻止 PR——分支保护仍然要求代码所有者的批准,发现只是让那个人看到按严重性排序的结论。下方绿色条是分层自治:越靠近生产,智能体可做的事越少。

传统 vs AI 原生

传统

评审能力围绕人类输出规划。一个 PR 等待评审者读完,评审质量随评审者负载波动,作者追着评审者跑,积压持续增长。

AI 原生

所有 PR 获得同一套评审通过集,发现按严重性排名。人类注意力移到一个更高的层级:变更是否做了计划意图的事,风险是否可接受。

执行步骤要点

  1. 托管 Code Review 服务是最快的开始——管理员启用并选择仓库。需要控制流水线或想通过自己的云协议路由模型调用时,在 CI 中用 claude-code-action 自行运行。
  2. 技术负责人把评审策略写成 REVIEW.md,分为组织关心的通过集,并定义什么算 Important 与 Nit、跳过什么。
  3. 设置人类阈值。发现不批准也不阻止 PR,分支保护仍要求代码所有者批准;想按发现对合并设关卡的平台工程师,可以读取检查运行发布的严重性计数作为机器可读统计。
  4. 让 Claude 处理评审评论。评审者或作者在评论上标记 @claude,Claude 处理并推送修复,PR 线程记录请求与变更。进一步的做法是让 Claude babysit PR 到合并:扫描未解决的评审评论与失败的检查,逐个处理直到 PR 变绿、只等代码所有者批准。
  5. 评审发现反馈到 CLAUDE.md。当评审第二次标记同一个错误,更正作为该次评审的一部分进入 CLAUDE.md——因为评审读 CLAUDE.md,这个错误从下一个 PR 起就被捕获。评审还应标记「变更何时使 CLAUDE.md 过时」。
  6. 每月调优一次。技术负责人给发现评分以便评审者改进,并在 REVIEW.md 中限制 Nit 数量;生成路径和 CI 已经强制的内容被排除。

示例 · REVIEW.md

# Review instructions

## Passes
Run three passes and tag each finding with its pass:
- Bugs: logic errors, broken edge cases, subtle regressions
- Security: injection risks, authentication gaps, PII in logs
- Compliance: the change matches spec.md, plan.md and our design principles

## What Important means here
Reserve Important for findings that would break behavior, leak data
or breach a policy. Style and naming are nits.

## Cap the nits
Report at most five nits per review; summarize the rest as a count.

## Do not report
Generated files under src/gen/ and anything CI already enforces.
# 审查指南

## 审查轮次
运行三轮审查,并在发现的每个问题上标注对应的轮次:

- 逻辑缺陷(Bugs):逻辑错误、边界情况失效、隐蔽的回归问题
- 安全性(Security):注入风险、身份验证漏洞、日志中的个人身份信息(PII)泄露
- 合规性(Compliance):变更是否符合 spec.md、plan.md 以及我们的设计原则

## 此处“重要(Important)”的含义
仅对会破坏系统行为、泄露数据或违反政策的发现保留“重要”标记。代码风格和命名规范仅属于微小瑕疵(nits)。

## 限制微小瑕疵的数量
每次审查最多报告 5 个微小瑕疵(nits);其余的汇总为一个统计数量即可。

## 无需报告的内容
src/gen/ 目录下的生成文件,以及 CI(持续集成)已经强制约束的任何内容。

CI/CD 集成与部署

传统流水线运行确定性脚本,任何需要判断的东西都等待人类——分类 flaky test、写变更日志、弄清楚构建为什么坏了;部署和回滚是人在压力下遵循的 runbook。AI 原生的做法是让 Claude 在流水线内非交互式地跑那些判断步骤,在具有有范围凭证的沙箱中;部署工具通过 MCP 暴露给智能体,所以写和测试变更的工作流也能发布它,并在组织为每个环境定义的关卡内回滚它。

示例 · 流水线步骤

- name: Triage failed build
  if: failure()
  run: >
    claude -p "Read the build log at out/build.log. Identify the most
    likely cause, say whether the failure looks flaky or real, and write a
    three-line summary for the PR thread." >> triage.md
- name: 诊断失败的构建
  if: failure()
  run: >
    claude -p "读取 out/build.log 中的构建日志。找出最可能的失败原因,
    说明该失败看起来是偶然交替出现的(flaky)还是真实存在的(real),
    并为 PR 讨论串写一份三行的总结。" >> triage.md
治理 · 三条控制

分支保护把智能体写的任何东西变成 PR,没有直接通往 main 的路径。
生产部署 hook阻止发布,直到具名的发布经理授权它。
每个非交互式运行以自己的身份行动,所以流水线日志能把「智能体做的」与「触发它的工程师做的」分开。

按环境的权限层级,决定了智能体在到达关卡途中可以做多少事。

托管设置 · 受监管企业的起点

由平台团队通过 MDM 或管理控制台部署,工程师不能编辑或覆盖任何内容。关键条款与控制含义:
permissions.deny 把秘密排除在上下文之外并阻断任意网络出口;
disableBypassPermissionsMode + allowManagedPermissionRulesOnly 让没有工程师、项目文件或命令行标志能扩大规则;
sandbox 关闭权限关不掉的缺口(工具级拒绝拦不住 shell 命令联网,OS 级域允许列表可以);
credentials 从每个沙箱化命令的环境中剥离命名秘密;
allowManagedHooksOnly 让本 play 的关卡成为唯一运行的 hooks。

前置指标 · Leading

第一次评审的时间(应该下降到分钟级),以及在没有人类触及分支的情况下解决的评审评论份额——数据直接存在 Git 上。审批关卡本身则测等待每个关卡的时间,从 hook 决定的 OpenTelemetry 导出读取。

后置指标 · Lagging

合并前捕获的缺陷与漏洞 vs 逃逸到生产的(从 PR 历史与事件追踪器导出),以及 DORA 度量——CI 系统与部署工具已经在发出这些指标。关卡层面则看hooks 前后到达生产的关卡违规。

06
Stage 6 · Maintain

维护:循环关闭,触发器调用 Claude,发现回到 Plan

核心理念

循环关闭。触发器调用 Claude,调用路径中没有一个人,它发现的内容作为 intent.md 重新进入流水线。

节点结构:确定性检测 → σ 分层 → 诊断写成 intent.md

前五个阶段都需要人类启动初始步骤,这个阶段把焦点转移到自主运行 Claude 以关闭循环。它无头运行,在阶段之间有独立的信心关卡——一个确定性检查或对抗性评审智能体,决定前一阶段的输出继续还是升级给人类。

闭环 —— 检测保持完全确定性,只有带状被突破之后才调用 Claude 步骤 1 生产指标 步骤 2 · 不涉及模型 确定性检测脚本 1σ · 仅记录(log) 2σ · Claude 只读诊断 3σ · 可行动(仅 PR / runbook) 步骤 5 · 收口 写成 intent.md 回到 Stage 1 Plan 找到的东西怎么处理 分类队列(服务所有者 / on-call) 修复 → 走 PR 评审关卡 驳回要带原因,并用于调优带状以降低噪音 计划扫描 —— 覆盖率从上次运行算起,而不是从第一次 连接仓库 · 首次全扫即基线 每周节奏 · 带置信度评级分类 有界修复走 PR,更宽的写 intent.md 代码每周变化、每一代模型发现前一代错过的漏洞 —— 所以扫描必须按计划重复

图 9 · Maintain 阶段节点图。最左边的检测层完全不涉及模型——它是版本控制、带单元测试的确定性脚本,用滚动窗口的均值与标准差加 Western Electric 规则,既能抓慢漂移也能抓尖峰。只有带状被突破之后才调用 Claude,层级决定它可以做什么(1σ 只记录 / 2σ 只读诊断 / 3σ 只能通过打开 PR 或触发预先批准的 runbook)。诊断最终写成 intent.md,回到 Stage 1——循环于是自我喂养。

传统 vs AI 原生

传统

维护是反应性阶段。所有工单或事件都等人对其采取行动再重启流程。警报在凌晨 3 点触发可能被错过,工单能在 backlog 里躺到有人捡起,事后行动可能根本不触及代码库——如果另一个火先烧起来。

AI 原生

一个触发器(控制带突破、工单、渠道消息或计划)在没有人的路径中调用 Claude。Claude 诊断,只通过关卡路由行动,把发现写成 intent.md 然后流经前述阶段。人分类和审查那项工作,而不再需要启动它。

闭环的执行步骤

  1. 选一个有稳定滚动基线的指标:CI 测试失败率、部署后 5xx 率,或 PR 周期时间。
  2. 写检测脚本:通常是滚动窗口上的均值和标准差,带 Western Electric 或类似规则,以便带状同时捕获慢漂移和尖峰。脚本是版本控制和单元测试的,检测保持完全确定性,不涉及模型。
  3. 在版本控制配置中定义响应层级:1σ 只记录;2σ 调用 Claude 只读诊断;3σ Claude 可以行动,但只能通过打开 PR 进入评审关卡、或触发预先批准的 runbook。
  4. 触发层可以是 GitHub/GitLab 中的计划工作流、来自现有监控栈的 webhook,或网络内的 Cron Job。Claude 无状态运行——作为 CI runner 上的非交互式步骤,或沙箱容器中的 Agent SDK 服务。因为运行是无状态且非交互式的,循环可以在没有人启动的情况下开始和结束。
  5. 智能体把诊断写成 Stage 1 格式的 intent.md:异常及其证据、提议结果、受影响的系统、开放问题。从那里,发现像其他任何东西一样通过流水线。
  6. 服务所有者或 on-call 工程师分类队列,把面向产品的发现路由给产品负责人。现在修复、安排或驳回。驳回调优带状并帮助减少噪音。
  7. 当修复发布时,为该事件添加一个 eval(回到 Test 阶段的持续 evals play),确保此类问题在未来受到保护。

示例 · bands.yaml(监控 CI 测试失败率)

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_test_failure_rate(CI测试失败率)
基线:rolling_30d(近30天滑动窗口)
规则:western_electric(韦斯特电信号码规则/控制图规则)
层级:
  1sigma:{ 动作:记录日志 }
  2sigma:{ 动作:故障诊断,
            工具:"Read,Grep,Bash(gh run view *)" }
  3sigma:{ 动作:提出方案/建议,
            路由:[拉取请求, 运行手册:回滚部署] }

三个典型闭环例子

CI 失败率突破 3σ

智能体隔离 flaky test,或打开 revert PR——评审关卡决定。

部署后 5xx 突破 3σ

且窗口中有部署时,智能体触发已有的回滚流水线。

PR 周期时间漂移

智能体为工程领导层写一份报告——说明 harness 同样适用于流程指标,而不只是生产指标。

计划扫描与 on-call

安全扫描是关于特定模型下代码库的时间点陈述,两半都会过时:代码每周变化,每一代模型都发现前一代错过的漏洞。AI 原生的答案是按计划运行扫描,调用路径中没有人类,并把它发现的内容通过与任何其他代码库变更相同的关卡发送。

Claude Security · 计划扫描的托管形式

连接一个 GitHub 仓库,扫描在 Anthropic 基础设施上的 Claude Mythos 5 上运行,每个发现都在报告前被验证并附加置信度评级。建议的补丁在 Claude Code on the web 中审查和应用。执行要点:对最关键仓库先跑首次完整扫描并当作基线——它可能会在被认为干净的代码中浮现发现;积极开发的服务每周是一个合理默认;带原因驳回以便同一发现不会在下次运行时作为新发现返回;比一个补丁更宽的发现(架构弱点、跨服务重复模式)写成 intent.md 从 Plan 开始。

Claude Tag · 事件从沟通渠道到达

事件也可以从 Slack / Teams 这类渠道到达。Claude Tag(公共 beta)让 Claude 以自己的身份成为那些频道的成员,所以每个新事件获得一个第一响应者,响应本身成为循环和未来事件记忆的一部分。频道就是审计追踪:请求、诊断、人类授权和修复都留在事件被处理的地方。通过 MCP 访问,Claude 验证指标回到基线并在线程中确认,把事后分析写到版本控制的经验文件。小而界定良好的修复作为 PR 通过评审关卡,更大的任何东西被写为 intent.md 用于 Stage 1。

前置指标 · Leading

从带状突破到「分类队列中出现 intent.md」的时间,与旧的「从事件到事后行动」相比——检测脚本日志里有突破时间戳与事件层级。扫描侧则看按计划连接仓库的份额与从发现被报告到补丁进入 PR 评审关卡的时间。

后置指标 · Lagging

成为合并修复的发现份额(分类队列 vs 实际 PR 历史),以及同一类别的重复事件——随着修复向 eval 套件添加案例,它应该下降。扫描侧则看计划扫描发现的漏洞 vs 在生产中或外部报告发现的,以及经过几次运行的仓库上每次扫描发现的趋势。

10控制体系:skill / hook / 沙箱的三层分工

整份 playbook 里最容易被误读的一点,是把 skills 当成「策略执行器」。原文的定位很明确:skill 是建议性控制,hook 是它背后的确定性层。分不清这两者,就会得到一堆「写了标准但没人遵守」的装饰。

强制力自上而下递增:建议 → 确定性 → 不可绕过 Skills 建议性 · advisory 在写代码时可能应用策略,但没有任何东西强制会话遵守它。 触发词命中时才加载 调用记录进会话追踪 Hooks 确定性 · deterministic 在每个匹配它的操作上运行,可以允许、询问或阻止。 PreToolUse 按工具匹配 exit 2 阻止并说明原因 权限 / 沙箱 不可绕过 · non-bypassable 托管设置由平台团队部署,工程师无法编辑或覆盖任何内容。 托管规则不可被扩权 OS 级沙箱 failIfUnavailable 放置判据:必须无条件成立的策略 → hooks + 托管设置;必须一致应用但无需强制的知识 → skills;团队约定与命令 → CLAUDE.md。 失败模式自检:如果引用某策略的评审发现不向零下降,要么 skill 没有触发,要么它的文本已经偏离官方策略。

图 10 · 控制分层。三层不是替代关系而是兜底关系:skill 负责让 Claude「知道」策略,hook 负责让违反策略的操作「跑不起来」,权限与沙箱负责关掉 hook 也管不到的口子——例如工具级拒绝拦不住 shell 命令联网,只有 OS 级域允许列表可以。

常见误配与症状

如果只用了这一层会发生什么修正
只有 skills 策略文本漂亮但可以被绕过;同一类评审发现在多个 PR 上反复出现,说明「让违规罕见」没有兑现成「几乎不可能」 在 skill 后面加 hook;对必须无条件成立的条款,改用托管设置
只有 hooks 违规被拦住但智能体不理解为什么,于是换个写法再试一次;批准提示过多会把所有并行会话拉回同一条关键路径 先用 skill 教会做法,再用 hook 兜底;把「要求人工批准」的 hook 归入部署关卡而非构建期
只有人工评审 评审者成为唯一瓶颈,队列堆积;且评审质量随负载波动 让机械证据(测试输出、构建日志、截图 diff)先附加到 PR,人类只裁决意图与风险
策略变了但 skill 没变 评审发现不下降,因为代码生成时应用的是过期标准 把「策略所有者批准 → skill 合并」的耗时作为前置指标来管
一句话判据

Skill 使违规罕见,hook 使它们几乎不可能。如果你需要「几乎不可能」,就必须在 skill 之外再加确定性的一层。

11度量体系:每个阶段都必须成对度量

playbook 为每个阶段都同时给出前置指标与后置指标,这不是凑数。只给前置指标,团队会优化过程而不优化结果;只给后置指标,反馈太慢、无法在一周内纠正。

阶段前置指标(Leading)后置指标(Lagging)数据来源
Plan 从首次对话到 intent.md 提交的时间(期望从数周降到数小时) intent.md 存活率;同一变更在首次 spec.md 提交后的 intent 改动次数 intent 归属地 git 历史
Design intent.md 提交与 spec.md 提交之间的经过时间 构建开始后的需求返工(首次 plan.md 提交之后的 spec 提交) git 时间戳 / git log
Build 第一次实现通过就合并的份额;计划批准到合并 PR 的时间 每个变更的返工周期;合并 diff 仍匹配 plan.md 的频率 PR 元数据
Test 智能体编写变更的第一次 CI 成功率;eval 通过率;事件变成永久 eval 的耗时 每个 PR 的评审时间;CI 中捕获的回归 vs 生产中发现的回归 CI 系统 / 事件追踪器
Deploy 第一次评审的时间(应降至分钟级);无人类触及分支即解决的评审评论份额;等待每个审批关卡的时间 合并前捕获的缺陷与漏洞 vs 逃逸到生产的;DORA 度量 Git / hook 的 OpenTelemetry 导出 / CI 与部署工具
Maintain 带状突破到「分类队列出现 intent.md」的时间;按计划连接的仓库份额;发现被报告到补丁进入 PR 的时间 成为合并修复的发现份额;同类重复事件;计划扫描发现 vs 生产发现;每次扫描发现数的趋势 检测脚本日志 / 扫描历史 / PR 元数据 / 事件追踪器
为什么这套度量「能落地」

注意上表的数据来源——绝大部分是 git、PR 元数据、CI 与既有事件追踪器。整套度量体系几乎不需要新建遥测管道,它是对已有元数据的重新切片。这是它能被持续使用、而不是变成一年后没人看的仪表盘的前提。

反 Goodhart 原则

前置指标单独存在会被直接优化(例如「缩短评审时间」可以通过不看 diff 达成)。所以每条前置指标都配了一条后置指标做对照——评审时间下降的同时,逃逸缺陷不能上升。同理,「并行会话数」必须与「返工率」一起读,「自动分类的故障份额」必须与「DORA 指标」一起读。

度量成对出现,是为了让「过程变快」这件事必须同时证明「结果没变差」。

12采纳路径:从任何无前置的 play 开始

Plays 是非线性的。采纳顺序 ≠ 阶段顺序——依赖图决定的是「先采用哪些」,不是「先做哪个阶段」。

原文的规则很干脆:从任何没有箭头指向它的 play 开始——没有任何东西指向它,所以它不需要任何先决条件。对于任何其他 play,指向它的箭头就是需要先采用的 plays。

第 0 层 —— 无前置,可从任意一个开始(原文称为「clay play」) Plan · intent.md CLAUDE.md Skills Hooks 反馈回路(Test) 第 1 层 —— 需要第 0 层中的指定条目 Design · spec.md ← Plan · Skills plan mode ← Plan · CLAUDE.md PR 评审循环 ← CLAUDE.md 持续 evals ← CLAUDE.md · 反馈回路 第 2 层 —— 需要两个前置同时就位 并行会话 / 子智能体 ← CLAUDE.md · 反馈回路 CI/CD 自动化与沙箱执行 ← PR 评审循环 · Hooks 第 3 层 —— 需要多个前置全部到位(自主性最高) 闭环自动化(Maintain) ← intent 格式 · PR 评审 · Hooks · CI/CD 回滚 计划扫描(Claude Security) ← PR 评审 · Hooks · intent 格式 注意第 2、3 层包含了闭环的全部前置——所以「无人启动的循环」是采纳路径的终点,不是起点。

图 11 · 采纳依赖图。第 0 层的五个 play 全部无前置,可以从任意一个切入。往下每一层都需要上层的指定条目就位,第 3 层的「闭环自动化」需要四个前置全部到位——这解释了为什么自主运行流水线是转型的终点:它的每一个前置本身就是一次独立转型。

为什么采纳顺序不等于阶段顺序

一个常见的错误是按 Plan → Design → Build → Test → Deploy → Maintain 的顺序推进。但依赖图说明:CLAUDE.md、skills、hooks 三者都无前置,可以在没有任何流程改造的情况下先落地,并且它们会立刻改善后面所有阶段。反过来,闭环自动化(Maintain)看起来是「第六个阶段」,实际是最后一个能做的——它需要 PR 评审、hooks、CI/CD 回滚路径全部就位。

推荐的启动顺序

先做无前置且全局受益的三件事:写好 CLAUDE.md、把一条执行不一致的机构知识写成 skill、给一个必须无条件成立的约束配一个 hook。然后接入 intent.md 与反馈回路。PR 评审循环与 CI/CD 自动化在其后。把闭环自动化留到最后——它是对前面所有投入的乘法项,而不是起步项。

13反模式清单

以下每条都对应 playbook 中一个明确的机制。用法:找到你已经在做的那些,右边就是修正方向。

层反模式症状修正
战略 把 AI 原生 SDLC 当成工具采购 推了 Claude Code,流程照旧——瓶颈堆在 Plan、Review/Test、Deploy 上,生产力提升被关卡吃掉 转型必须覆盖 Build 左右两侧的人类速度节点,而不只是实现阶段
按阶段顺序推进六个 play 一开始就做闭环自动化,卡在「没有 PR 评审关卡、没有 hooks、没有回滚路径」 按依赖图走:先做无前置的 CLAUDE.md、skills、hooks、反馈回路
把配置当成一次性文档 模型升级或提示重写后,智能体输出质量悄悄下降却无人察觉 把 CLAUDE.md、skills、hooks 当作生产代码做回归测试(持续 evals)
工程 逐行人工评审智能体的 diff 评审队列堆积;或者代码在审查不足的情况下发布——受监管组织两者都不能接受 多层智能体评审给出按严重性排名的发现,人类注意力移到「变更是否做了计划意图的事」
没有已接受的计划就开始写代码 评审者看到的第一件事是完成的 diff,此时返工已经昂贵 用 plan mode 起步,批准的版本提交为 plan.md,PR 评审对照它检查
让智能体自己宣布「完成」 报告完成但没有机械证据,工程师被迫全量复检 在 CLAUDE.md 写明:报告完成前必须运行 build / test / lint 并粘贴输出
修复任务期间允许改测试 测试被削弱以让实现通过,回归保护失效 用 hook 在修复任务期间阻止编辑测试文件;或评审时拒绝任何触及测试的变更
并行会话数超过审查能力 开了六个会话,但没人能正确审查这么多流 从 2–3 个会话起步;实际上限就是「一个人能正确审查多少流」
治理 把 skill 当成策略执行器 标准写了,但违规照旧——skill 是建议性控制,没有任何东西强制会话遵守 必须无条件成立的策略,在 skill 后面补 hook、托管权限或沙箱
生产路径上没有关卡 智能体顺着流水线一路推到生产 按环境分层自治;生产部署由具名发布经理授权,并由 hook 强制
让智能体持有常设生产凭证 沙箱形同虚设,部署能力等于一段带凭证的 shell 脚本 短期有范围令牌;部署/回滚通过按环境限定范围的 MCP 工具暴露
只度量前置指标 「评审时间下降了」,同时逃逸到生产的缺陷上升 每条前置指标都配一条后置指标对照读取
最容易漏掉的一条

监督本身是一个生产系统,需要做回归测试。智能体没完成你期望的事,通常不是模型变差了,而是 harness 变了——提示被重写、skill 被更新、hook 被停用、权限被放宽。持续 evals 就是为这件事存在的。

14结论与出处

模型和 harness 已经足够成熟,允许组织改变的不只是产生代码的方式,而是整个软件开发生命周期。这种转型把人类判断保持在流程的中心,并考虑大型企业组织的治理和监管要求。

把六阶段串起来看,这份 playbook 实际上在说一件事:当执行变便宜之后,控制的成本结构必须一起改变。传统 SDLC 把控制放在「人的注意力」上——逐行评审、阶段签核、委员会例会。这些控制在人类速度下是廉价的,在智能体速度下是最贵的。AI 原生的答案是把控制从人的注意力搬到可执行的配置里:约定进 CLAUDE.md,策略进 skills,硬约束进 hooks 与托管设置,判断进关卡——而人只在关卡上出现。

如果只能记住三件事

一、每个阶段以提交一个工件结束,工件触发下一阶段——提交链就是审计追踪。
二、Skill 让违规罕见,hook 让违规几乎不可能。需要「几乎不可能」的,必须再加确定性的一层。
三、度量成对读,人的注意力落在关卡上而不是每一行 diff 上。

标注:这是观点,不是共识

本文整理的是 Anthropic Applied AI 团队基于客户合作总结的实践,不是经过对照实验验证的普适结论。文中给出的时间变化(如「从数周到数小时」)是期望值而非测量结果,量化示例(20–50 个 eval、2–3 个并行会话、5 个 nit 上限)也都是实践建议而非阈值定理。请把本文当作一套可检验的假设集合:逐条用你自己的前置/后置指标去验证,而不是直接当成结论采纳。

资源清单(大致按推出顺序)

原文给出的平台团队设置清单,按 rollout 顺序排列:

  1. 组织级 Claude Code 安装——管理员决策图 —— code.claude.com/docs/en/admin-setup
  2. Settings 参考与优先级(含全部 managed-only key) —— code.claude.com/docs/en/settings
  3. 从 Claude 管理控制台下发服务端托管设置 —— code.claude.com/docs/en/server-managed-settings
  4. Permissions —— code.claude.com/docs/en/permissions
  5. Sandboxing · OS 级文件系统与网络隔离 —— code.claude.com/docs/en/sandboxing
  6. Hooks 指南 —— code.claude.com/docs/en/hooks-guide
  7. Hooks 参考 —— code.claude.com/docs/en/hooks
  8. Skills —— code.claude.com/docs/en/skills
  9. Plugins 与私有 marketplace(skill 与 hook 的组织级分发方式) —— code.claude.com/docs/en/plugin-marketplaces
  10. Managed MCP · 集中管控智能体的工具面 —— code.claude.com/docs/en/managed-mcp
  11. 企业部署总览 · Bedrock / Vertex / Foundry —— code.claude.com/docs/en/third-party-integrations
  12. 企业网络配置 —— code.claude.com/docs/en/network-config
  13. 监控(OpenTelemetry) —— code.claude.com/docs/en/monitoring-usage
  14. 分析仪表盘 —— code.claude.com/docs/en/analytics
  15. Compliance API · 企业活动流、会话检索与删除 —— platform.claude.com/docs/en/manage-claude/compliance-api
  16. 安全模型 —— code.claude.com/docs/en/security