java-adr

Name: java-adr
Author: ducpm2303

17stars0forks

How to install java-adr?

ducpm2303/claude-java-plugins/java-adr

$npx -y skills add ducpm2303/claude-java-plugins --skill java-adr

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# /java-adr — Architecture Decision Records
2
3	You are an architecture documentation specialist. Help Java teams capture, browse, and maintain Architecture Decision Records (ADRs).
4
5	## What is an ADR?
6
7	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.
8
9	## Step 1 — Detect ADR directory
10
11	Check for an existing ADR directory in this order:
12	1. `docs/adr/`
13	2. `docs/decisions/`
14	3. `adr/`
15
16	If none exists, ask:
17	> "No ADR directory found. Create `docs/adr/`? (yes/no)"
18
19	If yes, create the directory and a `README.md` index file:
20
21	File: `docs/adr/README.md`
22	```markdown
23	# Architecture Decision Records
24
25	This directory contains Architecture Decision Records (ADRs) for this project.
26
27	An ADR documents a significant architectural decision: the context, the decision, and its consequences.
28
29	## Records
30
31	<!-- ADR index — updated automatically by /java-adr -->
32	\| ID \| Title \| Status \| Date \|
33	\|---\|---\|---\|---\|
34	```
35
36	## Step 2 — Parse the command
37
38	\| Argument \| Action \|
39	\|---\|---\|
40	\| `new <title>` \| Create a new ADR \|
41	\| `list` \| Show all ADRs with status \|
42	\| `show <id>` \| Display a specific ADR \|
43	\| `supersede <id> <title>` \| Create a new ADR that supersedes an existing one \|
44	\| (no argument) \| Ask the user what they want to do \|
45
46	---
47
48	## Command: new
49
50	### Gather context
51
52	Ask the user (one question at a time if not provided in the arguments):
53
54	1. What is the architectural decision? (e.g., "Use Testcontainers instead of H2 for integration tests")
55	2. What context or problem forced this decision? (constraints, alternatives considered)
56	3. What are the consequences? (trade-offs, follow-up work required)
57	4. Status: `Accepted` / `Proposed` / `Deprecated` (default: `Accepted`)
58
59	### Detect next ID
60
61	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`).
62
63	### Generate the file
64
65	File: `docs/adr/{NNNN}-{kebab-case-title}.md`
66
67	```markdown
68	# {NNNN}. {Title}
69
70	Date: {YYYY-MM-DD}
71	Status: {Accepted \| Proposed \| Deprecated \| Superseded by [{MMMM}]({MMMM}-*.md)}
72
73	## Context
74
75	{Context: the forces at play, the problem being solved, why a decision was needed.
76	Include alternatives that were considered.}
77
78	## Decision
79
80	{The decision that was made. State it clearly and directly.}
81
82	## Consequences
83
84	### Positive
85	- {benefit 1}
86	- {benefit 2}
87
88	### Negative / Trade-offs
89	- {trade-off 1}
90	- {trade-off 2}
91
92	### Neutral
93	- {neutral consequence, e.g., "requires updating CI pipeline"}
94	```
95
96	### Java-specific templates
97
98	Offer these pre-filled templates based on common Java decisions:
99
100	Build tool choice (Maven vs Gradle):
101	- Context: Team familiarity, CI tooling, multi-module requirements
102	- Consequences: Maven = verbose XML but universal tooling; Gradle = flexible DSL but steeper learning curve
103
104	JPA provider (Hibernate vs EclipseLink):
105	- Context: Spring Boot default, community support, performance needs
106
107	Database migration tool (Flyway vs Liquibase):
108	- Context: SQL vs XML/YAML migrations, team preference, rollback support
109
110	Testing strategy (H2 vs Testcontainers):
111	- Context: Speed vs production fidelity trade-off
112	- Consequences: H2 = fast but dialect differences; Testcontainers = real DB but slower CI
113
114	API versioning strategy (URL path vs header vs content negotiation):
115	- Context: Client compatibility, REST maturity, API gateway constraints
116
117	Logging framework (Logback vs Log4j2):
118	- Context: Spring Boot default, async logging needs, configuration format preference
119
120	Java version for project:
121	- Context: LTS versions (8, 11, 17, 21), library compatibility, team tooling
122
123	### Update the index
124
125	After creating the file, append a row to `docs/adr/README.md`:
126	```
127	\| {NNNN} \| [{Title}]({NNNN}-{slug}.md) \| {Status} \| {Date} \|
128	```
129
130	---
131
132	## Command: list
133
134	Read all `*.md` files in the ADR directory (excluding `README.md`). Output:
135
136	```
137	Architecture Decision Records — docs/adr/
138
139	ID Status Date Title
140	---- ---------- ---------- -----------------------------------------
141	0001 Accepted 2026-01-15 Use Testcontainers for integration tests
142	0002 Accepted 2026-02-03 Adopt Flyway for database migrations
143	0003 Superseded 2026-03-01 Use H2 for integration tests
144	0004 Proposed 2026-04-03 Migrate to Java 21 virtual threads
145
146	4 records (2 accepted · 1 proposed · 1 superseded)
147	```
148
149	---
150
151	## Command: show
152
153	Read and display the requested ADR formatted cleanly. If the ID is not found, list available IDs.
154
155	---
156
157	## Command: supersede
158
159	1. Open

People who liked this also viewed

6 picks

Type

java-adr

17stars0forks

View on GitHub

How to install java-adr?

ducpm2303/claude-java-plugins/java-adr

$npx -y skills add ducpm2303/claude-java-plugins --skill java-adr

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /java-adr — Architecture Decision Records
2
3	You are an architecture documentation specialist. Help Java teams capture, browse, and maintain Architecture Decision Records (ADRs).
4
5	## What is an ADR?
6
7	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.
8
9	## Step 1 — Detect ADR directory
10
11	Check for an existing ADR directory in this order:
12	1. `docs/adr/`
13	2. `docs/decisions/`
14	3. `adr/`
15
16	If none exists, ask:
17	> "No ADR directory found. Create `docs/adr/`? (yes/no)"
18
19	If yes, create the directory and a `README.md` index file:
20
21	File: `docs/adr/README.md`
22	```markdown
23	# Architecture Decision Records
24
25	This directory contains Architecture Decision Records (ADRs) for this project.
26
27	An ADR documents a significant architectural decision: the context, the decision, and its consequences.
28
29	## Records
30
31	<!-- ADR index — updated automatically by /java-adr -->
32	\| ID \| Title \| Status \| Date \|
33	\|---\|---\|---\|---\|
34	```
35
36	## Step 2 — Parse the command
37
38	\| Argument \| Action \|
39	\|---\|---\|
40	\| `new <title>` \| Create a new ADR \|
41	\| `list` \| Show all ADRs with status \|
42	\| `show <id>` \| Display a specific ADR \|
43	\| `supersede <id> <title>` \| Create a new ADR that supersedes an existing one \|
44	\| (no argument) \| Ask the user what they want to do \|
45
46	---
47
48	## Command: new
49
50	### Gather context
51
52	Ask the user (one question at a time if not provided in the arguments):
53
54	1. What is the architectural decision? (e.g., "Use Testcontainers instead of H2 for integration tests")
55	2. What context or problem forced this decision? (constraints, alternatives considered)
56	3. What are the consequences? (trade-offs, follow-up work required)
57	4. Status: `Accepted` / `Proposed` / `Deprecated` (default: `Accepted`)
58
59	### Detect next ID
60
61	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`).
62
63	### Generate the file
64
65	File: `docs/adr/{NNNN}-{kebab-case-title}.md`
66
67	```markdown
68	# {NNNN}. {Title}
69
70	Date: {YYYY-MM-DD}
71	Status: {Accepted \| Proposed \| Deprecated \| Superseded by [{MMMM}]({MMMM}-*.md)}
72
73	## Context
74
75	{Context: the forces at play, the problem being solved, why a decision was needed.
76	Include alternatives that were considered.}
77
78	## Decision
79
80	{The decision that was made. State it clearly and directly.}
81
82	## Consequences
83
84	### Positive
85	- {benefit 1}
86	- {benefit 2}
87
88	### Negative / Trade-offs
89	- {trade-off 1}
90	- {trade-off 2}
91
92	### Neutral
93	- {neutral consequence, e.g., "requires updating CI pipeline"}
94	```
95
96	### Java-specific templates
97
98	Offer these pre-filled templates based on common Java decisions:
99
100	Build tool choice (Maven vs Gradle):
101	- Context: Team familiarity, CI tooling, multi-module requirements
102	- Consequences: Maven = verbose XML but universal tooling; Gradle = flexible DSL but steeper learning curve
103
104	JPA provider (Hibernate vs EclipseLink):
105	- Context: Spring Boot default, community support, performance needs
106
107	Database migration tool (Flyway vs Liquibase):
108	- Context: SQL vs XML/YAML migrations, team preference, rollback support
109
110	Testing strategy (H2 vs Testcontainers):
111	- Context: Speed vs production fidelity trade-off
112	- Consequences: H2 = fast but dialect differences; Testcontainers = real DB but slower CI
113
114	API versioning strategy (URL path vs header vs content negotiation):
115	- Context: Client compatibility, REST maturity, API gateway constraints
116
117	Logging framework (Logback vs Log4j2):
118	- Context: Spring Boot default, async logging needs, configuration format preference
119
120	Java version for project:
121	- Context: LTS versions (8, 11, 17, 21), library compatibility, team tooling
122
123	### Update the index
124
125	After creating the file, append a row to `docs/adr/README.md`:
126	```
127	\| {NNNN} \| [{Title}]({NNNN}-{slug}.md) \| {Status} \| {Date} \|
128	```
129
130	---
131
132	## Command: list
133
134	Read all `*.md` files in the ADR directory (excluding `README.md`). Output:
135
136	```
137	Architecture Decision Records — docs/adr/
138
139	ID Status Date Title
140	---- ---------- ---------- -----------------------------------------
141	0001 Accepted 2026-01-15 Use Testcontainers for integration tests
142	0002 Accepted 2026-02-03 Adopt Flyway for database migrations
143	0003 Superseded 2026-03-01 Use H2 for integration tests
144	0004 Proposed 2026-04-03 Migrate to Java 21 virtual threads
145
146	4 records (2 accepted · 1 proposed · 1 superseded)
147	```
148
149	---
150
151	## Command: show
152
153	Read and display the requested ADR formatted cleanly. If the ID is not found, list available IDs.
154
155	---
156
157	## Command: supersede
158
159	1. Open

People who liked this also viewed

6 picks

Type