AI 原生 SDLC 实践手册 · 杂七杂八集

如何借助 AI 逐阶段改造软件开发生命周期。

代码不再是瓶颈

各类组织已经开始用 AI 编写代码，速度之快在一年前还难以想象，但围绕代码的流程并没有同步跟上。

许多工程团队仍沿用原来的审批关卡、评审、交接和政策，导致 Claude Code 等 agentic 编码方案带来的生产力提升受阻。

软件开发生命周期（SDLC）是软件从构想到投入生产所经历的过程。大多数组织采用的流程都包含相同的六个阶段，涵盖软件的规划、设计、构建、测试、部署和维护。传统上，每个阶段彼此独立，由不同角色负责。产品经理编写需求，技术架构师把需求转化为设计，工程师根据设计进行构建，受监管企业的 QA 团队负责验证，发布团队负责上线，运维团队监控运行中的系统。工作通过文档、工单和签字确认在各阶段之间流转。

传统 SDLC 的流程很重，目的是确保每一步都权责明确、处于可控状态。然而，传统 SDLC 诞生于一个编写和实现代码最耗时、成本也最高的时代，因此它追求的是让那个时代的开发尽可能高效。如今，情况已经不同。产品需求文档（PRD）、估算流程和产品安全评审之所以存在，都是为了迫使各方在可能持续数周、数月甚至数个季度的开发过程中达成一致。

传统 SDLC 中的控制措施还假定每一步都由人完成。那些从 agentic AI 中获得最大价值的组织，已经围绕它如今具备的能力重建了流程，同时确保人始终参与其中。本指南将结合我们与客户合作的经验，介绍 Applied AI 团队在内部把 Claude 集成到 SDLC 各个阶段的一些最佳实践，帮助加快开发速度，让流程运转得更快。

当代码不再是瓶颈，构建阶段的速度又快到超出传统 SDLC 所能承载的范围时，会出现三种情况：

瓶颈会转移到构建阶段的前后环节，主要是规划、评审/测试和部署；这些环节仍按人的速度运行。
控制措施会脱离实际，变得难以执行。代码由人编写时，逐行人工评审合情合理；但当大部分 diff 都由 agent 编写时，这种做法就跟不上了。
治理成本会上升，因为例外情况仍需交由每周或每月才开一次的会议和委员会处理。

构建不再是制约因素，真正的制约来自它周围那些仍按人的速度推进的环节。构建阶段缩短到数小时，其他阶段所需的时间却没有变化。

以安全瓶颈为例。安全团队的人员配置是按人工产出规模确定的，因此，当 agent 让代码产出成倍增加时，要么评审队列越积越长，要么代码在评审不充分的情况下上线。受监管组织无法接受任何一种结果，所以安全和政策检查必须跟上 agent 的速度。

要更充分地释放 agentic AI 的生产力并确保其安全，传统 SDLC 也需要经历一场与实现阶段同等程度的改造。

代码不再是瓶颈
实践项
阶段 1——规划
阶段 2——设计
阶段 3——构建
阶段 4——测试
阶段 5——部署
阶段 6——维护
结语

什么是 AI 原生 SDLC？

AI 原生 SDLC 是一种重新构想的流程：它保留原有的控制目标，但采用新的执行方式。流程不再是线性的，而是形成闭环，并在每个环节嵌入 AI。AI 原生 SDLC 提倡自动交接并触发后续实践项，从而改善传统 SDLC 各阶段之间依赖人工、衔接笨重的交接方式。

这种转变也被称为 agentic SDLC、AI SDLC，或简称 agentic 软件开发。名称虽有不同，描述的却是同一件事。

AI 原生 SDLC 六个阶段的转变

下表展示了传统 SDLC 与 Claude 支持的 AI 原生 SDLC 这一区间的两个端点。大多数组织都处于两者之间。

阶段	传统 SDLC	AI 原生 SDLC
规划	由委员会收集需求，通过研讨会和签字确认加以提炼，再由人工整理成文	Claude 直接从信息源归纳痛点，将其记录在既方便人阅读、又能由机器执行的 `intent.md` 中
设计	分析师编写 spec，设计师再据此解读和设计	在一次与 agent 协作的工作会话中完成需求和设计，由编码为 skill 的标准提供指导，并在 git 中进行版本管理
构建	测试和代码由人工编写，文档则在主要开发工作完成后补写	测试和代码由 AI 生成，组织知识则以可进行版本管理、机器可读的 `CLAUDE.md` 文件和 skill 持续维护
测试	在阶段边界设置 QA 关卡	把持续 eval 贯穿实现过程
部署	人工评审每一行代码，治理通过评审周期开展，而且往往执行不一致	由多层 agent 评审，只把受监管代码和关键代码留给人工评审。治理在 AI 执行任务的同时落实，并以 hook 作为审批关卡
维护	由人监控生产环境中的 bug	agent 监控线上部署。一旦突破任何控制区间，就诊断问题，并将结果以新的 `intent.md` 写回闭环

右侧一列贯穿始终的是提交到版本控制的产物。每个阶段结束时都会提交一个产物，包括 intent.md、spec.md、plan.md、diff 及其测试、包含评审发现的 PR，以及事故记录；下一阶段则从读取这个产物开始。在前几个阶段，产物主要是 .md 文件，因为产品负责人和 agent 都能读取同一份文件并据此行动。从构建阶段开始，产物则变成代码及其相关记录。这一连串 commit 同时构成审计轨迹：谁提出了什么要求、agent 产出了什么，以及谁批准了它。

凡是需要判断的决策，最终责任仍由人承担。在 agentic SDLC 中，人的注意力会随着必须评审的产物一起转移。

每个阶段都会提交一个可供下一阶段读取的产物。意图、spec、plan、diff 和评审发现共同构成审计轨迹。

实践项

这些实践项是本手册的核心，分为六个非线性阶段（规划、设计、构建、测试、部署、维护），共同覆盖完整的生命周期。

每个实践项都包含：

有哪些变化；
如何开始；
具体实施步骤；
治理方面的考虑；以及
如何衡量它是否奏效。

这些步骤采用模块化设计，各组织可根据自身需求，在不同时间优先改造不同阶段。每个实践项都会在“前置条件”中列出其依赖关系，依赖关系图则会进一步呈现这些关系。

一个阶段以提交产物告终，这次 commit 会启动下一阶段。获准的 intent.md 会触发需求和设计流程；获批的 spec.md 会触发 plan mode；合并 PR 会触发流水线；如果生产环境突破了某个控制区间，系统就会写入下一份 intent.md，如此不断循环。

一开始，每一步都由你手动输入 prompt；最终则要形成一个闭环，让每个获准的产物自动触发下一道关卡。人的注意力集中在这些关卡上，评审 agent 标记的问题，而不必从头启动每个阶段。

图中按所属阶段列出了各个实践项，箭头则表示采纳顺序；两者并不相同。可以从任意一个陶土色实践项开始——没有箭头指向它，说明它不依赖其他实践项。对于其他实践项，所有指向它的箭头都表示需要先采纳哪些实践项。

规划

想法不必再等待某个人把它写出来。提出者只需用自己的语言记录一次意图，将其作为受版本控制、可供下一阶段直接采用的产物。

