What is an ADR?
ADR (Architectural Decision Record): A brief document used to capture a significant architectural choice made by the team. In the AI era, ADRs are the primary tool for combating Knowledge Debt, turning ephemeral "vibe-based" chat decisions into permanent engineering assets.
Why ADRs are Critical for AI Projects
AI coding assistants are great at how to write code, but poor at remembering why it was written that way. Without ADRs:
- Decision Loss: Successive AI prompts drift from original intent (Prompt Drift).
- The "Digital Archaeology" Nightmare: New hires can't explain why a "Magic Black Box" exists.
- Audit Failure: You can't prove human "authorship" for IP protection.
Anatomy of an AI-Era ADR
A Clean Vibe ADR (detailed in Appendix C) includes:
- Context: The specific problem we were trying to solve.
- Decision: The exact architectural choice made (Human Design).
- Alternatives: What else was considered? (Crucial for proving human authorship).
- Consequences: What is the technical debt taken? What are the future constraints?
Example ADR
# ADR-005: Use SSE for real-time updates
- **Status:** Accepted
- **Context:** Need real-time task updates.
- **Decision:** Use Server-Sent Events (SSE) instead of WebSockets.
- **Rationale:** Simpler implementation, less synthetic debt than WebSockets.
- **Consequences:** One-way communication only.
Statistics
90%
Retention of architectural intent
Source: Ch 16
ZERO
Comprehension Debt for documented modules
The ADR Workflow
In Clean Vibe Code, we recommend ADR-First Prompting:
- Human writes the ADR (Design).
- AI reads the ADR (Context).
- AI implements the logic (Implementation).
Related Terms
- Knowledge Debt: What ADRs eliminate.
- Memory File: A lighter, more ephemeral version of an ADR.
- IP Segregation: ADRs prove human design input.
Book Reference
- Chapter 16: Clean Teams — how to use ADRs for coordination.
- Appendix C: Templates for ADRs optimized for AI collaboration.