ADR-0000: Use ADRs for Architecture Decisions#
Status: Accepted Date: 2026-04-24
Context#
The ai-connectors mono-repo has grown to span multiple MCP servers (SharePoint, Outlook, Teams, and more planned), shared infrastructure patterns, and cross-cutting concerns such as authentication, audit logging, and deployment. Significant design decisions — such as choosing the OBO auth strategy, structuring Terraform with a single-folder Terragrunt approach, or deciding whether to share code across connectors — are currently captured only in pull request descriptions and GitHub issue comments.
This makes it difficult for new team members to understand why the system is shaped the way it is, and for existing team members to recall the reasoning behind past choices when revisiting an area of the codebase months later. PR descriptions are hard to discover and often mix implementation detail with rationale.
Decision#
We will use Architecture Decision Records (ADRs) to document significant architectural and design decisions. ADRs are stored as numbered markdown files in docs/adrs/ and are browsable directly on GitHub.
Each ADR captures the context, decision, consequences, and alternatives considered for a single decision. ADRs are immutable once accepted; to reverse a decision, a new ADR is created that supersedes the original.
Consequences#
Positive#
- Decisions and their rationale are discoverable in a single, well-known location
- New team members can read the ADR log to understand the system's evolution
- The act of writing an ADR encourages clearer thinking about trade-offs before committing to an approach
Negative#
- Adds a lightweight process step when making significant decisions
- ADRs can become stale if the team forgets to supersede them when direction changes
Risks#
- Over-documenting trivial decisions could reduce the signal value of the ADR log. The team should reserve ADRs for decisions that are hard to reverse or that future readers would benefit from understanding.
Relationship to GitHub Issues#
ADRs and GitHub issues serve complementary but distinct purposes:
| ADR | GitHub Issue | |
|---|---|---|
| Purpose | Record an architectural decision | Track work to be done |
| Mutability | Immutable once accepted | Closed when resolved |
| Focus | Why — rationale and trade-offs | What — tasks, acceptance criteria |
| Timing | Written when a decision is made | Opened when work is identified |
| Audience | Future readers asking "why is it this way?" | Current team planning and executing work |
| Location | docs/adrs/NNNN-title.md |
GitHub Issues |
When to use each#
- Use an ADR when you are choosing between architectural approaches (e.g., "share auth code via a library vs. duplicate per service") and want to record the reasoning.
- Use a GitHub issue when you have a piece of work that needs to be tracked, discussed, or planned.
- Both can coexist: A GitHub issue might trigger a decision that deserves an ADR (e.g., issue #104 led to ADR-0001).
Alternatives Considered#
Rely on PR descriptions#
PR descriptions are already written but are tied to individual changes and hard to find later. They also mix rationale with implementation notes, making them less useful as a decision record.
Confluence or wiki pages#
A wiki provides more formatting options but introduces a separate tool and URL namespace. Keeping decision records in the repository ensures they travel with the code and are versioned alongside it.