The event sourcing analogy really clicks. I've been using ADRs (Architecture Decision Records) in repos for years but they always end up as this forgotten folder nobody reads. The @decision annotation in actual code is what makes this different — it's context right at the point where you need it, not buried in docs/.
The part about specs drifting is spot on too. I've worked on projects where we maintained Confluence pages alongside the code and within 3 months they were basically fiction. Append-only log avoids that whole class of problem.
One question though — how do you handle decision density? In a large codebase, I could see the number of annotations getting noisy. Like, at what point does "check DL-045 before touching this" start feeling like the same overhead as reading through a spec doc? Have you found a natural limit where you stop annotating?
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
The event sourcing analogy really clicks. I've been using ADRs (Architecture Decision Records) in repos for years but they always end up as this forgotten folder nobody reads. The
@decisionannotation in actual code is what makes this different — it's context right at the point where you need it, not buried in docs/.The part about specs drifting is spot on too. I've worked on projects where we maintained Confluence pages alongside the code and within 3 months they were basically fiction. Append-only log avoids that whole class of problem.
One question though — how do you handle decision density? In a large codebase, I could see the number of annotations getting noisy. Like, at what point does "check DL-045 before touching this" start feeling like the same overhead as reading through a spec doc? Have you found a natural limit where you stop annotating?