AI-Native 架构决策记录：从 ADR 到 AIDR

AIDR 增强维度:
  
  1. 结构化 (Structured):
     传统: 自然语言描述
     AIDR: 结构化数据 + 自然语言解释
     优势: 机器可解析，AI 可理解
  
  2. 可验证 (Verifiable):
     传统: 人类阅读理解
     AIDR: 自动化验证规则
     优势: 代码是否符合规范，自动检查
  
  3. 可追溯 (Traceable):
     传统: 记录决策结果
     AIDR: 记录完整推理链 + 支持证据
     优势: 理解决策背后的 Why
  
  4. 可复用 (Reusable):
     传统: 每个项目独立
     AIDR: 决策模式库，跨项目复用
     优势: 相似场景快速套用
  
  5. 活的 (Living):
     传统: 写完后很少更新
     AIDR: 与代码同步演进
     优势: 文档永远反映真实状态

# AIDR-001: 服务间通信方式
aidr_id: AIDR-001
title: 服务间通信使用异步消息队列
status: accepted
date: 2026-03-14
authors: [architect-team]

# 结构化决策
decision:
  statement: 微服务间通信优先使用异步消息队列 (EventBridge)
  scope: 所有微服务间的非实时数据交换
  exceptions:
    - 实时查询场景可使用同步 HTTP
    - 内部工具可跳过

# 支持证据
evidence:
  requirements:
    - id: REQ-001
      description: 系统需要支持峰值 10k TPS
    - id: REQ-002
      description: 服务间需要松耦合
  
  alternatives:
    - name: 同步 HTTP
      pros: [简单, 实时]
      cons: [耦合度高, 级联故障风险]
      rejected_reason: 不满足松耦合要求
    
    - name: gRPC
      pros: [高性能, 强类型]
      cons: [学习成本高, 调试复杂]
      rejected_reason: 团队熟悉度不足
  
  metrics:
    - name: latency_p99
      target: "< 100ms"
      actual: "45ms"
    - name: throughput
      target: "> 10k TPS"
      actual: "15k TPS"

# 可验证规则
validation:
  rules:
    - id: VAL-001
      description: 服务间调用必须通过 EventBridge
      severity: error
      check: |
        // 伪代码规则
        for each service in services:
          for each call in service.outgoing_calls:
            if call.target_type == "service" and call.protocol != "EventBridge":
              fail("Violation of AIDR-001")
  
  tools:
    - static_analysis: custom-linter
    - runtime_check: service-mesh-policy

# 关联决策
related:
  supersedes: []
  depends_on: [AIDR-000: 微服务划分原则]
  superseded_by: null

# 影响范围
impact:
  services_affected: [order-service, inventory-service, payment-service]
  requires_changes: [重构现有 HTTP 调用]
  estimated_effort: 2 weeks

# 生命周期
lifecycle:
  review_date: 2026-06-14
  triggers:
    - 如果消息队列延迟 > 200ms，重新评估
    - 如果团队规模翻倍，考虑 gRPC

# templates/default.yml
aidr_id: AIDR-XXX
title: "[简明扼要的标题]"
status: proposed  # proposed | accepted | deprecated | superseded
date: YYYY-MM-DD
authors: []

decision:
  statement: ""
  scope: ""
  exceptions: []

evidence:
  requirements: []
  alternatives: []
  metrics: []

validation:
  rules: []
  tools: []

related:
  supersedes: []
  depends_on: []
  superseded_by: null

impact:
  services_affected: []
  requires_changes: []
  estimated_effort: ""

lifecycle:
  review_date: null
  triggers: []

# .github/workflows/aidr-validation.yml
name: AIDR Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Validate AIDR format
        run: aidr validate --format
      
      - name: Check decision consistency
        run: aidr validate --consistency
      
      - name: Verify code compliance
        run: aidr verify --against=src/
      
      - name: Generate compliance report
        run: aidr report --output=aidr-compliance.md
      
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            const report = require('fs').readFileSync('aidr-compliance.md');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            });

# 架构决策不只是文档，而是系统的一部分

# 定义服务拓扑
topology:
  services:
    order-service:
      allowed_calls:
        - target: inventory-service
          protocol: EventBridge
          timeout: 5s
        - target: payment-service
          protocol: EventBridge
          timeout: 10s
      
      forbidden_calls:
        - target: user-service
          reason: "Must go through API Gateway per AIDR-003"

# 这些定义会被转换为：
# 1. 服务网格配置 (Istio/Linkerd)
# 2. 静态分析规则
# 3. 运行时监控告警
# 4. 文档自动生成