模板

如何使用这些模板

模板在中英两个版本中都以英文印出，这样同一份文件可以直接放进任何代码库。方括号表示占位符。复选框 [ ] 是一项断言，你必须能用审计者可以打开查看的东西来支撑它：一份日志、一项设置、一个配置文件。没有任何组织用实际结果验证过这些表格；每一节都注明了它出自哪一章、依据什么证据，方便你判断每一行能承受多大分量。对照正在运行的系统来填写，而不是对照设计文档：按照权限规则，设置实际允许什么，你就处在什么级别。下文引用的厂商指南均截至 2026 年 10 月。

自评表

在任何试点之前使用，之后每个季度再用一次。它是第 2 章《AI-SDLC 成熟度模型》中那张表的空白版，第 13 章《评估你的起点》会逐步讲解如何填写。每个阶段、每种任务类型各占一行，绝不按团队打分。真正起作用的是两列。“判据 / 谁能修改”一列对应判据原则：如果智能体能修改这项检查，这一行最多算 L2。“所持凭据”一列对应权限规则：只要凭据能触及的范围超出了评审那一列，就记录更高的那个级别。

SELF-ASSESSMENT GRID        Scored by: [name]   Date: [date]   Window: last [30/90] days

PHASE         TASK TYPE        LEVEL  EVIDENCE (link)        ORACLE / WHO CAN EDIT   RISK CEILING  CREDENTIALS HELD
------------  ---------------  -----  ---------------------  ----------------------  ------------  ----------------
Requirements
Design
Coding
Review
Testing
CI/CD
Operations
Maintenance

Checks before signing:
[ ] Every LEVEL cites evidence (approval log, attribution, routing config), not opinion
[ ] Every L3 row names an oracle the agent cannot edit; otherwise it is L2
[ ] Every row's CREDENTIALS HELD reaches no further than its LEVEL; otherwise
    record the higher level and fix the credential or the review first
[ ] No row exceeds its RISK CEILING; no irreversible task is scored L4
[ ] Coding is at most one level above the lower of Review and Testing
    (a heuristic, not a law)

智能体指令文件

在一个代码库第一次接手委派给智能体的工作时使用。它就是第 6 章《编码》推荐的那份由人手写的最小起步文件。那一章的证据好坏参半：自动生成或泛泛而谈的文件只消耗 token，不提高成功率；而由人写的简短、具体的文件能让运行更快、更省。各节内容沿用 Anthropic《Claude Code 最佳实践》中的“应当包含”清单：智能体猜不到的命令、不同于默认的代码风格规则、测试运行器、代码库礼仪、项目特有的架构决策、环境上的怪癖和容易踩的坑。它的删减检验写在文件头里。边界的三个层级来自 GitHub 对两千五百多份 agents.md 文件的梳理：“始终要做”（Always do）、“先问再做”（Ask first）和“绝不要做”（Never do）。文字只是建议。必须成立的规则要放进钩子或 CI 检查，编码一章的护栏解释了原因。本站在《AGENTS.md、CLAUDE.md、Cursor 规则与智能体技能对比》中比较了各种文件格式。

# AGENTS.md   (or CLAUDE.md, .github/copilot-instructions.md)
# Written and maintained by a person. Owner: [name]. Reviewed: [date].
# Test every line: would removing it cause the agent to make mistakes?
# If not, cut it. No file-by-file description of the codebase.
# Anything that MUST hold belongs in a hook, lint rule or CI check, not here.

## Commands the agent cannot guess
- Build:            [command]
- Run all tests:    [command]
- Run one test:     [command]
- Lint and format:  [command]

## Style that differs from the language default
- [rule]

## Testing
- Test runner and where tests live: [path]
- Done means: [check that must pass before the agent stops]

## Decisions that constrain everyday code
- [rule, one line]  (reason: ADR-[n])

## Repository etiquette
- Branch names: [pattern]
- PR description must include: [what changed, why, how it was verified]
- Attribution: [label or trailer], per the provenance policy

## Environment quirks and gotchas
- [quirk]

## Boundaries
Always do:  [run the tests before finishing]
Ask first:  [new dependency] [schema change] [public API change]
Never do:   edit tests, CI config, hooks or this file to make a check pass;
            downgrade a dependency to make a build pass;
            read or use production credentials;
            [repository-specific item]