记录为 intent.md

用于启动软件开发流程的 intent.md 可以通过不同路径进入流程：某个人提出想法、有人提交工单，或者告警暴露出一起事故（参见阶段 6：维护）。

当某个人有了想法，可以和 Claude 一起进行头脑风暴，产出一份 Markdown 原型 spec。在传统 SDLC 中，这个人接下来还必须说服产品团队成员与自己一起整理想法，或代自己将其写成文档。

Claude 生成的原型 spec 便于人阅读，受版本控制，而且下一阶段可以立即使用。这份原型 spec 会保存为 intent.md。

无论意图来自事件触发器还是 agent，都要遵循相同步骤：产品负责人先评审并修正 agent 编写的 intent.md，然后再提交。

传统方式：一个想法要经过待办事项、用户故事、故事点和需求细化会议，才能真正有人着手处理。每次交接都会转移所有权，因此，当想法到达工程团队时，已经经过层层转述，与提出者的本意相隔了好几步。

AI 原生方式：提出者与 Claude 一起进行头脑风暴，再把结果写入 intent.md，形成一份使用提出者自己的表述撰写的原型 spec。该产物会记录想要什么、为什么需要，以及有哪些约束。重复性流程则编码为 skill。

如何开始

前置条件

无。

基础设施

需要为非工程人员提供 Claude 访问权限（claude.ai 或 Cowork）；约定统一的 intent.md 模板；提供一个由产品负责人关注、共享且受版本控制的意图存放位置。对于单一产品，最简单的做法是在产品 repo 中建立 intent/ 文件夹。这样，产物链就能和由它衍生出的代码放在一起。只有当意图横跨多个 repo 时，专用意图 repo 带来的额外开销才值得承担；在 monorepo 中，则只需使用一个目录。阶段 3“构建”的侧栏会说明这个存放位置如何与已经保存相关记录的 Jira 或需求工具配合。

平台团队或工程团队只需一次性完成这套配置。技术团队成员需要搭建意图存放位置，并决定谁拥有写入权限，因为许多贡献者会来自组织内的不同部门。

repo 建好后，没有 git 使用经验的贡献者也不需要直接操作 git。通过连接版本控制系统（如 GitHub）的连接器，他们可以在 claude.ai 或 Cowork 中让 Claude 代为提交 Markdown 文件。

如何执行

提出者用自己的话向 Claude 描述问题，可以说明现在有哪些事情做不到、这个想法会影响谁、理想状态是什么，或哪些内容不在范围内。无需使用正式语言。
持续进行头脑风暴，直到想法变得具体。Claude 会提出分析师通常会问的问题：范围、用户、约束，以及怎样才算成功。
让 Claude 使用组织的模板，把讨论结果写成 intent.md。这个模板可以编码为 skill，由技术团队成员配置，并经负责人批准。内容可以涵盖问题、预期成果、受影响的用户和系统、约束条件以及待解决的问题。
由提出者修正 Claude 误解的所有内容。
将 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?

治理方面的考虑

作为证据的是已提交的 intent.md，其中列有作者、时间戳和完整修订历史，并记录在意图存放位置的 git 历史中。产品负责人进行审批；决定意图是否进入阶段 2“设计”的接受或拒绝结果，会记录为 merge 或关闭的评审。

如何衡量

领先指标

从首次对话到提交 intent.md 所用的时间，可从意图存放位置的 git 历史中读取，其中记录了作者和时间戳。预期效果是把持续数周的需求发掘和细化周期缩短到数小时。

滞后指标

存活率，即产品负责人接受并送入阶段 2“设计”、而不是关闭的 intent.md 文件比例。接受或拒绝的决定会记录为产物的 merge 或评审关闭。此外，还要统计同一项变更中，对 intent.md 所做的修改里有多少发生在首次提交 spec.md 之后。

设计

需求和设计合并为一次会话。政策会在编写 spec 时直接落实，而不是等到几周后的评审才介入。

需求与设计

产品负责人批准后，Claude 会读取获准的 intent.md，生成需求与设计 spec。整个过程由组织针对品牌、安全、合规和 UX 制定的 skill 提供指导。

产品负责人负责评审这份 spec，但不亲自编写。这个流程的目标是创建一份工程团队可据以规划、并已标出需关注问题的 spec。

前端工作是最直观的例子。intent.md 获准后，产品负责人在 Claude Design（beta）中根据 intent.md 制作设计原型，反复调整，然后导出到 Claude Code 进行构建。

传统方式：需求和设计是两个独立阶段，分别由不同团队负责。分析师把想法正式整理成需求，设计师再将需求解读为设计。这种分工是为了明确责任，但过程缓慢，而且容易丢失信息。

AI 原生方式：两个阶段在同一次 prompt 会话中完成。Claude 读取 intent.md，在组织 skill 的约束下生成需求与设计 spec，并标出需关注的问题。

如何开始

前置条件

编写一份 intent.md 文件，并将品牌、安全、合规和 UX 政策写成 skill。

基础设施

一名可使用 Claude 的产品负责人。不要求具备工程技能。

如何执行

产品负责人开启一个会话，加载组织的 skill，并附上 intent.md。
产品负责人的 prompt 指向 intent.md，列出约束，并要求标出需关注的问题。最初先手动运行，之后再将其固化为组织级 slash command。接下来，把意图存放位置中接受 intent.md 设为触发器：由非交互式任务在 merge 时启动，加载组织的 skill 执行这一流程，并以 PR 的形式提交 spec.md（阶段 5“部署”中的 CI/CD 实践项会介绍如何串起这些环节）。从此以后，产品负责人第一次介入就是进行评审。
同一位产品负责人对照最初的想法评审 spec：它是否解决了所述问题？intent.md 中的待解决问题是否已经得到回答，或延续到 spec 中？
优先处理标出的需关注问题，因为分析师原本也会把这些问题上报。产品负责人要在工程团队看到 spec 之前，与相应的政策负责人逐一解决这些问题。
将 spec.md 与 intent.md 一同提交。这对文件记录了提出的要求和最终的决定。
产品负责人决定是否让 spec 和 intent 进入构建阶段；对于组织归类为较高风险的事项，则要咨询技术负责人。这个决定始终由人类团队成员作出，而接受 spec 会启动阶段 3“构建”中的 plan mode 实践项。

实际示例（prompt）

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.

治理方面的考虑

现行政策会在编写 spec 时直接读取并应用，而不是等到几周后的评审才介入。组织的 skill 会作为 spec 的约束条件。spec、生成它的 prompt，以及当时生效的 skill 版本，都会记录在版本控制中。产品负责人签字批准 spec，并将标出的需关注问题转交给对应的政策负责人。

如何衡量

领先指标

同一项变更提交 intent.md 与提交 spec.md 之间经过的时间（即两个 git 时间戳之差），并将其与过去“需求加设计”周期的耗时比较。

滞后指标

构建开始后的需求返工量。统计同一项变更的 spec.md commit 中，有多少日期晚于首个 plan.md commit；git log 可以直接给出这个数据。

构建

没有获批的计划，就不得开始实现任何内容。组织知识要转化为 agent 能读取的文件，护栏也要以代码运行，而不能只靠习惯维持。

