Decision Log
Check DECISIONS.md before making architectural choices. Past decisions exist for reasons that aren't obvious from code alone.
The Rule
Before any architectural choice, check for DECISIONS.md. This includes:
- •Adding new entities or data models
- •Choosing between implementation patterns
- •Selecting libraries or approaches
- •Any non-obvious technical trade-off
Red Flags - STOP and Check DECISIONS.md
- •Adding an ID field to any entity
- •Creating shared behavior (inheritance vs composition?)
- •Adding user-facing changes (feature flags?)
- •Choosing data formats, protocols, or storage
- •"This is simple, I'll just..."
Time pressure is not an excuse. Urgent tasks still require checking. A wrong choice made quickly creates more work than checking first.
| Rationalization | Reality |
|---|---|
| "This is too small to check" | Small choices compound. ID format affects entire codebase. |
| "I already know there's nothing relevant" | You don't know what you don't know. Check anyway. |
| "The file probably doesn't exist" | Takes 2 seconds to verify. Check. |
| "Checking will slow me down" | Wrong choice creates more rework than checking. |
| "This is obvious/standard" | Project-specific decisions override industry defaults. |
Workflow
dot
digraph decision_flow {
"Architectural choice needed" [shape=box];
"DECISIONS.md exists?" [shape=diamond];
"Relevant precedent?" [shape=diamond];
"Apply and cite decision" [shape=box];
"Uncertain if applies?" [shape=diamond];
"Ask user" [shape=box];
"Proceed with choice" [shape=box];
"Offer to log if non-obvious" [shape=box];
"Architectural choice needed" -> "DECISIONS.md exists?";
"DECISIONS.md exists?" -> "Relevant precedent?" [label="yes"];
"DECISIONS.md exists?" -> "Proceed with choice" [label="no"];
"Relevant precedent?" -> "Apply and cite decision" [label="yes"];
"Relevant precedent?" -> "Uncertain if applies?" [label="no exact match"];
"Uncertain if applies?" -> "Ask user" [label="yes"];
"Uncertain if applies?" -> "Proceed with choice" [label="no"];
"Proceed with choice" -> "Offer to log if non-obvious";
}
When Applying a Decision
Cite it explicitly:
"Per DECISIONS.md (2024-11-15), using UUID for the product ID rather than auto-increment integer."
After Resolving Non-Obvious Choices
If you and the user worked through a technical trade-off, offer:
"This decision about X might be worth logging in DECISIONS.md for future reference. Want me to add it?"
What Belongs in DECISIONS.md
- •Foundational architectural choices with rationale
- •Conditional trade-offs (when X, do Y because Z)
- •Domain knowledge not obvious from code
What Doesn't Belong
- •Patterns already visible in existing code
- •Temporary fixes or debugging choices
- •Style preferences (put in CLAUDE.md)