adr

Architecture Decision Record (ADR)

Create a new ADR to document the architectural decision described by the user: $ARGUMENTS

Steps

0. Read language configuration from .aidocs/config.yaml (or .aidocs/config.yml):

   ! cat .aidocs/config.yaml 2>/dev/null || cat .aidocs/config.yml 2>/dev/null || echo "language: en"

   Extract the language field (default: en if neither file exists or the field is absent). All content written to .aidocs/ must be in this language.

1. Review existing ADRs to understand context and avoid duplicates:

   ! ls .aidocs/adrs/ 2>/dev/null || echo "No ADRs yet"

2. Determine the filename: use today's date and a kebab-case slug derived from the decision title.

   • Format: YYYYMMDD-<description-slug>.md
   • Example: 20260320-adopt-hexagonal-architecture.md

3. Gather context: read relevant source files, configs, or documentation that inform the decision. Ask the user for clarification if the context or motivation is unclear.

4. Write the ADR in .aidocs/adrs/ using the template below. Every section is mandatory — do not skip any.

5. Present the ADR to the user for review before finishing.

ADR Template

# <Title of the decision>

- **Date**: YYYY-MM-DD
- **Status**: Proposed | Accepted | Deprecated | Superseded by [ADR-YYYYMMDD](./YYYYMMDD-slug.md)

## Context

Describe the situation, the forces at play, and why a decision is needed. Include relevant technical constraints, business requirements, and any pressure points.

## Decision

State the decision clearly and concisely. Use active voice: "We will..."

## Consequences

### Positive

- List the benefits and improvements this decision brings.

### Negative

- List the trade-offs, risks, or downsides accepted.

### Neutral

- List any side effects that are neither clearly positive nor negative.

## Alternatives Considered

For each alternative:

### <Alternative name>

- **Description**: Brief explanation of the alternative.
- **Reason for rejection**: Why this option was not chosen.

Guidelines

• Be specific and concrete — avoid vague statements.
• Focus on the why behind the decision, not just the what.
• Reference relevant code paths, libraries, or external resources when applicable.
• Keep language professional but accessible to future readers who may lack full context.
• If this ADR supersedes a previous one, update the status of the superseded ADR to Superseded by [ADR-YYYYMMDD](./YYYYMMDD-slug.md).