adr-summarization

架构决策记录摘要

概述

此技能涵盖 ServiceNow 企业架构中的架构决策记录（ADR）摘要：

• 检索和解析 ADR 内容，包括背景、决策、理由和后果
• 将 ADR 与相关业务应用和技术标准关联起来
• 分析多个 ADR 中记录的权衡
• 生成包含影响评估的高管级摘要
• 识别决策模式以及 ADR 之间可能存在的冲突
• 将 ADR 与企业架构图和路线图关联起来

适用场景： 利益相关者需要汇总的架构决策视图、进行架构评审或合规审计，或评估拟议变更对现有决策的影响时。

前提条件

• 角色： ea_admin、ea_viewer 或 admin
• 访问权限： sn_ea_architecture_decision_record、cmdb_ci_business_app、sn_ea_tech_standard、sn_ea_diagram 表
• 插件： 必须激活 Enterprise Architecture (com.snc.enterprise_architecture)
• 知识： ADR 格式（背景、决策、状态、后果）、企业架构概念
• 相关技能： 完成 ea/business-app-insights，以获取应用级背景

操作流程

步骤 1：发现 ADR 表架构

查询前，先了解表结构。

使用 MCP：

Tool: SN-Get-Table-Schema
Parameters:
  table_name: sn_ea_architecture_decision_record

使用 REST：

GET /api/now/table/sn_ea_architecture_decision_record?sysparm_limit=1
Accept: application/json

关键字段：

字段	说明
number	ADR 编号标识符
title	决策标题
status	当前状态（proposed、accepted、deprecated、superseded）
context	推动该决策的业务或技术背景
decision	已做出的架构决策
rationale	决策背后的推理
consequences	预期结果和权衡
business_application	相关业务应用引用
technology_standard	关联的技术标准
created_by	决策作者
sys_created_on	创建日期
sys_updated_on	最后修改日期

步骤 2：查询架构决策记录

检索所有有效的 ADR：

使用 MCP：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: status=accepted^ORstatus=proposed
  fields: sys_id,number,title,status,context,decision,rationale,consequences,business_application,technology_standard,sys_created_on,sys_updated_on
  limit: 100

使用 REST：

GET /api/now/table/sn_ea_architecture_decision_record?sysparm_query=status=accepted^ORstatus=proposed&sysparm_fields=sys_id,number,title,status,context,decision,rationale,consequences,business_application,technology_standard,sys_created_on,sys_updated_on&sysparm_limit=100
Accept: application/json

按业务应用筛选 ADR：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: business_application=[app_sys_id]
  fields: sys_id,number,title,status,decision,rationale,consequences
  limit: 50

按日期范围筛选 ADR：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: sys_created_on>=javascript:gs.dateGenerate('2025-01-01','00:00:00')^status=accepted
  fields: sys_id,number,title,status,decision,consequences
  limit: 100

步骤 3：检索相关背景信息

获取关联业务应用的详细信息：

Tool: SN-Query-Table
Parameters:
  table_name: cmdb_ci_business_app
  query: sys_id=[business_application_sys_id]
  fields: sys_id,name,short_description,business_criticality,lifecycle_stage,owned_by,managed_by

获取相关技术标准：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_tech_standard
  query: sys_id=[tech_standard_sys_id]
  fields: sys_id,name,status,description,category,lifecycle_stage

获取关联的架构图：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_diagram
  query: business_application=[app_sys_id]
  fields: sys_id,name,description,diagram_type,sys_updated_on
  limit: 20

步骤 4：分析权衡和冲突

针对每条 ADR，提取并分类：

1. 正面后果 - 后果字段中提及的收益和优势
2. 负面后果 - 已确认的风险、限制和成本
3. 依赖项 - 引用的其他系统或决策
4. 约束条件 - 背景中提及的技术或业务约束

识别可能相互冲突的决策：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: status=accepted^technology_standard=[same_standard_sys_id]
  fields: sys_id,number,title,decision,consequences
  limit: 50

步骤 5：生成摘要

按以下部分组织 ADR 摘要：

1. 决策概览 - 标题、状态、日期、作者
2. 背景摘要 - 精简后的业务／技术背景
3. 决策陈述 - 用一到两句话概述核心决策
4. 理由要点 - 支持该决策的关键原因
5. 权衡分析 - 优缺点矩阵
6. 影响评估 - 受影响的应用、标准和团队
7. 相关决策 - 指向相关或已被取代 ADR 的链接
8. 建议 - 建议的后续行动或评审

步骤 6：保存摘要（可选）

使用生成的摘要更新 ADR：

