adr-writer

To document architecture decisions with rationale, you record multiple viable options, their trade-offs, criteria, risks, and supporting evidence using a standard Markdown template, ensuring decisions remain auditable and revisitable over time.

The best way to structure an architecture decision record is to use a standard ADR Markdown template that captures context, options, decision, and evidence, linking decisions to canonical context documents like ARCHITECTURE.md for traceability.

You need to create an ADR when teams face multiple viable approaches affecting interfaces, timing, safety, or protocols, and when formal architecture decision documentation is required to ensure traceability across the project.

You store and version architecture decision records by generating ADR Markdown files under the docs/decisions directory, allowing them to be tracked, reviewed, and linked to context documents like PROJECT_CONTEXT.md within your version control system.

Yes, you can link architecture decision records to existing context documents such as PROJECT_CONTEXT.md and ARCHITECTURE.md, maintaining traceability between your architectural choices and the broader project context.

Standard ADR templates capture options, criteria, risks, and evidence effectively but require manual maintenance to stay relevant, relying on consistent linking to canonical context documents to prevent documentation drift over time.