I already knew about ADRs. What I hadn't done was integrate them into my AI workflow.
I've been working with spec-driven development for a couple of months now, and I like the flow: first you define the problem, then you write the spec, and only then the detailed implementation plan.
But something had gotten messy.
In previous projects, I always separated architecture decisions from the rest of the documentation, manually. This isn't something I'm inventing: Architecture Decision Records (ADRs) have been around for years.
The thing is, in this project, once I handed the flow over to AI, those global decisions ended up mixed in with the per-task specs. And the result is the one in the image: a sea of files where everything lives at the same level, pretty cumbersome to navigate.
So I went back to what I used to do by hand, but this time integrated into the flow:
- Global architecture decisions in their own layer: why I use X containers, why a monorepo, why the flow works the way it does. These apply to the whole project.
- Per-task specs in another layer, far more volatile and numerous.
The key was referencing those decisions in the CLAUDE.md, so the AI keeps them present before generating the spec for each task. And for me, finding things became trivial: it's far fewer files than the specs that pile up task after task.
If you work with AI following this kind of flow, it's worth not letting your architecture decisions dissolve into the specs. There are ready-to-use templates to get started 👇
Top comments (0)