Domain-Driven Agents: Making Legacy Codebases Ready for LLMs
LLMs excel in greenfield projects but stumble on legacy codebases where ambiguity and missing shared language cause them to guess wrong. The author argues the fix isn't upgrading the model but preparing the code. He combines Domain-Driven Design with AI agents: a `.workflow.json` manifest and `CONTEXT.md` glossaries define bounded contexts and ubiquitous language, while a generator produces a context map and detects disagreements between declarations. Strategic decisions remain human; tactical implementation is delegated to agents via skills and sub-agents, turning issues into PRs for review. This approach makes the codebase answer the questions models previously guessed at.
The model is not what needs upgrading. The code is not ready, and readiness is something we can build.
- stephen
I've also been a little-d DDD fan, and we've had luck with per-entity `md` files to language-independent document domain behavior/quirks/usages.
I.e. an `Author.ts` has an `Author.md`, `Book.ts` has an `Book.md`.
For agents, we've given them a skill to read & write the `md` files:
https://github.com/joist-orm/joist-orm/blob/main/packages/co...
And so agent-written `md` updates are showing up in PRs. So far it seems useful (our main repo is a 350k LOC TypeScript monolith).
Admittedly, this is way less sophisticated (& less complicated) than the "graph of edges in/out of every bounded context" in the OP, but that is probably again my "little-d" DDD perference, where I find some of "DDD at scale" patterns lead to, imo, over-engineering.
- owaiswiz
Something i read in the earlier paragraphs about llms being easier to work with in greenfield projects…
My experience has been the opposite. They work well on existing projects but are not so great at new ones (unless you are just vibe coding something simple).
I think it has something to do with it being able to rely on years of established structure/conventions on existing projects that makes them better IME
- scotty79
When asked about DDD at a job interview I joked it was Debug Driven Development, when you start with empty directory and file the first bug "The app doesn't do anything. It should ..."
Non-ironically that's pretty much the way I work with AI agents now.