ADR Introduction
================

Architectural Design Records (ADRs) are short documents that capture a single architectural or design decision, its context, and its consequences. Less is more, keep these brief.
Each ADR is a separate markdown file located in this directory. ADRs provide a clear, version-controlled history of why decisions were made.

See: `Michael Nygard’s ADRs <https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html>`_

Guidelines for Writing ADRs
---------------------------

- **One Decision per ADR:** Each ADR should document a single architectural or design decision.
- **Be Concise:** Focus on clarity and brevity. Avoid unnecessary detail.
- **State the Context:** Clearly describe the background and forces at play that led to the decision.
- **List Alternatives:** Briefly mention other options considered and why they were not chosen.
- **Explain the Decision:** Clearly state what was decided and why.
- **Describe Consequences:** Note the implications, both positive and negative, of the decision.
- **Use Simple Language:** Write for future team members who may not have current context.
- **Version Control:** Store ADRs in version control to track changes and history.
- **Consistent Format:** Use a standard template for all ADRs to ensure consistency.
- **Reference Related ADRs:** Link to previous or related ADRs where relevant.

Following these guidelines helps ensure ADRs are useful, maintainable, and easy to understand.