architecture-review
Traceability matrix mapping GDD requirements to ADRs. Finds gaps, cross-ADR conflicts, engine compatibility. PASS/CONCERNS/NOT ASSESSED/FAIL.
HYClub · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add HYClub/deepseek-harness-game-studios --skill architecture-review技能说明
name: architecture-review description: "Traceability matrix mapping GDD requirements to ADRs. Finds gaps, cross-ADR conflicts, engine compatibility. PASS/CONCERNS/NOT ASSESSED/FAIL." argument-hint: "[focus: full | coverage | consistency | engine | single-gdd path/to/gdd.md]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/architecture-review/../../hooks/yaml-helper.sh" resolve_config *) model: opus
!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow
Architecture Review
The architecture review validates that the complete body of architectural decisions covers all game design requirements, is internally consistent, and correctly targets the project's pinned engine version. It is the quality gate between Technical Setup and Pre-Production.
Argument modes:
- No argument /
full: Full review — all phases coverage: Traceability only — which GDD requirements have no ADRconsistency: Cross-ADR conflict detection onlyengine: Engine compatibility audit onlysingle-gdd [path]: Review architecture coverage for one specific GDDrtm: Requirements Traceability Matrix — extends the standard matrix to include story file paths and test file paths; outputsdocs/architecture/requirements-traceability.mdwith the full GDD requirement → ADR → Story → Test chain. Use in Production phase when stories and tests exist.
Every AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
workflow (see .claude/docs/workflow-modes.md):
full— full traceability matrix across all GDDs and all ADRs.standard— reduced scope: architecture doc + critical ADRs only.minimal— not applicable (no architecture doc required).
Phase 1: Load Everything
Phase 1a — L0: Summary Scan (fast, low tokens)
Freshness check before any scan. Locate the latest prior report — Glob
docs/architecture/architecture-review-*.md and take the newest — then:
Bash: bash .claude/scripts/review-receipts.sh check "[latest-report]" docs/architecture/adr-*.md design/gdd/*.md
- Any
UNRESOLVED— check this FIRST; it disqualifies every option below. One of the two globs matched no file, so that whole document class was never examined and the comparison covered less than it appears to. Say which pattern came back unresolved and stop: an ADR or GDD directory that is empty, renamed or misspelled is a finding about the project, not a reason to stand on a prior report. Never read a set ofUNCHANGEDlines as "everything is current" while anUNRESOLVEDline is present — the set compared was not the set requested. - Everything
UNCHANGED(and noUNRESOLVED) — nothing this review reads has changed since that report; re-running reproduces it. Surface the prior report's date and verdict and offer viaAskUserQuestion:[A] Stand on the prior report (Recommended)/[B] Re-run the full review anyway—guidedproceeds with [A] and notes it;autonomouslogs vialog_decisionand stands on the prior report. - Some
CHANGED/NEW— name them, then scope instead of re-running everything: recommend/architecture-review [system](single-system mode) for just the changed systems. A full re-run stays available on request, and structural changes (aNEWADR, a deleted file) warrant one. RECEIPT: NONE— no prior report, or one written before receipts existed. Proceed with the full review; this run's report will carry the first stamps.
Before reading any full document, use Grep to extract ## Summary sections
from all GDDs and ADRs:
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 4
Grep pattern="## Summary" glob="docs/architecture/adr-*.md" output_mode="content" -A 3
Fail open on a missing Summary. Establish the denominator: glob
design/gdd/*.md and count N. A scan matching fewer than N means those GDDs
predate ## Summary (/design-system emits it, but older GDDs lack it) — never
treat an absent Summary as a system out of scope. A zero-match scan means "no GDD
carries a Summary yet", not "nothing to review": full-read the unmatched set.
For single-gdd [path] mode: use the target GDD's summary to identify which
ADRs reference the same system (Grep ADRs for the system name), then load only
those ADRs' sections per Phase 1b. Skip unrelated GDDs entirely.
For engine mode: load ADR sections only — GDDs are not needed for engine checks.
In practice this is the ## Engine Compatibility scan alone.
For coverage or full mode: proceed to Phase 1b for the full in-scope set.
This is a section load, not a full-file load — see below for why, and for the
narrow cases that still justify escalating to a whole document.
Phase 1b — L1/L2: Targeted Section Load
Load the sections the later phases actually consume — not whole files. This skill reads the two largest document sets in the project (every GDD and every ADR); at realistic sizes a full load of both exhausts the context window before Phase 2 starts, and most of what it loads is narrative this skill never uses.
Establish the denominator first. Glob design/gdd/*.md and count N_gdd;
glob docs/architecture/adr-*.md and count N_adr. Report both. A section
scan matching fewer than the denominator means those documents lack the section —
never treat an absent section as an absent document. The scan narrows the
read set; it never shrinks the in-scope set.
Design Documents
Phase 2 extracts technical requirements — data structures, performance constraints, engine capabilities, cross-system communication, persistence, threading, platform needs. Those live in a known set of sections; Overview and Pl
阅读完整来源 ↗