规格模板

用于某个已命名、反复出现、又无法用一句话说清的任务类型。它就是第 5 章《需求、规格与设计》所要求的固定规格格式。中间几节沿用 Anthropic 对最有用的规格的描述：它们“写明涉及的文件和接口，说明哪些不在范围之内，并以一个能证明功能可用的端到端验证步骤收尾”。顶部的规模门槛是同一份指南对做计划的规定：“如果你能用一句话描述这个 diff，就跳过计划。”验收标准可以用 EARS 记法来写：“WHEN [condition/event] THE SYSTEM SHALL [expected behavior]”（Kiro 文档，截至 2026 年 10 月）。决定级别的是两行。批准那一行就是 L2 的证据。负责实现的智能体不得修改验收标准或验证步骤，这条规则就是判据原则在规格上的应用。本站的规格驱动的智能体开发实战手册介绍了相关工具。

SPEC: [feature name]                               ID: [spec-id]   Version: [n]
Task type: [named recurring type]
Size gate: can the diff be described in one sentence?  YES = no spec, stop here.
Drafted by: [person | agent + tool]       Owner: [person]
APPROVED BY: [name]   DATE: [date]        (no implementation before this line)

1. Problem and user
   [who needs what, and why now]

2. Acceptance criteria (testable; EARS optional)
   AC-1  WHEN [condition/event] THE SYSTEM SHALL [expected behaviour]
   AC-2  [...]

3. Files and interfaces involved
   [paths, APIs, schemas, events]

4. Decisions that apply (do not reopen)
   [ADR links]

5. Out of scope
   [what the agent must not build or change]

6. Questions raised while drafting, and their answers
   [all resolved before approval]

7. End-to-end verification step
   Proof the feature works: [command or test]
   Owned by: [person or team]   Agent may edit: NO (code owners / hook)

8. Changes after approval
   Any change to section 2 or 7 needs re-approval by: [name]

评审清单

L2 级别下，人对智能体编写或 AI 辅助的变更所做的每一次评审都用它；L3 路由仍然送到人手里的那些变更也用它。它汇集了第 7 章《代码评审》的护栏。职责分离来自 GitHub Copilot 云端智能体的默认设置：提出这项工作的人不能批准它（截至 2026 年 10 月）。之所以设一节“只能由人评审的设计”，是因为一个评审机器人如果像 Uber 说 uReview 那样“只能访问代码”，就评审不了设计。之所以设一节“判据”，是因为智能体会改动它够得着的东西：Elastic 发现，它的智能体在版本升级失败时，用删掉这次升级的办法来“修复”（Elastic Search Labs，2025 年 9 月，T3；另见《CI/CD 与发布》）。最后一节为回退触发条件表所监测的“没有用”（Not useful）比例提供数据。

REVIEW CHECKLIST - agent-authored or AI-assisted change
PR: [link]   Task type: [type]   Risk tier: [tier] (rule: [rule id])

Before reading the diff
[ ] Attributed: label, trailer or agent account
[ ] Neither the author, the requester nor the authoring agent is an approver
[ ] Within the size cap ([n] lines); otherwise send back to be split
[ ] Linked spec or issue; acceptance criteria unchanged since approval
[ ] Required checks ran and passed: build, tests, static analysis, secret scan

What only a person reviews
[ ] Fits recorded design decisions (ADRs); no new architecture slipped in
[ ] Data model, compatibility and migration effects
[ ] Security-relevant paths: authentication, PII, crypto, input handling
[ ] Matches the intent of the spec, not just its letter

The oracle and the agent's controls
[ ] No test deleted, skipped or weakened; no assertion loosened
[ ] No dependency downgraded or check disabled to make a build pass
[ ] Changes to tests, CI config, hooks, or permission/MCP/rules files
    are routed to their human code owners
[ ] New dependencies exist, are in the lockfile and on the allow-list

AI reviewer findings
[ ] Each finding fixed, or dismissed with a reason
[ ] Wrong or noisy findings marked "Not useful"

Decision:  [ ] approve   [ ] request changes   [ ] route to full review
Reviewer: [name]   Minutes spent: [n]

合并就绪包（证据包）

