architecture-decision
Create an ADR documenting a technical decision: context, alternatives considered, consequences.
Donchitos · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Donchitos/Claude-Code-Game-Studios --skill architecture-decision技能说明
name: architecture-decision description: "Create an ADR documenting a technical decision: context, alternatives considered, consequences." argument-hint: "[title | retrofit | accept ] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion model: sonnet
!source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && resolve_config --keys review_mode,automation,workflow,docs.density,team.size
Resolved above — use as-is; --review overrides review_mode. No block →
defaults in .claude/docs/config-resolution.md.
When this skill is invoked:
0. Parse Arguments — Detect Retrofit / Acceptance Mode
See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.
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).
team.size: which agents validate this ADR (orthogonal to review_mode/workflow).
individual(default):technical-director+lead-programmer+ the engine-specialist.small: + an engine sub-specialist where applicable.studio: + an adversarial review by an alternate engine-specialist. Any non-core agent needed atindividualroutes through the nearest active core agent with a note.
docs.density — it controls the depth of the ADR's prose sections, not
which sections the skeleton emits (that is fixed). modes.rigor sets it
alongside workflow; set docs.density explicitly to vary ADR verbosity alone:
terse = decision + alternatives as bullets, one line of rationale each;
balanced = paragraph per section with light rationale (default); thorough =
full prose with trade-offs and worked rationale in Decision, Alternatives, and
Consequences. Apply it to the prose sections; the Engine Compatibility, ADR
Dependencies, and GDD Requirements tables are structural and stay whole at every
density.
workflow (see .claude/docs/workflow-modes.md):
full— all ADRs on the required ADR list must be completed.standard— critical ADRs only (Foundation-layer systems).minimal— not required. Can still be run voluntarily.
If the argument starts with retrofit followed by a file path
(e.g., /architecture-decision retrofit docs/architecture/adr-0001-event-system.md):
Enter retrofit mode:
- Read the existing ADR file completely.
- Identify which template sections are present by scanning headings:
## Status— BLOCKING if missing:/story-readinesscannot check ADR acceptance## ADR Dependencies— HIGH if missing: dependency ordering breaks## Engine Compatibility— HIGH if missing: post-cutoff risk unknown## GDD Requirements Addressed— MEDIUM if missing: traceability lost
- Present to the user:
## Retrofit: [ADR title] File: [path] Sections already present (will not be touched): ✓ Status: [current value, or "MISSING — will add"] ✓ [section] Missing sections to add: ✗ Status — BLOCKING (stories cannot validate ADR acceptance without this) ✗ ADR Dependencies — HIGH ✗ Engine Compatibility — HIGH - Ask: "Shall I add the [N] missing sections? I will not modify any existing content."
- If yes:
- For Status: ask the user — "What is the current status of this decision?" Options: "Proposed", "Accepted", "Deprecated", "Superseded by ADR-XXXX"
- For ADR Dependencies: ask — "Does this decision depend on any other ADR? Does it enable or block any other ADR or epic?" Accept "None" for each field.
- For Engine Compatibility: read the engine reference docs (same as Step 1 below) and ask the user to confirm the domain. Then generate the table with verified data.
- For GDD Requirements Addressed: ask — "Which GDD systems motivated this decision? What specific requirement in each GDD does this ADR address?"
- Append each missing section to the ADR file using the Edit tool.
- Never modify any existing section. Only append or fill absent sections.
- After adding all missing sections, update the ADR's
## Datefield if it is absent. - Suggest: "Run
/architecture-reviewto re-validate coverage now that this ADR has its Status and Dependencies fields."
If the argument starts with accept followed by an ADR id
(e.g., /architecture-decision accept ADR-0005):
Enter acceptance mode. This is the only path in the framework that moves an
ADR from Proposed to Accepted. Authoring always produces Proposed
(Step 5), while
/create-control-manifest, /create-epics, /create-stories and /gate-check
all require Accepted — so without this mode the pipeline had a state it could
enter and never leave.
-
Resolve the id to a file, then read it. Glob
docs/architecture/adr-NNNN-*.mdfor the given number. If no file matches, or more than one does, stop and say which — do not pick one. If the file has no## Statussection, stop and say so; a missing Status is exactly what retrofit mode is for. -
Check the current status. If it is already
Accepted, say so and stop. If it isDeprecatedorSuperseded, refuse: reviving a superseded decision is a new ADR, not a status edit. -
Check its dependencies first. Read
## ADR Dependencies.If that section is absent, empty, or reads
UNKNOWN, do not read it as "no dependencies" — refuse and say which:"ADR-0005's dependency section is [absent / UNKNOWN], so I cannot tell what this decision rests on. An empty dependency list and an unexamined one look identical here, and only one of them is safe to accept. Run
/architecture-decision retrofit <path>to establish