| name | ts-ddd-adr-writer |
| description | Write a structured Architecture Decision Record (ADR) for any technology or design choice in a TypeScript DDD clean architecture project. Trigger when the user says "document this decision", "write an ADR", "why did we choose X", "we decided to use Y instead of Z", "record this architecture choice", or when a significant design trade-off is being discussed and should be captured for the team. Also trigger when the user debates between two patterns (e.g. TypeORM vs Prisma, REST vs gRPC, monolith vs microservices). |
ADR Writer — TypeScript DDD
Produce a clear, concise Architecture Decision Record that captures the context, trade-offs, and outcome of a design decision. Good ADRs are written at decision time, not retrospectively — they record what was known and what was uncertain when the decision was made.
ADR file location
Save ADRs to docs/adr/ using the naming convention:
docs/adr/NNNN-short-title-in-kebab-case.md
Increment NNNN from the highest existing number. If no ADRs exist yet, start at 0001.
ADR template
Use this exact structure:
# ADR-NNNN: [Title — one sentence, imperative mood]
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Deciders:** [roles or names, e.g. "System Architect, Backend Lead"]
**Tags:** [domain, infrastructure, testing, security, etc.]
---
## Context
[2-4 sentences. What problem or constraint forced this decision? What is the current state of the system? What are the forces at play — technical constraints, team skills, time pressure, compliance requirements?]
## Decision Drivers
- [Most important criterion — e.g. "must not couple domain layer to ORM"]
- [Second criterion]
- [Third criterion]
## Considered Options
| Option | Summary |
|--------|---------|
| **Option A** | [one-line description] |
| **Option B** | [one-line description] |
| **Option C** | [one-line description, if applicable] |
## Decision
**We chose Option [X].**
[1-2 sentences explaining the primary reason.]
## Consequences
### Positive
- [concrete benefit this decision enables]
- [another benefit]
### Negative / Trade-offs
- [concrete cost or constraint introduced]
- [another trade-off]
### Neutral
- [things that change but are neither good nor bad]
## Option Analysis
### Option A — [Name]
**Pros:** ...
**Cons:** ...
### Option B — [Name]
**Pros:** ...
**Cons:** ...
## Implementation Notes
[Optional. Specific things the team must do or avoid when implementing this decision. Reference specific files or patterns if relevant.]
## Links
- [Related ADR, RFC, or ticket]
- [External reference, doc, or benchmark]
Quality rules
- Status is always set. Default to
Proposed if the decision hasn't been ratified yet.
- Context explains the why, not the what. Avoid restating the decision in the context section.
- Decision drivers are ranked by importance — the most critical constraint first.
- Consequences are honest. Every decision has trade-offs. If the "Negative" section is empty, dig deeper.
- Implementation notes are optional — only include them if there's something non-obvious the reader needs to know to implement the decision correctly.
- Tags enable filtering — always tag with the layer (domain, application, infrastructure, presentation) and concern (orm, auth, testing, observability, etc.)
DDD-specific context prompts
When writing ADRs for DDD decisions, consider surfacing these forces:
- Does this decision affect the dependency rule? (Does it risk infrastructure concerns leaking into domain?)
- Does it change the ubiquitous language? (Does a library force different naming than the domain model?)
- Does it affect aggregate boundaries? (Does the choice constrain how we model consistency boundaries?)
- Does it introduce a shared kernel or anti-corruption layer requirement?
Example titles (good)
Use Prisma as the ORM for infrastructure layer implementationsAdopt CQRS for read-heavy bounded contexts onlyEnforce one aggregate per transaction as the consistency boundaryUse Domain Events over direct service calls for cross-context communication
Example titles (bad — too vague)
Database choiceWe picked PrismaArchitecture update
