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

> Learn to create Architecture Decision Records ADRs quickly. Use the Claude Code Game Studios skill to scaffold, template, and review your ADRs for acceptance.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: how-to-guide
- Published: 2026-04-16

---

**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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main//.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main//.claude/docs/templates/architecture-decision-record.md).
- Adds the ADR to the architecture registry at [`docs/registry/architecture.yaml`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/registry/architecture.yaml)) with metadata:

```yaml
- 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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main//.claude/docs/templates/architecture-decision-record.md) with mandatory sections including GDD traceability.
- **Register dependencies** in [`docs/registry/architecture.yaml`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/WORKFLOW-GUIDE.md)【source: [docs/WORKFLOW-GUIDE.md line 467-485]】.