默认从 Claude Code plan mode 开始

工程师以 plan mode 启动 Claude Code 会话，将阶段 2“设计”中批准的 spec.md 交给 Claude，再让 Claude 通过提问了解需求、反复完善计划，直到工程师满意为止。

传统方式：工程师读完设计就开始写代码。具体要怎么改，细到改哪些文件、做哪些测试，要么只留在工程师脑中，要么至多写在工单评论里。其他人无法提前评审。评审者第一次看到的已经是最终 diff，而此时返工会很慢。

AI 原生方式：先由 Claude 在 plan mode 下写出计划，再开始工作；在这种模式下，它可以读取代码库，但不能做任何修改。工程师在代码编写前修正计划，并将批准后的版本提交为 plan.md，供后续阶段对照检查。

如何开始

前置条件

如有意图产物（intent.md 或 spec.md），请准备好；有 CLAUDE.md 文件也会有所帮助。

基础设施

能够访问 repo 的 Claude Code。

如何执行

工程师与 Claude 一起以 plan mode 启动会话。
工程师向 Claude 提供 intent.md 和 spec.md，要求它制定一份实施计划，明确要修改的文件、工作顺序，以及用哪些测试来证明改动有效。
深入追问这份计划：改动可能破坏什么、哪一步风险最高，以及 Claude 放弃了哪些其他方案。
反复完善，直到一位从未看过这段对话的工程师仅凭计划就能实现这项改动。
将批准后的计划提交为 plan.md。这份计划会成为审计轨迹的一部分，而 PR 评审实践项（阶段 5：部署）会据此检查最终 diff。
接受计划，让 Claude 开始实现。计划足够扎实时，实现通常一遍就能完成。
如果实现偏离计划，应在同一个 commit 中更新 plan.md。可以考虑用 hook 强制两者保持同步。

实际示例（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.

治理方面的考虑

设计评审要在生成任何代码之前完成，此时要改变方向还只需修改一份文档。plan mode 本身就能落实这一点，因为在工程师接受计划前，Claude 无法编辑文件。计划及其修订记录会被保存，同时记录由谁批准。常规改动由工程师批准；凡是组织归为较高风险的改动，则交由技术负责人或架构师批准。

如何衡量

领先指标

一次实现就能合并的改动占比，以及从计划获批到 PR 合并所需的时间；相关数据应记录在 PR 元数据中。

滞后指标

每项改动的返工轮次，同样取自 PR 元数据；以及合并后的 diff 与已提交的 plan.md 仍然一致的频率。

Claude Code auto mode

Claude Code 也可以在 auto mode 下运行：工程师批准计划，并在反复完善至满意后，由 Claude 应用每一项改动，无须逐次提示工程师确认。随着后续实践项中的护栏逐渐成熟——经过调优的 CLAUDE.md、将政策编码其中的 skill、阻止不安全操作的 hook，以及 Claude 可以自行运行的测试套件——自动接受将成为常规工作的默认方式：spec.md 严密、影响范围小，而且已有测试覆盖相关代码。

工作方式将从用户盯着 agent 修改、逐项评审操作，转向在更长时间的自主会话结束后评审产物。自动接受模式配合 worktree，还能进一步提升个人与团队的并行能力；它也是让 SDLC 自主运行、并按阶段 6“维护”所述实现闭环的基础。

侧栏

遗留系统与事实来源

适用于流程产出的每一种产物。

现有 SDLC 流程很可能已经在追踪各种产物，只是它们并不存放在 Markdown 文件中。工作项可能放在 Jira，需求可能放在内置监管追溯能力的工具里，设计可能放在 Figma，变更审批则可能由变更委员会管理。这些系统很难被取代，因为审计人员和监管机构已经认可它们，其他团队也依赖它们，所以 AI 原生 SDLC 必须适配现状。

向 AI 原生 SDLC 迁移时，应针对流程产出的每一种产物，指定一个系统作为事实来源，其他地方只保存副本或原始记录的链接。下面几种配置都能确立一个事实来源，而且不同产物可以采用不同选择：

以 repo 为事实来源。 Markdown 产物是权威记录，遗留系统则引用 commit 中的文件。对于工程主导型组织，这可能是最简洁的配置之一，因为所有记录都存放在同一个工具中，并使用同一个权威时间戳来源。

以遗留系统为事实来源。 Jira、ServiceNow 或需求管理工具保存权威记录，Markdown 产物则是工作副本。Claude 在会话开始时读取记录，并在产出 spec 或 plan 的同一次会话中，通过 MCP 连接器将结果写回。

最低要求是建立关联。 所有产物都要注明记录 ID，所有遗留系统记录也要包含 Markdown 文件所在 commit 的 SHA。开始向 AI 原生 SDLC 迁移时，可以先建立这种关联，同时接受暂时存在两个事实来源。

遗留系统和 Markdown 优先的系统可以并存，只要两者之间建立了链接，或者明确指定其中一个为事实来源。

CLAUDE.md

CLAUDE.md 为 Claude 提供新成员入职时需要的 context，包括约定、命令、架构，以及团队最常遇到的错误。过去只存在于人们脑中和 wiki 上的知识，会变成 agent 每次会话开始时读取的文件；整个团队共同维护它，并在每次出错后持续完善。

如何开始

前置条件

无。

基础设施

一个 repo、已安装的 Claude Code，以及一位非常熟悉代码库的工程师。

如何执行

在 repo 中运行 /init。Claude 会根据发现的内容生成一份初始 CLAUDE.md。
精简生成的文件，只保留新成员入职第一天需要了解的内容：构建、测试和 lint 命令，重要约定，以及 Claude 反复出错的地方。
将 CLAUDE.md 提交到 repo 根目录并纳入 git，让整个团队共享同一个版本，所有改动也像代码一样接受评审。
可以定一条实用规则：Claude 同一个错误犯两次，就把纠正方法写进 CLAUDE.md。
将它控制在一页以内，因为 Claude 会在会话开始时读取全部内容；任何过时信息都只会白白占用 context。

实际示例（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/.

治理方面的考虑

CLAUDE.md 受版本控制，因此 agent 遵循的指令可供评审和审计。团队约定通过该文件统一应用，文件变更会记录在 git 历史中，并由代码所有者在 PR 评审时批准。

如何衡量

领先指标

Claude 重复犯下本应由 CLAUDE.md 避免的错误有多频繁。对 CLAUDE.md 的纠正或改动应在 git 历史中留有记录。

滞后指标

根据 PR 历史统计，新团队成员从加入到首个 PR 合并所需的时间。

将 skill 用作组织知识

skill 能让组织知识真正落实到工作中。指令会被明确写出、纳入版本控制、广泛应用，并在政策变化时集中更新。经验法则是：必须始终如一执行的组织知识，应写成 skill；本应放进 CLAUDE.md 或 prompt 的内容，则不要写成 skill。

如何开始

前置条件

无硬性要求。有 CLAUDE.md 会有所帮助，因为它能把 agent 工作所需的知识保存在 repo 中，但 skill 并不依赖它。

基础设施

一项有明确负责人、并具备书面事实来源的政策。

如何执行

