adr-writer

Skill for creating and editing Architecture Decision Records (ADRs). Use when requests involve "create ADR", "record architecture decision", or "document design decisions". Supports creating new ADRs, updating existing ADRs, and reviewing ADR format.

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 20, 2025⬇️2downloads

When & Why to Use This Skill

The ADR Writer skill streamlines the creation and management of Architecture Decision Records (ADRs), ensuring that critical software design choices are documented consistently. By enforcing a standardized markdown format—including context, decision rationale, consequences, and alternatives—it helps engineering teams maintain a clear, searchable history of their technical evolution and improves long-term project maintainability.

Use Cases

  • Recording major architectural shifts, such as selecting a specific database or migrating to a microservices pattern, to capture the 'why' behind the change.
  • Onboarding new developers by providing a structured history of design decisions and the trade-offs considered during the project's lifecycle.
  • Standardizing documentation across a large engineering organization by enforcing strict naming conventions and file structures for all design records.
  • Facilitating technical reviews by generating clear, pseudocode-based descriptions of architectural decisions without cluttering records with implementation-specific code.
nameadr-writer
descriptionSkill for creating and editing Architecture Decision Records (ADRs). Use when requests involve "create ADR", "record architecture decision", or "document design decisions". Supports creating new ADRs, updating existing ADRs, and reviewing ADR format.

ADR Writer

A skill for creating Architecture Decision Records (ADRs). Generates ADRs following project-specific format conventions.

ADR Format

File Naming Convention

adr-NNN-short-description-in-english-with-hyphens.md

Example: adr-002-new-feature.md

Storage Location

docs/adr/

Structure

# Title (in English)

## Status

Approved

## Context

Describe the background, challenges, and current issues. Follow the flow: facts → challenges → what you want to solve.
Use lists to enumerate facts and issues. Avoid adding sub-headers; prefer prose and lists within this section.

## Decision

Start with a brief summary of the overall decision (1-2 paragraphs). Then, if there are multiple decisions, create a sub-section for each (e.g., ### Decision 1).
However, avoid creating too many sub-sections unnecessarily. Use tables or Mermaid diagrams as needed.

**Important**: Do NOT include implementation-specific code. Use pseudocode only to illustrate concepts.

## Consequences

### Positive

- Positive outcomes and benefits

### Negative

- Negative outcomes, drawbacks, and trade-offs

### Neutral

- Neutral impacts and side effects

## Notes

### Alternatives Considered

- **Alternative A**: Reason for not adopting
- **Alternative B**: Reason for not adopting

### References

- Related ADRs and external resources

Creation Steps

  1. Determine next ADR number: Check existing files in docs/adr/ to determine the next number
  2. Use example: Refer to assets/adr-example.md
  3. Fill in each section:
    • Title should be concise and in English
    • Context/Decision/Consequences/Notes should be detailed and in Japanese
    • Add code blocks, tables, and Mermaid diagrams as needed
  4. Save file: Save as docs/adr/adr-NNN-description.md

Examples

  • assets/adr-example.md - Structure template with explanations
  • Before writing, read the two most recent ADRs in docs/adr/ to understand the current format and writing style

Writing Guidelines

  • Status: Always set to "Approved"
  • Strict structure adherence: Follow the defined ADR format strictly. Before adding any new headers or sections, carefully consider whether it is truly necessary. Prefer using lists or prose within existing sections
  • Context: Clearly explain "why this decision is needed now"
  • Decision: Be specific and implementation-ready. Avoid vague expressions
  • Code examples: Never include implementation-specific code from the actual codebase. Use pseudocode only to illustrate concepts and help readers understand the design. Pseudocode should be language-agnostic and focus on the "what" rather than the "how"
  • Consequences: Honestly describe both benefits and drawbacks. No solution is perfect
  • Alternatives Considered: Document alternatives that were considered and explain why they were not adopted