跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

architect-analyze

Analyze architecture for consistency between ADRs and AD, completeness, and quality issues. Use when validating generated or refined architecture artifacts, before feature development, during architecture review, or periodically to detect drift.

tikalk · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add tikalk/adlc-team-skills --skill architect-analyze

技能说明


name: architect-analyze description: Analyze architecture for consistency between ADRs and AD, completeness, and quality issues. Use when validating generated or refined architecture artifacts, before feature development, during architecture review, or periodically to detect drift. disable-model-invocation: true

architect-analyze

What this skill does

Performs a read-only architecture consistency analysis between ADRs (Architecture Decision Records) and AD (Architecture Description). It identifies discrepancies, quality issues, and gaps without modifying any files.

Key analysis dimensions:

  1. ADR Quality — Completeness, clarity, and standards compliance
  2. ADR to AD Consistency — Bidirectional drift detection
  3. Internal Consistency — Cross-artifact coherence
  4. Staleness Detection — Outdated references and placeholders

This skill validates architecture artifacts for consistency, completeness, and quality.

When to use

  • After /architect-implement — Validate generated AD.md
  • After /architect-clarify — Verify ADR refinements
  • Before feature development — Ensure architecture is solid
  • During architecture review — Quality gate for architecture docs
  • Periodically — Detect drift as the codebase evolves

Do not use when no architecture artifacts exist; use /architect-init or /architect-specify first. Do not use to create architecture — this is analysis-only.

Process

User Input

Consider the user input before proceeding (if not empty):

$ARGUMENTS

Examples:

  • "system" — Focus on root-level AD.md and adr/ directory only
  • "feature auth" — Focus on specific feature architecture
  • "adrs" — Focus on ADR quality and inter-ADR consistency
  • "views" — Focus on AD.md view completeness and internal consistency
  • Empty input — Full analysis of all architecture artifacts

Goal

Perform read-only architecture consistency analysis. Identify discrepancies, quality issues, and gaps without modifying any files.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report. Offer remediation suggestions (user must explicitly approve before any follow-up editing commands would be invoked manually).

Constitution Authority: The project constitution (memory/constitution.md) is non-negotiable within this analysis scope. Constitution conflicts are automatically CRITICAL.

Role & Context

Act as an Architecture Analyst validating architecture documentation quality:

  • Validate ADR completeness against MADR standards
  • Detect drift between ADRs and AD.md
  • Identify internal inconsistencies across artifacts
  • Flag staleness and quality issues

Architecture document hierarchy:

DocumentLocationPurpose
AD.mdProject rootFull Architecture Description (Rozanski & Woods)
adr/{REPO_ROOT}/.adlc/memory/System-level ADRs (individual files)
constitution.md{REPO_ROOT}/.adlc/memory/Governance principles and constraints

Outline

  1. Initialize Analysis Context — Load architecture artifacts
  2. Determine Analysis Scope — System, feature, or full
  3. Execute Detection Passes — A through G
  4. Assign Severities — CRITICAL/HIGH/MEDIUM/LOW
  5. Generate Report — Structured markdown analysis
  6. Provide Next Actions — Remediation suggestions

Phase 1: Initialize Analysis Context

Objective: Load all architecture artifacts for analysis

  1. Run Setup Script:

    • Execute scripts/bash/setup-architect.sh from repo root
    • Parse JSON for file paths and existence status
  2. Load System-Level Artifacts:

    • Read AD.md (project root) if exists
    • Read ADRs from all locations (priority order):
      1. {REPO_ROOT}/.adlc/memory/adr/adr.md (canonical — Accepted ADRs)
      2. {REPO_ROOT}/.adlc/drafts/adr/ (working copy — Proposed/Discovered, individual file format)
    • Read {REPO_ROOT}/.adlc/memory/constitution.md if exists
  3. Load Feature-Level Artifacts (if analyzing features):

    • Scan specs/*/AD.md for feature architectures
    • Scan specs/*/adr/ADR-*.md for feature ADRs
  4. Build Artifact Inventory:

    ArtifactPathStatus
    System ADAD.mdFound/Missing
    System ADRs (canonical){REPO_ROOT}/.adlc/memory/adr/adr.mdFound/Missing
    System ADRs (drafts){REPO_ROOT}/.adlc/drafts/adr/Found/Missing
    Constitution{REPO_ROOT}/.adlc/memory/constitution.mdFound/Missing
    Feature ADsspecs/*/AD.mdCount: N
    Feature ADRsspecs/*/adr/Count: N

Phase 2: Determine Analysis Scope

Objective: Focus analysis based on user input

User InputScopeArtifacts Analyzed
(empty)FullAll system artifacts
"system"System onlyAD.md, system ADR locations
"adrs"ADR qualityAll ADR files
"views"AD completenessAD.md

Phase 3: Execute Detection Passes

Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.

Pass A: ADR Quality Analysis

Objective: Validate each ADR against MADR standards

Quality Dimensions:

DimensionCheckSeverity if Missing
ContextProblem clearly stated, forces documentedMEDIUM
DecisionActionable, testable decision statementHIGH
Positive ConsequencesBenefits documentedMEDIUM
Negative ConsequencesTrade-offs acknowledgedHIGH
RisksIdentified with mitigationsMEDIUM
AlternativesAt least 2 options with neutral trade-offsHIGH
StatusValid status (Proposed/Accepted/Deprecated/Superseded/Discovered)LOW
Constitution AlignmentMUST principles complied withCRITICAL

ADR Quality Checklist:

For each ADR, verify:

  • Clear context explaining the prob
阅读完整来源 ↗