选择一项目前没有得到一致执行的要求，可以是安全标准、API 设计约定，也可以是品牌规范。
将它写成 skill：建立一个文件夹，其中包含 SKILL.md；frontmatter 说明何时触发，正文说明具体该怎么做。由工程师依据政策负责人的事实来源编写，并可让 Claude 从旁协助。
将 skill 放进 repo 的 .claude/skills/<name>/，让它随代码一同交付；或者通过 plugin 在整个组织内分发。
测试 skill 能否触发。用不同方式要求 Claude 执行相关任务，并确认 skill 每次都会加载。
政策变化时，更新 skill，并由政策负责人批准改动。
工程师会在下一次会话中自动使用新版本。

实际示例（.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.

治理方面的考虑

skill 是一种控制措施，但只是建议性控制。它会让 Claude 更有可能在编写代码时落实政策，却没有任何机制能强制会话遵守。必须无条件满足的政策，需要在 skill 之后再加一层确定性措施，例如用 hook 阻止相关操作，或在 PR 阶段通过一次评审重新检查政策。skill 让违规变得少见，hook 则让违规几乎不可能发生。skill 的调用会记录在会话轨迹中，政策负责人也会像评审代码一样评审 skill 的变更。

如何衡量

领先指标

从政策负责人批准政策变更，到更新后的 skill 合并所需的时间；数据取自 skill 文件夹对应的 PR。

滞后指标

PR 评审中引用该政策的问题数量。在代码编写阶段由 skill 应用政策后，这一数量应逐渐趋近于零。如果没有趋近于零，要么是 skill 没有触发，要么是其文本已经偏离正式政策。

将 hook 用作构建阶段的护栏

skill 是建议性控制，而 hook 是它背后的确定性控制层。Claude 在实现过程中的大多数操作都是编辑文件和执行 shell 命令，因此构建阶段往往也是 hook 触发最频繁的阶段。

构建阶段的 hook 可以：

阻止编辑受保护的路径，例如生成的类或已冻结的软件包；
在文件编辑后运行格式化工具和 linter，避免格式偏差不断积累；
防止凭据进入 diff。

凡是政策必须无一例外得到执行的 skill，都应由 hook 提供保障。hook 会对每项匹配的操作运行，因此构建阶段的 hook 应该足够快，并且只针对发生变化的文件。完整测试套件等更重的检查，则应放到 commit 或 PR 阶段执行。

需要人工批准的 hook 应归入阶段 5“部署”的关卡，因为在构建期间弹出批准提示，会把人重新放回所有并行会话的关键路径上。

并行会话与 subagent

一位工程师可以同时推进多条工作流。

并行会话是另一个完整的 Claude Code 实例，在自己的 git worktree 中处理独立任务。每个独立会话都不知道其他会话的存在；它们唯一的共同点，是由同一位工程师引导。

subagent 在单个会话中运行，是一种负责特定范围工作的辅助 agent，拥有独立的 context window 和工具限制。它适合处理多项任务中都会重复出现的工作，例如验证应用是否按预期运行。

并行会话能增加工程师同时推进的任务数量，subagent 则让每个会话专注于自己的任务。工程师的职责是引导并评审所有这些工作。

传统方式：一位工程师一次只做一项任务，每天或每周都会花相当多的时间等待构建、测试和评审。等待时虽然可以切换到其他任务，但切换 context 很累，所以很少有人愿意这么做。

AI 原生方式：一位工程师同时运行多个 Claude 会话，每个会话都在自己的 worktree 中处理各自的任务。重复性工作会变成拥有独立 context 和工具限制的 subagent。工程师的职责转向编排，并最终转向构建和监控循环。

如何开始

前置条件

需要 CLAUDE.md，因为所有会话都会读取这个文件。反馈循环（阶段 4：测试）也会有所帮助，因为当会话能够自行验证工作时，工程师所需的监督就会减少。

基础设施

一个 git repo，因为隔离由 worktree 提供；还需要适当调整权限设置，让会话在执行组织认定为安全的命令时，无须等待批准提示。

如何执行

工程师将工作拆分为修改不同文件的任务，并借助 plan mode 实践项（阶段 3：构建）中制定的计划，判断哪些工作可以独立进行。会修改相同文件的任务则放在同一个会话中依次执行。
每个并行任务都有自己的 worktree，例如在一个终端中运行 claude --worktree feature-auth，在另一个终端中运行 claude --worktree fix-rate-limit。worktree 是位于独立分支上的单独检出副本，可以防止不同会话在文件上发生冲突。
可以先从两三个会话开始。实际上限取决于一个人能认真评审多少条工作流，因此只有在评审跟得上的前提下，才继续增加会话。
将重复性工作转化为 subagent，并在 .claude/agents/ 中用 Markdown 文件定义；每个 subagent 都要有名称、何时使用的说明，以及允许使用的工具。例如：在主 agent 完成后删除不必要复杂性的代码简化 agent；运行应用并检查行为的验证 agent；探索代码库并汇报结果、但不会让主 context 被大量信息淹没的研究 agent。将这些定义提交到 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.

治理方面的考虑

会话越多，产出也越多，因此控制措施必须来自 repo 中的配置。repo 内的 hook 和权限设置会应用于所有会话，而每个会话执行的操作都会被记录，并归属到启动该会话的工程师名下。

如何衡量

领先指标

在评审质量不下降的前提下，每位工程师同时运行的会话数——根据 OpenTelemetry 导出数据统计；以及每天用于引导会话而非等待的时间占比。

滞后指标

每位工程师每周合并的改动数，并结合 PR 历史所反映的返工率一起考察。

测试

每个会话都会在人工查看前检查自己的工作；用于引导 agent 的配置，也会像 agent 编写的代码一样接受回归测试。

为 Claude 建立反馈循环

无论是测试、构建还是截图差异对比，始终要给 Claude 一种验证自身工作的方法。会话会先检查自己的工作并修正错误，然后再交给工程师查看。

反馈循环不要与验证 subagent（阶段 3：构建）混为一谈。反馈循环贯穿整个任务：工作迭代多少次，它就运行多少次。验证 subagent 则是在会话认为工作已完成后，启动一个全新的 context window 来执行最终检查。这样，最终结论就不会受到生成代码时所持假设的影响。

传统方式：代码能否正常工作的信号来得很晚：几分钟后才有 CI 结果，几天后才有测试人员反馈，几周后才有生产环境反馈。当代码由 agent 生成时，信号来得太晚，就意味着必须由人检查它的全部输出，而这个人也就成了瓶颈。

AI 原生方式：在交给人查看之前，先让会话有办法检查自己的工作：运行测试、执行构建、截取屏幕截图。Claude 会不断迭代，直到检查通过，因此工程师最终收到的内容已经经过验证。建立这一循环是运行会话的工程师的责任，下面的步骤就是写给他们的。

如何开始

前置条件

无。

基础设施

一套测试和一套构建流程，二者在本地都能分别通过一条命令运行。对于 UI 工作，关键是让 Claude 能看到结果：可以使用浏览器工具，也可以通过 MCP 接入截图工具。

如何执行

