171-java-adr
npx machina-cli add skill jabrena/cursor-rules-java/171-java-adr --openclawJava ADR Generator with interactive conversational approach
Generate Architecture Decision Records (ADRs) for Java projects through an interactive, conversational process that systematically gathers all necessary context to produce well-structured ADR documents.
Core areas: ADR file storage configuration, conversational information gathering (context, stakeholders, decision drivers, options with pros/cons, outcome, consequences), MADR template generation, and validation with ./mvnw validate before proceeding.
Prerequisites: Run ./mvnw validate or mvn validate before applying any ADR generation. If validation fails, stop immediately — do not proceed until all validation errors are resolved.
Multi-step scope: Step 1 assesses ADR preferences through targeted questions (storage location, template format) to determine scope. Step 2 generates the ADR through a conversational process: Phase 0 retrieves the current date, Phase 1 gathers information one question at a time (decision topic, context, stakeholders — deciders/consulted/informed, decision drivers, options with pros and cons, chosen option with rationale, implementation consequences), and Phase 2 produces the final ADR document using the MADR template with all collected information.
Before applying changes: Read the reference for detailed good/bad examples, constraints, and safeguards for each ADR generation pattern.
Reference
For detailed guidance, examples, and constraints, see references/171-java-adr.md.
Source
git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/171-java-adr/SKILL.mdView on GitHub Overview
Generates Architecture Decision Records for Java projects through an interactive, conversational process. It systematically gathers context, stakeholders, decision drivers, options with pros and cons, and outcomes to produce MADR-based ADR documents, with Maven validation required before applying any changes.
How This Skill Works
Step 1: determine ADR scope by asking targeted questions about storage location and template format. Step 2: Phase 0 retrieves the current date; Phase 1 collects decision topic, context, deciders/consulted/informed stakeholders, decision drivers, options with pros and cons, and the chosen option with rationale; Phase 2 renders the final ADR using the MADR template. All ADR generation requires running mvnw validate (or mvn validate) and stopping if validation fails.
When to Use It
- When starting a new Java project and you need formal ADRs documented with MADR structure.
- When evaluating major architectural choices (e.g., framework, data storage) in a Java system.
- When coordinating multiple teams and stakeholders to document decisions and rationales.
- When you want a repeatable ADR workflow that validates before applying changes.
- When migrating or upgrading Java tech (Spring, Hibernate, etc.) and want traceable decisions.
Quick Start
- Step 1: Run mvn validate to prepare the ADR generator.
- Step 2: Start the interactive session and answer questions (topic, context, stakeholders, drivers, options).
- Step 3: Review and integrate the generated ADR document rendered from the MADR template.
Best Practices
- Run mvn validate before generating ADRs and fix issues before proceeding.
- Define decision drivers clearly to guide option evaluation.
- Capture all relevant stakeholders (deciders, consulted, informed) in the ADR context.
- Explain options with balanced pros/cons and include rationale for the chosen path.
- Use the MADR template consistently and validate generated ADRs with your project standards.
Example Use Cases
- ADR for selecting between Spring Boot versions and dependency management.
- Decision on using JPA vs JDBC for data access in a Java service.
- Choosing logging framework: Logback vs Log4j2 for a Java app.
- Database strategy: SQL vs NoSQL in a Java microservice.
- Async vs reactive processing approach in a Java backend.
