AI_template/docs/adr

Architecture Decision Records (ADR)

ADRs are short, versioned documents that capture why we made a major architectural/product decision. They prevent “tribal knowledge” and make reversals/migrations explicit.

---

Phase: Phase 0 (Planning)
Status: Draft — adopt in Phase 1
Owner: Tech Leads

When to write an ADR

Create an ADR whenever a decision is:

• hard to reverse later,
• affects multiple modules/teams,
• has meaningful trade‑offs,
• changes default recommendations in /docs.

Examples:

• modular monolith vs microservices,
• Postgres + pgvector vs external vector DB,
• billing model (subscription vs usage),
• RAG vs non‑RAG architecture,
• auth provider choice.

Where ADRs live

One file per decision in docs/adr/.

Naming convention:

• 0001-short-title.md
• 0002-another-decision.md

Status lifecycle: proposed → accepted → (superseded | rejected)

How ADRs relate to RECOMMENDATIONS.md

• RECOMMENDATIONS.md is the current snapshot of locked decisions and constraints.
• ADRs are the history and rationale behind those decisions. Link every ADR from RECOMMENDATIONS.md once accepted.

Template

Start from docs/adr/0000-template.md.