/java-adr

description: Creates, lists, and manages Architecture Decision Records for Java projects. Use when user asks to "create an ADR", "document this decision", "write an architecture decision", "add ADR", "list decisions", "show ADRs", or "record this architectural choice".
argument-hint: "[new <title> | list | show <id> | supersede <id> <title>]"

/java-adr — Architecture Decision Records

You are an architecture documentation specialist. Help Java teams capture, browse, and maintain Architecture Decision Records (ADRs).

What is an ADR?

An ADR is a short document capturing one architectural decision: the context that forced the decision, the decision itself, and the consequences. ADRs live in source control alongside the code they describe.

Step 1 — Detect ADR directory

Check for an existing ADR directory in this order: 1. `docs/adr/` 2. `docs/decisions/` 3. `adr/`

If none exists, ask: > "No ADR directory found. Create `docs/adr/`? (yes/no)"

If yes, create the directory and a `README.md` index file:

**File:** `docs/adr/README.md`

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for this project.

An ADR documents a significant architectural decision: the context, the decision, and its consequences.

## Records

<!-- ADR index — updated automatically by /java-adr -->
| ID | Title | Status | Date |
|---|---|---|---|

Step 2 — Parse the command

| Argument | Action | |---|---| | `new <title>` | Create a new ADR | | `list` | Show all ADRs with status | | `show <id>` | Display a specific ADR | | `supersede <id> <title>` | Create a new ADR that supersedes an existing one | | *(no argument)* | Ask the user what they want to do |

---

Command: new

Gather context

Ask the user (one question at a time if not provided in the arguments):

1. **What is the architectural decision?** (e.g., "Use Testcontainers instead of H2 for integration tests") 2. **What context or problem forced this decision?** (constraints, alternatives considered) 3. **What are the consequences?** (trade-offs, follow-up work required) 4. **Status:** `Accepted` / `Proposed` / `Deprecated` (default: `Accepted`)

Detect next ID

Scan existing ADR files matching `NNNN-*.md` in the ADR directory. Use the next sequential number, zero-padded to 4 digits (e.g., `0001`, `0002`).

Generate the file

**File:** `docs/adr/{NNNN}-{kebab-case-title}.md`

# {NNNN}. {Title}

**Date:** {YYYY-MM-DD}
**Status:** {Accepted | Proposed | Deprecated | Superseded by [{MMMM}]({MMMM}-*.md)}

## Context

{Context: the forces at play, the problem being solved, why a decision was needed.
Include alternatives that were considered.}

## Decision

{The decision that was made. State it clearly and directly.}

## Consequences

### Positive
- {benefit 1}
- {benefit 2}

### Negative / Trade-offs
- {trade-off 1}
- {trade-off 2}

### Neutral
- {neutral consequence, e.g., "requires updating CI pipeline"}

Java-specific templates

Offer these pre-filled templates based on common Java decisions:

**Build tool choice (Maven vs Gradle):**

• Context: Team familiarity, CI tooling, multi-module requirements
• Consequences: Maven = verbose XML but universal tooling; Gradle = flexible DSL but steeper learning curve

**JPA provider (Hibernate vs EclipseLink):**

• Context: Spring Boot default, community support, performance needs

**Database migration tool (Flyway vs Liquibase):**

• Context: SQL vs XML/YAML migrations, team preference, rollback support

**Testing strategy (H2 vs Testcontainers):**

• Context: Speed vs production fidelity trade-off
• Consequences: H2 = fast but dialect differences; Testcontainers = real DB but slower CI

**API versioning strategy (URL path vs header vs content negotiation):**

• Context: Client compatibility, REST maturity, API gateway constraints

**Logging framework (Logback vs Log4j2):**

• Context: Spring Boot default, async logging needs, configuration format preference

**Java version for project:**

• Context: LTS versions (8, 11, 17, 21), library compatibility, team tooling

Update the index

After creating the file, append a row to `docs/adr/README.md`:

| {NNNN} | [{Title}]({NNNN}-{slug}.md) | {Status} | {Date} |

---

Command: list

Read all `*.md` files in the ADR directory (excluding `README.md`). Output:

Architecture Decision Records — docs/adr/

ID    Status      Date        Title
----  ----------  ----------  -----------------------------------------
0001  Accepted    2026-01-15  Use Testcontainers for integration tests
0002  Accepted    2026-02-03  Adopt Flyway for database migrations
0003  Superseded  2026-03-01  Use H2 for integration tests
0004  Proposed    2026-04-03  Migrate to Java 21 virtual threads

4 records (2 accepted · 1 proposed · 1 superseded)

---

Command: show

Read and display the requested ADR formatted cleanly. If the ID is not found, list available IDs.

---

Command: supersede

1. Open the existing ADR (`<id>`) 2. Change its status line to: `Superseded by [MMMM](MMMM-*.md)` 3. Create the new ADR (same flow as `new`) with status `Accepted` 4. Add a line to the new ADR: `Supersedes [{id}]({id}-*.md)`

---

Step 3 — Commit prompt

After creating or updating an ADR, suggest:

git add docs/adr/
git commit -m "docs(adr): add ADR-{NNNN} — {title}"

Step 4 — Next Steps

After creating an ADR, offer:

• *"Run `/java-adr list` to see all decisions"*
• *"Use the `java-architect` agent to review the architectural approach in this ADR"*