Like many developers, I’ve been experimenting with LLM code development. Over the past 6 months or so I’ve landed on a model that I call Recommendation Decisioning Records or RDRs.
When prompting code directly via an LLM like Claude Code, I found myself in a corner more than once. This was especially true for complex features. Being stubborn, I felt I could prompt myself out of it without having to discard the code I had spent the last few hours generating. I learned a lot over the past few hours and all of it was in my head or locked in the codebase. The idea of throwing the code away felt wasteful.
I almost never prompted myself out of the corners.
Architectural Decision Records are a great way to document a decision. They are created, discussed, revised, and then agreed on. When I write an ADR I’m also writing the code to better understand the problem. My ADRs are documentation, but also the journey. They capture why I landed on the decision.
An RDR is a prompt. It is the journey to a decision. It is a specification. It has the background as to why I want things the way I want them. It captures the hard won discoveries about the problem I couldn’t originally articulate or technical details that I had to search through research and source code to find.
An RDR is also not code and is subsequently more concise.
This model is context engineering. The problem I want to design and solve is bigger than the LLM context I can work with to find a reasonable implementation. My context and subsequent purpose start to drift as I start coding. Because the moment I start coding, I discover new problems or options, and every side-quest throws me off track.
So the solution was to not start coding, but to start specifying and defining and researching.
An RDR is the specification for a single cohesive concept.
When faced with a related set of new features or designs, I create multiple RDRs, before coding, in order to maintain conceptual integrity across the design and reduce coupling between the components. You can see an example here in my Arcaneum project RDRs.
How to get started?
Copy the relevant bits from the RDR repository. Then ask Claude to create a new RDR using the README.md and TEMPLATE.md for guidance for a given problem statement. For example, “I need a logging utility that will mask PII and emit structured logs”. Once the file is created, I’ll ask to research the source code ecosystem for any existing libraries or utilities. In this particular case, I might realize I’m conflating two issues. PII masking and structured logging causing me to create two RDRs instead of one where I crisply define PII masking in the first and then how to leverage that solution best in the second RDR.
Some notes.
Ensure you use the RDR to identify multiple options/solutions to the problem statement. I find as I get to know the problem better, an originally less attractive option may float up as the best solution.
I lock down an RDR before implementation. If I got the design wrong on the RDR, I throw the code out and revise the RDR itself. I’m not terribly strict about this, but if you find yourself meandering away from the original RDR, reconsider.
I never delete an RDR, but if I find it no longer relevant, I mark it unimplemented or abandoned. I’ve also reverted an RDR after implementation.
Mentioned above, stack RDRs that are related and cross reference them for conceptual integrity.
I use Arcaneum to index source code dependencies that I may be leveraging or deciding to use in a design option. This prevents API hallucinations, which I find common. Use the RDR to capture any hidden flags or APIs that are relevant.
RDRs do end up with a fair amount of code in them to capture API usage etc. This is ok, but I’ve been trying to bias toward pseudo-code vs actual code where I can to reduce the token count.
The final solution, the actual implementation, will inevitably drift from the RDR. The goal of the RDR is to prevent the drift happening too early in the cycle, because once it begins it’s too hard to get back into focus. At some point I’ll begin capturing the drift in a post-mortem document to accompany the RDR so that I can better craft future RDRs via an improved template. This is one reason I recommend to lock the RDR before implementation (in a single git commit) so the gaps and methods to prevent the gaps can be reasoned about.