当某个任务类型从 L2 升到 L3、人不再逐行阅读时使用。人改读的就是这份包。名称和五项标准来自 Hassan 等人，他们把合并就绪包（Merge-Readiness Pack，2025 年 9 月）描述为“提交给人审批的结构化证据包”。它必须展示功能完整、验证可靠、软件工程规范堪称典范、理由清晰，以及完全可审计。它还应支持“渐进式披露”，也就是先给摘要，再往下一层给证据。那篇论文是一个概念性提议，并非经过测量的实践。各字段的内容取自第 7 章《代码评审》（跑了哪些检查、AI 评审者的发现及其处理结果、变更的风险类别及理由），以及第 11 章《维护与迁移》（核验器日志、diff 摘要、文件抽样）。本站关于决策回执与审计的文章讲了如何保存这份记录。

MERGE-READINESS PACK                      PR: [link]   Pack version: [n]
Task type: [type]   Risk class: [class]   Routed by rule: [rule id @ version]
Agent: [tool] [model + version]           Run log: [link]

0. SUMMARY (one screen; the reviewer starts here)
   What changed and why:          [3-5 lines]
   Approach and trade-offs:       [2-3 lines]
   Required checks:               ALL PASS / [failures]
   Oracle files touched by agent: NONE / [list = route to full review]

1. FUNCTIONAL COMPLETENESS
   Acceptance criteria from spec [id]:  AC-1 PASS  AC-2 PASS  [...]
   End-to-end verification:             [result + link]

2. SOUND VERIFICATION
   Verifiers run outside the agent's control: [list + log link]
   Tests added or changed: [list]   Tests removed or skipped: NONE / [list]
   Coverage or mutation-score change (if tracked): [value]

3. HYGIENE
   Static analysis, lint, secret scan, dependency check: [links]
   New dependencies: NONE / [list, each on the allow-list]

4. AI REVIEW
   Findings: [n]   Fixed: [n]   Dismissed with reason: [n]

5. AUDITABILITY (frozen links)
   Spec version | instruction-file commit | tool config | agent run log
   CI rounds: [n]   Retries: [n]

6. FLEET CHANGES ONLY
   Files in change: [n]   Files sampled by a person: [n] (chosen by [rule])

Human decision: [ ] approve  [ ] return   By: [name]   Date: [date]
Selected for audit sample: [ ] yes  [ ] no

来源标注政策

在 AI 辅助的工作进入共享代码库之前使用：没有归属标注，任何阶段都无法高于 L1。它出自第 15 章《向更多团队推广》，该章梳理了开源项目形成的三种治理阵营：禁止、推定有污染，以及允许但须披露。本模板采用第三种，参照的是 Linux 内核的 AI 编码助手指南（截至 2026 年 10 月，7.3.0-rc7 版文档）。该指南写明：“AI 智能体绝不能（MUST NOT）添加 Signed-off-by 标签。只有人类才能在法律上认证开发者原创证书（DCO）。”它要求提交补丁的人负责“审查所有 AI 生成的代码”、确保符合许可要求、加上自己的签署标签，并“为这份贡献承担全部责任”。它的标签格式是 Assisted-by: LLM [TOOL1] [TOOL2]，并说明“基础开发工具（git、gcc、make、编辑器）不应列出”。这个格式仍在变化：2026 年 10 月查阅时，linux-next 中同一页面已没有归属标注一节。有两部分是本书的提议，而非内核政策：在 trailer 中写明智能体和模型，以便按工具计算指标；以及一条规则，规定一份没有人亲手写过的 L3 变更由谁签字。许可现状在附录 B《监管与许可现状》中注明了日期。

PROVENANCE POLICY      Version: [n]   Owner: [name]   Effective: [date]

1. STANCE
   AI assistance is:  [ ] prohibited   [ ] allowed with disclosure
   Repositories covered: [list]    Excluded, with reason: [list]

2. DISCLOSURE
   Every commit made with AI assistance carries a trailer:
       Assisted-by: [agent]:[model-version] [TOOL1] [TOOL2]
   Do not list basic development tools (git, compiler, make, editor).
   Agent-authored pull requests also carry the label: [label]