Tool: SN-Update-Record
Parameters:
  table_name: sn_ea_architecture_decision_record
  sys_id: [adr_sys_id]
  data:
    work_notes: |
      AI-Generated Summary (as of YYYY-MM-DD):

      Decision: [condensed decision statement]

      Key Trade-offs:
      + [positive consequence 1]
      + [positive consequence 2]
      - [negative consequence 1]
      - [negative consequence 2]

      Impact: Affects [N] business applications
      Related Standards: [standard names]

      Recommendation: [follow-up action]

使用 REST：

PATCH /api/now/table/sn_ea_architecture_decision_record/[adr_sys_id]
Content-Type: application/json
{
  "work_notes": "AI-Generated Summary: ..."
}

工具使用

工具	用途
SN-Get-Table-Schema	发现 ADR 表的字段和关系
SN-Query-Table	检索 ADR、应用、标准和图表
SN-Get-Record	获取包含所有字段的单个 ADR 详细信息
SN-Update-Record	将生成的摘要存回 ADR 记录
SN-Create-Record	创建新的摘要记录或任务

最佳实践

• 按领域分批处理： 按业务领域或应用分组总结 ADR，以形成连贯的叙述
• 保留原文措辞： 引用决策依据时，保留原文措辞，避免造成误解
• 标记过时决策： 突出显示超过 12 个月未审核的 ADR，以便考虑重新评估
• 交叉核对标准： 始终检查所引用的技术标准是否仍然有效
• 跟踪版本： 记录 sys_updated_on 日期，以表明摘要的时效性
• 结合利益相关者背景： 根据受众（高管或技术人员）调整摘要的详略程度
• 检测冲突： 总结多个 ADR 时，主动查找相互矛盾的决策
• 纳入已取代决策的历史： 如果某个 ADR 取代了另一个 ADR，应包含决策链

故障排除

查询未返回 ADR

症状： 查询返回空结果集 原因：

1. Enterprise Architecture 插件未激活
2. 实例中尚未创建 ADR
3. 权限不足 解决方案：

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: ORDERBYDESCsys_created_on
  fields: sys_id,number,title,status
  limit: 5

缺少业务应用引用

症状： ADR 中的 business_application 字段为空 原因： 创建 ADR 时未关联业务应用 解决方案： 单独查询 cmdb_ci_business_app，并根据名称或描述中的关键词进行关联

ADR 内容字段为空

症状： context、decision 或 rationale 字段返回空白 原因： ADR 可能使用自定义字段或日志字段 解决方案： 检查表架构中的自定义列，或使用 work_notes/comments 字段

Tool: SN-Get-Table-Schema
Parameters:
  table_name: sn_ea_architecture_decision_record

权限被拒错误

症状： 出现 403 或权限不足错误 原因： 用户缺少 ea_viewer 或 ea_admin 角色 解决方案： 验证角色分配情况或申请提升访问权限

示例

示例 1：总结单个 ADR

# Step 1: Get the ADR
Tool: SN-Get-Record
Parameters:
  table_name: sn_ea_architecture_decision_record
  sys_id: abc123def456

# Result contains:
#   title: "Adopt Kubernetes for Container Orchestration"
#   status: "accepted"
#   context: "Our microservices deployment requires automated scaling..."
#   decision: "Adopt Kubernetes as the standard container orchestration platform..."
#   rationale: "Kubernetes provides auto-scaling, self-healing, and wide ecosystem..."
#   consequences: "Requires team training, increases infrastructure complexity..."

# Step 2: Get related application
Tool: SN-Query-Table
Parameters:
  table_name: cmdb_ci_business_app
  query: sys_id=[business_application_value]
  fields: name,business_criticality,lifecycle_stage

# Step 3: Generate summary output:
# ADR-0042: Adopt Kubernetes for Container Orchestration
# Status: Accepted | Created: 2025-06-15
# Application: Cloud Platform Services (Business Critical)
#
# Context: Microservices architecture requires automated container management
# Decision: Standardize on Kubernetes for all container orchestration
#
# Trade-offs:
# + Auto-scaling and self-healing capabilities
# + Large ecosystem and community support
# - Requires significant team training investment
# - Increases infrastructure complexity
#
# Impact: Affects 12 microservices across 3 business applications

示例 2：按领域批量总结 ADR

# Step 1: Get all ADRs for a specific business domain
Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: status=accepted^contextLIKEcloud^ORtitleLIKEcloud
  fields: sys_id,number,title,status,decision,consequences,sys_created_on
  limit: 50

# Step 2: For each ADR, fetch related records and build consolidated summary
# Step 3: Output a domain-level summary with decision timeline and dependency map

相关技能

• ea/business-app-insights - 应用健康状况和依赖关系分析
• genai/app-summary - 特定范围的应用分析
• security/audit-compliance - 架构决策的合规影响
• cmdb/relationship-mapping - 了解受 ADR 影响的 CI 依赖关系