如果如今检查工作需要依次运行多条命令，还需要了解一些环境细节，就把它封装成一个统一入口，例如“make test”或“npm test”，并确保失败时以非零状态码退出。
在 CLAUDE.md 的 Commands 部分列出每条命令，并附上正常输出示例。
明确一个可量化的目标，让 Claude 无需询问你就能自行检查工作。例如：“test_status.py 中的所有测试均通过”“截图与所附设计稿一致”，或“端点返回 200，且包含新字段”。
修复 bug 时，先编写一个会失败的测试。让 Claude 用测试复现 bug，运行测试，并确认测试失败的原因与你的预期一致。提交这个测试。然后再让 Claude 在不修改测试的前提下使其通过，并用最后一步中的测试文件 hook 强制执行这一限制。如果测试在修复前就已存在，而且 agent 无法改写它，那么测试通过就能证明 bug 已经消失。
对于 UI 工作，用视觉检查闭合反馈循环。给 Claude 提供浏览器或截图工具，再把设计稿交给它，让它自行迭代：实现、截图、对比、调整。通常需要两三轮，而且每一轮的结果都应该有所改善。
把验证纳入“完成”的定义。这项要求写在 CLAUDE.md 中：报告任务完成之前先运行测试，并展示输出。
最后，反馈循环本身也需要保护，因为修复代码的 agent 不能同时削弱对这些代码的检查。可以用 hook 阻止 agent 在修复任务期间编辑测试文件。另一种做法是在评审时检查 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.

治理方面的考虑

强制执行什么

一是任务报告完成前必须验证，二是 agent 在修复期间不得编辑测试文件；如果组织希望确保这两项要求得到执行，可以用 hook 来落实。

以什么作为证据

Claude 实际运行并粘贴的“make test”输出、构建日志或截图差异。这样，证据直接来自工具链。

记录在哪里

一份记录保存在会话 transcript 中，并由 OpenTelemetry 导出到组织的可观测性技术栈；另一份记录保存在 PR 的 check run 中，评审者和日后的审计人员都可以查看。

由谁审批

由评审 PR 的代码负责人审批。由于机械性的证据已经附上，他们可以把精力集中在意图和风险上。

如何衡量

领先指标

agent 编写的改动首次通过 CI 的比例；现有 CI 系统已经能够提供这一指标。

滞后指标

每个 PR 的评审时间（来自 PR 元数据）以及变更失败率（来自事故跟踪系统）。当测试开始捕获过去要靠评审者发现的问题后，PR 评审时间应该会下降。

在 CI 中持续运行 eval

eval 相当于 AI 原生 SDLC 中的阶段关卡式 QA。实践中，这意味着每当 agent 配置发生变化时，都要运行一套 eval。换用新模型或改写 prompt 后，eval 套件会判断 agent 是否仍能以同样的标准完成工作。

这套 eval 应被视为持续演进的套件。随着模型改进，过去能够拉开差距的用例会逐渐失去区分度，因此必须根据持续监控中出现的新情况补充用例。

有些团队可能会根据使用场景，选择按固定周期离线运行这些 eval，而不是每次变更都运行。下面的步骤针对持续 eval。

如何开始

前置条件

CLAUDE.md 和反馈循环（阶段 4：测试）。

基础设施

能够以非交互方式运行 Claude Code 的 CI，以及一枚预算足以支持 eval 运行的 API key。

如何执行

平台工程师从近期工作中收集 20 至 50 个真实任务，并为每个任务附上预期或已验收的结果。
把每个任务写成一项 eval，即 prompt 加上定义“可接受”的检查条件（测试通过、lint 无问题、行为未改变、遵守政策）。
eval 套件会在 CI 中以非交互方式定期运行，并在 CLAUDE.md、skill 或 hook 发生任何变化时运行。因为这些配置会引导 agent，理应像代码一样接受回归测试。
将 eval 结果设为配置变更的关卡。如果某项 skill 变更导致通过率下降，就必须在合并前接受评审。
每起生产事故都要转化为一项 eval，由负责处理该事故的团队编写，并作为回归测试永久保留在套件中。

实际示例（.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

治理方面的考虑

eval 为 QA 提供了一道能够跟上 agent 产出速度的关卡。通过率阈值会作为合并检查强制执行；每次运行都会留下记录，便于纵向比较结果；配置变更则由负责该配置的团队审批。

如何衡量

领先指标

eval 套件每次运行所报告的长期通过率变化，以及一起生产事故需要多长时间才能转化为永久 eval。

滞后指标

对比在 CI 中捕获的回归问题与进入生产环境后才发现的回归问题，数据来自事故跟踪系统。

部署

评审是双向的，agent 行动时也会受到治理约束。agent 可以完成生产环境关卡之前的一切工作，但绝不能越过这道关卡。

让 AI 进入 PR 评审循环

Claude 既会给出评审意见，也会接收评审意见。它依据组织政策评审传入的 PR，也会自行处理自己提交的 PR 上的评审评论。这样，工程师就能在 PR 评审中专注于行为层面，归根结底只需判断意图和风险。

传统方式：评审能力是围绕人类产出速度规划的。PR 要等待评审者通读全部内容；评审质量会随评审者的负荷波动；积压越来越多时，作者还得不断催促。

AI 原生方式：所有 PR 都会经过同一套评审流程，发现的问题按严重程度排序。人的注意力上移一层：判断改动是否实现了计划意图，以及风险是否可以接受。

如何开始

前置条件

阶段 3“构建”中更新过的 CLAUDE.md 文件；如果评审流程要执行书面政策，还需要相应的 skill；此外还要有定义好的 subagent。

基础设施

repo 中已安装 Claude 集成：可以由管理员启用托管的 Code Review 服务（仍处于 research preview 阶段），也可以在自己的 CI 中运行 claude-code-action；必要时，模型调用可通过 AWS Bedrock、Google Vertex 或 Microsoft Foundry 完成，以遵循组织自己的云服务协议（CI/CD 实践项会介绍部署选项）。此外，也值得配置分支保护政策，要求代码负责人批准。

如何执行

最快捷的起点是托管的 Code Review 服务。管理员启用服务并选择 repo。如果需要掌控流水线，或希望 API 调用经由组织自己的云服务协议路由，则在自己的 CI 中通过 claude-code-action 运行评审（CI/CD 实践项会介绍相关接线方式）。
技术负责人在 repo 根目录编写 REVIEW.md，把它划分为组织关心的几轮评审：bug 和逻辑错误；安全与漏洞；是否符合 spec（需求实践项中的 spec.md）、实施计划（plan mode 实践项中的 plan.md）及设计原则。REVIEW.md 还要界定什么问题算 Important、什么只算 Nit，以及哪些内容应跳过。
技术负责人设定需要人工介入的阈值。评审发现本身既不会批准 PR，也不会阻止 PR，分支保护仍然要求代码负责人批准。如果平台工程师希望根据评审发现来阻止合并，可以读取 check run 发布的严重程度计数；该计数采用机器可读格式。
评审者或作者在评审评论中提及 @claude 后，Claude 会处理评论并推送修复。PR 中的对话会同时记录请求和改动。这个修复循环通过 claude-code-action 运行。在托管服务中，评论 @claude review 则会请求重新评审。对于 Claude 创建的 PR，还可以更进一步，让 Claude 持续照看，直到 PR 合并。团队可以用自定义 slash command 封装这一循环：反复扫描 PR 中尚未解决的评审评论和失败的检查，逐一处理并推送修复，直到 PR 全部变绿，只等代码负责人批准。
评审发现会反馈到 CLAUDE.md。当评审第二次发现同一种错误时，就在本次评审中把纠正方法写入 CLAUDE.md。由于评审会读取 CLAUDE.md，从下一个 PR 开始就能捕获这类错误。评审还会指出某项改动是否已使 CLAUDE.md 过时。
技术负责人每月调整一次配置：对评审发现进行评级，以改进评审效果；同时在 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.

