# AI-Native（AI 原生）SDLC 实践指南 Translated by not specified · Original article: [The AI-native SDLC playbook](https://claude.com/resources/articles/the-ai-native-sdlc-playbook) by Louis Claxton · Published: 2026-08-21 Translation published: 2026-09-04 / 66 min read Updated: 2026-09-15 这篇 Anthropic 实践指南译文面向软件研发团队，介绍如何在规划、设计、构建、测试、部署和维护六个阶段使用 AI。核心做法是把意图、工程标准、测试证据与人工审批纳入可追踪的交付流程，而不只加快编码。文中的案例和建议基于原作实践，具体工具与治理方式仍须结合团队环境验证。 [View more blogs with the tag #AI](https://guog.github.io/tags/AI/), [View more blogs with the tag #软件工程](https://guog.github.io/tags/%E8%BD%AF%E4%BB%B6%E5%B7%A5%E7%A8%8B/), [View more blogs with the tag #Claude](https://guog.github.io/tags/Claude/) > 英语原文: [Anthropic《 The AI-Native SDLC playbook》](https://claude.com/blog/the-ai-native-sdlc-playbook) 2026-08-21 > > 原文中存在不少专有技术名词，且目前缺少确切的中文翻译，仍建议有条件直接读原文。 如何分阶段改造软件开发生命周期，让 AI 真正进入日常开发流程。 ## 代码已不是瓶颈 如今，各个团队已经开始使用 AI 来编写代码，速度比一年前快了很多。不过，围绕代码相关的工作流程并没有加快。 很多团队仍沿用过去的审批、评审、交接和管理政策。这些流程跟不上 Claude Code 等工具带来的开发速度。 软件开发生命周期（SDLC, software development lifecycle）是从想法到产品发布的整个过程。 大多数团队仍按以下六个阶段协作，各阶段由不同角色负责： 1. 计划(Planning): 产品经理编写需求文档 2. 设计(Design): 技术架构师将需求转化为设计方案 3. 构建(Building): 工程师负责实现这些设计 4. 测试(Testing): 质量保证团队在受监管的企业中对其进行验证 5. 部署(Deploying): 发布团队负责产品的发布工作 6. 维护(Maintaining): 而运营人员则负责监控系统的运行状况 各个阶段之间的协作是通过文档、任务单和审批流程来进行的。 传统 SDLC 流程繁重，目的是在每一步保留责任和控制。 **传统的 SDLC 设计初衷，是为了在编写代码这一最耗时、最昂贵的阶段，实现效率最大化**，而如今情况已不再如此。 产品需求文档（PRD）、估算仪式(estimation rituals)和产品安全审查等流程，都是为了在可能持续数周、数月甚至数季度的开发工作期间，强制使各个参与角色达成一致。 传统 SDLC 的控制环节假定每一步都由人工执行。现在，领先团队正围绕自主 AI 能完成的工作重构流程，同时把监督和决策留给人。本指南汇集应用 AI 团队在 SDLC 各阶段使用 Claude 的实践，以及与客户合作中得到的经验。 当代码不再成为瓶颈，且构建阶段的运行速度超过传统 SDLC 所能达到的水平时，就会出现以下三种情况： - 瓶颈转移到构建前后的计划、评审、测试和部署，这些环节仍按人的节奏运转。 - 原有控制方式不再适用。代码由人逐行编写时，逐行检查尚可行；当大部分代码由 AI 生成时，这种做法很难持续。 - 治理成本上升，因为决策仍要经过按周或按月召开的会议与委员会。  > **构建已不再是瓶颈——围绕它的那些“人类速度”步骤才是。** 人类速度阶段的耗时保持不变，而构建（时间）却缩减至数小时。 以安全瓶颈为例。 安全团队的规模通常是依据人工产出量来配置的，因此当多个 Agent 产出成倍代码时，要么审查队列越积越长，要么代码在审查不足的情况下就被推送上线。受监管的团队无法接受这两种结果中的任何一种，因此其安全与策略检查必须跟上 Agent 的速度。 要用好 Agentic AI 的生产力，同时保持安全可控，SDLC 其他环节也必须与构建阶段同步改造。 ## 什么是 AI-Native(AI 原生) SDLC AI-Native SDLC 在保留控制目标的同时改变执行方式。流程从线性接力变为循环，AI 进入每个环节，并自动交接、触发后续工作。它也常被称为“Agentic SDLC”“AI SDLC”或“Agentic 软件开发”。  ### AI-Native(AI 原生) SDLC 六阶段的变化 下表对比传统 SDLC 与 AI 原生 SDLC。多数团队会处在两者之间。 | 阶段 | 传统 | AI-Native | | ------------ | ------------------------------------- | -------------------------------------------------------------------------- | | 计划(Plan) | 由委员会收集的需求信息，经过研讨会和审批流程后整理归纳，然后手工撰写成文。 | Claude 直接从各种来源收集了相关的问题点，并将这些信息整理在 `intent.md` 中。这个**格式既易于人类阅读，也能被机器有效处理。** | | 设计(Design) | 由分析师编写规范，由设计师进行解析 | 在一次与 Agent 的会话中，即可完成所有需求与设计的制定工作。所有操作都遵循既定的标准，这些标准被编码为技能，并通过 Git 进行版本管理。 | | 构建(Build) | 测试和代码都是手工编写的，而文档则是在主要开发完成后才撰写的。 | 测试和代码是由 AI 生成的，团队知识以版本化的、机器可读的 `CLAUDE.md` 文件或 SKILL 的形式维护。 | | 测试(Test) | 在各阶段衔接处进行质量关卡。 | 实现过程中持续评估。 | | 部署(Deploy) | 人类会逐一审查每一行代码，通常**假装**会定期进行。 | 多层 Agentic Review，关键代码保留人工审核。治理在 AI 行动时即被强制执行，以钩子（hooks）作为审批关卡。 | | 维护(Maintain) | 人类监控生产环境中的 Bug | Agent 实时监控线上运行状况。一旦发现任何异常情况，就会将其记录到循环中，作为新的 `intent.md` 数据进行处理。 | 右侧列的主线是“提交的工件(artifact)”。 每个阶段结束时，都会向版本控制写入工件：`intent.md`、`spec.md`、`plan.md`、代码差异及测试、带评审意见的 PR、事件记录等。 下一个阶段从读取这些工件(artifact)开始。 前期阶段，主要的工件(artifact)是 `.md` 文件，因为 PM(产品经理)和 AI 都能阅读并操作同一份文件。 从构建(Build)阶段起，工件(artifact)就是代码及相关记录。 提交(Commit)记录本身也是审计追踪信息：谁提出了什么需求，AI 产生了什么结果，谁批准了。 凡涉及决策，仍由人类负责。在 AI SDLC 中，人类的注意力转移到需要审查的工件(artifact)上，而不是从头介入每一步。 > 每个阶段都提交一个可供下一阶段读取的工件(artifact)。意图、规范、计划、代码差异和审查发现共同构成了审计信息。 ## 实践 “场景”是本文的核心，按六个非线性的阶段：计划(Plan)、设计(Design)、构建(Build)、测试(Test)、部署(Deploy)、运维(Maintain)，覆盖完整软件开发生命周期。 每个实践模块包含： - 变化; - 起步; - 执行; - 治理; - 度量。 所有步骤都是模块化的，不同团队可以根据自身需求，按不同优先级开展不同阶段的改造。每个模块在“前置条件”中列出依赖项，依赖关系图也给出了直观说明。 每个阶段结束时提交一个工件，并进入下一阶段。被接受的 `intent.md` 触发需求和设计环节，获批的 `spec.md` 进入计划模式，合并的 PR 触发流水线，而生产环境触发条件又生成新的 `intent.md`，如此继续循环。 刚开始，人类工程师手动输入提示词驱动每个阶段；而最终，流程变为自动循环，每个阶段产生的工件(artifact)被接受后，自动触发下一个阶段。 人只在关键决策点介入，优先审查 AI 标记的内容，而非从头参与每个步骤。  > 不必按阶段顺序推进。先做没有依赖的模块，再处理依赖较少的，最后解决复杂依赖。 ## 01 规划 Plan > 创意不需要再等着人编写。意图一次性捕获，以发起者自己的方式表述，作为一个版本化的工件，供下一阶段操作。 ### 将意图转为 `intent.md` 文件 - 传统方式下，创意要经过层层转述和会议才能形成文档，耗时且信息失真。 - AI-Native 方式下，发起者直接与 Claude 交互，产出受版本控制的 `intent.md`。后续的设计、构建环节可直接读取和使用它。 #### 变化 启动开发的 `intent.md` 可能有多种来源：人的想法、工单、或者告警暴露的事故(参见: 阶段 06 运维)。 当某个人有了创意，他会和 Claude 一起头脑风暴，生成一份 Markdown 格式的初稿规格。传统 SDLC 下，这个人还得说服产品团队某位成员和他一起，或者替他写成正式需求。 Claude 生成的初稿可读、可版本控制，也可直接交给下一阶段。它保存为 `intent.md`。 无论意图来自事件触发还是 AI 自身，流程都一样：产品负责人在提交之前审查并修正 AI 写的 `intent.md`。 | 传统 | AI-Native | | --------------------------- | --------------------------------- | | 创意经过待办事项、用户故事、故事点、细化会议层层传递； | 发起者直接与 Claude 头脑风暴，产出 `intent.md` | | 信息在交接中丢失 | 一次性捕获意图（What、Why、Rules） | | 重复流程靠人工记忆或文档 | 重复性流程使用 SKILL | #### 起步 **先决条件(Prerequisites)** 无。 **基础设施(Infrastructure)** 为非工程师用户提供的 Claude 访问方式（[claude.ai](https://claude.ai/) 或 [Cowork](https://claude.com/product/cowork)）； 一个统一的 `intent.md` 模板； 一个共享的、可版本控制的意图存储库，由产品负责人进行管理。对于单个产品来说，最简单的存储位置是在产品仓库中的 `intent/` 文件夹。这种设置使得工件链能够紧跟其衍生出的代码。只有当意图涉及到多个仓库时，才需要创建一个专用的意图存储库；而在单体仓库中，只需使用一个目录即可。第三阶段：构建(Build)侧边栏部分介绍了这个存储库如何与已经包含相关记录的 Jira 或需求管理工具进行关联。 平台或工程团队只需搭建一次“意图仓库”，并明确写入权限，因为贡献者可能来自团队各处。 仓库建好之后，不熟悉 git 的贡献者无需直接操作 git。通过 GitHub、GitLab 等，Claude 可以直接在 [claude.ai](https://claude.ai/) 或 Cowork 中代他们提交 Markdown 文件。 #### 执行 1. 提出者用自己的话向 Claude 描述问题：现在做不了什么、影响谁、理想状态是什么、哪些不在考虑范围。无需正式格式。 2. 继续讨论，直到想法足够具体。Claude 会追问范围、用户、约束和成功标准。 3. 让 Claude 按团队的模板生成 `intent.md`。这个模板可以封装为“技能”，由技术人员设定，负责人审批。内容涵盖问题、预期结果、影响范围、约束、待定问题。 4. 提出者纠正 Claude 理解有误的地方。 5. 将 `intent.md` 提交到共享仓库。作者和时间戳自动记录，产品负责人从这里接手。 #### `intent.md` 示例 ```md # Intent：理赔状态自助服务 作者：J. Ortiz（理赔运营） 状态：草稿 ## 问题 客户致电联络中心询问他们的理赔进展。 客服人员大约三分之一的通话时间用于处理仅查询状态的请求。 ## 提议的结果 客户在门户中可以看到理赔状态、下一步和预计日期。 ## 受影响的用户和系统 理赔客服人员、门户团队、理赔核心API。 ## 约束 门户会话中不新增PII（个人身份信息）。仅限现有身份验证。 ## 未解决的问题 第三方损失理算员是否也需要访问权限？ ``` #### 治理 证据就是提交的 `intent.md`，包含作者、时间戳和完整修订历史，记录在意图仓库的 git 历史中。产品负责人审批，接受或拒绝的决定（即进入阶段 2：设计）以合并或关闭评审的形式留存。 #### 度量 **前置指标(Leading indicator)** 从想法产生到形成可执行的 `intent.md` 文件所需的时间。 从首次会话到提交 `intent.md` 的时间，可从意图仓库的 Git 历史读取作者和时间戳。目标是把原本数周的启发和细化周期压缩到数小时。 **后置指标(Lagging indicator)** - **存活率**：产品负责人接受而非关闭 `intent.md` 的比例，反映需求质量的稳定性。接受或拒绝会记录为工件的合并或关闭评审。 - **二次修改次数**：同一变更首次提交 `spec.md` 后，对 `intent.md` 的修改次数。次数越多，说明原始需求越不清晰。 ## 02 设计 Design > 需求与设计整合为一次会议完成。策略在规格(spec)编写时即被应用，而不是在数周后的审查中才发现。 ### 需求和设计 #### 变化 产品负责人批准后，Claude 基于 `intent.md` 生成需求与设计规格。规格受团队的[SKILL](https://agentskills.io/)约束，包括：品牌、安全、合规、用户体验等。 产品负责人审查规格，但不亲自写。目标是为工程团队产出一份可据此做计划的规格，并标出需要关注的区域。 前端工作最典型：`intent.md` 获批后，产品负责人在 [Claude Design](https://claude.com/product/design) 里根据内容生成设计稿，反复迭代，然后导出到 Claude Code 进行开发。 | 传统 | AI-Native | | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | 需求和设计是独立的阶段，由不同的团队执行。分析师将想法形式化为需求，然后设计师将其解析为设计。这种分离是为了问责，但既缓慢又有信息损耗。 **slow（缓慢）**：两个团队先后接力，中间需要多次沟通和转译。 **lossy（有信息损耗）**：每次交接都可能导致原始意图的丢失或变形。 | 这两个阶段在同一次提示会话中一气呵成。Claude 接收 `intent.md`，在团队已有 SKILL 的限制下产出需求与设计规格，同时把需要特别留意的区域标出来。 | #### 起步 **先决条件(Prerequisites)** 编写一个 `intent.md` 文件，并将品牌、安全、合规和用户体验策略编写为 SKILL。 **基础设施(Infrastructure)** 一名拥有 Claude 访问权限的产品负责人。不需要开发人员技术。 #### 执行 1. 产品负责人启动会话，加载组织 SKILL，附上 `intent.md`。 2. 产品负责人的提示词指向 `intent.md`，明确约束，并要求标记关注点。 先手动操作，然后将其固化为组织级别的“/“命令。 之后，让意图仓库中 `intent.md` 的合成为触发器，自动运行一个非交互任务（加载组织 SKILL），生成 `spec.md` 并作为 PR 提交（部署阶段的 CI/CD 模块会处理底层配置）。 此后，产品负责人首次介入就是审查 PR。 3. 产品负责人对照原始意图审查规格：是否解决了问题？`intent.md` 中的待定问题是否已解答或继续跟进？ 4. 优先处理标记的关注点，这些本应是分析师会升级的问题。产品负责人和相关政策负责人先解决它们，再让工程师看到规格。 5. 将 `spec.md` 与 `intent.md` 一同提交。这两个文件记录了需求和决策。 6. 产品负责人决定是否进入构建，高风险事项会咨询技术负责人。这个决定必须由人来做出，规格获批即触发阶段 3 的计划模式。 #### 提示词示例 ```md 阅读所附的 intent.md，并生成一份将其集成到我们现有代码库中的需求与设计规范。 应用你可用的技能，使计划符合我们的品牌指南、安全策略和用户体验标准。 将规范完整记录为 spec.md，准备交给工程团队。 清楚地描述任何需要关注的领域，尤其是在你无法满足相互冲突的策略时。 ``` #### 治理 - **策略前置**：合规要求不是在事后审查时才发现问题，而是在规范生成的同时自动应用。 - **可审计**：规范、提示词、技能版本全部记录在版本控制中，形成完整的审计线索。 - **责任明确**：产品负责人最终签批，并将需要关注的问题直接分发给对应的策略负责人，确保决策闭环。 #### 度量 **前置指标(Leading indicator)** 从 `intent.md` 次提交到 `spec.md` 次提交之间所经过的时间，用于衡量同一变更所需的周期（两个 Git 时间戳）。 将其与旧的“需求加设计”周期比较即可。 **后置指标(Lagging indicator)** 同一变更的 `intent.md` 提交与 `spec.md` 提交之间的耗时（两个 git 时间戳），与旧的需求加设计周期进行比较。 它衡量从记录想法到形成设计规范所需的时间，并与传统“需求加设计”两阶段的总耗时对比。Git 日志可直接提供这项数据。 ## 03 构建 Build > - **先有计划**：代码实施基于已批准的 `plan.md`。 > - **知识可执行**：团队经验、架构决策和常见错误沉淀为 `CLAUDE.md` 与 Skills，供代理编码时读取。 > - **护栏写进代码**：用 Hooks、自动格式化和 lint 替代只靠习惯与人工检查的做法。 ### 把 Claude Code 的计划模式(plan)作为默认开端 #### 变化 > 以 Claude Code 的计划模式(Plan)作为默认起点，OpenCode、Codex 等编码 Agent 中也有 plan 模式 开发工程师以 Plan 模式启动 Claude Code，把阶段 2 获批的 `spec.md` 交给 Claude，让它像访谈一样提问，反复调整计划，直到开发工程师满意。 | 传统 | AI-Native | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | 工程师阅读设计并开始编写代码。 变更将如何实施——涉及哪些文件和哪些测试——只存在于工程师的脑海中，最多也就是工单中的一条评论。 没有其他人可以审查它。 审查者看到的第一件事就是完成的代码差异，到那时返工已经变得很慢。 | 工作从一份书面的计划开始，由 Claude 在计划模式(Plan)下生成，在此模式下它可以读取代码库而不做任何更改。 工程师在代码编写之前纠正计划，批准后的版本被提交为 `plan.md`，供后续阶段对照检查。 | | **缺乏透明度**：变更计划只存在于工程师脑中，团队无法提前评审。 | Claude 在计划模式(Plan)生成书面计划，可审查可修正 | | **反馈滞后**：评审发生在代码写完之后，发现问题时返工成本高。 | 计划在编码前提交为 `plan.md`，供后续阶段对照 | | 返工慢 | 先产出书面计划（`plan.md`），在编码前就能被审查和修正。 | #### 起步 **先决条件(Prerequisites)** 意图工件（`intent.md` 或 `spec.md`，如果存在的话），以及 `CLAUDE.md` 文件会有所帮助。 **基础设施(Infrastructure)** Claude Code 可以访问代码库。 #### 执行 1. 工程师启动一个 Claude Code 会话，使用计划模式(Plan)； 2. 把 `intent.md` 和 `spec.md` 给 Claude，要求它输出实施计划：涉及哪些文件、工作顺序、如何测试验证； 3. 质疑计划：这次改动可能破坏什么？哪一步风险最高？Claude 放弃了哪些替代方案？ 4. 迭代计划，直到未参与该对话的工程师也能仅凭计划完成开发。 5. 将获批的计划提交为 `plan.md`，它成为审计线索的一部分。PR 评审环节（阶段 5）会核对最终代码是否与计划一致。 6. 批准计划后，让 Claude 执行。计划足够清楚时，通常一次即可完成。 7. 若实施偏离计划，在同一个提交中更新 `plan.md`。可以用钩子(Hook)强制两者同步。 #### `plan.md` 示例 ```md # 计划：理赔状态自助服务（来自 intent.md 2026-06-02） ## 变更的文件 portal/src/claims/StatusPanel.tsx（新增）, claims-api/routes/status.py, claims-api/tests/test_status.py ## 工作顺序 1. 在现有身份验证之后添加状态端点。 2. 针对该端点构建面板。 3. 接入门户导航。 ## 风险 理赔核心 API 的速率限制为 50 rps；面板必须使用缓存。 ## 验证 test_status.py 覆盖四种理赔状态；截图与已批准的设计模型一致。 ``` #### 治理 设计评审发生在生成代码之前，此时调整方向只需改文档。计划模式会限制 Claude 编辑文件，直到工程师批准计划。 计划和修订版本连同批准人一起记录。 常规变更由工程师批准，高风险项会交由技术负责人或架构师。 #### 度量 **前置指标(Leading indicator)** - **首次通过率**：有多少变更在第一次实施后就被合并，无需返工。 - **交付周期**：从计划批准到最终合并拉取请求（PR）的时间，要求 PR 元数据中记录所需信息（如关联的计划文件、测试结果等）。 **后置指标(Lagging indicator)** - **返工周期数**：统计每次变更需要经历多少轮修改才能合并，反映计划和实施的准确度。 - **计划匹配度**：最终合并的代码与最初批准的 `plan.md` 是否一致，衡量实施过程是否偏离计划。 这些数据均可从 PR 元数据中提取，实现量化追踪。 ### Claude Code 的自动模式 > 护栏机制（`CLAUDE.md`、技能、钩子、测试套件）成熟后，常规工作无需工程师逐步确认，Claude 可自主完成实施。工程师则从盯着操作转为审查较长自主会话产出的工件；配合 [Git worktree](https://git-scm.com/docs/git-worktree/zh_HANS-CN) 可并行工作，并为阶段 6 的自动闭环打下基础。 Claude 代码也可以在自动模式下运行。在这种情况下，工程师会批准计划，一旦满意并进行了修改，Claude 就会自动应用这些更改，而无需额外的编辑提示。随着后续版本中的安全机制不断完善（比如改进的 `CLAUDE.md` 、编码策略的技能、阻止不安全行为的钩子，以及一套完整的测试套件），自动接受成为常规工作的默认方式：简洁的 `spec.md` 、较小的爆炸半径，以及已经涵盖在测试中的代码。 现在的趋势是：**人类从观察 Agent 进行编辑和审核操作，发展为长时间自主会话之后对成果进行审核**。当与工作树(worktree)一起使用时，自动接受模式还能实现不同成员之间的并行工作，这对于实现自主化的 SDLC 流程以及实现第 6 阶段所描述的闭环操作至关重要。 > **遗留系统与事实来源**，适用于流程产生的每一个工件。 > > 现有 SDLC 往往已在追踪工件，只是不是 Markdown：工作项在 Jira，需求在受监管工具，设计稿在 Figma，变更由委员会审批。这些系统已被审计、合规和其他团队依赖，AI 原生 SDLC 应与它们共处，而不是一并替换。 > > 迁移时，每份工件都应明确一个**权威来源（事实来源）**；其他系统只保留副本或原始文件链接。不同工件可采用不同策略： > > - **以代码仓库为事实来源**：在这种模式下，Markdown 工件是权威记录，遗留系统则通过引用提交中的文件来关联这些记录。对于以工程为核心的组织而言，这是最简洁的方案之一，因为所有记录统一存放在同一个工具中，时间戳的权威性也自然得到保证。 > - **以遗留系统为事实来源**：Jira、ServiceNow 或需求管理工具持有权威记录，Markdown 工件仅作为工作副本。Claude 在会话启动时读取遗留系统中的记录，并在生成规范（spec）或计划（plan）的同一会话中，通过 MCP 连接器将结果写回该系统。 > - **以链接为最低要求**：所有工件均标注对应的记录 ID，而所有遗留记录也都包含 Markdown 文件的提交哈希值（commit SHA）。在迁移初期，采用“链接”方式是一个稳妥的起点，它承认并接受两个事实来源并存的现实。 > > 只要两者之间建立了双向链接，或者明确指定了其中一方为事实来源，遗留系统与以 Markdown 为核心的体系便能够共存，各司其职。 ### `CLAUDE.md` 文件 `CLAUDE.md` 为 Claude 提供新加入的人类成员所需了解的上下文：约定、命令、架构、常见坑点。这些原本存在于人脑和 wiki 的知识，现在变成一个文件，AI 在每次会话开始时读取。整个团队共同维护，每次犯错了就迭代更新。 #### 起步 **先决条件(Prerequisites)** 无。 **基础设施(Infrastructure)** 一个仓库(Repo)，Claude Code 已安装，一名熟悉代码库的工程师。 #### 执行 1. 在仓库根目录运行 `/init`，Claude 会根据现有内容生成初始 `CLAUDE.md`； 2. 将生成的内容精简，压缩到新团队成员第一天使用时所需掌握的程度。保留构建(build)、测试(test)和代码检查(lint)命令，以及那些非常重要的惯例规则。同时，还要保留 Claude 常犯的错误。 3. 将 `CLAUDE.md` 提交到仓库根目录，让全团队共享同一版本，变更像代码一样走评审。 4. 一个实用规则：Claude 犯同样的错误两次，就把修正写进 `CLAUDE.md`。 5. 保持在一页以内，因为 Claude 每次会话开始时都要全文读取，过时的内容只会浪费上下文。 #### `CLAUDE.md` 示例 ```md # 支付服务 ## 命令 - 构建：`make build` - 测试：`make test`（单元测试），`make itest`（集成测试，需要 Docker 环境） - 代码检查：`make lint`（CI 中运行；推送前务必修复） ## 约定 - Java 21，Spring Boot 3。不再使用新的 Lombok。 - 金额统一使用 `BigDecimal`，绝不使用 `double`。 - 每个端点都必须在 `src/itest` 中有对应的集成测试。 ## 架构 - `api/` 存放 REST 控制器，`core/` 存放领域逻辑，`adapters/` 负责与外部系统通信。 - Kafka 事件定义在 `schemas/` 目录下；生成的类切勿手动修改。 ## Claude 容易犯错的地方 - 不要自行升级依赖版本——由平台团队统一管理。 - 旧版 `v1/` 包已冻结；所有新变更请放入 `v2/`。 ``` `CLAUDE.md` 是仓库根目录的项目指南。Claude 会在会话开始时读取它，获得项目上下文、编码规范和常见陷阱提示。 #### 治理 `CLAUDE.md` 受版本控制，因此 AI 执行的指令可审查、可追溯。团队约定通过文件落地，变更记录在 git 历史中，代码所有者通过 PR 审批这些变更。 #### 度量 **前置指标(Leading indicator)** *（实时纠错能力）——看 AI 是否“屡教不改”* **错误重复率**：跟踪 `CLAUDE.md` 的修改频次和 Claude 重复出现同类错误的频率。若同一偏差反复发生，说明说明不够清楚，或 Claude 未有效遵循。修复缺陷时应同步把经验写回 `CLAUDE.md`。 **后置指标(Lagging indicator)** *（长期团队效率）——看新人是否“秒变老手”* **新人上手时间**：统计新成员从加入到首次合并 PR 的时间。`CLAUDE.md` 中的命令、架构约束和工程约定也服务于人类协作。时间缩短，说明团队知识已被有效沉淀。 这两项指标分别观察错误能否快速收敛，以及文档是否真正帮助团队协作。 ### SKILL 作为组织知识 技能(Skills)是把组织知识转化为操作能力的方式。说明清晰、版本受控、广泛适用，政策变化时集中更新。 基本原则： - 为那些需要一致执行的制度性知识写 SKILL； - 那些本属于 `CLAUDE.md` 或提示词的内容就不必写成 SKILL。 #### 起步 **先决条件(Prerequisites)** 不需要。有 `CLAUDE.md` 会有所帮助，因为它将 Agent 的工作知识保存在仓库(Repo)中，但 SKILL 并不依赖它。 **基础设施(Infrastructure)** 由指定负责人管辖，且具备书面事实来源的策略。 #### 执行 1. 选一项目前执行不一致的知识，比如安全标准、API 设计规范、品牌规则。 2. 将其写成一项技能：一个包含 `SKILL.md` 的文件夹。其前置元数据（frontmatter）声明触发条件，正文说明执行要求。工程师依据策略负责人提供的书面事实来源，借助 Claude 完成编写。 3. 将技能放在仓库的 `.claude/skills//` 下，随代码一起分发；或者通过插件在组织层面推广。 4. 测试技能是否能被触发。用不同方式让 Claude 执行相关任务，确认每次都加载了该技能。 5. 当策略发生变更时，须同步更新相应的技能，并由该策略的指定负责人签批此次变更。 6. 工程师们在下一次会话中会自动获取新版本的 SKILL。 #### SKILL 示例(`.claude/skills/secure-api-review/SKILL.md`) ```md --- name: secure-api-review description: 应用API安全标准。在创建或修改面向外部的端点、审查API代码或生成OpenAPI规范时使用。 --- # 安全API审查 当你创建或更改API端点时： 1. 身份验证：每个端点都需要网关JWT；/health之外没有匿名路由。 2. 输入验证：根据OpenAPI模式验证请求体，并拒绝未知字段。 3. 审计：每个改变状态的端点都发出审计事件，包含操作者、操作、实体和时间戳。 4. 数据分类：模式中标记为pii的字段绝不能出现在日志或错误消息中。 运行 scripts/check-endpoints.sh 并将其输出包含在你的摘要中。 ``` #### 治理 SKILL 是一种建议性控制。它能提高 Claude 遵守政策的概率，但不能强制会话合规。 对于那些必须严格执行的策略，需要在 SKILL 背后增加确定性措施，比如用钩子(Hook)阻止操作，或在 PR 评审中重新检查。 SKILL 用于预防，钩子用于强制。 SKILL 调用记录在会话追踪中，策略负责人像审查代码一样审查 SKILL 变更。 #### 度量 **前置指标(Leading indicator)** **策略变更到技能合并的周期**：从策略负责人批准策略变更，到更新后的 SKILL 完成合并的耗时，依据 SKILL 文件夹的 PR 记录进行统计。 周期越短，说明策略→代码的转化效率越高。 **后置指标(Lagging indicator)** **PR 中引用该策略的评审意见数量**：PR 审查中引用该策略的评审意见数量——一旦技能在代码编写时已有效应用该策略，此类意见应趋近于零。若该数量未能下降，则表明技能未能正确触发，或其内容已偏离官方策略。 趋近于零，说明 SKILL 已在编码阶段有效前置拦截了问题。 ### 钩子(Hook)：构建时的防护栏 SKILL 是建议性的，而钩子是其背后的确定性防线。Claude 在实施阶段的主要动作是文件编辑和 shell 命令，因此构建阶段是钩子最常触发的地方。 构建阶段的钩子可以： - 阻止编辑受保护路径（如生成的类文件或冻结的包）； - 在文件编辑完成后，运行格式化和代码检查工具，以避免错误持续累积； - 始终排除凭据。 为必须严格遵守的 SKILL 配备钩子。 钩子会匹配每个符合条件的动作，因此构建阶段的钩子必须快，且只作用于变更的文件。 更重的检查（如完整测试套件）放在提交或 PR 阶段。 需要人工审批的钩子应当放在阶段 5 的部署关卡中，因为构建过程中出现审批提示，会让所有并行会话的进度都卡在人的环节。 ### 并行会话和子代理(Parallel Sessions and Subagents) 一位工程师可以同时推进多条工作流程。 并行会话就是另起一个完整的 Claude Code 实例，在自己的 [git worktree](https://code.claude.com/docs/zh-CN/worktrees) 里独立干活。每个会话互不知情，唯一共享的是操控它们的工程师。 [Subagents](https://code.claude.com/docs/zh-CN/sub-agents)运行在单个会话内部，是一个作用域受限的助手，拥有独立的上下文窗口和工具限制。适合那些在多任务中重复的工作，比如验证应用是否正常运行。 并行会话让工程师同时推进多个任务；子代理处理会话内边界清晰的重复工作。工程师负责协调和监督。 #### 变化 - 传统 一位工程师每次只处理一项任务，并且花费大量时间进行构建、测试以及审核工作。虽然在等待期间可以切换任务，但这种上下文的切换相当耗费精力，因此很少有人愿意这样做。 - **单一任务串行**：一次只专注于一个任务，难以并行推进多项工作。 - **大量等待时间**：构建、测试、审查等环节占用大量时间，工程师在这些过程中处于被动等待状态。 - **切换成本高**：虽然理论上可以利用等待间隙切换任务，但认知负担（上下文切换）过大，实际很少人这么做。 - AI-Native 一位工程师同时运行多个 Claude 会话，每个会话在其独立的工作树中处理各自的任务。重复性工作转化为具有独立上下文和工具限制的子代理。工程师的职责随之转向任务编排，并最终演进为构建与监控循环。 | 维度 | 传统方式 | AI 原生方式 | | ----- | -------- | -------------------- | | 任务处理 | 串行，一次一个 | 并行，多个会话同时推进 | | 隔离机制 | 无（上下文混杂） | 独立工作树(worktree)，互不干扰 | | 重复工作 | 人工重复执行 | 封装为子代理，自动复用 | | 工程师角色 | 执行者 | 编排者 → 循环构建者 | **演进路径**： 1. **编排阶段**：工程师启动多个 Claude 会话，分配不同任务，监控进展，审查结果。 2. **循环构建阶段**：随着自动化程度提升，工程师的角色进一步抽象为设计流程闭环（如阶段 6 维护所述——生产环境异常自动触发新的 intent.md，形成持续改进循环）。 工程师的注意力从操作细节转向任务分配、审查和流程设计。 #### 起步 **先决条件(Prerequisites)** `CLAUDE.md` 文件，因为所有会话都读取。阶段 4（测试）所建立的反馈循环在此同样具有助益——当会话能够自主验证工作成果时，工程师的监督需求即显著降低。 - **`CLAUDE.md` 的必需性**：所有 Claude 会话在启动时都读取此文件，它提供了项目级的约定、命令和架构上下文，确保每个会话遵循相同的规范。若缺少此文件，每个会话都需人工重复说明项目背景，无法有效并行。 - **测试反馈循环的辅助作用**：阶段 4（测试）建立了自动化验证机制（如持续评估、测试套件）。当会话可以运行测试并自我验证代码变更是否正确时，工程师就不再需要时刻盯着每个会话的每步操作，从而释放人力，使并行化真正可行。 **基础设施(Infrastructure)** 基础设施层面需具备 Git 仓库支持，因为会话间的隔离机制由工作树（worktrees）提供；同时权限配置应经过调优，以消除会话在组织认定为安全的命令上等待审批提示的必要性。 - **Git 工作树（worktrees）**：为每个会话提供独立的代码工作目录和分支环境，避免文件冲突，实现真正的隔离并行。 - **调优后的权限配置**：对组织标记为“安全”的命令（如常规构建、测试、格式化等），会话可直接执行而无需人工逐次确认，避免阻塞。 > 如果每条命令都要人工审批，并行化的收益会被等待抵消。应预先定义信任边界，只让高风险操作请求审批。 #### 执行 1. 根据计划模式产出的 `plan.md`，工程师将工作拆解为改动不同文件的任务。共享文件的任务在一个会话中顺序执行。 2. 每个并行任务都有自己的 worktree，例如一个终端 `claude --worktree feature-auth`，另一个 `claude --worktree fix-rate-limit`。worktree 是独立分支上的单独检出，避免会话之间文件冲突。 3. 两到三个会话是合理的起点。实际上限取决于一个人能妥善审查多少条线，因此只应在审查跟得上的情况下增加会话。 4. 将重复性工作封装为子代理(subagents)，在 `.claude/agents/` 下用 markdown 定义：名称、适用场景、可用的工具。例如：主代理完成后精简代码的简化器、运行并验证行为的验证器、探索代码库并汇报而不污染主上下文的研究员。将定义提交到 git，让全团队共享。 #### 示例(`.claude/agents/verifier.md`) ```md --- name: verifier description: 在会话报告完成之前运行应用并验证变更是否生效 tools: Bash, Read --- 使用 `make run` 启动应用。针对变更的功能及其相邻的两个流程进行测试。报告所执行的测试内容、观察结果，以及与 `plan.md` 不符的任何行为。仅作报告，不予修复。 ``` **与 SKILL 的对比**： - **Skill**：策略性的指导，在编码过程中应用。 - **Subagent**：任务性的执行，在编码后或特定环节自动化验证。 #### 治理 更多的会话意味着更多的产出，因此控制措施必须来自仓库中的配置。仓库中的钩子和权限设置适用于所有会话，且每个会话的操作都会被记录并可追溯至运行该会话的工程师。 #### 度量 **前置指标(Leading indicator)** 在保持审查质量的前提下，每位工程师的并发会话数（通过 [OpenTelemetry](https://opentelemetry.io/)导出数据统计），以及每日用于指挥调度而非被动等待的时间占比。 **并发会话数 + 工程师主动工作时间占比**: 会话数提升且“指挥而非等待”时间占比增加，表明自动化程度提高。 **后置指标(Lagging indicator)** 结合 PR 历史所确定的返工率，统计每位工程师每周合并的变更数量。 **人均周合并变更数 + 返工率**：合并数增加且返工率不升，表明并行化真正带来了净效率提升 并发会话数增加不等于效率提升。应同时追踪产出（合并 PR 数）和质量（返工率），确认工程师的时间确实从等待转向协调。 ## 04 测试 Test > 每个会话在人工介入之前均自行完成工作验证，且指导 Agent 行为的配置本身，也需像其生成的代码一样接受回归测试。 ### 给 Claude Code 一个反馈循环(feedback loop) 始终让 Claude 能自行验证工作成果——无论是测试、构建还是截图对比。会话会在工程师看到结果之前自查并修复错误。 反馈循环不同于[阶段 3：构建](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#03-%E6%9E%84%E5%BB%BA-build)中的验证子代理。反馈循环贯穿任务，并会随进展多次运行；验证子代理则在会话认为工作完成后，以新的上下文进行最终检查，避免沿用编码时的假设。 #### 变化 - 传统 代码运行正常的反馈信号往往姗姗来迟——持续集成（CI）在数分钟后提供反馈，测试人员在数天后给出结论，而生产环境的验证则需数周之久。 当代码由 Agent 生成时，延迟的反馈即意味着人工须逐一核查其全部产出，而人便成为流程瓶颈。 - AI-Native 会话在人工介入之前，即被赋予自行验证工作成果的能力——运行测试、执行构建、截取界面快照。Claude 会持续迭代直至所有检查通过，因此最终呈递给工程师的内容已经过验证。配置此反馈循环的责任归属于运行该会话的工程师，后续步骤即专门为其所撰写。 将“质量验证”从代码完成后的独立阶段，前置并嵌入到构建过程本身。 工程师的角色从手动检查代码，转向配置和维护验证循环。 #### 起步 **先决条件(Prerequisites)** 无。 **基础设施(Infrastructure)** 测试套件与构建流程应能够通过各自的一条命令在本地完成执行。对于前端界面相关工作，Claude 能够查看运行结果至关重要——可通过浏览器工具或经 MCP 集成的截图工具实现。 如果测试、构建或 UI 验证不能由 Claude 以自动化方式（单命令）完成，则反馈循环(feedback loop)就无法自闭环——工程师仍需手动介入验证，从而重新成为瓶颈。 测试阶段转型的前提是：验证过程能完全自动化，并可由 Agent 调用。 #### 执行 1. 若当前验证工作需执行一连串命令并依赖特定环境知识，则应将其封装为单一目标命令，例如 `make test` 或 `npm test`，并在验证**失败时以非零状态码退出**。 > Claude 在执行 Shell 命令时，通过命令退出状态即可判断成功或失败，无需解析复杂的日志输出。这与持续集成系统中的常见模式一致，便于将反馈循环无缝融入代理工作流。 2. 在 `CLAUDE.md` 的命令（Commands）段落中，为每一条命令附上正常输出（healthy output）的示例。 > AI 无法像人类一样凭经验感知“看起来对不对”。通过提供正常输出的模板，Claude 可在执行命令后以输出为参照进行比对，从而可靠地判断当前变更是否通过验证——即使命令仅以状态码指示成功或失败，输出示例也有助于处理非预期的情况。这一细节确保了反馈循环的稳健性。 3. 明确提出一项目标并使其可量化，使 Claude 能够自行验证工作成果而无需向你询问。例如：“`test_status.py` 中的所有测试均通过”、“截图与所附设计稿一致”或“该端点返回包含新增字段的 200 状态码”。 > 将“工作做完了”转成“测试通过”“截图匹配”等可验证断言，代理才能自行判断任务是否完成。 4. 修复缺陷时，先写一个会失败的测试。让 Claude 用测试复现 bug，确认失败原因符合预期后提交测试；再让 Claude 在不修改测试的情况下使其通过。可用钩子禁止编辑测试文件。修复前就存在、且 AI 无法重写的测试，才是缺陷修复的可靠证据。 > 先写失败测试，再用钩子保护测试文件，可避免为了让测试通过而放宽验收标准。 5. 针对前端界面开发工作，应通过视觉检查来形成闭环。为 Claude 配备浏览器或截图工具，并提供设计稿，使其能够反复迭代——实施修改、截取画面、比对差异、调整优化。通常经历两至三轮迭代后结果趋于稳定，且每一轮均应较前一轮有所改进。 > UI 的正确性不只靠单元测试。把视觉比对纳入反馈循环，Claude 才能对照目标自行修正偏差。 6. 在 `CLAUDE.md` 中将验证作为“done”的一部分。在报告任务完成之前，须先执行测试并展示其输出结果。 > 通过将验证标准预先写入 `CLAUDE.md`，Agent 在报告“任务完成”时即自动触发测试并展现结果。此举将质量意识嵌入开发过程的每一个任务中，形成“完成即验证”的默认行为模式。 7. 最后，这一反馈循环本身也需加以防护——因为修复代码的代理不应具备削弱代码检查条件的能力。通过在修复任务期间配置阻止编辑测试文件的钩子（hook），即可达成此目的。另一种替代方案则是在审查阶段检查代码差异（diff），并拒绝任何涉及修改测试的变更。 > 当代理被赋予“修复代码使测试通过”的任务时，若允许其同时修改测试文件，则存在一个隐患——代理可能通过降低测试标准（如删除断言、放宽预期）来“伪造”成功。通过阻止对测试文件的编辑，确保了测试是**固定的验收标准**，代理必须修改产品代码来满足测试，而非反过来调整测试以适应代码。这维护了测试驱动开发的核心原则：**测试即契约，契约不可被代理修改**。 #### `CLAUDE.md` 中的验证块示例 ```md ## 工作验证 - 构建：`make build`（必须以“Build succeeded”作为结束标志） - 测试：`make test`（全部通过；绝不可跳过或删除任何失败的测试） - 代码检查：`make lint`（零警告） 在报告任何任务完成之前，须运行以上全部三项检查，并粘贴其输出结果。 若测试失败，应修复代码，而非修改测试。 ``` #### 治理 - 什么是强制执行的？ 在任务标记为完成前进行验证，以及在缺陷修复过程中阻止代理编辑测试文件——这两项机制均通过钩子（hooks）实现，并应用于组织要求强制保障的场景中。 - 证据是什么？ 由 Claude 执行并粘贴的 `make test` 原始输出、构建日志或截图比对结果——以此确保证据直接来源于工具链路，而非人工陈述。 - 在何处进行记录？ 上述证据须同时记录于两处：一是会话日志，通过 OpenTelemetry 导出至组织的可观测性平台；二是 PR 的检查运行记录，可供审查者及后续审计人员查阅。 - **实时可观测**：通过 OpenTelemetry 纳入统一监控体系； - **永久可审计**：PR 记录作为版本控制的一部分，形成不可篡改的审计线索。 - 谁批准了？ 负责审查 PR( Pull Request )的开发者，可专注于理解系统的意图和潜在风险，因为相关的技术文档已经附在了 PR 中。 人类审查者可把时间放在架构合理性、业务影响和潜在风险上，而不必重复验证语法或基本功能。 #### 度量 **前置指标(Leading indicator)** Agent 生成代码的首次 CI 通过率（该指标由 CI 系统原生支持）。 **Agent 生成代码的首次 CI 通过率**：通过率越高，说明 AI 生成代码的质量越高，反馈循环有效。 **后置指标(Lagging indicator)** 每项 PR 的审查耗时（来源于 PR 元数据），该指标应随测试覆盖范围的扩展而下降——当测试能够捕获此前仅由人工审查发现的问题时，审查时间即显著缩短；同时，源自事件追踪系统的变更失败率亦应同步下降。 **PR 审查耗时 + 线上故障率**：审查时间缩短且线上故障率不升反降，说明测试已有效接管了人工审查的验证职责。 > 测试阶段的目标是让自动化测试尽早发现原本依赖人工发现的问题，缩短 PR 审查时间，同时不提高线上故障率。 ### CI 中持续评估 评估（Evals）是 AI 原生时代的阶段门控 QA。它是一套测试集，每当 Agent 配置变化时运行——换了新模型、重写了提示词，评估会告诉你 Agent 是否还能达到同样的标准。 评估套件需要持续维护。模型能力变化后，旧用例可能失去区分度，应根据监控中新发现的问题补充用例。 根据具体的使用场景，有些团队可能更倾向于以固定的节奏在离线环境下进行这些评估，而不是每次发生变更时都进行评估。以下的步骤适用于连续性的评估情况。 #### 起步 **先决条件(Prerequisites)** `CLAUDE.md` 和反馈循环（阶段 4：测试）。 **基础设施(Infrastructure)** 具备非交互式运行 Claude Code 能力的持续集成（CI）系统，以及配备评估运行预算的 API 密钥。 > 持续评估需要在不依赖人工介入的情况下自动执行，因此必须依托 CI 系统来实现调度和执行；同时，评估运行可能涉及大量 API 调用，需通过预算控制来管理成本，避免无限消耗。 #### 执行 1. 平台工程师从近期工作中收集 20\~50 个真实任务及其预期结果。 2. 将每个任务写成评估项：即提示词 + 判定通过的条件（测试通过、lint 干净、行为不变、合规）。 3. 该评估套件在 CI 中以非交互方式运行，按既定计划触发，并在 `CLAUDE.md`、技能（skills）或钩子（hooks）发生任何变更时自动执行——因为此类配置直接指导代理行为，理应享有与产品代码同等的回归测试保障。 4. 根据评估结果对配置变更进行把关。任何导致通过率下降的技能(Skills)变更，在合并前均须经过审查。 5. 每次生产环境事故都编写一个对应的评估项，由负责团队撰写，作为回归测试永久保留在套件中。 #### CI 持续评估示例(`.github/workflows/agent-evals.yml`) ```yaml 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 ``` > 这是[Github Actions](https://docs.github.com/zh/actions)语法示例。 #### 治理 评估为 QA 提供了能跟上 AI 产出速度的门控。通过率阈值作为合并检查强制生效，运行记录留存以便随时间比较，配置变更由所属团队审批。 #### 度量 **前置指标(Leading indicator)** 评估套件在每次运行时，报告通过率随时间的演变趋势，以及生产事件从发生到转化为永久评估用例所需的周期。 **通过率趋势**：随时间变化，通过率稳定或提升。 **事件→评估转化周期**：转化周期短即学习闭环快。 **后置指标(Lagging indicator)** CI 中捕获的回归问题数量与源自事件追踪系统的生产环境回归问题进行对比。 **CI 发现 vs 生产发现的回归数量对比**：CI 发现远多于生产发现，表明评估套件已有效前置拦截问题。 > 持续评估要尽量在 CI 阶段发现问题。若生产环境仍不断出现同类回归，应据此补充评估用例。 ## 05 部署 Deploy > 评审是双向的，治理控制会在 Agent 执行任务时生效。Agent 可处理生产门禁之前的工作，越过门禁则交由其他机制。 ### AI 参与 PR review 循环 Claude 既会评审别人的 PR，也会处理自己 PR 上的评审意见。它按组织政策审查传入 PR 并回应评论，工程师则聚焦于变更意图和风险。 在这一双向审查模式中： - **机械性检查**（是否符合策略、编码规范）由 Claude 自动执行，无需人工介入； - **人类工程师**的审查焦点则从“检查代码细节”上移到“判断变更意图是否合理、风险是否可控”的战略层面。 #### 变化 AI 接管机械性工作，人类专注需要判断力的决策。 **传统** 审查产能由人工产出决定。一份 PR 需要等待审查者通读全部内容，审查质量随审查者当前负载而波动，提交者不断催促，而积压的待审请求却日益增多。 **AI-Native** 所有 PR 均接受一组统一的审查流程，审查发现按严重程度分级标注。 人类审查者判断变更是否实现计划中的意图，以及风险能否接受。 #### 起步 **先决条件(Prerequisites)** 来自[阶段3 (03 构建Build)](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#03-%E6%9E%84%E5%BB%BA-build)的已更新 `CLAUDE.md` 文件；若审查通过，则技能（skills）将强制执行既定的策略，以及已定义好的子代理（subagents）。 **基础设施(Infrastructure)** 安装配置 Claude 集成的仓库(Repo)，可由管理员启用 [代码审查 (Code Review)](https://code.claude.com/docs/zh-CN/code-review)，或者在自己的 CI(持续集成)环境中运行 [claude-code-action](https://code.claude.com/docs/zh-CN/github-actions)。 必要时，模型调用可通过 AWS Bedrock、Google Vertex 或 Microsoft Foundry 完成（CI/CD 相关剧本涵盖了具体的部署选项）。同时，要求代码所有者审批的分支保护策略亦值得采用。 #### 执行 1. 托管式代码审查服务最容易上手：管理员启用并选择仓库即可。若要控制流水线或让 API 调用走自有云协议，可在 CI 中用 claude-code-action 运行评审。 2. 技术负责人在仓库根目录编写评审政策 `REVIEW.md`，按组织关注点划分审查维度：缺陷和逻辑错误、安全漏洞、是否符合规格（来自需求模块的 `spec.md`）和实施计划（计划模式的 `plan.md`）及设计原则。`REVIEW.md` 还要明确哪些算“重要”问题，哪些只是“吹毛求疵”，以及跳过哪些内容。 3. 技术负责人设定人工阈值。评审发现本身不会自动批准或拒绝 PR，分支保护仍要求代码所有者审批。如果平台工程师想依据发现来卡合并，可以读取检查运行输出的严重性计数（机器可读）。 4. 当评审人或作者在评论中 `@claude` 时，Claude 会处理该评论并推送修复。PR 中会记录请求和改动。这个修复循环通过 [claude-code-action](https://code.claude.com/docs/zh-CN/github-actions) 运行。 在托管服务中，评论 `@claude review` 会触发重新审查流程。 对于 Claude 自己开的 PR，可以更进一步让 Claude 负责合并。 团队可封装自定义斜杠命令，循环处理未解决评论和失败检查，直到 PR 只等待代码所有者批准。 1. 评审发现会反馈回 `CLAUDE.md`。当评审两次标记同一类错误时，修正内容作为该评审的一部分写入 `CLAUDE.md`。由于评审会读取 `CLAUDE.md`，下次 PR 就能提前捕获该错误。评审也会提示 `CLAUDE.md` 是否因变更而过时。 2. 技术负责人每月根据评审发现的质量来调整配置，并在 `REVIEW.md` 中限制“吹毛求疵”的数量。自动生成的路径和 CI 已强制的内容不予报告。 #### Review\.md 示例 ```md # Review instructions ## Passes 执行三个维度的审查，并为每项发现标注所属类别： - 缺陷（Bugs）：逻辑错误、边界条件缺失、细微回归 - 安全（Security）：注入风险、认证漏洞、日志中包含个人身份信息（PII） - 合规（Compliance）：变更是否符合 spec.md、plan.md 及设计原则 ## “重要”的判定标准 仅将可能导致行为异常、数据泄露或违反策略的发现标记为“重要”。代码风格与命名问题归类为“细枝末节”。 ## 细枝末节数量限制 每次审查最多报告五处细枝末节，其余部分仅汇总计数，不予逐条列出。 ## 不报告范围 不审查 `src/gen/` 目录下的生成文件，也不报告 CI 系统已强制覆盖的检查项。 ``` #### 治理 职责分离得到保留：写代码的 AI 无法批准自己的 PR。 `REVIEW.md` 中的评审政策应用于所有 PR，发现、修复、评级和审批都记录在 PR 历史中，因此 PR 本身就是审计凭证。 审批由人类通过分支保护完成，并参考 AI 的发现。 关于这些控制措施在生产规模下如何组合，请参阅 [How Anthropic secures its AI-native software development lifecycle](https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle)。 #### 度量 **前置指标(Leading indicator)** 首次审查响应时间（预期将缩短至数分钟级别），以及无需人工直接操作分支即可解决、且相关数据直接存储于 Git 中的审查评论所占比例。 **响应速度**：首次审查响应时间(Time to first review)，从 PR 提交到收到第一条审查反馈的耗时；目标是缩短至分钟级（传统方式可能数小时或数天）。 **自动化程度**：自动化解决评论比例(review comments resolved)，审查中提出的问题由 AI 自动修复并提交，无需人工手动操作，且所有操作记录直接存储在 Git 中; 比例越高，说明代理的自主修复能力越强，人工介入越少。 **后置指标(Lagging indicator)** 将合并前捕获的缺陷与漏洞，与逃逸至生产环境的缺陷与漏洞进行对比——数据分别来源于 PR 历史记录与事件追踪系统。 **合并前捕获**：PR 历史记录（审查评论、自动化检查发现）；已被拦截的问题，代表门禁的有效性。 **逃逸至生产**：事件追踪系统（Incident Tracker）；未被拦截的问题，代表门禁的遗漏。 该对比反映生产门禁的拦截能力。若合并前捕获的问题显著多于逃逸到生产的问题，说明门禁发挥了作用。 ### 钩子作为审批关卡 在构建阶段([03 构建Build](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#03-%E6%9E%84%E5%BB%BA-build))，用钩子作为护栏，无需人工参与，自动决定是否进行某些操作。 钩子也可以发起请求，暂停操作直至人类批准，这正是发布门禁需要的机制。 之所以将这个模块放在阶段 5（[05 部署Deploy](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#05-%E9%83%A8%E7%BD%B2-deploy)），是因为发布门禁是最典型的场景，但钩子不是部署阶段特有的：它们会在 Claude 执行任何操作时运行。 例如，在阶段 3（[03 构建Build](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#03-%E6%9E%84%E5%BB%BA-build)）中，钩子可在无变更工单的情况下阻止对迁移脚本和基础设施代码的编辑；在阶段 4（[04 测试Test](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#04-%E6%B5%8B%E8%AF%95-test)）的缺陷修复任务中，钩子亦可阻止代理修改测试文件。 #### 起步 **先决条件(Prerequisites)** 无。 **基础设施(Infrastructure)** 一份变更流程所要求的各项审批的书面清单。 明确变更流程需要哪些人工审批节点（如安全、架构、业务负责人审批），并将清单固化为 AI 执行发布门禁的依据。 #### 执行 1. 各相关团队（如：工程管理层、变更管理、及合规团队）共同拟定一份必须保留的人工审批门禁清单，例如变更管理签批、发布授权，以及对受保护路径的编辑操作。 2. 平台工程师将每一项门禁实现为一个钩子（hook）——即在 Claude 执行操作前运行的脚本，该脚本可决定允许、询问或阻止该操作。 3. 团队级钩子存放于 Git 仓库中的 `.claude/settings.json` 文件内；而不可协商的强制性钩子则置于平台或 IT 管理员所拥有的托管设置(GitLab 或 Github)中，个别工程师无权将其关闭。 4. 当钩子阻止操作时，其自身应具备解释能力——Claude 的输出中须明确显示阻止原因及审批路径。 > 把人工审批门禁从流程文档变成可执行的钩子，并分层管理：团队维护常规规则，平台控制组织级强制策略。钩子拦截操作时应说明原因和审批路径。 #### Claude Code 门禁钩子配置示例 **Claude Code 钩子示例 `.claude/settings.json`** ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh" } ] } ] } } ``` 其中钩子实质是一个 shell 脚本 `${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh`。 **门禁脚本示例 `.claude/hooks/production-gate.sh`** ```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 ``` #### 治理 钩子即审批门禁。 - **强制执行**：门禁在任何人的任何操作中均强制执行，不可跳过 - **可审计性**：所有允许/阻止决策均被记录，并附带时间戳，形成完整审计线索 - **审批定义**：门禁须预先明确何为有效批准（如变更工单状态、发布经理签批），确保代理和人类对“通过”有一致理解。 > 将审批门禁写成可执行钩子，配合日志和明确的审批定义，使治理在操作发生时生效。 #### 治理示例 **企业账户管理配置示例** > 由平台团队通过移动设备管理（MDM, Mobile Device Management）或管理控制台进行部署；普通工程师无权编辑或覆盖其中任何内容，由企业管理员相关角色统一配置。 ```json { "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` 则预先批准安全的内部循环操作，从而使拒绝列表不会演变为“提示词疲劳”； - `disableBypassPermissionsMode` 与 `allowManagedPermissionRulesOnly` 两项配置的组合生效后，任何工程师、项目文件或命令行参数均无权放宽权限规则。 - `sandbox` 弥补了权限机制所无法覆盖的安全缺口。对 `WebFetch` 工具设定的拒绝规则无法阻止 shell 命令访问网络；而操作系统层面的域名白名单，则可直接从源头阻断数据流出。 - `failIfUnavailable` 与 `allowUnsandboxedCommands` 两项配置使沙箱成为一道门禁：当沙箱无法初始化时，Claude Code 将拒绝启动；而在沙箱内执行失败的命令，亦无法被转移至沙箱外部重试。 - `credentials` 配置弥补了拒绝规则所遗留的安全缺口。`permissions.deny` 仅能控制 Claude 的文件工具，但沙箱中的 shell 命令默认仍可读取 `~/.ssh` 或 `~/.aws/credentials` 等敏感文件；而 `credentials` 配置会拒绝这些读取操作，并从每个沙箱命令的环境中剥离指定密钥。 - `allowManagedHooksOnly` 配置表示当前定义的审批门禁为唯一可执行的钩子；任何本地配置均不得增补或替换这些钩子。 - `disableSideloadFlags` 与 `strictKnownMarketplaces` 两项配置意味着工程师机器上的**每一项技能（skill）、代理（agent）、钩子（hook）及 MCP 服务器，均须通过组织批准的插件市场获取，不得来自用户主目录等本地来源**。 - `allowManagedMcpServersOnly` 配置将代理的工具调用范围，限制为仅可使用由平台团队所拥有的白名单中的 MCP 服务器。 - `requiredMinimumVersion` 配置将拒绝在 Claude Code 低于批准基线版本的条件下启动，从而确保控制措施由组织实际评估过的构建版本执行。 上述配置只是起点，不应照搬。每条拒绝规则都会牺牲一部分能力，取舍取决于仓库的数据分类等级。 设置参考文档对每一个配置键均有说明，包括仅限托管模式的键值：[code.claude.com/docs/en/settings](https://code.claude.com/docs/en/settings) #### 度量 **前置指标(Leading indicator)** 各审批门禁的等待耗时。每次钩子的决策（允许或阻止）均附带时间戳写入 OpenTelemetry 导出数据，因此每一处门禁的等待时间皆可观测。 **门禁等待耗时**：每个审批门禁从触发到获得批准/拒绝所花费的时间；数据来源自 OpenTelemetry（含时间戳与决策结果）。反映审批流程的效率瓶颈。若等待时间过长，说明人工审批环节拖慢了部署节奏，需考虑简化或进一步自动化。 **后置指标(Lagging indicator)** 钩子启用前后，逃逸至生产环境的门禁违规数量——数据来源于事件追踪系统。 **门禁违规逃逸数量**：钩子启用前后，绕过审批门禁进入生产环境的变更数量对比。数据来源自事件追踪系统（Incident Tracker）。反映钩子作为审批门禁的实际拦截效果。若钩子启用后逃逸数量显著下降，则证明门禁机制有效；若仍居高不下，则说明门禁规则存在缺口或钩子未被正确触发。 两项指标共同反映生产门禁在效率与安全之间的取舍。 ### CI/CD 集成与部署 在 CI/CD 流水线中非交互运行 Claude Code；通过沙箱限制风险、通过 MCP 暴露部署能力，并提前演练回滚路径。 #### 变化 **传统** 流水线执行确定性的脚本，而任何需要判断力的工作则留待人工处理。例如，对不稳定测试进行归类、编写变更日志，或排查构建失败的原因。部署与回滚则是操作手册（runbooks），由人类在压力下按步骤执行。 **AI-Native** 对于需要判断力的步骤，Claude 在流水线中以非交互方式运行，并在具备受限凭证的沙箱中执行。部署工具通过 MCP 向代理暴露，因此编写并测试变更的工作流亦可执行发布与回滚操作，且整个过程受限于组织按环境所定义的审批门禁。 #### 起步 **先决条件(Prerequisites)** Claude 嵌入 PR Review 循环中，钩子作为审批门禁——因为门禁必须在自动化流程加速任何操作之前就已就位。 - **Claude in the PR review loop**：Claude 作为双向审查参与者，既审查传入 PR，也响应自身 PR 上的评论； - **hooks as approval gates**：钩子作为审批门禁，在执行关键操作前拦截并请求人工批准。 **基础设施(Infrastructure)** - **CI 平台 / 运行器**：安装了 `claude-code-action` 的 CI 平台，或任何能执行 `claude -p`（非交互式命令）的运行器； - **模型访问**：通过 API 直接调用，或经 AWS Bedrock / Microsoft Foundry / Google Vertex 调用——后者适用于流量须符合组织云协议的场景； - **用户部署到目标的 MCP 服务**：将部署目标（如 Kubernetes、云服务）封装为 MCP 服务器，供 AI Agent 调用； - **沙箱环境**：代理任务在沙箱中执行，且不配置常驻生产凭证（采用临时凭证或运行时注入） #### 执行 1. 平台工程师(platform engineer)从只读判断开始：在流水线任务中用 `claude -p` 来分类构建失败、总结不稳定测试、草拟变更日志。 2. 在现有门禁后面增加写入步骤，比如 fix lint、更新生成的文档、通过 `@claude` 处理 review 意见。AI Agent**产生的任何变更都通过分支保护以 PR 形式提交**，AI Agent 没有直接推送到主分支(通常为 main 或 master)的权限。 3. 执行环境沙箱化：Agent 任务运行在容器中，受网络策略限制，使用短期作用域令牌，默认不持有生产凭证。 4. 通过 MCP 暴露部署能力。部署、状态查询、回滚都成为工具，按环境限定作用域，因此 AI Agent 的部署权限由白名单控制，而非带凭证的 shell 脚本。 5. 按环境划分自主等级：开发环境代理可自由部署；生产环境 Agent 准备发布，但需人类(发布负责人)授权，并由钩子强制执行生产门禁；预发布环境介于两者之间。 6. 回滚应是流水线中演练最多的路径：一条 Agent 可执行的命令，并定期在预发布环境验证。阶段 6 会在控制阈值被突破时调用它，必须先证明其可用。 #### Pipline 示例 ```yaml - 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 形式提交，不能直接进入主分支。 - 在部署过程中，这个“部署钩子”会阻塞发布操作，直到指定的发布管理员批准为止。 - 每次非交互运行都使用 Agent 自己的身份，流水线日志清晰区分 Agent 的动作，和发起这些的工程师的动作。 - 按环境划分的权限层级决定了 Agent 在抵达门禁前能做什么。 #### 度量 **前置指标(Leading indicator)** 自动化故障处理占比：流水线运行中发生的故障，由 AI 自动诊断、分类并处理的比例（无需通过告警系统唤醒来介入）。 > 比例越高，说明代理在部署流水线中的自主故障处理能力越强 **后置指标(Lagging indicator)** DORA（DevOps 研究与评估，DevOps Research and Assessment）指标，由 CI 系统及部署工具链原生输出。 > 部署阶段的度量指标可复用业界标准——**DORA 四项指标**（部署频率、变更前置时间、变更失败率、服务恢复时间）。这些数据由现有 CI/CD 与部署工具链直接产生，无需额外采集，可作为代理部署效果评估的补充基准。 ## 06 维护 Maintain > 循环至此闭合。一个触发器在调用路径中无需人工介入的情况下唤醒 Claude，而其所发现的问题将以 `intent.md` 的形式重新进入流水线。 ### 运维与闭环(Maintenance and closing the loop) 前面我们说明了如何在 SDLC 各阶段引入 Claude，但每个阶段仍需人工初始启动。 而这一阶段则重点是让 Claude 自主运行，形成闭环。 例如，一个持续运行的监控 Agent 在缺陷工单生成后，可以自动创建 `intent.md`，然后一路经过需求、计划、构建、测试、评审等阶段。阶段 6 是无人操作(headless)的，各阶段之间有独立的置信度门禁，一个确定性检查或对抗性评审 Agent，负责决定前一阶段输出是继续流转还是升级给人类处理。 #### 变化 **传统** 维护是一个被动响应的。所有工单或事件均须等待人员介入处理并重新启动流程。凌晨 3 点触发的告警可能被忽略，工单可能在积压队列中滞留直至有人认领，而若新的紧急问题抢先出现，事后复盘所确定的改进措施甚至可能完全无法落地至代码库。 **AI-Native** 触发器(Trigger)——例如控制区间突破、工单、频道消息或定时计划——在调用路径中无需人工介入即可唤醒 Claude。Claude 执行诊断，仅通过受门禁保护的路径执行操作，并将其发现记录为 `intent.md`，随后该文件即进入前述各阶段流程。人员负责对工作进行分类与审查，而不再需要从头启动这一过程。 > 维护从被动等待人工响应，转为自动检测、诊断、规划并进入开发流水线；人只在分类、审批等关键决策点介入。 ### 实现闭环(Closing the loop) 一个确定性脚本监控生产，当控制阈值被突破时调用 Claude。这种监控违规的方式是自主循环的一个典型示例，而阶段末尾的 [Claude Tag](https://claude.com/product/tag)（在 Slask 中使用@方式使用 Claude ，与飞书中使用 OpenClaw、或 Hermes 同理）则覆盖了通过其他渠道到达的工作。 #### 起步 **先决条件(Prerequisites)** `intent.md` 为闭环提供了结构化的输出，用以重新启动流程。Claude 加速了 PR 审查，钩子作为行动边界，而 CI/CD 的回滚路径（由最高自主级别的代理所调用）亦已就位。 | 要素 | 在闭环中的角色 | | ------------------- | ------------------------------------ | | **intent.md** | 作为诊断输出的结构化工件，重新进入 SDLC 起始阶段（规划） | | **Claude 加速 PR 审查** | 闭环中的代码变更通过已有的 AI 审查机制快速处理 | | **钩子作为行动边界** | 确保 Claude 在诊断和执行修复时，操作范围受门禁约束（不越权） | | **CI/CD 回滚路径** | 若修复引入新问题，最高自主级别的代理可调用预演过的回滚路径恢复至安全状态 | > 这四项要素构成维护闭环：问题触发后，Claude 诊断并生成 `intent.md`，再进入规划、设计、构建、测试和部署；部署出问题时调用已演练、已审批的回滚路径。 **基础设施(Infrastructure)** 检测脚本可查询的指标存储（如 Prometheus、CI 系统 API 或同类方案）、仓库的读取权限、在 CI 中以非交互方式运行 Claude Code 的方法，或用于接收 Webhook 的 Agent SDK。 | 基础设施项 | 作用 | | ----------------------- | ----------------------------------------------------------------- | | **指标存储** | 检测脚本（如监控告警规则）可查询 Prometheus 等时间序列数据库或 CI API，以获取性能指标、错误率等数据作为触发条件 | | **仓库读取权限** | 代理需要读取代码仓库以进行诊断（如检查最近变更、读取日志、分析配置） | | **非交互式 Claude Code** | 在 CI 中以无人值守方式运行 Claude，用于执行自动化诊断任务 | | **Agent SDK / Webhook** | 若采用外部服务触发方式（如通过消息、工单系统 webhook 唤醒），则需要 Agent SDK 来接收和处理这些外部事件 | > 这些基础设施分别支撑检测（指标存储）、诊断（仓库读取与非交互式 Claude）和触发（Agent SDK/Webhook）。 #### 执行 1. 服务负责人或平台工程师选定一个具有稳定滚动基线（stable rolling baseline）的指标，例如 CI 测试失败率、部署后 5xx 错误率，或 PR 周期时间。 2. 随后编写检测脚本——通常采用滚动窗口内的均值与标准差，并结合西部电气（Western Electric）或类似判定规则，使控制区间能够捕捉缓慢漂移与突发尖峰。该脚本受版本控制并经过单元测试，检测过程保持完全确定性，不涉及任何模型调用。 > **Western Electric**规则：是一套用于**统计过程控制（SPC, Statistical Process Control）** 的经典判异准则，简单来说，它就像一套**用于监控系统指标是否“异常”的精密规则**，用来判断某个过程（在本文中就是软件开发流程）是否处于“失控”状态。详情参见：[维基百科- Western Electric rules](https://en.wikipedia.org/wiki/Western_Electric_rules)。 3. 响应层级在版本化配置文件（见下方 `bands.yaml`）中定义：在 1σ 偏差时仅记录日志，在 2σ 时调用 Claude 以只读方式进行诊断，在 3σ 时 Claude 可采取行动，但仅限通过发起 PR 进入审查门禁，或触发预先审批的操作手册（runbook）。 > `σ`：希腊字母 sigma ，在统计学中，σ 代表标准差。在技术或科学领域，‘1σ’ 通常用于描述数据的统计分布，表示约 68%的数据点落在平均值的一个标准差范围内 4. 触发层可以是 GitHub/GitLab 的定时工作流（workflow)、现有监测系统的 Web 钩子( webhook ) ，或网络内的定时任务(Cron Job) 。Claude 以无状态方式运行——要么是 CI Runner 上的非交互步骤，要么是沙盒容器中的 Agent SDK 服务。CI/CD 模块负责部署和模型访问。由于运行是无状态且非交互的，循环可以无人启动即开始和结束。 5. AI Agent 将诊断结果写成 `intent.md`（采用 [01 计划Plan](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#01-%E8%A7%84%E5%88%92-plan)的格式），包含异常现象和证据、建议方案、影响系统及待定问题。然后这条发现像其他需求一样走流水线。 6. 服务负责人或值班工程师负责处理排队请求，将有关产品的反馈信息传递给相关责任人。这些反馈可能包括修复问题、安排维修或驳回某些请求。驳回一些请求有助于减少噪音干扰，从而提升服务质量。 7. 修复上线后，为这次事故增加一个评估项（持续评估模块），确保今后不再出现同类问题。 #### 示例 (`bands.yaml` 监控 CI 测试失败率) ```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] } ``` #### 治理 响应层级的边界由版本控制的配置文件强制执行，并辅以权限配置与托管设置，拒绝生产环境的直接访问。 每次调用、诊断发现及分类决策均附带时间戳记录在案。 服务负责人对发现进行分类与审批，由此产生的变更经由常规 PR 审查门禁处理，而代理可能触发的操作手册（runbooks）则需事先获得审批。 | 要素 | 说明 | | ---------- | ----------------------------------------------- | | **配置驱动** | 响应层级（1σ/2σ/3σ）的边界由版本控制的配置文件强制执行，确保变更可追溯 | | **权限隔离** | 通过权限配置和托管设置，拒绝 AI 直接访问生产环境（仅通过门禁或预批 runbook 行动） | | **全链路审计** | 每次调用、诊断结果、分类决策均带时间戳记录，形成完整审计线索 | | **人工决策权** | 服务负责人负责分类与审批，确保关键判断仍由人类做出 | | **常规审查路径** | 修复变更经由正常 PR 审查流程，不设特殊通道 | | **预批操作手册** | AI 可能触发的 runbook 需事先审批，确保应急操作已通过安全审查 | > 闭环不等于让 Agent 任意操作。配置、权限隔离、审计日志、人工分类和预批机制共同限制自动化响应的范围。 #### 度量 **前置指标(Leading indicator)** 从控制区间被突破到 `intent.md` 进入分类队列所需的时间——作为对比基准的是旧模式下从事件发生到事后复盘行动启动的时间。检测脚本的日志中记录了突破时间戳与事件所属层级。 | 指标 | 含义 | 对比基准 | | ---------- | --------------------------------------------- | ----------------------------------- | | **闭环响应时间** | 从异常被检测到（控制区间突破）到 AI 输出 `intent.md` 并进入分类队列的耗时 | 旧模式下，从事件发生到人工启动事后复盘（post-mortem）的时间 | | **可观测性** | 检测脚本日志中记录了突破时间戳和事件层级（1σ/2σ/3σ） | 确保每一次闭环触发都有据可查 | > **核心逻辑**：此指标直接验证闭环机制是否实现了“缩短从发现到响应的时间”这一目标。若闭环响应时间显著短于旧模式的事后复盘启动时间，则证明自动化诊断与规划流程有效。同时，日志中的时间戳与层级信息为后续分析（如阈值调优、响应效率评估）提供了数据基础。 **后置指标(Lagging indicator)** 诊断发现中最终转化为合并修复的比例（以分类队列与 PR 历史记录对比为准），以及同类事件的重复发生率——后者应随修复为评估套件新增用例而逐步下降。 | 指标 | 含义 | 健康信号 | | ------------ | ------------------------- | --------------------------------------------------------------- | | **发现→修复转化率** | 诊断发现中最终通过 PR 合并落地为修复方案的比例 | 转化率越高，说明自动化诊断的质量越高，分类决策的有效性越强 | | **同类事件重复率** | 同类问题在修复后是否再次出现 | 应持续下降——每次修复后都会为评估套件（Eval suite）补充新的用例，从而使后续版本能够更早捕获同类问题，防止其再次发生 | > 每次修复都应为评估套件增加用例，让同类问题在后续版本中更早暴露。 #### 示例 - 当 CI 测试失败率超过 3σ，AI Agent 隔离不稳定测试或开一个回退 PR，由 Review 门禁决定。 - 当部署窗口内后部署 5xx 率超过 3σ，AI Agent 触发现有的回滚流水线。 - 当 PR 周期时间触发漂移规则，AI Agent 为管理层写一份报告，证明这套机制同样适用于流程指标和生产指标。 > 检测过程保持确定性。仅在控制区间被突破时才调用 Claude，且调用后的操作权限由该事件所属的响应层级决定。 ### 定期扫描代码 安全扫描是在特定模型对代码库的一次快照分析，但会很快过时： - 代码每周都在变， - 新一代模型会发现旧模型漏掉的漏洞。 AI 原生的方案是按计划定期运行扫描，无需人工触发，并将其发现像普通代码变更一样走相同的流程。 [Claude Security](https://claude.com/product/claude-security) (注：Github/Gitlab 也有类似机制 )是云端定期扫描服务。连接 GitHub 仓库后，扫描工作运行在 Anthropic 基础设施中，基于 Claude Mythos 5 模型，每个扫描结果都会经过验证并附置信度评分。 建议的修复方案可在 Claude Code 网站 中审查和应用。组织无需访问模型本身即可获得扫描结果。 #### 变化 **传统** 安全扫描常由事件触发：发布或审计前扫一次，报告送入追踪系统，积压问题由人工逐一处理，直到下一次触发。在这段期间，新代码的安全性主要依赖 PR 审查。 **AI-Native** 扫描按既定计划对每一个已连接的代码仓库运行，采用当时可用的最强模型执行，且扫描发现会在任何人查看之前即被验证。每一条发现的处理方式与控制区间突破时的处理方式一致：若修复方案可容纳于单次 PR，则经由常规审查门禁处理；若涉及范围更大，则转化为 `intent.md` 进入规划流程。覆盖范围的有效期以最近一次扫描的时间为准，而非以首次扫描的时间为准。 > 安全扫描应从间隔检查变为持续覆盖。扫描结果先经过去重、上下文确认和误报过滤，再交给人处理；覆盖有效期以最近一次扫描为准。 #### 起步 **先决条件(Prerequisites)** 安全扫描发现经由 PR 审查门禁与钩子（作为审批门禁，见[05 部署Deploy](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#05-%E9%83%A8%E7%BD%B2-deploy)）处理，使各项发现与其他变更一样通过审查流程。 对于规模过大、无法容纳于单次 PR 的发现，则采用 [01 规划Plan](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#01-%E8%A7%84%E5%88%92-plan)中定义的 `intent.md` 格式输出。 **基础设施(Infrastructure)** [Claude Security](https://claude.com/product/claude-security) 现已向 Claude Enterprise 组织开放公开测试版。使用该功能需满足以下条件：在目标代码仓库（云托管于 [github.com](https://github.com/)）上安装 Anthropic GitHub 应用；启用 `Claude Code on the Web`；开启 `Extra Usage` 并设定消费上限；为执行扫描的人员配备高级席位；并由管理员在 `claude.ai/admin-settings/claude-code` 处开启该功能。 扫描按 Mythos 5 模型的使用量计费，因此消费上限应与代码仓库的规模和数量相匹配。 > **Claude Security** 是 Anthropic 于 2026 年 4 月推出的漏洞扫描服务，面向 Claude Enterprise 客户开放公测。该工具可直接集成 GitHub 仓库，对代码库进行扫描并生成漏洞修复补丁。扫描结果包含 CWE 分类、置信度级别、严重性评级和修复建议等信息。 #### 执行 1. 安全负责人连接仓库，并按仓库、服务或团队将其组织成项目，确保发现归属从一开始就清晰。 2. 对最关键仓库进行首次全量扫描，包括之前被其他工具或旧模型扫描过的。把首次扫描作为基线。第一次扫描很可能在原本认为干净的代码里发现问题。 3. 为每个项目设定计划。对于活跃开发的服务，每周一次是合理的默认值；对于大型或混合仓库，可将扫描范围限定到特定目录或分支。 4. 根据置信度评分进行分类。忽略时需注明原因，这样忽略记录会被保留，同一条发现不会在下次扫描中又被当作新问题报告。 5. 对于范围可控的发现，在网页版 Claude Code 中打开建议补丁，审查后像普通变更一样走 PR 评审关卡。提出修复方案的代理无权批准它。 6. 对于超越单个补丁的问题（如架构弱点、跨服务重复模式），按[01 规划Plan](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#01-%E8%A7%84%E5%88%92-plan) 格式写成 `intent.md`，从规划阶段开始处理。 7. 修复上线后，在持续评估中为该漏洞类别增加一个评估项，确保今后引导 AI Agent 的配置会针对该类漏洞进行测试。 8. 将发现导出为 CSV 或 Markdown，或使用 webhooks，将结果同步到组织现有的跟踪和审计系统（审计人员已习惯使用这些系统）。 #### 治理 扫描在组织的管理控制下运行：连接哪些仓库、谁持有扫描席位、预算上限都集中设置。 每个发现都有验证结果和置信度评分，每次忽略都有理由，因此扫描历史就是一份审计记录，记录了发现、修复和有意接受的内容。 修复通过 PR 评审门禁和分支保护机制到达生产，而非直接从扫描结果合入。 Claude Security 是对现有静态分析和依赖扫描的增强。确定性检查留在 CI 中，模型驱动扫描则负责发现那些确定性检查无法捕捉的、依赖上下文的漏洞。 #### 度量 **前置指标(Leading indicator)** 已连接的仓库按计划扫描占比，以及从发现被报告到其补丁进入 PR 审查门禁的耗时——数据来源于扫描历史与 PR 元数据。 **后置指标(Lagging indicator)** 定时扫描所发现的漏洞数量，与生产环境中或外部报告所发现的漏洞数量进行对比——数据来源于事件追踪系统；同时，经过多轮扫描的仓库中，每次扫描的发现数量趋势应随修复与评估用例的积累而逐步下降。 | 指标 | 含义 | 健康信号 | | ------------ | -------------------------- | ------------------------------------- | | **仓库覆盖率** | 按计划实际完成扫描的仓库占应扫描仓库的比例 | 趋近 100%，确保无盲区 | | **修复响应时间** | 从漏洞被发现到其补丁进入 PR 审查门禁的耗时 | 越短越好，反映自动化修复链路的效率 | | **漏洞发现来源对比** | 定时扫描发现 vs 生产环境/外部报告的漏洞数量对比 | 扫描发现量应高于生产/外部发现量，验证扫描的前置拦截能力 | | **扫描发现趋势** | 同一仓库多轮扫描中每轮发现的数量变化 | 应逐步下降——每轮修复都会为评估套件补充用例，使后续扫描能更快排除同类问题 | 这些指标用于观察扫描覆盖是否完整、修复是否及时、门禁是否有效，以及发现数量是否随修复持续下降。若多轮扫描后发现反而增加，应检查开发流程是否持续引入新漏洞。 ### Claude Tag 用 Claude 值班 事件可以通过 Slack、Teams 等办公即时通信工具触发，比如晚上 10 点在事件频道里的一条紧急修复消息，现在可以立即被响应。[Claude Tag](https://claude.com/product/tag)（目前 Slack 公开测试版）让 Claude 以独立身份加入这些频道，每个新事件都有第一响应人，而响应过程本身也纳入闭环，成为未来事件的记忆。 对话和知识沉淀在频道(Channel)里，任何频道成员都能引导和操作响应。 团队成员可以测试假设、探索新方案、实时调查，频道历史增强了可审计性。 通过 MCP 接入，Claude 能验证指标回到基线并在话题(thread，与飞书“话题”功能相似，参考[飞书-使用话题群](https://www.feishu.cn/hc/zh-CN/articles/360049067735-%E4%BD%BF%E7%94%A8%E8%AF%9D%E9%A2%98%E7%BE%A4))中确认，还将复盘总结写入版本控制的经验文件，供未来调查参考。 事件不是 Claude Tag 唯一能处理的工作。通过 MCP 被标记在工单上，或在频道中被询问，Claude 会以同样方式分诊。小范围、边界清晰的修复以 PR 形式走评审关卡；更大范围的工作则写成 `intent.md` 进入[01 规划Plan](https://guog.github.io/blog/the-ai-native-sdlc-playbook/#01-%E8%A7%84%E5%88%92-plan) ，由此循环自我驱动。 详情参见 [Claude on call: How Claude Tag serves as Anthropic’s first responder for CI/CD failures](https://claude.com/blog/ai-ci-cd-on-call)，了解 Anthropic 内部如何使用 Claude Tag 处理 CI/CD 相关的 紧急任务。 > 在 Anthropic 内部，这套系统的工作流程是：当 CI/CD 流水线出现故障（如大量测试失败），工程师只需在 Slack 值班频道 **@Claude** 并询问情况。Claude Tag 会立即作为“第一响应人”展开调查，利用其权限和工具访问权限分析问题。  该频道(channel)是审计追踪——请求、诊断、人工授权与修复操作，均保留在事件处理的原始上下文中。 ## 总结 模型和配套工具日益强大，不仅能改变编码方式，还能重塑整个软件开发生命周期(SDLC)。 这种转变始终将人的判断置于核心，并兼顾大型企业的治理与合规需求。 本指南整理了应用 AI 团队在客户实践中反复使用的方法，可作为团队落地时的参考。 > **持续循环，人类决断。** > > The loop keeps running. Human judgement stays above it. ## 参考资源 以下文档是平台团队搭建这些控制措施所需的材料，大致按落地顺序列出。 - [Set up Claude Code for your organization — the admin decision map; start here](https://code.claude.com/docs/en/admin-setup) - [Settings reference and precedence, including every managed-only key](https://code.claude.com/docs/en/settings) - [Server-managed settings from the Claude admin console](https://code.claude.com/docs/en/server-managed-settings) - [Permissions](https://code.claude.com/docs/en/permissions) - [Sandboxing — OS-level filesystem and network isolation](https://code.claude.com/docs/en/sandboxing) - [Hooks — guide](https://code.claude.com/docs/en/hooks-guide) - [Hooks — reference](https://code.claude.com/docs/en/hooks) - [Skills](https://code.claude.com/docs/en/skills) - [Plugins and private marketplaces — how skills and hooks are distributed organization-wide](https://code.claude.com/docs/en/plugin-marketplaces) - [Managed MCP — central control of the agent’s tool surface](https://code.claude.com/docs/en/managed-mcp) - [Enterprise deployment overview — Bedrock, Vertex, Foundry](https://code.claude.com/docs/en/third-party-integrations) - [Enterprise network configuration](https://code.claude.com/docs/en/network-config) - [Monitoring (OpenTelemetry)](https://code.claude.com/docs/en/monitoring-usage) - [The analytics dashboard](https://code.claude.com/docs/en/analytics) - [Compliance API — Enterprise activity feed, chat retrieval and deletion](https://platform.claude.com/docs/en/manage-claude/compliance-api) - [Security model](https://code.claude.com/docs/en/security) [HTML](https://guog.github.io/blog/the-ai-native-sdlc-playbook/) · [llms.txt](https://guog.github.io/llms.txt)