AGENT SKILL

architecture-review

Review sprint architecture updates for consistency, quality, and risk

License 许可
MIT
最近更新
2026-09-25
Stars
★ 0
Forks
0

01 前言 Front Matter

name
architecture-review
description
Review sprint architecture updates for consistency, quality, and risk

03 SKILL.md 正文

Architecture Review Skill

Evaluate a sprint's architecture update for consistency with the existing system, design quality, risks, and completeness. Skippable for trivial/small sprints -- record the gate result as skipped rather than running the review.

Process

Where step 2 reads from depends on Project.design_docs_opt_in:

Not opted in (design_docs_opt_in is None or False)

  1. Read the current architecture in docs/clasi/architecture/.
  2. Read the sprint's architecture update (the Architecture section of the sprint's sprint.md).
  3. Explore the codebase to check alignment between documented and actual architecture.
  4. Review against the criteria below.

Sprints planned before the single-doc rewrite (sprints 001-017) may still carry this content in a separate architecture-update.md file in the sprint directory -- read that file instead for those sprints.

Opted in (design_docs_opt_in is True)

  1. Read the current canonical docs: docs/design/design.md and the subsystem doc(s) named by the sprint's overlay (Project.design_dir).
  2. Read the sprint's overlay diffs: every <name>.diff.md file in the sprint's clasi/sprints/NNN-slug/design/ directory (SUC-007) -- not a sprint.md Architecture section, which is not used for architecture content when opted in (see architecture-authoring Mode 2a). A .diff.md is agent-reviewer input specifically: it shows pristine-vs-edited content as a fenced diff block, generated by clasi.design.overlay.generate_diffs, not authored directly by the sprint-planner. The stakeholder's own review path is git diff on the sprint's design/ directory (e.g. in VS Code) between the seed commit and the pre-execution-approval commit -- reading .diff.md files is this skill's job, not the stakeholder's.
  3. Confirm the overlay validates first. A stale or missing .diff.md is a clasi design validate / validate_design failure (SUC-003) that should have been caught before this review starts -- if architecture-authoring's Step 5 (Validate before handoff) was skipped, run validation now and stop the review with a request to fix it rather than reviewing against a diff that may not reflect the overlay's current content.
  4. Explore the codebase to check alignment between the diffs' claims and actual architecture, same as the not-opted-in path.
  5. Review against the criteria below -- unchanged; apply the same five categories to the diffs' content instead of a sprint.md section.

No sprint.md Architecture section exists to read under opt-in for a compact or substantial sprint -- do not fall back to reading one. For a trivial sprint under opt-in, there is no overlay and no section either; record the gate result skipped, same as today.

The five review categories below and the verdict levels are unchanged between the not-opted-in and opted-in paths -- only the input source (step 2 above) differs.

Review Criteria

Version Consistency

  • Not opted in: changes in Sprint Changes section reflected in document body? Updated architecture internally consistent? Design rationale updated for changed decisions?
  • Opted in: does each .diff.md's content match what the corresponding overlay file currently contains (i.e. is the diff not stale)? Is the edited overlay document internally consistent? Design rationale updated for changed decisions?

Codebase Alignment

  • Does current code match documented architecture?
  • If drift exists, does the sprint plan account for it?
  • Are proposed changes feasible given actual code state?

Design Quality

  • Cohesion: Each component responsible for one concern?
  • Coupling: Minimal, intentional, no circular dependencies?
  • Boundaries: Clear, enforceable, narrow interfaces?
  • Dependency health: No cycles, consistent direction, reasonable fan-out?

Anti-Pattern Detection

  • God component, shotgun surgery, feature envy
  • Shared mutable state, circular dependencies
  • Leaky abstractions, speculative generality

Risks

  • Data migration issues, breaking changes
  • Performance or security implications
  • Deployment sequencing concerns

Verdict

  • APPROVE: No significant issues.
  • APPROVE WITH CHANGES: Minor issues addressable during implementation.
  • REVISE: Significant structural issues that need resolution first.

Guidelines:

  • Circular deps, god components, broken interfaces → REVISE
  • Single contained anti-pattern → APPROVE WITH CHANGES
  • Inconsistencies between Sprint Changes and document body → REVISE
  • Missing rationale for significant decisions → APPROVE WITH CHANGES

04 同仓库更多 Skills