AI coding agents write code confidently, but they don't know why your code looks the way it does. DLD (https://github.com/jimutt/dld-kit) is an ope...
For further actions, you may consider blocking this person and/or reporting abuse
Love this idea and execution. Great write-up
I've been thinking on a similar line, but because I work on graph data in append-only style (Datomic db) I've inevitably been thinking about how decisions in a team on large projects are a growing knowledge graph. I'm pretty convinced that markdown is higher noise to signal than we actually need for an effective LLM tool like this.
I have also seen LLMs operate on Datomic insanely faster than reading directories of markdown files to resolve information and links between information in my system, so why not shift the information about building my system to there too?!
Thank you! You're right, markdown is not going to scale over time in larger projects. I've been thinking about testing different storage and retrieval solutions but keeping the same code "anchoring" and overall process.
With a more robust harness than the current loose collection of skills + bash script one could offer freedom of choice between a number of storage & retrieval options. After all, markdown gives a very low barrier of entry and makes for an easy evaluation, so I'd rather keep it but support an option for larger projects.
The decision-to-code link is the piece most agent workflows skip. We ended up embedding architecture decision records directly in the repo so agents read the reasoning before modifying anything — similar intent to DLD, different mechanism.
The append-only decision log approach is brilliant — it sidesteps the biggest pain point of traditional specs, which is keeping them in sync with reality. The @decision annotation acting as a "stop and read" signal for AI agents is exactly the kind of human-machine interface pattern we need more of.
this is the missing piece I keep running into managing AI agents as team members. the agent writes confidently but has no idea why a particular pattern was chosen 6 months ago. your DLD approach is basically what good onboarding looks like - context before contribution. curious whether you found agents actually use the decision records or just skip to the code anyway.
The spontaneous lookup frequency on standars ad-hoc agent prompts varies also with this approach, it's hard to get it fully consistent without going over board and having the agent scan through most decisions for every query and task, which you obviously don't want to. But I have found that the in-code annotations paired with a short set of institutions in the general AGENTS.md has improved that behavior. In the sense that even if it at first skipped reading the decisions, it quite often goes back and does so before changing code with existing decision annotations.
For development that uses the opiniated skill workflow (/dld-plan -> /dld-implement being the core actions) it of course work much more consistently given the guidance and guardrails it provides.
the AGENTS.md pairing makes sense - general instructions plus in-code context at the point of relevance. i have been experimenting with similar patterns. the scan-everything approach is too slow but pure AGENTS.md misses the local context. layering them seems like the right direction.
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?
The gap you're identifying here is one I've been bumping into constantly — AI agents treat code as purely structural, but the reasoning behind architectural choices is what actually prevents bad refactors. I've found that even something as simple as markdown checkpoint files with a "Decisions" section (why we chose approach A over B) dramatically reduces the number of times an agent tries to "helpfully" undo intentional tradeoffs.
What I'm curious about is how DLD handles decision drift — when the original reasoning becomes outdated but the code it's linked to still works fine. In my experience, stale documentation is almost worse than no documentation because the agent follows it confidently in the wrong direction. Do you have a pattern for flagging decisions that need review?
"The missing link" is the right framing - agents are great at generating code and blind to whether it actually fits the living system around it. The gap is grounding: the agent needs the real contracts (types, tests, schemas, call sites) as hard constraints, not just the prose in your prompt, or it confidently modifies code in ways that compile-but-break.
This is exactly why the harness matters more than the model: feed the agent the actual structure and gate its output on the real checks, and "missing link" closes. It's how I think about Moonshift (prompt to a shipped SaaS on your own GitHub+Vercel) - the model proposes, but tests/types/build gates decide what lands, so generated code is grounded in the system, not floating next to it. Strong post; is your "link" static analysis fed back in, or runtime feedback? (Moonshift's first run's free, no card, if the gated approach is interesting.)
Great idea!.