How to Create Architecture Decision Records (ADRs) in Claude-Code-Game-Studios

Use the /architecture-decision skill to scaffold a new ADR in docs/architecture/, complete the required sections using the canonical template, and submit it via the /architecture-review skill to move it from Proposed to Accepted status.

Creating architecture decision records (ADRs) is mandatory for every new system, API, or cross-module contract introduced in the Donchitos/Claude-Code-Game-Studios repository. These records serve as the single source of truth for technical decisions and must be stored in docs/architecture/ to ensure traceability with Game Design Documents (GDDs) and implementation stories.

When to Create an ADR

You must create an ADR before writing any code when introducing a new system or cross-module contract. The workflow guide explicitly states: "Every new system needs a corresponding ADR in docs/architecture/"【source: [src/CLAUDE.md line 16]】.

Create an ADR in the following situations:

• New system or API: Introducing a new subsystem, public API, or cross-module contract requires a Proposed ADR before implementation begins.
• Design divergence: When existing code diverges from the original design intent, use the reverse-document skill to capture the decision post-hoc.
• Superseding decisions: When an architectural decision is replaced, update the old ADR status to Deprecated or Superseded and reference the new ADR.

ADR Lifecycle and Status Workflow

ADRs follow a strict lifecycle managed by the architecture-review skill. The skill validates dependencies and blocks stories until requirements are met【source: [docs/WORKFLOW-GUIDE.md line 467-485]】.

The lifecycle states are:

1. Proposed: Initial draft created by the author. Peer review is required.
2. Accepted: Approved by the Technical Director or Lead Programmer. Stories referencing this ADR become Ready for implementation.
3. Deprecated / Superseded: The decision is no longer valid or has been replaced by a newer ADR. Downstream ADRs must be updated to reflect the change.

ADR File Location and Naming Conventions

All ADR files must reside in docs/architecture/ and follow the naming convention:

ADR-[NNNN]-<title>.md

The repository provides a canonical template at /.claude/docs/templates/architecture-decision-record.md【source: [template file]】. This template defines all required sections and formatting standards.

Required ADR Sections

The canonical template mandates the following sections to ensure comprehensive documentation【source: [template line 59-67]】:

Section	Purpose
Status	Current lifecycle state (Proposed, Accepted, Deprecated, etc.).
Date / Last Verified	Creation and verification timestamps.
Decision Makers	Participants in the decision process.
Summary	One-sentence problem statement and decision.
Engine Compatibility	Engine version, domain, knowledge risk, and post-cutoff API usage.
ADR Dependencies	Other ADRs required, enabled, or blocked by this decision.
Context	Problem, current state, constraints, and requirements.
Decision	Architecture diagram, key interfaces, and implementation guidelines.
Alternatives Considered	Comparison of rejected options.
Consequences	Positive, negative, and neutral impacts.
Risks	Probability, impact, and mitigation strategies.
Performance Implications	Before/after metrics.
Migration Plan	Rollout and rollback procedures.
Validation Criteria	Measurable tests proving the decision.
GDD Requirements Addressed	Mandatory traceability to at least one GDD requirement.
Related	Links to superseded or dependent ADRs.

Step-by-Step Creation Process

Using the Architecture Decision Skill

Invoke the /architecture-decision skill to scaffold a new ADR. This skill is listed as a quick-start action in .claude/docs/quick-start.md【source: [.claude/docs/quick-start.md line 50]】.

The skill automatically:

• Creates a new file in docs/architecture/ with the correct naming format.
• Populates the template sections from /.claude/docs/templates/architecture-decision-record.md.
• Adds the ADR to the architecture registry at docs/registry/architecture.yaml.

Filling Out the Template

Complete each section with specific technical details:

1. Engine Compatibility: Specify the Godot version (e.g., Godot 4.6) and flag any post-cutoff APIs.
2. ADR Dependencies: Define the dependency graph. If this ADR requires ADR-0005 to be accepted first, list it under "Depends On".
3. GDD Requirements Addressed: Link to specific requirements in design/gdd/ documents. This is mandatory for acceptance.

Registering and Reviewing

After saving the file, the skill updates the registry (docs/registry/architecture.yaml) with metadata:

- adr: ADR-0010
  status: proposed
  domain: UI
  engine: Godot 4.6
  dependencies: []
  enables:
    - ADR-0012
  blocks:
    - Story-42

Submit the ADR for review by invoking the /architecture-review skill. This skill validates:

• All required fields are present.
• Dependencies form an acyclic graph.
• GDD traceability is satisfied.

Only when the status changes to Accepted will blocked stories (like Story-42 in the example above) become unblocked for implementation.

Best Practices for Maintaining ADRs

• Keep the Summary concise: Limit to under two sentences. The architecture-review skill scans this field to decide whether to load the full file.
• Update Last Verified dates: Whenever the engine version changes, update this field to trigger re-verification.
• Flag post-cutoff APIs: Use the Engine Compatibility table to mark any APIs used after the knowledge cutoff; this triggers extra verification steps.
• Never delete superseded ADRs: Set status: superseded_by: ADR-XXXX instead. The registry relies on historical records for dependency tracking【source: [docs/registry/architecture.yaml line 11-14]】.

Summary

• Create ADRs before coding using the /architecture-decision skill to scaffold files in docs/architecture/.
• Follow the strict lifecycle: Proposed → Accepted → Deprecated/Superseded, enforced by the /architecture-review skill.
• Use the canonical template at /.claude/docs/templates/architecture-decision-record.md with mandatory sections including GDD traceability.
• Register dependencies in docs/registry/architecture.yaml to enable topological validation and prevent circular references.
• Maintain historical records by marking superseded ADRs rather than deleting them, ensuring the registry remains accurate.

Frequently Asked Questions

What happens if I write code before creating an ADR?

Writing code before creating an ADR violates the workflow defined in src/CLAUDE.md. If the code diverges from design intent, you must use the reverse-document skill to create a post-hoc ADR. However, this is discouraged because the /architecture-review skill will block dependent stories until the ADR reaches Accepted status, potentially halting development.

How do I update an ADR when the engine version changes?

Update the Last Verified field in the ADR header and modify the Engine Compatibility table to reflect the new Godot version (e.g., Godot 4.6). If the new version uses post-cutoff APIs, flag them in the Post-Cutoff APIs Used field. This triggers the verification steps in the /architecture-review skill to ensure compatibility.

Can I delete an ADR that is no longer relevant?

No, you should never delete an ADR. Instead, update its Status to Deprecated or Superseded and add a superseded_by: ADR-XXXX reference. The docs/registry/architecture.yaml file relies on historical records for dependency tracking, and deleting files would break the topological sort performed by the /architecture-review skill【source: [docs/registry/architecture.yaml line 11-14]】.

How does the architecture-review skill check ADR dependencies?

The /architecture-review skill performs a topological sort of all ADRs listed in docs/registry/architecture.yaml. It validates that the dependency graph is acyclic, checks that all Depends On references point to Accepted ADRs, and verifies that GDD Requirements Addressed links are valid. If any ADR is still in Proposed status, the skill blocks dependent stories from becoming Ready, enforcing the lifecycle rules defined in docs/WORKFLOW-GUIDE.md【source: [docs/WORKFLOW-GUIDE.md line 467-485]】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}