治理方面的考虑

职责分离得以保留，因为编写代码的 agent 无法批准代码。REVIEW.md 中的评审政策会应用于所有 PR；评审发现、修复、评级和审批都记录在 PR 历史中，因此 PR 本身就是审计记录。最终由人通过分支保护完成审批，并参考评审发现作出判断。

如需了解这些控制措施如何在生产规模下协同运作，请参阅 Anthropic 如何保护 AI 原生 SDLC。

如何衡量

领先指标

首次收到评审意见所需的时间——这一时间应该缩短到几分钟；以及无需人操作分支即可解决的评审评论占比。相关数据直接保存在 Git 中。

滞后指标

合并前捕获的缺陷和漏洞，与遗漏到生产环境的缺陷和漏洞之间的对比；数据来自 PR 历史和事故跟踪系统。

用 hook 设置审批关卡

构建阶段使用 hook 作为护栏，在无需人介入的情况下允许或阻止操作（阶段 3：构建）。hook 也可以请求批准，暂停操作，直到指定人员同意；发布关卡需要的正是这种能力。

这一实践项放在阶段 5“部署”中，因为发布关卡是最清晰的用例，但 hook 并非部署专属：只要 Claude 执行操作，hook 就可以运行。例如，在阶段 3“构建”中，如果没有变更工单，hook 可以阻止修改迁移和基础设施；在阶段 4“测试”的修复任务中，hook 也可以阻止 agent 编辑测试文件。

如何开始

前置条件

无。

基础设施

一份书面清单，列出变更流程要求的各项审批。

如何执行

工程管理层与变更管理、合规团队共同列出必须保留的人工审批关卡，例如变更管理签核、发布授权，以及对受保护路径的编辑。
平台工程师把每道关卡表示为一个 hook，也就是在 Claude 行动前运行、能够允许、询问或阻止操作的脚本。
团队 hook 放在纳入 git 管理的 .claude/settings.json 中；不可协商的 hook 则放在由平台或 IT 管理员控制的托管设置中，确保工程师个人无法关闭。
阻止操作时应说明原因。因此，当 hook 停止某项操作时，Claude 的输出中应显示原因以及申请批准的路径。

实际示例（.claude/settings.json）

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

关卡脚本本身（.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

治理方面的考虑

hook 就是审批关卡。每个人每次操作都会受到关卡条件的强制约束。允许和阻止的决定都会连同时间戳记录下来。关卡还会定义什么才算获得批准，例如变更工单已获批，或发布经理已经签核。

实际示例

受监管企业的托管设置

由平台团队通过 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 可阻止敏感信息进入 agent 的 context，并阻止工具任意访问外部网络；permissions.allow 则会预先批准安全的内部循环，避免拒绝列表带来没完没了的确认提示。

disableBypassPermissionsMode 与 allowManagedPermissionRulesOnly 配合使用，意味着任何工程师、项目文件或命令行参数都无法放宽这些规则。

sandbox 填补了权限机制无法覆盖的缺口。即使在工具层禁止 WebFetch，也无法阻止 shell 命令访问网络；操作系统层的域名允许列表则会直接阻断其他外连。

failIfUnavailable 和 allowUnsandboxedCommands 将 sandbox 变成一道关卡：sandbox 无法初始化时，Claude Code 会拒绝启动；某条命令在 sandbox 内失败后，也不能转到 sandbox 外重试。

credentials 填补了拒绝规则留下的缺口。permissions.deny 管控的是 Claude 的文件工具，但默认情况下，sandbox 中的 shell 命令仍可能读取 ~/.ssh 或 ~/.aws/credentials；这一配置区块会禁止这些读取，并从每条 sandbox 命令的环境中移除指定的敏感凭证。

allowManagedHooksOnly 意味着只有本实践项中的审批关卡 hook 可以运行；本地设置无法添加或替换这些 hook。

disableSideloadFlags 与 strictKnownMarketplaces 配合使用，意味着工程师机器上的每个 skill、agent、hook 和 MCP server 都来自组织批准的 plugin 市场，而不是从用户主目录加载。

allowManagedMcpServersOnly 把 agent 可用的工具范围限定为由平台团队维护的允许列表。

requiredMinimumVersion 会拒绝在低于获批最低版本的 Claude Code 上启动，确保这些控制措施由组织实际评估过的构建版本执行。

以上配置应作为按需调整的起点，而不是照抄的建议。每一条拒绝规则都会牺牲一部分能力，正确的平衡取决于 repo 的数据分级。设置参考文档列出了所有配置项，包括仅限托管设置使用的配置项：code.claude.com/docs/en/settings

如何衡量（针对 hook 本身）

领先指标

每道审批关卡的等待时间。每次 hook 决策都会连同时间戳及允许或阻止的结论写入 OpenTelemetry 导出数据，因此每道关卡的等待时长都清晰可见。

滞后指标

启用 hook 前后，进入生产环境的关卡违规事故数量；数据来自事故跟踪系统。

CI/CD 集成与部署

在 CI/CD 流水线中以非交互方式运行 Claude Code；将执行过程置于 sandbox 中，让长时间运行的 agent 也能安全工作；通过 MCP 集成开放部署能力；并在 agent 真正需要回滚之前，预先演练回滚路径。

传统方式：流水线运行确定性脚本，任何需要判断的工作都要等人处理，例如排查不稳定测试、编写变更日志，或弄清构建失败的原因。部署和回滚则依靠人在压力下照着操作手册执行。

AI 原生方式：Claude 在流水线内部以非交互方式执行需要判断的步骤，运行于 sandbox 中，并使用范围受限的凭证。部署工具通过 MCP 开放给 agent，因此，编写并测试改动的同一个工作流也可以发布和回滚这些改动，同时受到组织针对各环境所设关卡的约束。

如何开始

前置条件

让 Claude 进入 PR 评审循环，并将 hook 设为审批关卡。在自动化加速任何流程之前，这些关卡必须已经存在。

基础设施

安装了 claude-code-action 的 CI 平台，或任何能够调用 claude -p 的 runner；通过 API 访问模型，或者在流量必须遵循组织云服务协议时通过 Bedrock、Foundry 或 Vertex 访问；面向部署目标的 MCP server；用于 agent 作业的 sandbox 配置，其中不含长期有效的生产环境凭证。

如何执行

