/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"