AI 扩展计划 / Playbooks
AI Architecture Decision Records Governance Playbook
本手册把 AI ADR 视为组织级决策知识系统, 用来保存 AI 系统为何这样设计、证据如何支持、风险由谁接受、以及哪些条件会推翻原决策。
853 行AI_ARCHITECTURE_DECISION_RECORDS_GOVERNANCE_PLAYBOOK.md
AI Architecture Decision Records Governance Playbook
配对阅读：本手册的原理/架构解读版是
docs/ai-foundations/papers/62-ai-architecture-decision-records-governance.md。先读 paper 建立机制与取舍，再用本手册落地为模板、RACI 与门禁，两者不需要重复精读。
版本: v1.0 日期: 2026-06-29
核心导读: 本手册把 AI ADR 视为组织级决策知识系统, 用来保存 AI 系统为何这样设计、证据如何支持、风险由谁接受、以及哪些条件会推翻原决策。
学习主线: 从决策识别、证据组织、架构取舍、风险接受、上线门禁到持续复审, 建立一条可追溯、可挑战、可反转的 AI 决策治理链。
使用边界: 本文是系统学习和内部治理训练材料, 不是法律意见、审计意见、采购结论或监管解释。正式项目必须由 Legal、Compliance、Risk、Model Risk、Privacy、Security、Data Owner 和业务负责人确认正式义务。
1. Source Anchors
这些来源作为 ADR、架构描述和 AI 风险治理的学习锚点。本文把它们转化为金融零售 AI 项目的决策治理方法, 不是法律意见、审计意见、采购结论或监管解释。
| Anchor | Link | 本手册采用的思想 | 落地到 AI ADR |
|---|---|---|---|
| Michael Nygard: Documenting Architecture Decisions | https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions | 用短小、可维护、按序编号的记录保存架构重要决策、背景和后果; 被替代的决策保留并标记为 superseded | AI ADR 不只写结论, 还记录 context、forces、status、consequences、replacement 和 future reviewer 需要理解的动机 |
| ADR GitHub Organization | https://adr.github.io/ | ADR 捕获单个 architectural decision 及其 rationale, ADR 集合构成 decision log, 属于 architectural knowledge management | 建立 AI decision log, 把模型、数据、eval、HITL、供应商、权限和风险接受决策作为架构知识管理 |
| ISO/IEC/IEEE 42010 / IEEE 1471 | https://www.iso-architecture.org/ieee-1471/ | 架构描述围绕 stakeholder、concern、view、viewpoint 组织; 一个架构不是单一图纸, 而是多视角描述 | 每个 AI ADR 必须说明受影响 stakeholder concern, 并链接到 C4、数据流、风险视图、流程视图、运行视图和证据视图 |
| NIST AI Risk Management Framework | https://www.nist.gov/itl/ai-risk-management-framework | 用 Govern、Map、Measure、Manage 组织 AI 风险识别、度量、处置和治理; 关注可信 AI 系统全生命周期 | AI ADR 需要把决策映射到 risk owner、control、eval evidence、monitoring threshold、review cadence 和 residual risk |
使用纪律:
- Anchor 用于建立共同语言, 不是把外部框架机械转成表格。
- AI ADR 的价值不在于“多写文档”, 而在于让未来团队知道当时为什么这样选、什么证据支持、什么条件会推翻。
- 金融零售项目必须由 Legal、Compliance、Risk、Model Risk、Privacy、Security、Data Owner 和业务负责人确认正式义务。
- 任何 ADR 都必须绑定系统版本、模型版本、知识库版本、prompt 版本、eval 版本或流程版本, 否则无法成为审计证据。
2. 核心导读与学习主线
系统定位:
AI ADR Governance 是把 AI 产品和架构中的关键选择转化为可追溯、可挑战、可复核、可反转的决策知识系统, 用来连接产品需求、架构评审、风险接受、上线门禁和持续运营。
学习主线不是套用 ADR 模板, 而是形成五个系统判断:
- 能识别哪些 AI 决策具有架构意义。
- 能把业务目标、质量属性、风险约束和模型行为放进同一个决策框架。
- 能要求团队用证据支持选择, 而不是用供应商宣讲、benchmark、个人偏好或 demo 效果做决定。
- 能在 PRD、Architecture Review、Eval Gate、Release Gate 和 Post-release Review 之间建立同一条决策链。
- 能把 AI 决策从个人记忆、会议口头共识或供应商话术, 转成组织可复核、可继承、可重开的架构知识。
系统边界:
- ADR 记录架构重要决策, 不替代正式法律、合规、采购、模型验证或审计结论。
- ADR 不记录所有实现细节, 只记录会影响系统边界、质量属性、风险、成本、客户影响、供应商依赖或未来演进路径的选择。
- ADR 的状态必须能随证据变化而变化: proposed、accepted、superseded、deprecated 和 reopened 都是治理状态, 不是文档标签。
证据输出:
| 输出对象 | 核心内容 | 治理价值 |
|---|---|---|
| Decision log | 关键 AI 决策、level、owner、status、gate、freshness | 让组织知道哪些选择正在塑造系统 |
| Full ADR | context、options、decision、tradeoffs、evidence、consequences、triggers | 保存选择背后的约束、证据和后果 |
| Traceability table | PRD / architecture / eval / control / release gate 的 ADR ID 连接 | 让需求、架构和上线证据同源 |
| Reopened ADR | 触发条件、新证据、旧决策局限、新决策影响 | 证明治理能随模型、法规、成本和事故演进 |
3. 为什么 AI ADR 是架构知识
传统 ADR 记录的通常是数据库、消息队列、部署方式、服务拆分、API 风格、云厂商、缓存策略等技术选择。AI 系统把“架构决策”的边界扩大了。
AI 项目里的关键架构知识包括:
- 模型如何被选择、替换、路由和降级。
- RAG、fine-tune、规则、workflow、agent、vendor API、自研模型之间如何取舍。
- 数据和知识如何进入系统, 谁拥有, 如何保留, 如何过期, 如何删除。
- Prompt、system instruction、tool schema、retrieval policy、guardrail policy 如何版本化。
- Eval 如何定义上线门槛, 谁接受残余风险, 失败样本如何进入修复循环。
- Agent 可以调用哪些工具, 能否写入生产系统, 是否需要 human approval。
- HITL 是真实控制点, 还是 UI 上的责任转移。
- 供应商条款、数据使用、区域、可用性、退出路径如何影响架构。
- 当模型质量、成本、延迟、法规、数据漂移、业务策略或供应商条件变化时, 决策如何被重新打开。
AI ADR 的核心价值是保留“选择背后的约束和证据”。没有 ADR, 团队只能记得“当时选了某模型”; 有 ADR, 团队能回答:
| 问题 | 没有 ADR 的风险 | 有 AI ADR 的治理价值 |
|---|---|---|
| 为什么用 RAG 而不是 fine-tune? | 后续团队重新争论, 或误把 RAG 当永久方案 | 保留知识更新频率、证据引用、权限过滤、成本和 eval 结果 |
| 为什么某场景必须 HITL? | 团队被质疑“太保守”, 或运营绕过复核 | 记录客户影响、法规敏感性、错误代价、人工责任和抽检证据 |
| 为什么允许 agent 调用退款工具? | 权限扩大后无人知道边界 | 记录 tool allowlist、审批条件、限额、日志、熔断和反转触发器 |
| 为什么接受某残余风险? | 事故后找不到批准人和到期日 | 记录 risk owner、business benefit、mitigation、expiry、review trigger |
| 为什么替换模型供应商? | 采购、工程、风险各自保存不同版本理由 | 记录供应商能力、合同边界、数据处理、迁移成本、退出条件和证据 |
3.1 决策链定位
PRD 说明要解决什么问题; 架构图说明系统如何构成; Eval 说明是否达到门槛; AI ADR 说明为什么在这些约束下选择这条路, 以及什么时候必须重新选择。
4. AI ADR Taxonomy
AI ADR taxonomy 的作用是帮助团队判断“哪些决策必须记录”。不是所有实现细节都需要 ADR, 但凡影响系统边界、质量属性、风险、成本、可审计性、供应商依赖、客户权益或未来演进路径的选择, 都应记录。
4.1 决策类别总览
| 类别代码 | 决策类别 | 典型问题 | 主要 Owner | 必备证据 |
|---|---|---|---|---|
| ADR-AI-001 | Use Case Scope Decision | AI 到底做 draft、retrieve、recommend、classify、decide 还是 act? 哪些环节禁止 AI? | Product Owner / Process Owner / Business Owner | PRD、流程图、客户影响评估、风险分级 |
| ADR-AI-002 | AI Pattern Decision | 用 RAG、fine-tune、agent、workflow、rules、traditional ML、vendor API 还是组合? | Architect / ML Lead / Product Owner | 方案矩阵、eval baseline、数据可用性、成本延迟估算 |
| ADR-AI-003 | Model Selection Decision | 选择哪个 foundation model、专用模型、自研模型或传统模型? | Architect / ML Lead / Procurement | benchmark、任务 eval、供应商评估、安全隐私评审 |
| ADR-AI-004 | RAG vs Fine-tune Decision | 需要外部知识 grounding、风格适配、领域术语还是任务能力迁移? | Architect / Data Owner / Product Owner | 知识库更新频率、golden set、检索评估、微调数据说明 |
| ADR-AI-005 | Model Routing Decision | 单模型、规则路由、成本路由、风险路由、多模型仲裁如何设计? | Platform Architect | routing policy、fallback plan、cost model、latency SLO、质量对比 |
| ADR-AI-006 | Data and Knowledge Source Decision | 哪些数据、文档、系统、索引可以被模型访问? | Data Owner / Knowledge Owner / Architect | data lineage、权限模型、数据分类、保留政策、DPIA |
| ADR-AI-007 | Data Retention and Logging Decision | prompt、completion、retrieval context、user action、embedding、eval sample 保存什么、多久、给谁看? | Privacy / Security / Platform Owner | retention matrix、日志字段字典、访问控制、合同条款 |
| ADR-AI-008 | Prompt and Versioning Decision | system prompt、developer prompt、tool schema、retrieval prompt、policy prompt 如何版本化和发布? | AI Platform / Product Owner / QA | prompt registry、diff、approval、regression eval、rollback record |
| ADR-AI-009 | Eval Gate Decision | 上线前必须通过哪些 quality、safety、security、business acceptance 和 operational metrics? | QA / Model Risk / Product Owner | eval plan、test set card、error analysis、UAT、risk sign-off |
| ADR-AI-010 | HITL Decision | 哪些输出必须人工确认、谁确认、确认什么、如何抽检? | Business Ops / Risk / Product Owner | workflow map、review SOP、sample audit、override metrics |
| ADR-AI-011 | Agent Permission Decision | Agent 能否 read/write/execute? 调用哪些工具? 限额、审批、熔断如何配置? | Architect / Security / Business Owner | tool allowlist、RBAC/ABAC、threat model、audit log、incident runbook |
| ADR-AI-012 | Guardrail and Policy Decision | 输入过滤、输出过滤、PII mask、policy enforcement、refusal、redaction 如何设计? | Security / Risk / Architect | control matrix、red-team report、policy test、false positive analysis |
| ADR-AI-013 | Vendor and Build-vs-Buy Decision | 采用哪个供应商、是否自建、如何退出、数据是否用于训练? | Procurement / Architect / Legal | due diligence、contract summary、SLA、exit plan、risk assessment |
| ADR-AI-014 | Risk Acceptance Decision | 哪些残余风险被接受, 谁接受, 到何时, 条件是什么? | Risk Owner / Business Owner | risk register、mitigation evidence、approval record、review trigger |
| ADR-AI-015 | Reversal and Retirement Decision | 哪些条件触发暂停、回滚、模型替换、知识库冻结或功能下线? | Product Owner / Architect / Ops / Risk | monitoring thresholds、incident criteria、rollback plan、postmortem |
4.2 决策重要性分级
不是每个 AI 决策都要进入 Architecture Board。建议按影响分级:
| Level | 范围 | 例子 | 审批方式 |
|---|---|---|---|
| L1 Local Design Decision | 局部实现, 不改变风险、架构边界或用户承诺 | 单个 prompt 文案优化、非关键日志字段命名 | Team review, 记录在变更说明 |
| L2 Product-Architecture Decision | 影响 PRD、用户流程、数据流、成本、质量属性或版本管理 | 客服 Copilot 增加 citation requirement, AML summary 改为必须人工确认 | AI ADR, Product + Architecture review |
| L3 Risk-Significant Decision | 影响客户权益、合规义务、敏感数据、供应商依赖、agent 写权限或 residual risk | 允许 agent 发起退款、使用第三方 LLM 处理 PII、放宽 eval gate | AI ADR, Risk / Security / Privacy / Legal review |
| L4 Enterprise Policy Decision | 影响多业务线、多地区、平台标准或企业风险偏好 | 企业统一模型路由策略、AI 数据保留标准、禁止某类自动化决策 | Architecture Board / AI Governance Committee |
4.3 AI 决策与需求类型映射
AI ADR 不应脱离需求。每个高影响 ADR 至少映射一种需求类型:
| 需求类型 | AI ADR 应回答的问题 | 示例 |
|---|---|---|
| Functional Requirement | 决策如何支持用户任务和业务流程? | “系统生成 dispute response draft, 不直接发送给客户。” |
| Non-functional Requirement | 决策如何影响延迟、可用性、可扩展性、可维护性、成本? | “高风险 case 走强模型, 低风险 FAQ 走低成本模型。” |
| Data Requirement | 决策需要哪些数据、知识、权限和血缘? | “RAG 只检索 approved policy source, 不检索个人 mailbox。” |
| Control Requirement | 决策如何满足安全、隐私、合规、审计和人工复核? | “所有 fee waiver recommendation 必须保留来源、规则和 reviewer decision。” |
| Eval Requirement | 决策如何被验证? | “引用准确率低于 97% 不进入 pilot。” |
| Operational Requirement | 决策如何被监控、升级、回滚和持续改进? | “知识库超过 30 天未刷新, 系统自动降级到 read-only answer draft。” |
5. ADR Lifecycle
AI ADR 是活的决策记录。它不是一次性审批单, 也不是项目结束后补写的总结。
5.1 生命周期状态
| 状态 | 含义 | 进入条件 | 退出条件 |
|---|---|---|---|
| Draft | 决策正在形成, 事实和证据还在补充 | 产品、流程、架构或风险团队识别出架构重要决策 | 形成可评审版本 |
| Proposed | 有明确推荐方案, 可进入评审 | 已写清 context、options、decision、consequences、evidence gap | 被接受、有条件接受或退回 |
| Accepted | 决策被批准并可实施 | 必要 stakeholder sign-off 完成, 关键风险和证据可接受 | 被替代、反转、过期或退休 |
| Conditionally Accepted | 可在限定范围内实施 | 允许 pilot 或 limited release, 但存在必须关闭的条件 | 条件关闭后转 Accepted, 或超期转 Reopen |
| Rejected | 决策不被采用 | 方案与需求、风险偏好、成本或架构方向不匹配 | 保留记录, 防止未来重复走同一死路 |
| Superseded | 决策被后续 ADR 替代 | 新 ADR 明确引用旧 ADR | 保留历史, 作为演进证据 |
| Reopened | 决策因触发条件被重新评审 | 模型、数据、法规、成本、事故、漂移、供应商条款或业务策略发生变化 | 重新 accepted、superseded 或 retired |
| Retired | 决策对应能力下线或不再适用 | 系统、模型、流程、供应商或业务线退役 | 保留归档和审计保留期 |
5.2 生命周期流程
Trigger
-> classify decision significance
-> draft ADR
-> collect evidence
-> review options and consequences
-> decide status
-> implement with traceability
-> monitor assumptions and triggers
-> reopen / supersede / retire
5.3 触发 ADR 的事件
| 触发事件 | 为什么需要 ADR |
|---|---|
| 新 AI use case 进入 discovery | 明确 AI 作用边界、风险等级、no-AI alternative 和价值假设 |
| PRD 加入模型输出、推荐、自动化操作或 agent 能力 | 模型行为开始影响用户旅程和控制点 |
| 架构评审选择 RAG、fine-tune、agent、workflow 或 vendor API | 方案取舍会影响数据、成本、风险、可审计性和维护模式 |
| 数据源、知识库、embedding、prompt 或 eval 发生重大变更 | 上下文变化可能让原决策不再成立 |
| 模型供应商、区域、合同、SLA 或数据使用条款变化 | 第三方风险和退出路径发生变化 |
| 生产监控发现质量、漂移、成本、延迟或安全异常 | 原 assumptions 需要被验证或推翻 |
| 事故、投诉、监管问询或审计发现 | 决策证据、残余风险和控制有效性需要复核 |
| 架构路线图要求能力扩展到新市场、新人群或新渠道 | 原 pilot 决策不能自动扩展到新范围 |
5.4 ADR 的 evidence freshness
AI ADR 的证据会过期。建议在 ADR 中记录证据新鲜度:
| 证据类型 | 默认有效期 | 过期风险 | 刷新方式 |
|---|---|---|---|
| Eval report | 90 天或每次重大变更 | 模型、数据、prompt 或用户行为变化导致指标失真 | 重新运行 golden set、回归集和高风险样本 |
| Threat model | 180 天或每次权限扩大 | 工具调用、数据源、入口变化引入新攻击面 | 安全复评和 red-team test |
| Vendor risk assessment | 年度或合同/服务变化时 | 数据处理、子处理方、区域和 SLA 变化 | TPRM 复核、合同更新、exit drill |
| Data lineage and retention | 每个数据版本 | 数据源字段、权限、保留期限或用途不一致 | 数据说明书和血缘图更新 |
| HITL sample audit | 月度或季度 | 人工复核只存在流程中, 实际不运行 | 抽样复核 reviewer decision、edit diff、override |
| Risk acceptance | 到期日或 trigger event | 残余风险被长期默认接受 | 风险 owner 重新批准或关闭 |
6. Governance Workflow
AI ADR Governance 的目标是让决策在正确层级被正确的人审查, 而不是把所有事情都送到委员会。
6.1 端到端工作流
1. Intake
产品和流程团队识别 AI use case、业务流程、用户、价值假设和风险信号。
2. Decision Trigger
架构、产品和风险团队判断是否存在 architecturally significant decision。
3. ADR Draft
记录 context、decision question、options、recommended decision、consequences、evidence links。
4. Evidence Pack
补齐 PRD、流程图、C4、数据流、eval plan、risk assessment、vendor review、control mapping。
5. Review Routing
按 L1-L4 分级路由到 team review、architecture review、risk review 或 governance committee。
6. Decision Meeting
讨论 options 和 trade-off, 明确 accepted / conditionally accepted / rejected / reopened。
7. Implementation Traceability
把 ADR ID 写入 PRD、architecture diagram、ticket、eval report、release checklist 和 runbook。
8. Monitoring and Reopen
通过 metrics、incident、drift、cost、regulatory change 和 vendor change 触发复审。
6.2 RACI
| 活动 | Product | Process Analysis | Architect | ML / Data | Risk / Compliance | Security / Privacy | Procurement / Legal | Business Owner |
|---|---|---|---|---|---|---|---|---|
| 识别决策触发点 | A | R | R | C | C | C | C | A |
| 写业务上下文和需求映射 | A | R | C | C | C | C | I | A |
| 写架构选项和后果 | C | C | A/R | R | C | C | C | I |
| 提供数据和 eval 证据 | C | C | C | A/R | C | C | I | I |
| 审查风险和控制 | C | C | C | C | A/R | R | C | C |
| 审查供应商和合同 | I | I | C | C | C | C | A/R | C |
| 接受残余风险 | C | C | C | C | R | C | C | A |
| 批准上线条件 | A | C | A/R | R | R | R | C | A |
| 定期复核和重开 | R | C | R | R | R | R | C | A |
RACI 使用原则:
- Business Owner 不能把风险接受外包给技术团队。
- Architect 不能只画系统图, 还要维护决策与质量属性、约束和 evidence 的一致性。
- 产品和流程分析职能不能只写用户故事, 还要把 ADR 反向嵌入需求、验收标准和发布门禁。
- Risk / Compliance 不应在上线前才介入; 高影响决策从 Proposed 状态就应可见。
6.3 Decision Board 分层
| Board | 处理什么 | 不处理什么 | 输出 |
|---|---|---|---|
| Product-Architecture Working Session | L2 决策, 例如 RAG 方案、引用要求、人工复核流程 | 企业政策、重大供应商风险 | ADR accepted / revised, PRD 更新要求 |
| AI Architecture Review Board | L2-L3 架构显著决策, 例如 model routing、agent tool permission、数据流 | 纯业务优先级争论 | ADR decision, architecture conditions |
| AI Risk and Control Forum | L3 风险显著决策, 例如敏感数据、自动化建议、risk acceptance | 低风险 prompt 调整 | control conditions, residual risk approval |
| Vendor and Data Governance Forum | 供应商、数据处理、跨境、保留、合同和退出 | UI 交互细节 | vendor approval, data constraints, retention decision |
| Enterprise AI Governance Committee | L4 企业级政策, 多业务线标准、风险偏好、禁止用途 | 单项目普通方案选择 | policy decision, enterprise ADR, standard update |
7. 与产品需求和架构评审的连接
AI ADR 如果只存在于 docs/adr 文件夹, 很快会变成没人看的历史材料。它必须嵌入需求、评审、交付和运营。
7.1 PRD 中的 ADR 连接点
| PRD 模块 | 必须链接的 ADR | 目的 |
|---|---|---|
| Problem Statement | Use case scope ADR | 确认 AI 介入点不是为了追逐技术, 而是服务明确业务痛点 |
| User Journey / BPMN | HITL ADR、agent permission ADR | 确认 AI 输出在哪一步被使用、谁确认、谁承担最终动作 |
| Functional Requirements | AI pattern ADR、model selection ADR | 确认功能设计与模型能力和限制一致 |
| Non-functional Requirements | model routing ADR、vendor ADR、eval gate ADR | 确认延迟、成本、可用性、可解释性、可审计性有架构支撑 |
| Data Requirements | data source ADR、retention ADR | 确认数据授权、权限、保留、脱敏和 source of truth |
| Acceptance Criteria | eval gate ADR、guardrail ADR | 确认验收标准不是“看起来不错”, 而是可测指标 |
| Launch Plan | risk acceptance ADR、reversal trigger ADR | 确认上线条件、限制范围、回滚和复审触发器 |
7.2 Architecture Review 中的 ADR 连接点
| 架构评审材料 | ADR 如何使用 |
|---|---|
| C4 Context Diagram | 引用 scope、vendor、system boundary 和 stakeholder concern ADR |
| Container Diagram | 引用 model routing、RAG pipeline、logging、guardrail 和 tool permission ADR |
| Data Flow Diagram | 引用 data source、PII handling、retention、prompt logging 和 embedding storage ADR |
| Sequence Diagram | 引用 HITL、approval workflow、fallback、timeout 和 rollback ADR |
| Threat Model | 引用 agent permission、prompt injection、data exfiltration 和 privilege escalation ADR |
| Eval Report | 引用 eval gate、golden set、red-team 和 business acceptance ADR |
| Runbook | 引用 reversal trigger、incident threshold、fallback 和 risk owner ADR |
7.3 Requirements-to-ADR-to-Eval Traceability
建议每个高影响 AI capability 保持以下链路:
Business Objective
-> Product Requirement
-> Architecturally Significant Requirement
-> AI ADR
-> Architecture View
-> Eval / Control Evidence
-> Release Gate
-> Monitoring Metric
-> Reopen Trigger
示例:
| Trace ID | 内容 |
|---|---|
| BO-01 | 将信用卡争议处理平均 case preparation time 降低 25% |
| PRD-FR-07 | AI 生成争议回复草稿, 包含交易事实、政策引用和证据链接 |
| ASR-03 | 输出必须可追溯到批准知识源, 不得直接发送客户消息 |
| ADR-012 | 采用 RAG + mandatory citation, 不采用 fine-tune-only |
| VIEW-DATA-04 | RAG 数据流图显示 approved policy source、case evidence、entitlement filter |
| EVAL-09 | citation accuracy >= 97%, unsupported claim rate <= 1% |
| G7-RELEASE | 只允许 pilot 队列, 所有回复由 analyst 审批 |
| MON-11 | 每周抽样 100 条 draft, 监控 unsupported claim 和 reviewer override |
| TRIGGER-04 | unsupported claim 连续两周超过 1% 时冻结 prompt 和知识库版本 |
8. Financial Retail Examples
以下案例不是模板填空, 而是训练如何把产品、架构、风险和证据放进同一个决策记录。
8.1 AML Copilot: RAG vs Fine-tune
| ADR 字段 | 内容 |
|---|---|
| Decision Question | AML 告警调查助手应采用 RAG、fine-tune 还是两者组合? |
| Context | AML policy、typology、case evidence 更新频繁; 输出必须引用来源; 错误 narrative 可能影响 SAR 质量和监管检查 |
| Options | A. Fine-tune only; B. RAG only; C. RAG + limited style fine-tune; D. Vendor AML Copilot |
| Decision | pilot 阶段采用 RAG only, 使用批准知识源和 case evidence, 输出必须带 citation; 不做 fine-tune, 避免把过期政策固化到模型权重 |
| Consequences | 可追溯性强, 知识更新快; 需要投入检索质量、权限过滤和 citation eval; 对写作风格改善有限 |
| Evidence Links | policy source inventory、RAG retrieval eval、citation accuracy report、AML analyst UAT、data flow diagram |
| Reversal Trigger | 如果 citation accuracy 稳定达标但 analyst edit distance 过高, 可重开 ADR 评估 style fine-tune 或 prompt pattern library |
8.2 Credit Policy Assistant: Human-in-the-loop
| ADR 字段 | 内容 |
|---|---|
| Decision Question | 信贷政策助手能否对申请给出通过或拒绝建议? |
| Context | 场景涉及客户权益、授信政策、潜在公平性风险和监管解释; 业务目标是提升 policy lookup 和 memo drafting 效率 |
| Options | A. AI 直接给 approve/decline recommendation; B. AI 只生成 policy evidence 和 missing document checklist; C. AI 生成建议但必须人工确认 |
| Decision | 选择 B。AI 不给 approve/decline recommendation, 只提供政策引用、缺失材料、风险因素摘要和 memo draft |
| Consequences | 降低自动化决策风险, 提高合规接受度; 对效率提升幅度较温和; 需要更强的 workflow design |
| Evidence Links | customer impact assessment、policy citation eval、fair lending risk review、reviewer workflow SOP |
| Reversal Trigger | 如果未来进入 recommendation 模式, 必须新开 ADR 并完成 fairness eval、model risk review 和 customer impact review |
8.3 Payment Dispute Assistant: Data Retention
| ADR 字段 | 内容 |
|---|---|
| Decision Question | 支付争议 AI 助手是否保存完整 prompt、completion 和 evidence context? |
| Context | 需要审计追溯和争议复盘, 但输入包含交易信息、客户身份、商户信息和案件备注 |
| Options | A. 保存完整 prompt 和 completion 7 年; B. 保存结构化摘要、引用 ID、模型版本和 reviewer action, 不保存完整敏感上下文; C. 只保存统计指标 |
| Decision | 选择 B。保存可复盘的结构化日志、source document ID、redacted output、model/prompt/index version、reviewer decision 和 hash; 完整敏感上下文回到 source system 追溯 |
| Consequences | 平衡审计和隐私; 调试成本高于完整日志; 需要日志字段字典、访问控制和复盘工具 |
| Evidence Links | retention matrix、privacy review、log schema、access control test、incident reconstruction drill |
| Reversal Trigger | 如果监管、诉讼保全或内部审计要求更长或更细粒度记录, 由 Privacy、Legal、Audit 和 Business Owner 共同重开 |
8.4 Retail Customer Service Agent: Agent Permission
| ADR 字段 | 内容 |
|---|---|
| Decision Question | 客服 AI agent 是否可以直接执行退款、积分补发和地址修改? |
| Context | 业务希望降低客服处理时间; 这些动作会影响资金、客户权益、欺诈风险和运营补救 |
| Options | A. Agent 直接执行全部动作; B. Agent 生成 action recommendation, 人工确认后执行; C. Agent 只读查询, 不触发动作 |
| Decision | 选择分层权限。低金额积分补发可在规则限额内自动执行; 退款和地址修改必须人工确认; 高风险账户全部 read-only |
| Consequences | 提升低风险场景效率; 权限模型更复杂; 需要 action limit、fraud signal、audit log 和 kill switch |
| Evidence Links | tool permission matrix、fraud control review、API write test、agent audit log、rollback runbook |
| Reversal Trigger | 自动积分补发异常率超过阈值、欺诈损失上升或权限绕过事件发生时立即冻结 write tool |
8.5 Model Routing for Omnichannel Retail
| ADR 字段 | 内容 |
|---|---|
| Decision Question | 全渠道营销内容生成应采用单一高能力模型还是多模型路由? |
| Context | 渠道包括 app push、email、客服脚本和门店话术; 任务风险、成本、延迟和品牌要求差异明显 |
| Options | A. 全部走高能力模型; B. 按渠道、风险和语言路由; C. 全部走低成本模型并人工抽检 |
| Decision | 选择 B。高风险金融产品文案走强模型和严格审批; 普通运营文案走低成本模型; 敏感客群和合规词汇触发人工复核 |
| Consequences | 成本可控, 风险分层; 需要路由策略、版本管理和跨模型一致性 eval |
| Evidence Links | channel risk matrix、cost forecast、brand compliance eval、model comparison report |
| Reversal Trigger | 合规拒稿率、品牌偏差、客户投诉或单位内容成本超过阈值时重开 routing ADR |
8.6 Vendor Choice for Enterprise RAG Platform
| ADR 字段 | 内容 |
|---|---|
| Decision Question | 企业知识助手平台采用云厂商 managed RAG、AI 平台供应商, 还是自建 retrieval layer? |
| Context | 覆盖客服、运营、合规、HR 和内控知识库; 需要权限过滤、审计、数据驻留和多模型接入 |
| Options | A. 云厂商 managed RAG; B. 垂直 AI 平台; C. 自建 retrieval + model gateway; D. 混合 |
| Decision | 选择 D。短期使用云厂商 managed capability 支撑低风险 pilot; 同时建设自有 entitlement-aware retrieval layer 和 model gateway, 避免长期锁定 |
| Consequences | 上线快且保留战略控制; 复杂度高; 需要清晰的退出计划和平台路线图 |
| Evidence Links | vendor due diligence、security review、data residency check、exit plan、platform roadmap |
| Reversal Trigger | 供应商数据条款变化、成本不可控、权限过滤无法满足或多业务线扩展受限时迁移到自建层 |
9. Templates
模板的目标是让决策可复核, 不是让文档变长。每个模板都应根据风险级别裁剪, 但高影响 AI 决策不能省略 context、options、consequences、evidence、owner、trigger。
9.1 AI ADR Master Template
| Section | Required Content | Quality Bar |
|---|---|---|
| Title | ADR ID and decision title, written as a real decision such as ADR-0012: Use retrieval-backed generation for AML Copilot policy answers | The title reveals the choice, not only the topic |
| Metadata | Status, date, decision level, system/capability, PRD IDs, architecture views, evidence pack, owner, approvers, review cadence | Metadata is enough to route review and reconstruct scope |
| Context | Business process, user workflow, architecture boundary, stakeholder concerns, quality attributes, risk constraints, data constraints, vendor constraints, operational constraints | A reviewer can understand why the decision matters without attending prior meetings |
| Decision Question | A question with multiple credible answers, such as “Should AML Copilot use RAG, fine-tune or vendor workflow?” | The question is not biased toward the preferred answer |
| Options Considered | At least two credible options with benefit, risk, cost and evidence | Rejected options are treated seriously, not as strawman alternatives |
| Decision | Selected decision, allowed scope, forbidden scope, version, environment, user group, region and rollout stage | The decision is actionable and bounded |
| Rationale | Why this option wins under current constraints, including trade-offs and assumptions | The rationale explains why the answer could change later |
| Consequences | Positive consequences, negative consequences and neutral follow-up controls | Costs and operational burden are explicit |
| Evidence Links | Evidence name, version/date, owner, what it proves, freshness rule | Evidence can be opened and checked by reviewers |
| Risk and Control Mapping | Risk, control, owner, residual risk, acceptance or mitigation | Residual risk has accountable ownership |
| Reversal Triggers | Trigger, detection source, required action, owner, timeframe | The team knows when the decision stops being valid |
| Related ADRs | Superseded decisions, dependencies, conflicts and successor decisions | Decision history is preserved |
| Review Notes | Conditions, dissenting views, approval decisions and expiration | Governance decisions do not disappear into meeting memory |
9.2 AI Pattern Decision Matrix
| Criteria | RAG | Fine-tune | Agent Workflow | Rules / Deterministic Workflow | Vendor Product |
|---|---|---|---|---|---|
| Knowledge changes frequently | Strong | Weak to medium | Strong if retrieval-backed | Strong for explicit rules | Depends on vendor update model |
| Need citation and evidence | Strong | Weak unless combined with retrieval | Strong if tool and retrieval logs are retained | Strong | Depends on transparency |
| Need task style adaptation | Medium | Strong | Medium | Weak | Medium |
| Sensitive data constraints | Medium, depends on retrieval and logging | Higher training data burden | Higher tool and trace burden | Lower | Depends on contract |
| Operational complexity | Medium | Medium to high | High | Low to medium | Medium |
| Auditability | Strong with source IDs and logs | Medium, harder to explain memorized behavior | Strong if traces are complete | Strong | Depends on export and logs |
| Reversal ease | Medium | Lower if training pipeline becomes embedded | Medium if tools are modular | High | Lower if locked in |
| Best fit | Policy Q&A, evidence summary, knowledge assistant | Style, format, domain language, task specialization | Multi-step task execution with controls | Eligibility, fee, limit, deterministic decisions | Commodity capability or fast pilot |
Decision rule:
If the business needs current evidence, citation, permission filtering and source traceability, start with RAG or retrieval-backed workflow.
If the business needs consistent task behavior and has stable, approved training data, consider fine-tune as a scoped optimization.
If the system writes to downstream systems, treat it as an agent permission decision, not just a model decision.
9.3 Model Selection ADR Template
| Field | Content Guidance |
|---|---|
| Task Boundary | Specify exact tasks: summarize, classify, extract, draft, recommend, execute |
| Candidate Models | List model name, version, hosting region, vendor, modality, context window, deployment mode |
| Evaluation Dataset | Include source, time window, sample strategy, risk scenarios, protected or sensitive segments if applicable |
| Metrics | Include quality, groundedness, refusal, robustness, latency, cost, safety, policy compliance |
| Constraints | Include data residency, no-training terms, logging, availability, rate limits, model lifecycle |
| Decision | Select model and fallback model, with allowed task scope |
| Risk Acceptance | Identify residual risks and owner |
| Reversal Trigger | Include quality drift, cost, SLA, vendor term change, incident, better alternative threshold |
9.4 Data Retention ADR Template
| Data Object | Save? | Content | Retention | Access Role | Purpose | Deletion / Legal Hold |
|---|---|---|---|---|---|---|
| User input | Yes / partial / no | raw / redacted / hash / summary | duration | roles | audit / debugging / eval / incident | rule |
| Retrieved context | Yes / partial / no | doc ID / chunk / quote / embedding ref | duration | roles | citation / reconstruction | rule |
| Model output | Yes / partial / no | raw / redacted / approved version | duration | roles | QA / audit / user history | rule |
| Tool call | Yes | tool, args summary, result, status | duration | roles | non-repudiation / incident | rule |
| Human decision | Yes | approval, edit diff, override reason | duration | roles | HITL evidence | rule |
| Eval sample | Yes / partial | input, expected output, actual output, label | duration | roles | regression / model risk | rule |
9.5 Risk Acceptance ADR Template
| Section | Required Content | Quality Bar |
|---|---|---|
| Title | Specific risk acceptance decision, such as ADR-0021: Accept limited unsupported-claim risk for Payment Dispute Assistant pilot | The title states the risk and scope |
| Status and Expiry | Usually Conditionally Accepted, with effective date, expiry date and review cadence | Temporary acceptance cannot become permanent by silence |
| Risk Owner | Named accountable business owner, plus Risk, Compliance, Security, Privacy and Model Risk reviewers where relevant | Technology owner is not the sole risk acceptor |
| Risk Statement | Residual risk in business language, including customer, financial, regulatory, operational and reputational impact | The risk can be understood by business and control functions |
| Business Justification | Benefit, urgency, pilot scope and why acceptance is reasonable under constraints | Benefit is measurable, not aspirational |
| Controls Already Implemented | Controls and evidence that reduce the risk, such as HITL, sampling, guardrails, logging and rollback | Each control links to evidence |
| Conditions | Rollout scope, volume cap, user group, manual review, monitoring threshold and reporting cadence | Conditions are operationally enforceable |
| Stop / Reopen Criteria | Measurable triggers that pause the capability or reopen the decision | Triggers are tied to dashboards, incidents or control tests |
| Approval | Who accepts the risk, for which scope, until when, and under which conditions | Approval is explicit and auditable |
9.6 Reversal Trigger Catalogue
| Trigger Type | Example | Action |
|---|---|---|
| Quality Trigger | Citation accuracy below threshold for two consecutive review cycles | Freeze release, revert prompt/index/model version, reopen eval gate ADR |
| Safety Trigger | Red-team finds prompt injection leading to unauthorized data disclosure | Disable affected path, update guardrail, reopen security ADR |
| Cost Trigger | Unit cost exceeds forecast by 30% for two billing cycles | Review model routing, caching, batching and scope |
| Latency Trigger | P95 latency breaches workflow SLO and causes user abandonment | Revisit model choice, retrieval depth and async workflow |
| Data Trigger | Source policy documents become stale or owner cannot attest freshness | Disable source, rerun retrieval eval, notify knowledge owner |
| Vendor Trigger | Vendor changes data use, region, retention, SLA or subprocessor terms | Trigger TPRM review and exit plan evaluation |
| Regulatory Trigger | New regulation, supervisory expectation or internal policy affects AI use | Reclassify risk tier and reopen scope/control ADR |
| Incident Trigger | Customer harm, complaint spike, erroneous action or audit issue | Start incident runbook, preserve evidence, reopen relevant ADRs |
| Adoption Trigger | Users override AI output above expected threshold | Revisit workflow, training, prompt, model or product fit |
10. Review Gates
Review gates 把 ADR 从“写了”变成“能治理”。每个 gate 不要求所有决策都完成, 但要求关键决策的状态、证据和缺口透明。
10.1 Gate 总览
| Gate | 主要问题 | 必备 ADR | Decision Outcome |
|---|---|---|---|
| G0 Intake Gate | 这个 AI idea 是否值得 discovery? | Use case scope ADR draft | accept discovery / park / reject |
| G1 Product Requirement Gate | 需求是否清楚, AI 边界是否明确? | scope、HITL、data source ADR proposed | continue / refine / stop |
| G2 Architecture Pattern Gate | 架构模式是否匹配业务和风险? | AI pattern、RAG vs fine-tune、model selection ADR proposed | architecture direction |
| G3 Data and Vendor Gate | 数据、知识、供应商、保留和权限是否可接受? | data source、retention、vendor ADR proposed or accepted | ready / conditional / blocked |
| G4 Eval and Control Gate | 上线门槛、控制和风险接受是否足够? | eval gate、guardrail、risk acceptance ADR accepted | approve pilot / revise |
| G5 Release Gate | 是否可以生产发布或 limited release? | reversal trigger、HITL、logging、runbook ADR accepted | release / limited release / no-go |
| G6 Scale Gate | 是否可以扩展到更多流程、用户、地区或渠道? | model routing、risk acceptance refresh、vendor capacity ADR reviewed | scale / hold / redesign |
| G7 Quarterly Decision Review | 原决策是否仍然成立? | reopened / superseded / retired ADR list | continue / reopen / retire |
10.2 Gate Questions
| Gate | 评审问题 |
|---|---|
| G0 | AI 介入点是什么? 哪些地方明确不用 AI? 是否有 no-AI alternative? |
| G1 | PRD 是否列出 AI 输出如何被用户使用? 哪些客户或业务后果受影响? |
| G2 | 模型、RAG、agent、rules 或 vendor 的取舍是否有证据? 是否只因 demo 好看而决策? |
| G3 | 数据是否有 source of truth、owner、权限过滤、保留策略和日志策略? 供应商是否有退出方案? |
| G4 | Eval 是否覆盖真实失败模式? 门槛是否与风险等级匹配? 残余风险由谁接受? |
| G5 | 回滚、冻结、降级、人工接管和客户补救是否能执行? 证据是否能被审计复盘? |
| G6 | pilot 的 ADR 是否适用于 scale 范围? 新地区、新人群、新渠道是否改变 stakeholder concern? |
| G7 | 哪些 assumption 已失效? 哪些 trigger 被触发? 哪些 ADR 应 supersede 或 retire? |
10.3 Gate Evidence Checklist
| Evidence | G0 | G1 | G2 | G3 | G4 | G5 | G6 |
|---|---|---|---|---|---|---|---|
| AI opportunity brief | Required | Required | Reference | Reference | Reference | Reference | Reference |
| PRD and requirement IDs | Draft | Required | Required | Required | Required | Required | Required |
| BPMN / workflow map | Draft | Required | Required | Required | Required | Required | Refresh |
| C4 / system boundary | Reference | Draft | Required | Required | Required | Required | Refresh |
| Data flow / lineage | Reference | Draft | Draft | Required | Required | Required | Refresh |
| Decision matrix | Reference | Reference | Required | Required | Required | Reference | Refresh |
| Eval plan and report | Not needed | Draft | Draft | Draft | Required | Required | Required |
| Risk and control mapping | Initial | Draft | Draft | Required | Required | Required | Refresh |
| Vendor review | If relevant | If relevant | Draft | Required | Required | Required | Refresh |
| Reversal triggers | Initial | Draft | Draft | Draft | Required | Required | Required |
11. Operating Model
11.1 ADR Repository Structure
一个成熟团队可以采用如下结构:
docs/
adr/
ai/
0001-scope-aml-copilot.md
0002-rag-for-aml-copilot.md
0003-aml-copilot-data-retention.md
0004-aml-copilot-hitl-boundary.md
0005-aml-copilot-risk-acceptance-pilot.md
platform/
0001-enterprise-model-gateway.md
0002-model-routing-policy.md
0003-prompt-versioning-standard.md
命名建议:
- 编号单调递增, 不复用。
- 标题写决策, 不写会议主题。
- 被替代的 ADR 保留, 标记
Superseded by ADR-xxxx。 - ADR ID 要进入 PRD、Jira issue、release checklist、eval report 和 incident record。
11.2 ADR Metadata
建议每份 ADR 具备结构化 metadata:
| 字段 | 为什么重要 |
|---|---|
| ADR ID | 支撑引用和审计追踪 |
| Status | 区分草案、已接受、有条件接受、已替代和已退休 |
| Decision Level | 决定评审深度和审批层级 |
| System / Capability | 连接资产台账和系统卡 |
| Model / Prompt / Index Version | 让决策和 AI 行为版本绑定 |
| Requirement IDs | 连接 PRD 和验收 |
| Evidence Links | 连接 eval、风险、数据、供应商和控制证据 |
| Risk Owner | 确认谁接受残余风险 |
| Reversal Triggers | 防止决策永久化 |
| Review Cadence | 支撑持续治理 |
11.3 Metrics
AI ADR Governance 本身也需要度量:
| Metric | 含义 | 目标行为 |
|---|---|---|
| ADR Coverage Rate | 高影响 AI use case 中有关键 ADR 的比例 | 防止影子决策 |
| Evidence Link Completeness | ADR 中证据链接字段完整率 | 防止空泛论证 |
| Decision Lead Time | 从 Proposed 到 Accepted 的时间 | 发现治理瓶颈 |
| Reopened ADR Rate | 被重新打开的 ADR 比例 | 衡量持续学习, 不是越低越好 |
| Superseded with Rationale Rate | 被替代 ADR 中有明确替代理由的比例 | 保留决策演进 |
| Risk Acceptance Expiry Breach | 风险接受超期未复核数量 | 防止临时例外永久化 |
| Incident-to-ADR Trace Rate | AI 事故能追溯到相关 ADR 的比例 | 提升复盘质量 |
11.4 Anti-patterns
| Anti-pattern | 表现 | 修正方式 |
|---|---|---|
| Decision by Demo | 看到 demo 好就定方案 | 要求 task-specific eval、risk review 和 option matrix |
| Model Brand Bias | 因模型名气、榜单或供应商关系做决策 | 用业务任务、数据约束、SLO、风险和合同条件评估 |
| Hidden Risk Acceptance | 风险被默认接受, 没有 owner | 写 Risk Acceptance ADR, 设置 expiry 和 trigger |
| HITL Theater | 页面上有人类确认, 实际无抽检、无权责、无日志 | 定义 reviewer action、sampling、override 和 accountability |
| Prompt Drift | prompt 被频繁改动, 无版本、无回归测试 | 建立 prompt ADR、registry、diff 和 eval gate |
| Retrieval Without Ownership | 知识库无人维护, 文档过期仍被引用 | 每个 source 绑定 owner、freshness 和 disable rule |
| Agent Permission Creep | 工具权限一点点扩大, 没有重新评审 | 每次 write capability 或 limit change 触发 permission ADR |
| Supersede Without Memory | 新方案替换旧方案但删除旧记录 | 保留旧 ADR, 标记 superseded 和 replacement rationale |
12. 30-Day Training Plan
目标: 用 30 天训练把 AI ADR 从“会写模板”提升到“能主持决策治理”。节奏强调原理、证据、架构取舍、风险边界和持续复审。
| Day | 训练主题 | 实操任务 | 产出 |
|---|---|---|---|
| 1 | ADR 作为 Architecture Knowledge | 阅读 ADR anchor, 总结 context / decision / consequence 的作用 | 1 页 ADR 原理卡 |
| 2 | IEEE 1471 / 42010 视角 | 为一个 AI 客服系统列 stakeholder、concern、viewpoint | Stakeholder-concern map |
| 3 | NIST AI RMF 视角 | 把一个 AI use case 映射到 Govern / Map / Measure / Manage | AI risk function map |
| 4 | AI 决策识别 | 从一个 PRD 中找出 10 个潜在 ADR | Decision trigger list |
| 5 | Decision Leveling | 对 10 个决策做 L1-L4 分级 | Decision routing table |
| 6 | Use Case Scope ADR | 写“AI 做什么/不做什么”的 ADR | Scope ADR |
| 7 | Product Requirement Linkage | 把 ADR ID 嵌入 PRD acceptance criteria | PRD-to-ADR trace table |
| 8 | RAG vs Fine-tune | 为 Credit Policy Assistant 做方案矩阵 | Pattern decision ADR |
| 9 | Model Selection | 设计模型选择 eval 指标和供应商比较 | Model selection ADR |
| 10 | Data Source Decision | 为 AML Copilot 画数据源和权限边界 | Data source ADR |
| 11 | Data Retention | 设计 prompt、completion、retrieval、tool call 日志保留策略 | Retention ADR |
| 12 | Prompt Versioning | 设计 prompt registry、diff、approval、rollback | Prompt/versioning ADR |
| 13 | Eval Gate | 把业务验收转成 groundedness、citation、safety、latency 指标 | Eval gate ADR |
| 14 | HITL Boundary | 设计人工复核节点、职责、抽检和 override 指标 | HITL ADR |
| 15 | Agent Permission | 为客服 agent 设计 read/write 权限和工具限额 | Agent permission ADR |
| 16 | Vendor Decision | 比较 managed RAG、vendor platform、自建 model gateway | Vendor ADR |
| 17 | Risk Acceptance | 写一个 limited pilot residual risk acceptance | Risk acceptance ADR |
| 18 | Reversal Triggers | 为模型漂移、成本、供应商、事故定义触发器 | Trigger catalogue |
| 19 | Evidence Links | 为一个 ADR 补齐 evidence owner、version、freshness rule | Evidence matrix |
| 20 | Architecture Review | 用 C4 + data flow + ADR 讲解一个 AI 系统 | Architecture review pack |
| 21 | Security Review | 把 prompt injection、tool abuse、data exfiltration 写入 ADR | Security-linked ADR |
| 22 | Privacy Review | 评估 PII、日志、retention、cross-border 和 deletion | Privacy-linked ADR |
| 23 | Model Risk Review | 评估模型用途、限制、监控和独立验证 | Model risk review brief |
| 24 | Operations Review | 设计 monitoring、incident、rollback、freeze 和 kill switch | Ops runbook linkage |
| 25 | Quarterly Review Simulation | 假设一个 ADR trigger 被触发, 主持 reopen review | Reopened ADR |
| 26 | Superseding Exercise | 用新模型替代旧模型, 保留旧决策理由 | Superseded ADR pair |
| 27 | Decision Narrative Drill | 准备 5 个 AI ADR 治理决策叙事 | Decision narrative set |
| 28 | Decision Governance Case | 设计一个金融零售 AI ADR 系统案例 | Decision case outline |
| 29 | Review with Peers | 让架构、风险、业务运营三种视角挑战你的 ADR | Review notes |
| 30 | Final Evidence Package | 整理 PRD、ADR、架构图、eval、risk acceptance、release gate | AI ADR governance evidence pack |
30 天结束后应具备的能力:
- 看到 AI PRD 能识别架构重要决策。
- 能写出不空泛的 AI ADR。
- 能把 ADR 与需求、架构图、eval、风险和上线门禁串起来。
- 能主持跨产品、流程、架构、风险、安全、数据、供应商的决策评审。
- 能解释某个 AI 决策在什么条件下必须被反转。
13. Decision Narrative
13.1 AI ADR 的扩展边界
Decision Narrative:
AI ADR 仍然记录架构重要决策、背景和后果, 但它的决策对象从技术组件扩展到了模型、数据、prompt、eval、HITL、agent 权限、供应商和风险接受。传统 ADR 更关注系统结构和质量属性; AI ADR 还必须说明模型行为如何被验证、证据如何保留、残余风险谁接受、什么条件触发重开。
System Evidence:
AI ADR 应被看作架构知识管理和 AI 风险治理的交汇点。比如一个信用政策助手选择 RAG 而不是 fine-tune, 这不是单纯技术选择, 而是涉及政策更新频率、引用可追溯、权限过滤、审计复盘、模型幻觉和运营维护的综合决策。AI ADR 要记录 context、options、decision、consequences, 还要链接 PRD、C4 图、数据流、eval report、risk assessment、HITL SOP、vendor review 和 reversal trigger。这样未来模型换代、法规变化、事故发生或扩展到新市场时, 团队可以知道原决策为什么成立, 现在是否仍然成立。
13.2 ADR 触发条件
Decision Narrative:
凡是影响架构边界、数据流、模型行为、客户权益、风险控制、供应商依赖、成本延迟、审计追溯或未来演进的 AI 决策, 都应写 ADR。低风险 prompt 微调可以走普通变更记录, 但 RAG vs fine-tune、模型选择、数据保留、HITL、agent 写权限、供应商选择和风险接受必须写。
System Evidence:
判断时可使用三个问题。第一, 这个选择是否有多个合理选项, 且取舍会影响未来路径? 第二, 它是否影响客户、合规、安全、隐私、模型风险或运营责任? 第三, 事故或审计发生时, 团队是否需要解释当时为什么这样做? 如果答案是肯定的, 就进入 ADR。比如客服 agent 是否能自动退款, 这不仅是功能问题, 还影响权限、欺诈、资金损失、日志、人工确认和熔断, 必须作为 L3 风险显著 ADR 评审。
13.3 PRD 到 ADR 的连接
Decision Narrative:
PRD 应在问题定义、用户旅程、功能需求、数据需求、验收标准和上线计划中引用 ADR ID。PRD 说明“要什么”, ADR 说明“为什么这样设计”, eval 说明“是否达标”, release gate 说明“是否可以上线”。
System Evidence:
例如支付争议助手的 PRD 中有“生成客户回复草稿”。这个需求应拆成功能需求、数据需求、控制需求和 eval 需求: 输出必须引用交易证据和政策来源, 不得直接发送给客户, 所有回复由 analyst 审批, unsupported claim rate 要低于阈值。对应 ADR 包括 RAG decision、data retention decision、HITL decision 和 eval gate decision。这样需求不是孤立 user story, 而是被架构和治理支撑的产品承诺。
13.4 RAG 与 Fine-tune 的权衡记录
Decision Narrative:
不要把它写成“RAG 更好”或“fine-tune 更强”。应先写业务任务、知识更新频率、证据引用、权限过滤、数据可用性、eval 指标和运营成本, 再比较选项。需要当前知识和可追溯引用时, RAG 通常优先; 需要稳定风格或任务适配且有批准训练数据时, fine-tune 才是候选。
System Evidence:
以 AML Copilot 为例, 政策、typology 和 case evidence 都会变化, 输出还需要 citation, 所以 pilot 阶段通常倾向 RAG。ADR 会记录 fine-tune only、RAG only、RAG + limited fine-tune、vendor product 四个选项, 比较引用准确率、权限过滤、知识更新、审计、成本和维护复杂度。决策不是永久的。ADR 还要写 reversal trigger: 如果 RAG 引用准确率达标但 analyst edit distance 很高, 可以重开评估 style fine-tune。
13.5 Human-in-the-loop 作为架构控制点
Decision Narrative:
因为 HITL 经常被误用成一句“有人审核”。真正的 HITL 是架构和运营控制点, 必须定义谁审核、审核什么、何时必须审核、如何记录、如何抽检、override 如何分析、AI 不能做什么。
System Evidence:
在信贷、AML、支付争议和客服补偿中, HITL 决定了 AI 输出是否会影响客户权益和监管结果。比如信用政策助手不应直接给 approve/decline recommendation, 而是提供政策引用、缺失材料和 memo draft。这个决策必须写 ADR, 因为它影响产品体验、运营效率、风险控制和审计证据。ADR 里要写人工复核节点、角色、日志、抽检、override 指标、培训和触发重评的条件。
13.6 风险接受的记录边界
Decision Narrative:
风险接受不能藏在会议纪要里。它应是一个明确 ADR 或 ADR section, 写清风险是什么、业务收益是什么、控制已经做了什么、残余风险谁接受、适用范围到哪里、什么时候过期、什么条件触发停止或重开。
System Evidence:
比如一个客服 AI pilot 允许低金额积分自动补发。即使有规则限额和日志, 仍有误补、欺诈和客户公平性风险。Risk Acceptance ADR 要写清 pilot 人群、金额上限、欺诈信号、每日监控、异常冻结、客户补救和到期复核。Business Owner 必须接受残余风险, Risk、Security、Compliance 提供评审意见。这样事故发生时, 组织知道当时接受了什么, 没有接受什么。
13.7 AI ADR Review Gates
Decision Narrative:
ADR 应放进 discovery、product requirement、architecture pattern、data/vendor、eval/control、release、scale 和 quarterly review。早期关注是否值得做和边界是否清楚, 中期关注方案和证据, 上线前关注风险接受和回滚, 上线后关注 trigger 和决策是否仍有效。
System Evidence:
Gate 不是为了拖慢团队, 而是为了让风险前移。G1 要求 scope 和 HITL ADR 至少 proposed; G2 要求 AI pattern 和 model selection ADR 有证据; G3 要求 data retention 和 vendor ADR 被审查; G4 要求 eval gate 和 risk acceptance ADR accepted; G5 release gate 要求 reversal trigger、logging 和 runbook 都可执行。Scale gate 必须重新检查 pilot ADR 是否能扩展到新地区、新渠道或新人群。
13.8 AI ADR 的组织价值
Decision Narrative:
AI ADR 降低的不是文档风险, 而是错误决策被遗忘、被误用、无法审计和无法反转的风险。它让 AI 投资更快复用有效决策, 更早发现高风险选择, 并在监管、事故和模型换代时保留组织记忆。
System Evidence:
从技术治理视角看, AI ADR 帮助管理模型和平台复杂度, 避免每个团队重复争论 RAG、model routing、prompt versioning 和 vendor lock-in。从风险治理视角看, 它把风险接受、控制证据、eval gate 和 reversal trigger 显性化。从业务治理视角看, 它能保护上线速度: 高风险问题早暴露, 低风险决策不被过度治理。成熟的 ADR governance 不是增加审批, 而是建立可复用的决策资产。
14. System Evidence Pack
如果把本手册转化为系统学习案例, 不要只停留在“写了 ADR 模板”。更有价值的是建立一个完整的 decision governance case, 让读者能沿着业务问题、架构取舍、证据、风险接受和反转条件复盘整个决策链。
14.1 高影响案例主题
| 主题 | 适合展示的能力 |
|---|---|
| AML Copilot ADR Governance Pack | 高风险金融流程、RAG、HITL、evidence citation、监管审计 |
| Credit Policy Assistant Decision Log | 客户权益、政策解释、fair lending、人工复核、风险接受 |
| Payment Dispute AI Assistant | 交易证据、数据保留、客户沟通、case workflow、审计追溯 |
| Retail Customer Service Agent Permissions | Agent 工具权限、自动化动作、限额、欺诈控制、kill switch |
| Enterprise RAG Platform Build-vs-Buy | 供应商、平台架构、权限过滤、model gateway、退出策略 |
14.2 Evidence Package 最小包
| Artifact | 内容 | 展示价值 |
|---|---|---|
| 1-page executive brief | 业务问题、AI use case、风险等级、决策治理范围 | 能和高层沟通 |
| PRD excerpt | 用户旅程、需求、验收标准、ADR ID | 能把产品需求和架构治理连接 |
| Decision log | 8-12 个关键 ADR 列表、状态、owner、gate | 能识别架构重要决策 |
| 3 full ADRs | RAG vs fine-tune、HITL、data retention 或 agent permission | 能写高质量决策记录 |
| Architecture views | C4、data flow、sequence、threat model | 能用多视角解释系统 |
| Eval and evidence map | Eval 指标、控制证据、source links、freshness rule | 能证明不是口头治理 |
| Risk acceptance record | 残余风险、owner、scope、expiry、trigger | 能处理真实企业决策 |
| Review gate checklist | G0-G7 gate 条件和决策结果 | 能设计治理流程 |
| Reopened ADR example | 触发条件、复评过程、新旧决策对比 | 能展示持续治理和反转能力 |
| Decision narrative | 业务价值、架构权衡、风险接受、审计证据四种视角 | 能面向不同 stakeholder concern 解释同一条决策链 |
14.3 Decision Narrative
建议用这个叙事顺序:
选择一个金融零售高影响 AI 场景。
从业务流程、客户影响和 stakeholder concerns 开始, 不从模型宣传开始。
识别哪些 AI 决策具有架构意义。
用 ADR 记录关键决策、备选方案、证据、后果、残余风险和反转触发器。
把 ADR 连接到 PRD、架构图、eval gate、release gate 和 monitoring。
展示一个决策被重开的案例, 说明治理不是一次性审批, 而是持续学习系统。
14.4 治理评审展示顺序
| 阶段 | 内容 |
|---|---|
| 场景定位 | 业务场景和为什么这是高影响 AI 用例 |
| 需求连接 | PRD 到 ADR 的 traceability |
| 决策核心 | 三个关键 ADR: RAG / HITL / Retention 或 Agent Permission |
| 证据链 | 架构图、数据流、eval gate 和证据链 |
| 治理结论 | 风险接受、反转触发器和上线门禁 |
| 持续演进 | 决策被重开或替代的演进故事 |
14.5 质量标准
一个强 evidence package 应满足:
- 每个 ADR 都有真实 trade-off, 不是单一方案宣传。
- 每个高风险 decision 都能找到 owner、evidence、control 和 trigger。
- PRD、架构图、eval 和 release gate 引用同一组 ADR ID。
- 有至少一个“被拒绝的选项”和一个“被替代的历史决策”。
- 能清楚说明哪些事情 AI 明确不做。
- 能说明为什么 pilot 决策不能自动复制到 scale。
- 能覆盖技术、风险、业务领导层和内部审计的不同 concern, 但保持同一套证据口径。
15. 最小可执行版本
如果一个团队从零开始建立 AI ADR Governance, 不必一次性建设复杂平台。最小可执行版本如下:
| Week | 动作 | 产出 |
|---|---|---|
| Week 1 | 选 1 个高影响 AI use case, 建立 decision log | 8-12 个决策条目, 每个有 owner 和 level |
| Week 2 | 写 3 个高价值 ADR: AI pattern、data retention、HITL 或 agent permission | 3 份完整 ADR |
| Week 3 | 把 ADR 链接到 PRD、架构图、eval plan 和 release checklist | Traceability table |
| Week 4 | 做一次 review gate simulation 和 reopen simulation | Gate notes、reopened ADR、改进清单 |
成功标志:
- 团队不再只问“模型选哪个”, 而会问“这个选择支持哪个需求、证据是什么、风险谁接受、何时反转”。
- 架构评审不再只看图, 而能沿着 ADR 追溯到 business concern、data flow、eval 和 control。
- 产品需求不再把 AI 能力写成模糊承诺, 而能转成可测、可控、可审计的系统行为。
- 风险接受不再藏在口头共识里, 而有明确 owner、scope、expiry 和 trigger。
最终目标:
让 AI 决策成为组织资产, 而不是项目记忆、个人偏好或供应商话术。