3. SIGN-OFF AND APPROVAL ARE HUMAN-ONLY
   An agent never adds Signed-off-by, never approves a pull request,
   and never appears in CODEOWNERS.
   The human who signs off has reviewed the AI-generated code,
   checked licence compliance, and takes full responsibility.

4. WHO SIGNS A CHANGE NO HUMAN TYPED (L3 and above)
   The person who approves its Merge-Readiness Pack: [role]
   The person who started the agent run is accountable for its scope.

5. RECORDS
   Trailers, labels, agent run logs and approval logs kept for: [period]

6. REVIEW
   Next review of this policy: [date]
   Licensing and regulatory status checked against: [source, date]

权限边界检查清单

在授予某个级别之前使用；智能体的工具、令牌或运行环境一有变化，也要再用一次。它把第 12 章《安全、权限与爆炸半径》中权限边界的各行变成逐项检查。那份权限边界本身就是本书的提议，综合了厂商默认设置、事故后的修复措施以及 CSA 和 AWS 的控制框架；没有任何组织公布过按权限级别统计的事故率。勾选你所声称的级别对应的各行，外加“所有级别”各行。最后的结果一行，就是把权限规则写成了一道算式。

PERMISSION-ENVELOPE CHECKLIST
Agent/tool: [name]   Task class: [type]   Level claimed: [L2 / L3 / L4]
Checked against the running system by: [name]   Date: [date]

WHERE IT RUNS
 L2  [ ] Developer machine; permission prompts on; bypass and auto
         modes disabled in managed settings
 L3  [ ] Ephemeral sandbox, devbox or CI runner with filesystem AND
         network isolation
 L4  [ ] As L3, plus continuous monitoring and a kill switch
         (last tested: [date])

CREDENTIALS
     [ ] Inventory: every token the agent can reach, and what it reaches
 L2  [ ] No production credentials on the machine; secrets outside workspace
 L3  [ ] Short-lived, task-scoped, injected by a proxy, never in the sandbox
 L4  [ ] A narrow service identity for this class; no general cloud/API token

WRITE SCOPE
 L2  [ ] Workspace only; a human approves every commit
 L3  [ ] Own branch; cannot merge or approve; CI waits for human review
 L4  [ ] Auto-merges or acts only for the enumerated class, behind a
         verifier it cannot edit

NETWORK
 L2  [ ] Allow-list for package registries and documentation
 L3+ [ ] Default-deny egress plus an allow-list

IRREVERSIBLE ACTIONS
 L2  [ ] Never performed by the agent
 L3  [ ] Agent prepares the plan or migration; a human executes it
 L4  [ ] Only through APIs with undo or soft delete; backups outside the
         blast radius. If not, this class is NOT eligible for L4

UNTRUSTED INPUT (issues, web pages, tool and MCP output)
 L3  [ ] Agents Rule of Two: drops sensitive access OR external state change
 L4  [ ] Never untrusted input + sensitive access + state change together

ALL LEVELS
     [ ] Agent cannot write its permission, MCP or rules files; they sit
         under human code-owner review (sandbox-enforced at L3+)
     [ ] Lockfile and registry allow-list; unknown packages rejected
         (enforced in CI from L3)
     [ ] Gate - L2: human review + static analysis + secret scan
                L3: evidence bundle + human review of the PR
                L4: verification record per change + audit log + kill switch

RESULT
 Highest level that any row actually permits: [Ln]
 If above the level claimed, that IS the level. Fix before climbing.

试点计分卡

用于第 14 章《90 天试点》所规划的试点：一个阶段、一种任务类型、一个核验器、一条基线，以及在第一天之前就商定好的叫停规则。“准备就绪”一栏把环境放在模型前面。在 dotnet/runtime 中，团队修好智能体的运行环境之后创建的拉取请求成功率为 69%，此前为 38.1%（微软 .NET 团队，2026 年 3 月，T2；另见《案例研究》）。成功率沿用该团队的定义：已合并数除以已合并数与已关闭数之和。每一行流动指标下面都配一行稳定性指标。成本一行采用《经济性、风险与度量》中的单次合并变更成本模型，包含评审者的时间。之所以列出“不算成功标准”的项目，是因为一个以拉取请求数量来评判的试点，可能看起来很成功，而有效产出几乎没动（那个看起来很成功的试点）。阈值特意留空：在试点开始前根据你的基线填好。

