mcpField
A
architect-analyze

architect-analyze

github.com/tikalk测试与质量143187 次安装今天更新
代码仓库

关于 architect-analyze

architect-analyze 是一项只读技能，用于检查架构决策记录与架构描述。它帮助架构团队发现质量问题、内容不一致、过时信息和 Mermaid 图表错误，不会修改文件。

主要功能

  1. 01检查 ADR 的完整性与质量
  2. 02发现 ADR 与 AD.md 之间的偏差
  3. 03检查架构文档间的一致性
  4. 04标记过时引用与占位内容
  5. 05验证 Mermaid 图表

适用场景

  1. 01功能开发前审查架构
  2. 02架构变更后检查文档
  3. 03定期审计架构文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tikalk/adlc-team-skills --skill architect-analyze

安装后在 Claude Code 中输入/architect-analyze确认已加载。

详细介绍

architect-analyze

此技能的作用

对 ADR（架构决策记录）与 AD（架构描述）执行只读架构一致性分析。此技能会识别差异、质量问题和缺漏，但不会修改任何文件。

主要分析维度：

  1. ADR 质量 — 完整性、清晰度和标准合规性
  2. ADR 与 AD 的一致性 — 双向偏差检测
  3. 内部一致性 — 跨制品的一致性
  4. 过时内容检测 — 过时的引用和占位符
  5. Mermaid 语法 — 对图表块执行确定性有效性检查，并提供位置和建议的补丁（Mermaid 检测阶段）

此技能会验证架构制品的一致性、完整性和质量。

使用时机

  • 执行 /architect-implement 后 — 验证生成的 AD.md
  • 执行 /architect-clarify 后 — 验证 ADR 的完善情况
  • 功能开发前 — 确保架构稳固
  • 架构评审期间 — 作为架构文档的质量门禁
  • 定期执行 — 随着代码库演进检测偏差

如果不存在架构制品，不要使用此技能；请先使用 /architect-init 或 /architect-specify。不要使用此技能创建架构；此技能仅用于分析。

流程

用户输入

如果用户输入不为空，请在继续之前考虑该输入：

$ARGUMENTS

示例：

  • "system" — 仅关注根目录级别的 AD.md 和 adr/ 目录
  • "feature auth" — 关注特定功能的架构
  • "adrs" — 关注 ADR 质量和 ADR 之间的一致性
  • "views" — 关注 AD.md 视图的完整性和内部一致性
  • 空输入 — 分析所有架构制品
目标

执行只读架构一致性分析。识别差异、质量问题和缺漏，但不修改任何文件。

操作约束

严格只读：不得修改任何文件。输出结构化分析报告。提供整改建议（用户必须明确批准，才能手动执行任何后续编辑命令）。

宪章权威性：项目宪章（memory/constitution.md）在此分析范围内不可协商。与宪章冲突的问题会自动标记为 CRITICAL。

角色与上下文

作为架构分析师，验证架构文档质量：

  • 根据 MADR 标准验证 ADR 的完整性
  • 检测 ADR 与 AD.md 之间的偏差
  • 识别各制品之间的内部不一致
  • 标记过时内容和质量问题

架构文档层级：

文档位置用途
AD.md项目根目录完整的架构描述（Rozanski & Woods）
adr/{REPO_ROOT}/docs/adlc/memory/（旧版 .adlc/memory/ 作为回退路径）系统级 ADR（单独文件）
constitution.md{REPO_ROOT}/docs/adlc/memory/（旧版 .adlc/memory/ 作为回退路径）治理原则和约束
大纲
  1. 初始化分析上下文 — 加载架构制品
  2. 确定分析范围 — 系统、功能或全部
  3. 执行检测阶段 — A 到 G
  4. 分配严重级别 — CRITICAL/HIGH/MEDIUM/LOW
  5. 生成报告 — 结构化 Markdown 分析
  6. 提供后续操作 — 整改建议
阶段 1：初始化分析上下文

