Agent Skills: ADR Writer

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