90-DAY PILOT SCORECARD
Phase: [phase]   Task type: [one type]   Climb: L[n] to L[n+1]
Verifier (oracle): [check]   Who can edit it: [humans only - name the owners]
Owner: [name]   Start: [date]   Reviews: day 30 / day 60 / day 90
Baseline: [window before the pilot]   Comparison group: [same class, human-made]

READINESS (all ticked before day 1)
[ ] Agent runs in its real environment: builds, packages, network (tested [date])
[ ] Instruction file written by a person
[ ] Every agent change attributed
[ ] Permission-envelope checklist passed for the target level
[ ] Rollback-trigger sheet signed by: [name]

                                      Baseline  Day 30  Day 60  Day 90  Threshold
FLOW
 Success rate: merged/(merged+closed)
 Lead time to merge
 Review wait time
 Review active time
STABILITY (pairs with the flow lines)
 Reverts per merged change
 Escaped defects or incidents
 Rework: changed again within [n] days
 Human co-commit (rescue) share
COST
 Cost per merged change, incl. reviewer time
CONTEXT ONLY (never a success criterion)
 Engineers who used it at least once

NOT SUCCESS CRITERIA: self-reported speed-up; % of code written by AI;
pull-request count on its own.
Judge instruction-file, model or harness changes on several runs, never one.

DAY-90 DECISION:  [ ] climb   [ ] hold   [ ] roll back
Reason: [one paragraph]   Signed: [name]   Date: [date]

回退触发条件表

在试点之前写好，并在保持该级别期间一直保留。它属于第 17 章《衡量成效，以及何时回退》。还没有哪家公司公布过 AI 编码智能体的回退标准，所以这张表建立在其他领域的两个先例之上。Google 的 Tricorder 针对每个静态分析器，统计“请修复”（Please fix）与“没有用”（Not useful）两种点击之比：“如果某个分析器的这一比例超过 10%，Tricorder 团队就会停用该分析器，直到作者把它改进好”（Sadowski 等，CACM 2018，T2）。表中每一行都照搬这个结构：一个信号、一个事先定好的阈值、一个动作。Google 的 SRE 智能体补上了自动降级和停止控制：一个 L3 请求如果遇到“风险评分升高或生产状态异常”，就会降到 L2 并转给人处理；一个“红色按钮”可以“暂停所有正在执行的智能体操作”（Google SRE，未注明日期，2026 年 10 月查阅，T3；另见《运维与故障处理》）。NIST 的 AI RMF（NIST AI 100-1，MANAGE 2.4，2023 年 1 月）要求明确职责，并建立机制，用以“取代、脱离或停用那些表现或结果与预期用途不符的 AI 系统”；表中的负责人一行正是为此而设。Tricorder 的 10% 只是来自静态分析的起始值，并非针对 AI 验证过的数字。

ROLLBACK-TRIGGER SHEET            Signed before the pilot by: [name]  [date]
Phase / task type: [type]   Current level: L[n]   Falls back to: L[n-1]
Owner who acts on a trigger: [name]   Deputy: [name]
Stop control: [how every agent action is paused]   Last exercised: [date]

ID  SIGNAL                         THRESHOLD (fixed now)  WINDOW   ACTION
T1  "Not useful" rate on AI        above [10%] per        [2 wk]   disable that category
    review comments                category                        until fixed
T2  Reverts of agent changes       above baseline + [x]   [30 d]   back to 100% human review
T3  Escaped defect or incident     any of severity [n]    -        stop the class; level
    traced to an agent change      or worse                        down; postmortem
T4  Change failure rate (phase)    above baseline + [x]   [30 d]   level down
T5  Review wait time               above baseline x [n]   [2 wk]   throttle generation to
                                                                   review capacity
T6  Merges with no review          any rise               [1 wk]   freeze automatic routing
T7  Risk score or anomalous        automatic              live     request falls to L2;
    production state (ops)                                         page a human
T8  Envelope drift: a credential   any                    audit    revoke; re-score the row
    or setting above the level
T9  Cost per merged change         above [budget]         [1 mo]   cap usage; review the case

Re-climb only after: the fix ships, [n] clean days pass, the owner signs.
Log every firing: date | trigger | action taken | by whom | outcome