平台工程师先从只读的判断任务入手。在流水线作业中使用 claude -p，对失败的构建进行初步排查、总结不稳定测试，或起草变更日志。
对于修复 lint、更新生成的文档，或通过提及 @claude 处理评审评论等任务，在现有关卡之后增加写入步骤。agent 写入的所有内容都必须通过分支保护以 PR 形式进入，agent 没有任何直接推送到 main 的路径。
执行过程在 sandbox 中进行。agent 作业在受网络策略约束的容器中运行，使用短期、范围受限的 token，默认不持有生产环境凭证。
通过 MCP 开放部署能力。把部署、状态查询和回滚变成工具，并按环境限制权限。这样，agent 的部署能力就是一份允许列表，而不是一段携带凭证的 shell 脚本。
按环境划分自主程度。在开发环境中，agent 可以自由部署；在生产环境中，agent 负责准备发布，由发布经理授权，并由 hook 强制执行生产环境关卡；预发布环境则介于两者之间。
回滚应当是流水线中演练最充分的路径：它是一条 agent 可以运行的命令，并且要定期在预发布环境中执行。闭合循环实践项（阶段 6：维护）会在指标越过控制区间时调用这条回滚路径，因此必须提前验证它确实可用。

实际示例（流水线步骤）

- 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 可以行动到生产环境关卡为止，但不能越过它。下面这些控制措施会强制执行这一原则。

分支保护会把 agent 写入的任何内容转化为 PR，不允许直接进入 main。
生产环境部署 hook 会阻止发布，直到指定的发布经理授权。每次非交互运行都使用 agent 自己的身份，因此流水线日志可以区分哪些操作由 agent 完成，哪些操作由触发运行的工程师完成。
按环境划分的权限层级决定 agent 在到达关卡前可以做多少事情。

如何衡量

领先指标

无需呼叫人工介入即可完成初步排查的流水线失败占比；数据来自 CI/CD 流水线日志。

滞后指标

DevOps Research and Assessment（DORA）指标；现有 CI 系统和部署工具已经能够提供这些数据。

维护

循环在这里闭合。某个触发器会调用 Claude，调用链路中无需人工介入；Claude 的发现则会以 intent.md 的形式重新进入流水线。

维护与闭合循环

到目前为止，我们讨论了如何在 SDLC 流程的每个阶段引入 Claude，而每个阶段的初始步骤都需要由人启动。但在这个阶段，重点转向让 Claude 自主运行，从而闭合循环。

例如，一个持续运行的监控 agent 可以在 bug 工单创建后生成 intent.md，并依次流经需求、规划、构建、测试和评审阶段。阶段 6：维护以无人值守方式运行；各阶段之间设有独立的置信度关卡，由确定性检查或对抗式评审 agent 决定上一阶段的输出是继续流转，还是上报给人处理。

传统方式：维护是一个被动响应的阶段。所有工单或事故都要等人采取行动、重启流程。凌晨 3 点触发的告警可能被错过；工单可能一直躺在积压队列里，直到有人接手；如果新的紧急问题先出现，事后复盘的改进措施甚至可能永远进不了代码库。

AI 原生方式：一旦控制区间被突破、收到工单或频道消息，或到了预定时间，触发器就会调用 Claude，整个过程无需人工介入。Claude 先进行诊断，只通过设有关卡的路径采取行动，并将发现写成 intent.md，再进入上述各阶段。人负责分流和评审这些工作，不必再亲自启动流程。

闭合循环

确定性脚本会监控生产环境，并在指标突破控制区间时调用 Claude。监控控制区间被突破是循环自主运行模式的一个典型例子；本阶段末尾的 Claude Tag（public beta）一节则介绍了从不同渠道进入的工作。

如何开始

前置条件

能够为循环提供结构化输出、供其重新启动的 Intent.md；由 Claude 加速的 PR 评审；作为行动边界的 hook；以及 CI/CD 的回滚路径（最高自主层级会调用它）。

基础设施

一个可供检测脚本查询的指标存储系统（Prometheus、CI 系统的 API 或同类系统）；repo 的读取权限；在 CI 中以非交互方式运行 Claude Code 的方法，或者使用 Agent SDK 构建接收 webhook 的服务。

如何执行

服务负责人或平台工程师选择一项拥有稳定滚动基线的指标，例如 CI 测试失败率、部署后 5xx 错误率或 PR 周期时长。
编写检测脚本，通常是在滚动窗口内计算均值和标准差，并配合规则（Western Electric 规则或类似规则），让控制区间既能捕捉缓慢漂移，也能捕捉突增。脚本纳入版本控制并接受单元测试；检测过程始终完全确定，不引入任何模型。
在纳入版本控制的配置中定义响应层级（见下方 bands.yaml）。达到 1σ 时，脚本只记录日志；达到 2σ 时，以只读方式调用 Claude 进行诊断；达到 3σ 时，Claude 可以采取行动，但只能向评审关卡提交 PR，或触发预先批准的 runbook。
触发层可以是 GitHub 或 GitLab 中的定时工作流、现有监控技术栈发出的 webhook，也可以是网络内部的 Cron Job。Claude 以无状态方式运行：要么作为 CI runner 上的非交互步骤，要么作为 sandbox 容器中的 Agent SDK 服务；CI/CD 实践项介绍了部署和模型访问方案。由于运行过程既无状态也无需交互，整个循环可以在无人启动的情况下自行开始并结束。
agent 按照阶段 1：规划的格式将诊断结果写入 intent.md，其中包括异常及相关证据、预期成果、受影响的系统和所有待解决问题。此后，这项发现就和其他工作一样进入流水线。
服务负责人或值班工程师对队列进行分流，将面向产品的发现转交给产品负责人，并决定立即修复、排期处理还是忽略。忽略决定可用于调校控制区间，帮助减少噪声。
修复上线后，为该事故添加一项 eval（持续 eval 实践项），确保今后能够防范此类问题。

实际示例（用 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] }

治理方面的考虑

各层级的边界由纳入版本控制的配置强制执行，权限和托管设置会阻止生产环境访问。每次调用、每项发现和每个分流决定都会连同时间戳一起记录。服务负责人负责分流和批准发现；由此产生的改动会经过常规的 PR 评审关卡；agent 可以触发的 runbook 则都已预先获批。

如何衡量

领先指标

从控制区间被突破到分流队列中出现 intent.md 的时间，与以往从事故发生到形成事后复盘改进措施所需的时间进行比较。检测脚本的日志中会记录突破时间戳和事故层级。

滞后指标

最终转化为已合并修复的发现占比（对比分流队列与实际 PR 历史记录），以及同类事故的复发次数。随着修复不断向 eval 套件添加用例，复发次数应该下降。

示例

当 CI 测试失败率突破 3σ 控制区间时，agent 会隔离不稳定测试或提交回滚 PR，再由评审关卡作出决定。
当部署后 5xx 错误率突破 3σ 控制区间，且时间窗口内存在部署时，agent 会触发现有的回滚流水线。
当 PR 周期时长触发漂移规则时，agent 会为工程管理层撰写报告。这说明，这套 harness 不仅适用于生产环境指标，也适用于流程指标。

检测过程始终保持确定性。只有控制区间被突破后才会调用 Claude，而响应层级决定了 Claude 可以做什么。

定期扫描代码库