目标：加载所有架构制品以供分析

  1. 运行设置脚本：

    • 从仓库根目录执行 {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh（需要 architect-clarify 技能：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。
    • 解析 JSON，获取文件路径及其存在状态

  2. 加载系统级制品：

    • 如果 AD.md（项目根目录）存在，则读取
    • 从所有位置读取 ADR（按优先级排序）：
      1. {REPO_ROOT}/docs/adlc/memory/adr/adr.md（规范位置——已接受的 ADR；根据双重读取规则，旧版 {REPO_ROOT}/.adlc/memory/adr/adr.md 为回退位置）
      2. {REPO_ROOT}/.adlc/drafts/adr/（工作副本——提议中/发现的 ADR，采用单文件格式）
    • 如果 {REPO_ROOT}/docs/adlc/memory/constitution.md 或其旧版回退位置 {REPO_ROOT}/.adlc/memory/constitution.md 中任一存在，则读取

  3. 加载功能级制品（分析功能时）：

    • 扫描 specs/*/AD.md，查找功能架构
    • 扫描 specs/*/adr/ADR-*.md，查找功能 ADR

  4. 建立制品清单：

    制品路径状态
    系统 ADAD.md找到/缺失
    系统 ADR（规范位置）{REPO_ROOT}/docs/adlc/memory/adr/adr.md（旧版 .adlc/memory/adr/adr.md 为回退位置）找到/缺失
    系统 ADR（草稿）{REPO_ROOT}/.adlc/drafts/adr/找到/缺失
    宪章{REPO_ROOT}/docs/adlc/memory/constitution.md（旧版 .adlc/memory/constitution.md 为回退位置）找到/缺失
    功能 ADspecs/*/AD.md数量：N
    功能 ADRspecs/*/adr/数量：N
阶段 2：确定分析范围

目标：根据用户输入聚焦分析

用户输入范围分析的制品
（空）完整所有系统制品
"system"仅系统AD.md、系统 ADR 位置
"adrs"ADR 质量所有 ADR 文件
"views"AD 完整性AD.md
阶段 3：执行检测轮次

聚焦于高信号发现。总数限制为 50 条发现；超出部分汇总至溢出摘要。

轮次 A：ADR 质量分析

目标：根据 MADR 标准验证每个 ADR

质量维度：

维度检查项缺失时的严重性
背景清楚陈述问题，并记录影响因素中
决策可执行、可测试的决策陈述高
正面后果记录收益中
负面后果承认权衡高
风险识别风险并制定缓解措施中
备选方案至少 2 个选项，并对权衡作中性说明高
状态有效状态（Proposed/Accepted/Deprecated/Superseded/Discovered）低
宪章一致性遵守 MUST 原则严重

ADR 质量检查清单：

对于每个 ADR，请验证：

  • 背景清晰，说明问题/机会
  • 决策陈述明确且可执行
  • 记录正面和负面后果
  • 常见备选方案采用中性方式说明权衡（而非“因……而拒绝”）
  • 识别风险并制定缓解策略
  • 状态值有效
  • 不与宪章中的 MUST 原则冲突
轮次 B：ADR 间一致性

目标：检测 ADR 之间的冲突和不一致

检查项：

  1. 相互冲突的决策：

    • ADR 之间互相矛盾（例如，一个选择 PostgreSQL，另一个却假设使用 MongoDB）
    • 技术栈不一致

  2. 缺失的依赖关系：

    • 应互相引用却未引用的 ADR
    • 对其他决策的隐含假设

  3. 术语漂移：

    • 不同 ADR 对同一概念使用不同名称
    • 组件命名不一致

  4. 技术栈一致性：

    • 前端、后端和基础设施的选择相互匹配
    • 不存在相互冲突的框架决策
阶段 C：ADR 与 AD 不一致（正向同步）

目标：检测 ADR 中未反映在 AD.md 中的决策

检查项：

ADR 要素AD.md 中的预期内容视图／章节
系统架构风格上下文视图3.1
数据库选择信息视图3.3
API 风格功能视图3.2
身份验证方式安全视角4.1
部署平台部署视图3.6
CI/CD 方式开发视图3.5
扩展策略性能视角4.2
缓存策略信息视图3.3

检测逻辑：

对于每个 ADR：

  1. 确定 ADR 主要影响的视图（使用上方映射表）
  2. 在 AD.md 中查找对该决策的体现
  3. 如果缺少该决策的体现或与之矛盾，则标记
阶段 D：AD 与 ADR 不一致（反向同步）

目标：检测缺少 ADR 支持的 AD.md 要素

检查项：

  1. 缺少 ADR 的组件：

    • 功能视图中展示的主要组件，但没有决策依据
    • 上下文视图中的外部依赖，但没有 ADR 说明依据

  2. 缺少理由的模式：

    • 描述了架构模式，但未通过 ADR 说明
    • 视图中包含技术选择，但没有支持该选择的决策

  3. 基础设施决策：

    • 部署拓扑缺少基础设施 ADR
    • 扩展方式缺少性能 ADR
阶段 E：AD 内部一致性

目标：验证 AD.md 各视图之间的一致性

检查项：

  1. 跨视图一致性：

    • 所有视图中的同一组件名称保持一致
    • 信息视图中的数据实体与功能视图中的引用相符
    • 部署节点与功能组件保持一致

  2. 图文对应：

    • Mermaid 图与文字描述相符
    • 图中没有文字未提及的组件
    • 文字中没有图中未呈现的组件

  3. 视图完整性：

    • 所需章节齐全（引言、利益相关者、视图、关注点）
    • 包含核心视图（上下文、功能、信息、开发、部署）
    • 涵盖相关关注点（安全、性能）

  4. 图表语法验证（确定性检查——Mermaid 检测阶段）：

    • Mermaid 语法有效（没有损坏的图表）

    • 各图表的样式保持一致

    • 运行共享验证器；它会为每个损坏的代码块生成一条发现，包含严重性、位置（文件 + 行号 + 围栏索引）和建议的补丁：

      sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh
sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh --tsv <artifact>

      规则集仅在验证器中说明一次——请直接阅读验证器中的规则，不要在此重新推导。退出代码：0 表示无问题，1 表示存在 HIGH（语法错误），2 表示仅有 MEDIUM（样式）发现。无法识别的图表类型属于 MEDIUM，绝不会属于 HIGH：此规则集不得误报语法错误。该阶段为只读（生命周期写入范围）——修复应由 /architect-implement 或人工完成。

  5. 视图文件一致性（DAG 状态验证）：

    • 检查 .adlc/architect/state.json 是否存在，以及其中视图是否标记为“completed”
    • 检查 docs/adlc/architect/views/ 目录是否存在（旧版 .adlc/architect/views/ 为回退路径）
    • 验证 state.json 中每个标记为“completed”的视图是否在磁盘上有对应文件
    • 以下情况标记为 HIGH 严重性：
      • state.json 报告视图“completed”，但 views/ 目录为空
      • 视图文件不足 20 行（占位符/骨架内容）
      • 视图文件无法读取（损坏/缺少权限）
    • 报告格式： 
      检测到 DAG 状态不一致：
- 状态报告：已完成 [N] 个视图
- 磁盘上的文件：[M] 个视图文件
- 缺少的文件：[缺少的视图列表]
- 建议：重新生成视图或重置 state.json

  6. 技术中立性（功能视图）：

    • 扫描功能视图（§3.2）中元素描述和 Mermaid 图里的产品/供应商名称
    • 架构角色（可接受）：数据库、对象存储、缓存、消息队列、AI 网关、工作流运行时、应用外壳、API 网关、身份验证服务等
    • 产品名称（标记为 MEDIUM）：PostgreSQL、Neon、Vercel、Next.js、Redis、MongoDB、AWS、Azure、S3 等
    • 严重性：MEDIUM——不阻塞流程，但表明存在抽象违规
    • 注意：ADR 可追溯性章节可以引用产品（这是允许的）；仅标记元素描述和图表标签

  7. 功能-开发映射：

    • 验证开发视图（§3.5）是否包含技术栈映射表（§3.5.2）
    • 检查功能视图元素表（§3.2.1）中的每个元素是否至少在映射表中有一个对应条目
    • N:1 映射（多个功能元素 → 一种技术）可以接受
    • 严重性：缺少元素时为 MEDIUM；缺少映射表时为 LOW
    • 交叉检查：技术架构图（§3.5.3）的结构应与功能视图图表（§3.2.2）相对应
阶段 F：过时内容检测

目标：识别过时的引用和占位符

检查项：

  1. 仍被引用的已弃用 ADR：

    • AD.md 引用了状态为「已弃用」的 ADR
    • 已被取代的决策仍在实施

  2. 占位符检测：

    • [TODO]、[TBD]、[PLACEHOLDER] 标记
    • [SYSTEM_NAME]、[STAKEHOLDER_*] 未填写
    • ???、...、<placeholder> 模式

  3. 日期不一致：

    • ADR 日期明显早于 AD 的最后更新日期
    • 功能架构与系统架构不同步

  4. 孤立引用：

    • 提及了 ADR ID，但对应的 ADR 不存在
    • 引用了组件名称，但未定义该组件
阶段 G：功能与系统对齐（如果存在功能架构）

目标：验证功能架构是否符合系统边界

检查项：

  1. 功能 ADR 对齐：

    • 标记为「与 ADR-XXX 对齐」的功能 ADR 引用了有效的系统 ADR
    • 不存在没有记录理由的 VIOLATION 标记
    • 功能决策与系统约束一致

  2. 边界合规性：

    • 功能组件符合系统功能视图结构
    • 功能数据实体与系统信息视图一致
    • 功能未超出系统范围（上下文视图）

  3. 集成点：

    • 已记录功能与系统之间的接口
    • 跨越功能边界的数据流保持一致
阶段 4：严重程度分级

严重程度标准：

严重程度标准示例
CRITICAL违反宪章、存在安全性／数据完整性缺口、缺少核心 ADRADR 违反 MUST 原则、主要组件未记录
HIGHADR 与 AD 存在影响实施的偏差、ADR 冲突、缺少备选方案ADR 中选择了某个数据库，但 AD 中使用了错误的数据库；两个 ADR 相互冲突
MEDIUM后果说明不完整、内容过时、术语不一致、缺少可选视图ADR 缺少负面后果、TODO 占位符
LOW样式改进、轻微文档缺漏、可选细节格式不一致、措辞问题较轻微
阶段 5：生成分析报告

输出格式：

## Architecture Analysis Report

### Analysis Summary

| Attribute | Value |
|-----------|-------|
| **Mode** | [Full/System/Feature/ADRs/Views] |
| **Scope** | [Description of what was analyzed] |
| **Files Analyzed** | [List of files] |
| **Analysis Date** | [Current date] |

### Findings

| ID | Pass | Severity | Location | Summary | Recommendation |
|----|------|----------|----------|---------|----------------|
| A1 | ADR Quality | MEDIUM | ADR-003 | Missing negative consequences | Add trade-offs section |
| B1 | Inter-ADR | HIGH | ADR-002, ADR-005 | Conflicting database choices | Resolve PostgreSQL vs MongoDB conflict |
| C1 | ADR->AD Drift | HIGH | ADR-005 | Caching decision not in Information View | Update AD.md 3.3 |
| D1 | AD->ADR Drift | HIGH | AD.md:3.2 | Redis component has no ADR | Create ADR for cache choice |
| E1 | AD Consistency | MEDIUM | AD.md:3.2/3.6 | Component naming mismatch | Standardize "AuthService" naming |
| F1 | Staleness | LOW | AD.md:3.1 | [SYSTEM_NAME] placeholder | Fill in system name |
| G1 | Feature Align | HIGH | specs/auth/adr.md | VIOLATION flag unresolved | Document override justification |

### Coverage Metrics

| Metric | System | Feature: auth | Feature: payments |
|--------|--------|---------------|-------------------|
| ADR Count | 13 | 3 | 2 |
| AD Views Complete | 5/7 | 3/5 | 3/5 |
| ADR->AD Coverage | 85% | 100% | 67% |
| AD->ADR Coverage | 92% | 100% | 100% |
| Quality Score | 78% | 85% | 72% |

### Constitution Alignment

| Status | Count | Details |
|--------|-------|---------|
| Compliant | [N] | ADRs following MUST principles |
| Violations | [N] | ADRs violating MUST principles (CRITICAL) |
| Deviations | [N] | Justified SHOULD principle deviations |

### Issue Distribution

| Severity | Count |
|----------|-------|
| CRITICAL | [N] |
| HIGH | [N] |
| MEDIUM | [N] |
| LOW | [N] |

### Next Actions

Based on findings, recommended actions:

**If CRITICAL issues exist:**
- **Immediate**: Resolve constitution violations before proceeding
- Command: `/architect-clarify` to address ADR compliance

**If HIGH ADR quality issues:**
- **Refine**: Address missing alternatives and consequences
- Command: `/architect-clarify` to improve ADR quality

**If ADR->AD drift detected:**
- **Sync AD**: Update AD.md to reflect ADR decisions
- Command: `/architect-implement` to regenerate views

**If AD->ADR drift detected:**
- **Document**: Create missing ADRs for undocumented decisions
- Command: `/architect-specify` or `/architect-init` to add ADRs

**If feature alignment issues:**
- **Align**: Resolve feature-system boundary violations
- Command: Run `/architect-specify` or `/architect-init` to create missing ADRs
阶段 6：提供修复建议

呈现报告后，询问：

「你希望我针对最重要的 [N] 个问题提出具体的修复步骤吗？我可以为每项发现提供详细指导，但不会自动进行任何更改。」

关键规则
分析完整性
  • 绝不修改文件——这是一项只读分析
  • 绝不臆造缺失内容——准确报告缺失情况
  • 优先处理违反宪章的问题——此类问题始终为 CRITICAL
  • 基于证据得出发现——引用具体位置和内容
一致性标准
  • 交叉引用所有内容——双向验证（ADR 与 AD）
  • 检查所有层级——系统架构和功能架构必须保持一致
  • 验证术语——相同概念必须使用相同名称
  • 验证图表——Mermaid 语法必须有效
报告标准
  • 最多列出 50 项发现——超出部分汇总到摘要中
  • 注明位置——始终引用文件:行号或章节
  • 提供可执行的建议——为每项发现提供修复建议
  • 计算覆盖率指标——量化完整性

后续步骤

如果发现问题：

  • 运行 /architect-clarify 以完善 ADR（质量问题、缺少后果／备选方案、违反宪章）。
  • 检测到 ADR 与 AD 存在偏差时，运行 /architect-implement 以重新生成 AD.md。

对于缺失的 ADR 或功能边界问题，请酌情使用 /architect-specify 或 /architect-init。

验证

此技能的具体输出：

  • 架构分析报告（结构化 Markdown），包括：
    • 分析摘要（模式、范围、已分析文件、分析日期）
    • 发现项表格，包含 ID、通过情况、严重性、位置、摘要和建议
    • 覆盖率指标（ADR 数量、AD 视图完成情况、ADR→AD 覆盖率、AD→ADR 覆盖率、质量评分）
    • 宪章一致性摘要（符合项、违规项、偏差）
    • 按严重性划分的问题分布（CRITICAL、HIGH、MEDIUM、LOW）
    • 根据发现项类型定制的后续操作
  • 对 AD 和每个包含图表的产物运行 Mermaid 语法验证（共享检查器、Mermaid 检测流程）——报告每个有问题的代码块，并标明严重性、位置和建议的补丁。
  • 不修改任何文件——分析严格为只读。
  • 报告生成后，提供经用户批准的修复指导。

评论

支持 Markdown