六个阶段的交接，
全靠一串 commit
agent 写代码的速度已经变了，代码周围那套审批、review、交接和政策没跟着变，于是瓶颈从 build 挪到了它两侧。这份手册把六个阶段逐段改了一遍，串起来的是同一件东西：每阶段结束时提交的那份产物，它既是交接件，也是审计线索。
build 缩短到小时级，
它两侧还按人的速度跑
这份手册的作者是 Louis Claxton，内容是 Anthropic Applied AI 团队把 Claude 接进 SDLC 各阶段的一批最佳实践，原文写明它来自与客户的合作。它不是带对照组的实测报告，全篇没有效果百分比。
这里的 SDLC 指软件开发生命周期，即一个想法从提出、上线到持续运维的整套流程。多数组织跑的都是这六个阶段（plan / design / build / test / deploy / maintain）的某个版本。产品经理先用 PRD，也就是产品需求文档，说明要做什么；架构师把需求转成设计；工程师负责实现；受监管企业的 QA 团队验证结果；发布团队安排上线；运维团队监控系统运行。工作依靠文档、工单和签核从一个角色传给下一个角色。
这套流程之所以重，是因为每一步都要留下问责和控制。它背后有两个长期成立的假设。其一，写代码和实现功能是整个流程里最耗时、成本最高的部分，PRD、工作量估算和产品安全评审，都是为了让不同角色在持续数周、数月甚至数季的开发过程中保持一致。其二，每一步主要由人完成，因此各阶段的处理能力可以按照人的工作速度来配置。
agentic coding 改变了这两个假设。它不是让 AI 只补全几行代码，而是让 AI agent 自己读取代码库、修改文件、运行命令和测试，完成一段完整的编码任务。Claude Code 就是 Anthropic 提供的命令行编码 agent，能够在仓库里执行这些动作。
当实现工作缩短到小时级，plan、review、test 和 deploy 仍按原来的速度运行，瓶颈便移到了 build 两侧。原有控制手段也开始跟不上产出：一行行手工检查代码，在代码主要由人编写时是合理的，一旦大部分 diff（一次改动前后的代码差异）由 agent 生成，这种审查方式就跟不上了。例外事项仍要等待每周或每月召开的会议与委员会，治理成本随之上升。这里的治理，是公司用来确认谁批准了某项决定、依据什么标准批准，并为此留下证据的机制。
安全审查最能说明这种错位。安全团队的规模通常按照人的代码产出配置。agent 提高产出速度后，安全团队要么面对不断积压的 review，要么只能让审查不足的代码进入生产。受监管组织无法接受其中任何一种结果，安全检查和政策检查必须能够跟上 agent 的节奏。
手册给出的方向，是把 build 已经经历的改造扩展到整条 SDLC。AI-native SDLC 保留原有控制目标，但改变执行方式：AI 嵌在每个环节上，并推动阶段之间的自动交接与后续 play 的触发，改掉传统流程里那种手工、不顺畅的交接；流程从单向传递变成能把生产上的发现写回起点的循环。
| 阶段 | 传统 SDLC | AI-native SDLC |
|---|---|---|
| Plan | 需求由委员会搜集，经工作坊和签核提炼，手工写成文档 | Claude 直接从来源里综合出痛点，写进 intent.md，这份文件人能读、机器也能据以行动 |
| Design | spec 由分析师撰写，再由设计师解析 | 需求与设计压进与 agent 的一次工作会话，受编成 skills 的标准约束，在 git 里留版本 |
| Build | 测试和代码手写，文档在主要开发结束之后补 | 测试和代码由 AI 生成，制度性知识以带版本、机器可读的 CLAUDE.md 文件和 skills 形式维护 |
| Test | QA 闸门设在阶段边界上 | 持续 evals 织进实现过程 |
| Deploy | 人审每一行代码，治理发生在 review 周期里，且常常不一致 | 分层的 agentic review，人工 review 留给受监管与关键代码；治理在 AI 动手的当下被强制执行，hooks 充当审批闸门 |
| Maintain | 人盯着生产找 bug | agent 监控运行中的部署；任何被突破的控制带都被诊断，并作为一份新的 intent.md 写回循环 |
这张表列的是光谱两端，原文写明多数组织落在两列之间：Most organizations sit somewhere between the two columns.
每个阶段以一次 commit 结束，下一个阶段从读取它开始
对照表右栏的做法看似分散，串起它们的是 committed artifact，即提交到版本控制的产物。版本控制就是 git 这类记录改动作者、时间与历史的系统。
每个阶段都以一份产物写入版本控制结束，下一个阶段从读取这份产物开始。链条从 intent.md 起步，它记录要解决的问题和预期方向；随后是承载需求与设计的 spec.md，再到拆解实现工作的 plan.md。进入 Build 后，产物变成代码 diff 及其测试；进入 review 时，产物是带有检查结果和 review findings 的 PR。PR 是一组等待合并的代码改动，其中附有评论与自动检查结果。进入生产后，事故记录继续留在这条链上。
早期阶段采用 markdown 文件，是因为 product owner 和 agent 可以读取同一份材料并据此行动。product owner 是对某个产品需求负责、并决定是否推进的人。从 Build 往后，代码、测试、PR 和运行记录接过这项作用。
它同时就是审计线索。每一次提交都回答了几个关键问题：谁提出了什么要求，agent 产出了什么，谁批准了结果。需要判断的决定仍由人负责，变化的是人的注意力：它不再平均分布在每个阶段，而是跟着待审的产物移动，集中到真正需要批准的闸门上。
产物同时也是触发器，这是「流程从直线变成闭环」的具体机制。早期采纳时，这些步骤可以由人逐次给出 prompt；流程成熟后，每份被接受的产物会自动触发下一道闸门，人只需查看 agent 标出的重点，而不必在每个阶段重新组织上下文。
| 阶段结束时提交的产物 | 触发的下一步 |
|---|---|
intent.md 被接受 | 需求与设计那一遍 |
spec.md 获批 | plan mode |
| PR 被合并 | 交付流水线 |
| 生产上一条控制带被突破 | 写出下一份 intent.md |
遗留系统与唯一真相源
现有组织通常已经在跟踪这些产物，只是它们不一定存放在 markdown 中。工作项可能在 Jira，需求可能保存在具备合规追溯能力的工具里，设计可能在 Figma，变更审批可能由变更委员会管理。这些系统已被审计师、监管方和其他团队采用，很难直接替换。因此，AI-native SDLC 需要围绕既有系统生长。关键规则是：为流程产生的每一件产物指定一个 source of truth，即唯一真相源，其余系统只保存副本或指向原件的链接。不同产物可以选择不同的真相源。
| 配置 | 权威记录放在哪 | 代价 / 适用 |
|---|---|---|
| 仓库当真相源 | markdown 产物是权威记录，遗留系统引用 commit 中的文件 | 工程主导型组织较清晰的一种配置：所有记录集中在一个工具里，只有一套权威时间戳 |
| 遗留系统当真相源 | Jira、ServiceNow 或需求工具保存权威记录，markdown 只是工作副本 | Claude 在会话开始时读取记录，并在生成 spec 或 plan 的同一会话中，通过 MCP 连接器把结果写回原系统 |
| 只做关联（最低门槛） | 两边都保有记录 | 每份产物记下遗留记录的 ID，每条遗留记录保存 markdown 文件的 commit SHA；适合转型起步，但要承认存在两个真相源 |
MCP 连接器承担的是让 agent 直接访问外部工具并更新记录的工作；commit SHA 是这次提交的唯一标识。原文的收口是：Both the legacy system and the markdown-first system can coexist, so long as there is a link between the two or one is declared the source of truth.
12 个 play，箭头给的顺序不是阶段顺序
手册的主体由按六个非线性阶段分组的 play 构成。play 是一套可以单独采纳的流程做法，合起来覆盖完整生命周期。
每个 play 都按同一个 5 项结构展开：改变了什么；怎么起手；具体实施步骤；治理上的考虑；以及怎么衡量它有没有起作用。这里的衡量方式是指标定义，不是已经取得的结果。这些 play 可以在不同时间进入不同阶段，每个 play 的 Prerequisites 会列出必须先具备的条件，组织不需要一次改完整条流程。
依赖图上，12 个 play 按所在阶段标注，并分成 5 层。第一层有 5 个橙色 play，clay 只是图例中的橙色色名。它们没有任何指向自身的箭头，因此不要求先采纳其他 play，可以从其中任何一个开始。对其余 play 而言，指向它的箭头代表需要先采纳的项目。
The plays are listed with stage; the arrows give the order to adopt them in. The two are not the same. 图中实线与虚线箭头都表示前置关系 · 出处 The AI-Native SDLC playbook| 采纳层 | 这一层的 play（括号内为所属阶段） |
|---|---|
| 1 · 无前置，可任选其一起手 | Capture intent（Plan）、CLAUDE.md（Build）、Plan mode（Build）、Feedback loop（Test）、Hooks（Deploy） |
| 2 | Skills（Build）、Subagents（Build）、Evals（Test） |
| 3 | Requirements & design（Design）、PR review（Deploy） |
| 4 | CI/CD（Deploy） |
| 5 | Closing the loop（Maintain） |
因此，采纳工作可以从 Build 或 Test 的某个 play 开始，不必按照 Plan、Design、Build 的阶段顺序推进。无论从哪里起步，连接各阶段的规则保持不变：一个阶段以提交产物结束，这次提交再启动下一个阶段。
意图写一次，需求与设计收进同一次会话
Plan 阶段先把意图固定下来，不再等待另一个角色代写文档。入口可能是一个人的想法、一张工单，也可能是告警暴露出的事故。
提出人先与 Claude 头脑风暴，形成 markdown proto-spec，也就是尚未成为正式 spec 的原型规格，再存为 intent.md。无论意图来自事件还是 agent，产品负责人都要在提交前审阅并修正内容。传统路径中，一个想法往往要依次变成 backlog 条目、user story 和故事点，再进入 refinement 会议；每次交接都会转移所有权，工程师最终看到的内容与提出人的原意已经隔了多层。intent.md 则保留提出人的措辞，既可供人阅读，也能进入版本控制，并被下一阶段直接读取。
这套做法没有前置 play，但需要一次性搭好基础设施：非工程人员能够访问 claude.ai 或 Cowork，团队有统一的 intent.md 模板，也有产品负责人管理的共享意图存放地。单个产品可把它放在产品仓库的 intent/ 目录，让意图与据此生成的代码留在一起。只有意图横跨许多仓库时，独立仓库的成本才值得承担；在 monorepo 中，一个目录已经足够。平台或工程团队负责建立存放地并设置写入权限。不会使用 git 的贡献者可以通过 GitHub 等版本控制系统的连接器，让 Claude 在 claude.ai 或 Cowork 中代为提交 markdown。
提出人先用自己的话说明目前做不到什么、谁受影响、理想结果和 scope 之外的内容。Claude 继续追问用户、约束、范围和成功标准，直到想法足够具体，再按公司模板生成 intent.md。模板也可以编成 skill，由技术成员建立、lead 签核，内容可以覆盖问题、期望结果、受影响的用户与系统、约束及待解问题。提出人修正误解后提交文件，作者和时间戳随之进入记录，产品负责人从这里接手。
# 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?
提交后的 intent.md 就是治理证据：作者、时间戳和完整修订史保存在 git 历史中，产品负责人决定接受或拒绝，这个决定以合并动作、或那次关闭的 review 记录下来。
意图获批后，需求与设计收进同一次会话。Claude 读取 intent.md，并在品牌、安全、合规和 UX skills 的约束下生成 spec.md。产品负责人负责审，不负责从头写，重点确认 spec 是否解决原先陈述的问题，待解问题是否已经回答或明确带入下一步。传统流程把需求和设计交给不同团队，分析师先把想法正式化，设计师再把需求解析成设计；这种分工便于问责，却增加等待和信息损耗。前端场景最直观：产品负责人可将获批的 intent.md 交给 Claude Design (beta) 生成并迭代界面稿，再导给 Claude Code 实现。
首次执行可以手工开启会话，附上 intent.md，加载公司的 skills，并使用下面这段提示词。
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.
流程稳定后，这段操作可以编成组织级 slash command。再往后，intent.md 被接受本身就能触发非交互任务：任务在合并时加载公司 skills，生成 spec.md，再以 pull request 提交，产品负责人第一次介入便是 review。
Claude 标出的问题点要先处理。这些通常是分析师原本需要升级的问题，产品负责人应在工程团队看到 spec 前，逐项与 policy owner，也就是有权批准相应政策修改的负责人，确认清楚。spec.md 与 intent.md 一起提交，分别记录要求了什么和决定了什么。常规内容由产品负责人决定是否进入 Build，较高风险内容再与技术 lead 商议，但推进决定始终由人作出。接受 spec，就是下一阶段启动 plan mode 的信号。相关政策在 spec 形成时已经被读取和应用，spec、提示词以及当时使用的 skill 版本也都保存在版本控制中。
先有获批的计划，再有代码
手册给 Build 阶段定的规则是：没有获批的计划，就不开始实现。制度性知识写成 agent 能读取的文件，护栏则以代码运行。
工程师在 plan mode 中开启 Claude Code 会话。plan mode 只允许 Claude 读取代码库并编写实现计划，在工程师批准前不能修改文件。会话以 Design 阶段批准的 spec.md 为输入，Claude 先说明要改哪些文件、按什么顺序实施，以及用哪些测试证明改动有效。工程师继续追问可能破坏什么、风险最高的步骤在哪里、还有哪些考虑过但未采用的方案，直到一名没有看过会话的工程师仅凭计划也能完成实现。
传统做法中，工程师读完设计就开始编码，文件范围、实施顺序和测试安排常留在个人脑中，至多写进工单评论。review 人第一次看到的已经是完整 diff，此时改变方案的成本更高。plan mode 把这些决定提前写成 plan.md，批准的那版提交到 git，后续 PR review 会用最终 diff 与它对账。实现偏离计划时，plan.md 应在同一个 commit 中更新，也可以用 hook 强制同步。hook 是 agent 动作前后自动运行的脚本，能够放行、询问或直接拦截操作。
# 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.
工程师接受计划之前，Claude 不能编辑文件。因此设计评审发生在代码生成之前，改变主意只需修改文档。常规计划由工程师批准，较高风险的改动交给技术 lead 或架构师。
计划获批后可进入 auto mode，也称 auto-accept，Claude 会连续执行改动，不再每编辑一个文件都请求确认。随着 CLAUDE.md、skills、hooks 和可自动运行的测试套件逐渐成熟，auto-accept 可用于 spec.md 边界清楚、影响范围较小且测试充分的常规任务。工程师的关注点随之从逐个动作审批，转向较长会话结束后的产物 review。auto-accept 配合 worktree 还提高了个人与团队层面的并行度；按手册的说法，auto-accept 是把整条 SDLC 自主跑起来、让循环闭合的基础。
CLAUDE.md 保存新人第一天需要知道的仓库背景，包括构建、测试和 lint 命令，关键约定、架构信息以及团队常犯的错误。Claude 会在每次会话开始时读取它。团队可在仓库中运行 /init 生成初稿，再删去非必要内容，将文件控制在一页以内，签入仓库根目录并按代码变更方式 review。工作规则可以很直接：Claude 同一个错犯两次，就把修正写进 CLAUDE.md。过时内容需要及时删除，避免占用 context。
# 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/.
手册给的经验法则是：必须被一致执行的制度性知识写成 skill，本该留在 CLAUDE.md 或单次 prompt 里的东西不要写成 skill。团队先选择一项目前执行不一致的要求，例如安全标准、API 设计约定或品牌规则，再建立一个包含 SKILL.md 的文件夹。markdown 开头由 --- 包围的 frontmatter 写明触发条件，正文写明具体动作。工程师依据 policy owner 的正式政策编写，并测试不同表述下是否都能触发，再把它放进 .claude/skills/ 随代码发布，或作为插件分发到全组织。政策变化时集中修改 skill，由 policy owner 签核，工程师在下一次会话中自动获得新版本。
---
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.
skill 是建议性控制，hook 才是确定性层。skill 能让 Claude 很可能在编码时应用政策，却不能强迫所有会话遵守。必须始终成立的政策，需要在其后增加拦截动作的 hook，或者在 PR review 中重新核对。skill 的调用保存在会话轨迹中，其修改也像代码一样接受 policy owner 审查。
Build 阶段的文件编辑和 shell 命令最多，因此也是 hook 最频繁的阶段。hook 可以禁止修改受保护路径，在文件编辑后立即运行格式化和 lint，也可以阻止凭证进入 diff。与不可例外政策对应的 skill，背后都应有确定性检查。此处的 hook 要快，只处理刚变更的文件；完整测试留到 commit 或 PR。需要人工批准的 hook 则属于 Deploy 阶段，因为在 Build 中等待审批会让人重新进入所有并行会话的关键路径。
并行会话与 subagent 解决的是不同问题。并行会话是完整的 Claude Code 实例，各自在 git worktree 中处理任务。worktree 让同一仓库在磁盘上拥有多个独立检出，每个检出使用自己的分支，避免争抢文件，例如可分别运行 claude --worktree feature-auth 和 claude --worktree fix-rate-limit。拆分依据是任务是否修改不同文件，共享文件的工作应放在同一会话中顺序完成。手册建议两三个会话作为起点，实际上限取决于工程师能够及时 review 多少条工作流。
subagent 则运行在单个会话内部，拥有独立 context 和受限工具权限，适合反复出现的小任务，例如简化代码、启动应用验证行为，或探索代码库后返回结论。定义保存在 .claude/agents/ 下的 markdown 文件中，写明名称、使用时机和可调用工具，再签入 git 供团队共用。
---
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.
并行会话增加一个工程师同时推进的任务数，subagent 保持每个会话的主 context 聚焦。产出增加后，控制必须来自仓库内统一的 hooks 和权限配置；每个会话的动作都会被记录，并记在启动它的那位工程师名下。
会话先自证，配置也要跟着回归
Test 阶段要求每个会话在人看到产物前先检查自己的工作，同时让给 agent 下指令的那套配置，像代码一样接受回归测试。
Claude 始终需要一条验证路径，可以是测试、构建或截图对比。会话先运行检查，根据结果自行修正，再把产物交给工程师。传统流程中的信号往往较晚，CI、测试和生产反馈依次到来；代码由 agent 大量生成后，晚到的信号意味着要有一个人去检查它的全部产出，而这个人就重新成了瓶颈。
如果验证依赖一串命令和环境知识，应将其包装成 make test 或 npm test 这类统一目标，并在失败时返回非零退出码。命令及健康输出示例写进 CLAUDE.md 的 Commands 部分。目标必须可直接判断，例如 test_status.py 中所有测试通过、截图与设计稿一致，或者端点返回 200 并包含新字段。
修复 bug 时先写失败测试。Claude 先把问题复现为测试，运行并确认失败原因符合预期，提交该测试，然后在不能编辑测试的条件下修复代码，这条限制由 test-file hook 强制执行。一个在修复之前就存在、agent 又改不动的测试，就是 bug 已经没了的证据。
UI 工作使用视觉闭环。Claude 获得浏览器或截图工具及设计稿，依次实现、截图、对比和调整，两三轮是正常的，每轮都应缩小实现与设计之间的差异。验证还要写进任务的完成定义：报告完成前先运行检查并附上输出。agent 不应拥有削弱自身检查的权限，因此修复期间由 hook 禁止编辑测试文件；也可以在 review 中检查 diff，拒绝涉及测试文件的改动。
## 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.
治理落在四个问题上。要强制的有两条：完成前必须验证，以及修复期间禁止 agent 编辑测试文件；组织想要它们有保障时，就用 hook 来落实。证据是 make test 的原始输出、构建日志或截图对比，直接来自工具链。记录保存在会话轨迹和 PR check run 中，并通过 OpenTelemetry 导出到公司的观测系统；OpenTelemetry 是统一传递日志和指标的开放标准。最终批准者是 PR 的 code owner，机械检查已经附上，review 可以集中判断意图与风险。
continuous evals 对应传统流程中的 stage-gate QA，后者是在阶段边界设置质量闸门，不通过便不能继续。eval suite 是一批带预期结果的评测用例，在模型、prompt、CLAUDE.md、skills 或 hooks 变化时运行，用来判断 agent 是否仍按相同标准工作。模型能力变化后，旧用例可能不再能区分出表现差异，新用例需要从持续监控中补入；部分团队也会根据用例性质选择离线定期运行。
平台工程师从近期工作中收集 20 到 50 个真实任务，为每项任务保留预期或可接受结果，再写成包含 prompt 与检查条件的 eval。条件可以是测试通过、lint 干净、行为不变或政策得到遵守。套件在 CI 中非交互运行，既按计划定时执行，也在 agent 配置变化时触发。导致通过率下降的 skill 修改必须在合并前接受 review。每次生产事故还要由出事故的团队补一条 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
会话自证与配置回归都落在 Test 阶段，接下来是 review 与上线那一侧。
review 双向运行，闸门守在生产前
到了 Deploy，review 在两个方向上进行，治理则在 agent 动手时生效。agent 能做完生产闸门之前的每一步，但过不去这道闸门。
Claude 既 review 别人的 PR，也处理自己提交的 PR 上收到的评论。所有 PR 都经过同一套 review pass，findings，也就是发现的问题条目，按 severity 严重级别排序。人的注意力因此上移到改动是否符合原定意图、风险能否接受。传统流程按人的产出规划 review 容量，一个 reviewer 要读完整份 PR，质量随负载波动，积压也会随之增长。
起点是 Build 阶段更新过的 CLAUDE.md，再加上执行成文政策所需的 skills 和 subagents。仓库安装 Claude 集成后，可以选择管理员开通的托管 Code Review (research preview)，也可以在自己的 CI 中运行 claude-code-action，需要时通过 AWS Bedrock、Google Vertex 或 Microsoft Foundry 调用模型。前者起步最快，后者适合需要控制流水线或使用自有云合约的组织。git 平台还应配置 branch protection，例如合并前必须由 code owner 批准，code owner 是指定代码范围的负责人。
技术 lead 在仓库根目录维护 REVIEW.md，分别规定 bug 与逻辑错误、安全与漏洞、对 spec.md、plan.md 和设计原则的合规检查，并划清 Important、Nit 与无需报告的问题。Nit 指命名、风格等轻微意见。
# 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.
findings 本身不能批准或拦截 PR，最终批准仍由 code owner 通过分支保护给出。需要按 findings 阻止合并时，平台工程师可以读取 check run 输出的机器可读严重级别计数。
在评论里加入 @claude，Claude 会处理意见、推送修复，并把请求与改动留在 PR 线程中，这个回路通过 claude-code-action 运行。托管服务中的 @claude review 则要求重新 review。对于 Claude 自己创建的 PR，团队还可以把持续处理未解决评论和失败检查的过程封装成 slash command，直到 PR 全绿，只等 code owner 批准。
review 结果还会回写流程。相同错误第二次出现时，修正规则随本次 review 写入 CLAUDE.md，下一个 PR 便能直接检查；review 也会指出哪些改动已使 CLAUDE.md 过时。技术 lead 每月调一次设置，通过给 findings 打分改善 reviewer，在 REVIEW.md 中把 nit 限制为每次最多五条，其余只报一个总数，并排除生成路径和 CI 已经强制检查的内容。
review 政策适用于所有 PR，findings、修复、评分和批准都留在 PR 历史里。写代码的 agent 无法批准自己的代码，职责分离因此保住，PR 也同时构成审计记录。
hook 作为审批闸门
Build 阶段的 hook 可以直接放行或拦截动作，也可以暂停执行，等待指定人员批准。发布闸门只是最清楚的用例，它同样能在 Build 阶段阻止没有变更工单的 migration 或基础设施修改，在 Test 阶段阻止修复任务改写测试。工程领导层、变更管理和合规团队先确定必须保留的人工审批，平台工程师再把每一道闸门写成 hook。团队级规则进入 .claude/settings.json，不可协商的规则进入 managed settings，也就是由平台或 IT 管理员统一下发、工程师本地无法修改的设置。手册要求 hook 拦下一个动作时把理由讲清楚：原因和申请批准的路径都要出现在 Claude 的输出里。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh" }
]
}
]
}
}
#!/bin/bash
# Production deploys require a named release authorization
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 blocks the action; the message goes to Claude
fi
fi
exit 0
受监管企业的 managed settings 逐键解读
受监管企业的示例配置由平台团队通过 MDM 或管理控制台下发，工程师无法编辑或覆盖其中任何一项。MDM 是公司统一向员工设备配置策略的系统。
{
"permissions": {
"deny": [ "Read(.env*)", "Read(./secrets/**)", "WebFetch",
"Bash(curl *)", "Bash(wget *)" ],
"allow": [ "Bash(git *)", "Bash(make build)", "Bash(make test)",
"Bash(make lint)" ],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true,
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false,
"network": { "allowedDomains": ["git.internal.example.com",
"registry.npmjs.org"] },
"credentials": {
"files": [ { "path": "~/.ssh", "mode": "deny" },
{ "path": "~/.aws/credentials", "mode": "deny" } ],
"envVars": [ { "name": "GITHUB_TOKEN", "mode": "deny" } ]
}
},
"allowManagedHooksOnly": true,
"disableSideloadFlags": true,
"allowManagedMcpServersOnly": true,
"strictKnownMarketplaces": [ { "source": "github",
"repo": "example-corp/approved-plugins" } ],
"requiredMinimumVersion": "2.1.193"
}
| 配置键 | 在控制上买到了什么 |
|---|---|
permissions.deny / permissions.allow | 前者阻止 agent 读取机密或通过工具任意出网，后者预先放行安全的内部循环，减少反复提示 |
disableBypassPermissionsMode + allowManagedPermissionRulesOnly | 工程师、项目文件或命令行参数都无法放宽规则 |
sandbox | 补权限补不上的缺口：仅在工具层禁止 WebFetch 仍挡不住 shell 命令联网，操作系统层的域名白名单才直接掐掉出网 |
failIfUnavailable + allowUnsandboxedCommands | 把沙箱变成硬闸门：沙箱起不来时 Claude Code 拒绝运行，失败命令也不能转到沙箱外重试 |
credentials | 文件工具的 deny 覆盖不到 shell 默认可读的 ~/.ssh 与 ~/.aws/credentials，这一块禁止这些读取，并从每条沙箱命令的环境中移除指定机密 |
allowManagedHooksOnly | 只有组织下发的 hook 能运行，本地加不上也换不掉 |
disableSideloadFlags + strictKnownMarketplaces | skill、agent、hook 和 MCP server 只能来自组织审核过的 plugin marketplace，不能来自家目录 |
allowManagedMcpServersOnly | agent 可用的工具面成为平台团队维护的白名单 |
requiredMinimumVersion | 版本低于批准下限时拒绝启动，于是控制由组织真正评估过的构建执行 |
Consider the above a starting point to tailor, rather than a recommendation to copy. 这份配置是裁剪的起点，不是照抄的建议。每条 deny 都以部分能力为代价，平衡点取决于仓库的数据分级。
CI/CD 与生产闸门
CI/CD 先从只读的判断类任务开始，通过 claude -p 非交互地分诊构建失败、总结 flaky 测试或起草变更日志，再把修 lint、更新生成文档等写操作放到既有闸门后。所有 agent 改动都以 PR 出现，没有直接推送 main 的路径。任务运行在受网络策略约束的容器中，使用短时效、受限令牌，默认不持有生产凭证。deploy、status 和 rollback 通过 MCP 暴露为按环境限定的工具。开发环境里 agent 自由部署，生产环境则由 agent 准备发布、发布经理授权，hook 强制执行，staging 落在两者中间。按手册的要求，回滚应当是整条流水线里演练得最充分的一条路，在 staging 定期真实跑，以便 Maintain 阶段发现异常时调用。
- 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
最终边界很清楚：分支保护把 agent 写入变成 PR，生产 hook 等待指定发布经理授权，每次非交互运行以 agent 自己的身份留下日志，环境权限只决定它在闸门前能走多远。
循环闭合，发现被写成下一份 intent.md
此前每个阶段仍需要人启动最初几步。Maintain 把启动动作也接入循环：持续监控的 agent 可以在 bug 工单出现后创建 intent.md，再依次进入需求、计划、构建、测试和 review。
这一阶段以 headless 方式运行，各阶段之间设置独立的置信度闸门，由确定性检查或对抗性 review agent 决定是继续往下走，还是升级给人。传统维护依赖人发现告警、领取工单并重启流程，凌晨告警可能遗漏，backlog 中的工单可能长期无人处理，post-mortem 的行动项也未必进入代码库。AI-native 一侧则由控制带被突破、工单、频道消息或定时计划触发 Claude；控制带是按历史均值和波动范围划出的正常区间。Claude 诊断后只沿设有闸门的路线行动，把发现写成 intent.md，人负责分诊和 review，不再负责启动。
服务负责人或平台工程师选择具有稳定滚动基线的指标，例如 CI 测试失败率、部署后的 5xx 率或 PR 周期时间。检测脚本的典型做法是在滚动窗口上计算均值和 σ，σ 是衡量波动幅度的标准差，再配上 Western Electric 这一类规则，让控制带既能抓尖峰也能抓缓慢漂移。脚本进版本控制并带单元测试，响应档位写入 bands.yaml。
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] }
触发层可以是 GitHub 或 GitLab 的定时工作流、监控系统发出的 webhook，或内部网络中的 Cron Job。Claude 以无状态、非交互方式运行，可以作为 CI runner 的一步，也可以在沙箱容器中通过 Agent SDK 启动。一次循环因此能够在无人发起的情况下开始并结束。
诊断按 Plan 阶段的格式写入 intent.md，记录异常证据、期望结果、受影响系统和待解决问题，再进入完整流水线。服务负责人或值班工程师对队列分诊，面向产品的发现交给产品负责人，选择立即修复、排期或驳回；驳回结果用于调整控制带和降低噪声。修复上线时，事故会在 Test 阶段增加一条 eval，防止同类问题再次漏过。
权限和 managed settings 拒绝生产访问，调用、findings 与分诊决定都带时间戳。CI 测试失败率突破 3σ 时，agent 可以隔离 flaky 测试或创建 revert PR，由 review 闸门决定是否合并；统计窗口内有一次部署、而部署后的 5xx 率又突破 3σ 时，agent 可以触发既有回滚流水线；PR 周期时间触发漂移规则时，agent 向工程领导层生成报告，原文指出这说明这套 harness 对流程指标也管用，不只对生产指标管用。
Claude Tag：频道里的第一响应人
事故也可能从 Slack 或 Teams 进入。晚上十点出现的紧急事故消息可以立即获得响应。Claude Tag (public beta，当前在 Slack 可用) 让 Claude 以独立身份加入频道，新事故的首次响应、调查过程和制度知识都保留在线程中。频道里的任何人都能引导和推进这次响应，实时验证假设、探索选项、做调查，而频道里的历史记录本身就是可查的凭据。Claude 可以通过 MCP 验证指标是否恢复基线，在频道中确认结果，并把 post-mortem 写入版本控制中的 lessons 文件。它也能在工单或频道里分诊其他请求：边界清楚的小修复创建 PR，较大的事项写入 intent.md，重新进入 Plan。
模型和 harness 的增强，使改造范围从代码生成延伸到完整的软件开发生命周期。人的判断仍位于流程中心，治理与监管要求也被保留下来。这份指南汇总的是 Applied AI 团队每天为客户执行的许多真实最佳实践。
The loop keeps running. Human judgement stays above it.
每个 play 两个指标，数据都在已有系统里
手册给每个 play 都配了两个衡量指标。leading 指标先发生变化，通常观察时间；lagging 指标随后反映返工、逃逸缺陷或问题复发。它们描述的是应该衡量什么，并不代表已经取得了某种效果。
把 12 个 play 放在一起，数据源都来自组织已有系统，包括存放意图和 skill 的 git 历史与时间戳、PR metadata 与 PR 历史、CI、OpenTelemetry 导出、事故追踪器，以及 eval 套件每次运行报告的通过率。按下表逐行看，指标的数据源都落在这些既有系统上。
举两个例子。Plan 的 leading 指标是从第一次对话到 intent.md 提交所用的时间，原文预期它从数周的需求收集和打磨缩短到数小时，这是一项预期，不是实测结果。它的 lagging 指标是 intent.md 的存活率，即产品负责人接受并送入 Design、而不是关闭的比例。Skills 的 lagging 指标则是 PR review 中引用相关政策的 findings 数量，预期趋近于零；若没有下降，可能是 skill 未被触发，也可能是其文本已与正式政策偏离。
| play（阶段） | leading 指标 | lagging 指标 |
|---|---|---|
| Capture intent Plan | 从第一次对话到 intent.md 被提交的时间，读意图存放地的 git 历史；预期从数周的需求搜集与打磨周期降到数小时 | intent.md 的存活率（被接受进 Design 而非关闭的占比）；以及同一变更首个 spec.md 提交之后仍对 intent.md 做的改动数 |
| Requirements & design Design | 同一变更的 intent.md 与 spec.md 两次提交之间的时间（两个 git 时间戳），对比旧的「需求 + 设计」周期 | build 开始后的需求返工：数同一变更首个 plan.md 提交之后的 spec.md 提交数，git log 直接给 |
| Plan mode Build | 第一遍实现就合并的变更占比，以及从计划批准到 PR 合并的时间（数据在 PR metadata） | 每个变更的返工轮次（PR metadata），以及合并的 diff 仍与提交的 plan.md 一致的频率 |
CLAUDE.mdBuild | Claude 重复犯本该被 CLAUDE.md 挡住的错的频率；修正记在 git 历史里 | 新成员到第一个合并 PR 的时间（PR 历史） |
| Skills Build | 从 policy owner 批准政策变更到 skill 更新合并的时间（skill 目录上的 PR） | PR review 中引用该政策的 findings，应趋近于零；不降说明 skill 没触发，或其文本已与正式政策漂开 |
| Subagents / 并行会话 Build | 在 review 质量不下降的前提下每位工程师的并发会话数（从 OpenTelemetry 导出计数），以及一天中用于 steering 而非等待的时间占比 | 每位工程师每周合并的变更数，与返工率一起读（PR 历史） |
| Feedback loop Test | agent 所写变更的首次 CI 通过率（CI 系统已支持） | 每个 PR 的 review 时间（PR metadata），测试接住过去靠 reviewer 接的东西之后应当下降；以及变更失败率（事故追踪器） |
| Continuous evals Test | eval 通过率随时间的变化（每次运行由套件自己报告），以及一次生产事故变成常驻 eval 所需的时间 | 在 CI 里抓到的回归数，对比在生产中发现的回归数（事故追踪器） |
| PR review Deploy | 首次 review 的时间，应降到分钟级；以及无人碰分支就解决掉的 review 评论占比（数据直接在 git 上） | 合并前抓到的缺陷与漏洞，对比逃到生产的（PR 历史 + 事故追踪器） |
| Hooks Deploy | 每道审批闸门上的等待时间；每次 hook 决策都带时间戳和 allow / block 判决写进 OpenTelemetry 导出，因此可按闸门分别看 | 上 hook 前后到达生产的闸门违规数（事故追踪器） |
| CI/CD Deploy | 无需叫人就完成分诊的流水线失败占比（取自 CI/CD 流水线日志） | DORA 指标，CI 系统与部署工具本来就在发 |
| Closing the loop Maintain | 从控制带被突破到 triage 队列里出现 intent.md 的时间，对比旧的「事故到 post-mortem 行动项」；检测脚本日志里有突破时间戳与档位 | findings 变成已合并修复的占比（triage 队列对比 PR 历史），以及同类事故的复发，随修复给 eval 套件添用例而下降 |