adr-summarization

アーキテクチャ意思決定記録の要約

概要

このスキルでは、ServiceNow Enterprise Architecture のアーキテクチャ意思決定記録（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	現在のステータス（提案、承認、非推奨、置き換え済み）
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. 意思決定の記述 - 核となる意思決定を 1～2 文で記述したもの
4. 根拠の要点 - 意思決定を支持する主な理由
5. トレードオフ分析 - メリットとデメリットのマトリックス
6. 影響評価 - 影響を受けるアプリケーション、標準、チーム
7. 関連する意思決定 - 関連する ADR または置き換えられた 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 の依存関係を把握します