0. Use Markdown Architectural Decision Records

Date: 2025-10-09

Status

Proposed

Context

We need to record the architectural decisions made on this project.

Decision

We will use Architecture Decision Records, as described by Michael Nygard in this article.

Consequences

Positive

• One ADR describes one significant decision for a specific project.
• The consequences of one ADR are very likely to become the context for subsequent ADRs.
• Developers and project stakeholders can see the ADRs, even as the team composition changes over time.
• The motivation behind previous decisions is visible for everyone, present and future.

References

• Michael Nygard's article
• iOS eng Presentation
• Why write ADRs
• Earn maintainers esteem with ADRs