documentation-and-adrs

1# Documentation and ADRs
2 
3## Overview
4 
5Document decisions, not just code. The most valuable documentation captures the *why* — the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase.
6 
7## When to Use
8 
9- Making a significant architectural decision
10- Choosing between competing approaches
11- Adding or changing a public API
12- Shipping a feature that changes user-facing behavior
13- Onboarding new team members (or agents) to the project
14- When you find yourself explaining the same thing repeatedly
15 
16**When NOT to use:** Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
17 
18## Architecture Decision Records (ADRs)
19 
20ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.
21 
22### When to Write an ADR
23 
24- Choosing a framework, library, or major dependency
25- Designing a data model or database schema
26- Selecting an authentication strategy
27- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
28- Choosing between build tools, hosting platforms, or infrastructure
29- Any decision that would be expensive to reverse
30 
31### Match the existing convention first
32…