安全扫描反映的只是特定时间点、特定模型对代码库的判断，而这两方面都会过时：代码每周都在变化，新一代模型也会发现上一代模型遗漏的漏洞。AI 原生的做法是按计划定期运行扫描，不让人出现在调用链路中，并让扫描发现像其他代码库改动一样经过同一套关卡。

Claude Security 是托管式定期扫描服务。连接 GitHub repo 后，扫描会在 Anthropic 的基础设施上使用 Claude Mythos 5 运行；每项发现都会先经过验证，再附上置信度评级并生成报告。建议的补丁会在网页版 Claude Code 中接受评审和应用。组织无需直接访问模型本身，也能获得扫描发现。

传统方式：安全扫描是一项阶段性活动，通常在发布或审计前发起。报告进入跟踪系统，由人工逐项清理积压，直到下一次扫描。在两次扫描之间编写的代码，能否得到保护取决于 PR 评审发现了什么。

AI 原生方式：针对每个已连接的 repo，使用当前能力最强的模型按计划定期扫描；在任何人看到发现之前，先对其进行验证。每项发现都像控制区间被突破一样处理：能在一个 PR 内完成的修复进入评审关卡，范围更大的问题则转为 intent.md。覆盖情况以最近一次运行日期为准，而不是首次运行日期。

如何开始

前置条件

PR 评审关卡和作为审批关卡的 hook（阶段 5：部署），确保扫描发现像其他改动一样经过评审；以及阶段 1：规划中的 intent.md 格式，用于记录无法通过单个 PR 解决的发现。

基础设施

Claude Security 目前以 public beta 形式面向 Claude Enterprise 组织提供。使用它需要：在目标 repo（云托管的 github.com）中安装 Anthropic GitHub App；启用网页版 Claude Code；开启 Extra Usage 并设置支出上限；为运行扫描的人员分配 premium seat；由管理员在 claude.ai/admin-settings/claude-code 中启用该功能。扫描按 Claude Mythos 5 的费率根据用量计费，因此支出上限应与 repo 的规模和数量相匹配。

如何执行

安全负责人连接 repo，并按 repo、服务或团队将其组织成项目，从一开始就明确每项发现的归属。
首先对最关键的 repo 运行一次完整扫描，包括此前已由其他工具或较早模型扫描过的 repo。将首次扫描作为基线。这次扫描很可能会在原本被认为没有问题的代码中发现漏洞。
为每个项目设置扫描计划。对于持续开发的服务，每周一次是合理的默认频率；如果 repo 规模庞大或包含多种内容，则将扫描范围限定在某个目录或分支。
结合置信度评级对发现进行分流。忽略某项发现时要说明原因，确保系统记录这一决定，且同一发现不会在下次运行时再次被当作新问题返回。
对于范围明确的发现，在网页版 Claude Code 中打开建议的补丁，评审后像其他改动一样将其送入 PR 评审关卡。提出修复方案的 agent 无权批准自己的改动。
对于范围超过单个补丁的问题，例如架构弱点或在多个服务中反复出现的模式，按照阶段 1 的格式将其写成 intent.md，并从规划阶段开始处理。
修复发布到生产环境后，针对该类漏洞向持续 eval 实践项的套件中添加一项 eval。此后，引导 agent 的配置就会持续接受该类问题的测试。
将发现导出为 CSV 或 Markdown，或者使用 webhook，让组织现有的跟踪和审计系统继续充当审计人员所认可的事实来源。

治理方面的考虑

扫描在组织的管理控制下运行，这意味着连接哪些 repo、谁拥有扫描席位以及支出上限是多少，都由组织集中设置。每项发现都有验证结果和置信度评级，每次忽略都有理由，因此扫描历史可以作为审计记录，说明哪些问题已被发现、哪些已经修复、哪些经审慎判断后被接受。

修复通过 PR 评审关卡和分支保护进入生产环境，而不是由扫描本身直接推送。Claude Security 是对现有静态分析和依赖扫描的补充。确定性检查继续留在 CI 中，而模型驱动的扫描则覆盖那些依赖 context、并非这些检查所擅长发现的漏洞。

如何衡量

领先指标

已连接且设置了扫描计划的 repo 占比，以及从发现生成报告到其补丁进入 PR 评审关卡所需的时间；相关数据可从扫描历史和 PR 元数据中读取。

滞后指标

定期扫描发现的漏洞，与生产环境中发现或外部报告的漏洞进行对比，数据来自事故跟踪系统；此外还包括已经历多轮扫描的 repo 中，每次扫描所发现问题数量的变化趋势。随着修复和 eval 不断积累，这一数字应该下降。

通过 Claude Tag 让 Claude 参与值班

事故也可能通过其他渠道出现，例如 Slack 或 Teams 等办公沟通应用。晚上 10 点，事故频道中可能突然出现一条请求紧急修复的 Slack 消息；如今，这类事故可以立即得到处理。Claude Tag（public beta，目前可在 Slack 中使用）让 Claude 以自己的身份成为这些频道的一员，因此，每起新事故都会立即得到初步响应，而响应过程本身也会进入循环，成为未来处理事故时可用的记忆。

对话和组织知识会留在频道中，频道里的任何人都可以引导响应并推动实际处理。任何团队成员都可以实时验证假设、探索新方案并展开调查；频道历史则让整个过程更便于审计。Claude 通过 MCP 确认指标已经恢复基线，并在对话中给出确认；随后将事后复盘写入纳入版本控制的经验文件，供未来调查读取。

Claude Tag 接手的不只有事故。无论是在通过 MCP 连接的工单中被提及，还是在频道里收到请求，Claude 都会用同样的方式对工作进行分流。范围小且边界清晰的修复会以 PR 形式进入评审关卡；范围更大的问题则会写成 intent.md，交给阶段 1：规划处理。此时，循环就开始自行运转。另见：Claude Tag 如何在 Anthropic 承担 CI/CD 值班工作。

频道就是审计轨迹：请求、诊断、人工授权和修复都会留在处理事故的频道里。

结语

模型和 harness 日益先进，使组织不仅能够改变代码生产方式，还能改造整个软件开发生命周期。

这种转型始终把人的判断置于流程核心，同时兼顾大型企业组织的治理和监管要求。

本指南汇集了我们 Applied AI 团队在日常客户工作中实践的诸多最佳方法，希望它能成为一份实用、可落地的参考资料。

循环会持续运行，而人的判断始终在其上把关。

资源与致谢

以下文档大致按照平台团队部署这些控制措施的顺序排列，涵盖了完成配置所需的内容。

为组织设置 Claude Code——管理员决策指南；从这里开始设置参考与优先级，包括所有仅限托管设置使用的配置项通过 Claude 管理控制台配置服务器托管设置权限 Sandbox——操作系统级文件系统和网络隔离 Hook 指南 Hook 参考 Skill plugin 和私有市场——如何在组织范围内分发 skill 与 hook 托管 MCP——集中控制 agent 的工具范围企业部署概览——Bedrock、Vertex、Foundry 企业网络配置监控（OpenTelemetry）数据分析面板 Compliance API——企业活动数据流、聊天记录检索与删除安全模型

感谢 Jim Blackhurst、Will Steuk 和 Jamal Arif 对本指南的贡献；本指南的灵感来自他们此前的大量工作，也是在这些工作的基础上完成的。