{"id":23609,"date":"2026-08-31T21:07:00","date_gmt":"2026-08-31T21:07:00","guid":{"rendered":"https:\/\/scannn.com\/domain-driven-agents\/"},"modified":"2026-08-31T21:07:00","modified_gmt":"2026-08-31T21:07:00","slug":"domain-driven-agents","status":"publish","type":"post","link":"https:\/\/scannn.com\/lv\/domain-driven-agents\/","title":{"rendered":"Domain-Driven Agents"},"content":{"rendered":"\n
\n

I’ve been using LLMs heavily in the last years in coding, or more generally, in software
\nengineering. I watched many times what productivity boost I could gain from it, and I used LLMs in more and more of my projects. It works well in greenfield projects,
\nand small ones. The reality is that in day to day work we need to introduce agents into legacy codebases with heavy dependency trees, strong coupling, and a tech debt backlog full of everything we never got to. We quickly notice that the quality of work LLMs can deliver drops sharply.<\/p>\n

The failure has a specific shape. Ask for a “job offer status” field in a
\ngreenfield repo and you get one. Ask for it in a system that has been shipping for four years
\nand the model invents a fourth spelling of a concept that already exists three times, because
\nthe codebase itself never decided which one was real. It writes an adapter where a call was
\nfine, or calls straight through where an adapter was the whole point. Every one of those is a
\nquestion about the system that the system does not answer anywhere. The model guesses, and often guesses wrong.<\/p>\n

So brownfield projects are deep, and technical depth is only the first layer. Underneath sits a
\nsecond one: confusion, missing meaning, and no shared language to resolve it in. That is
\nthe layer the model falls into. The model is not what needs upgrading. The code is not
\nready<\/strong>, and readiness is something we can build. Incrementally. Piece by piece.
\nLet me show you how I do it.<\/p>\n

It is easier than before#<\/a><\/h2>\n

At the beginning of software engineering there was the one and only: tech debt. It’s a natural
\nconsequence of what we, as devs, are trying to achieve. We’re not ready for business decisions
\nfrom the future shifting our current view of the code. We need to deliver, and deliver fast,
\npaying some tradeoffs. As a consequence, code smell grows bigger and bigger. The usual answer
\nis to spend part of the engineering budget on cleanups: earmark 10-20% of the technology budget for
\nresolving tech debt. In theory… In the next quarter…<\/p>\n

A fifth of the budget is the toll on deciding<\/em> what should change and then typing<\/em> it out, and those two halves have never had the same price. Deciding stayed about as expensive as it was. Typing it out collapsed. An LLM will do the mechanical half of a cleanup (the extracted module, a refactor across two packages, more test coverage)
\nat a cost that no longer resembles 2020. Paying tech debt still takes time. It takes
\nsignificantly less of it, and what is left for me is the deciding part.<\/p>\n

Strategic vs tactical#<\/a><\/h3>\n

I split the work in two, and I’ll borrow the words from John Ousterhout’s A Philosophy of
\nSoftware Design<\/em> while being honest that I’m bending them. He uses tactical<\/strong> and
\nstrategic<\/strong> for two attitudes you can hold while coding: tactical programming is
\ngetting-it-working-now, strategic programming is investing in the design as you go. I use the
\nsame pair for a split of authorship<\/em>, because the economics above cut along that line.
\nStrategic<\/strong> work is deciding: reading the system, working out what has to change and why, and
\nwhether the change actually serves the feature. Tactical<\/strong> work is carrying that decision
\ninto the files. The first is the part that needs the system in your head. The second is the
\npart that got cheap.<\/p>\n

What I do#<\/a><\/h4>\n

In the first one I’m fully involved and
\nin the second one I’m rather a reviewer than an implementer. In the first path I analyze the
\ncodebase in a more generic way, assessing the changes that need to be implemented and their
\nalignment to the features I want to deliver. The effect of those approaches is GitHub issues I
\ncreate in each repository.<\/p>\n

The issues are then addressed by my AI system based on skills<\/strong> and sub-agents<\/strong>. A skill
\nis a written procedure: a markdown file of instructions the model loads when the task matches
\nit, so “address an issue” or “regenerate the context map” runs the same way every time instead
\nof the way I happened to phrase it that morning. A sub-agent is a separate model session with
\nits own fresh context and its own narrow job (implement, review for security, review against
\nthe spec), reporting back a result rather than dumping its whole transcript into mine.<\/p>\n

When they are implemented, PRs are ready to jump into. I go through the review sessions,
\naccepting the changes or asking for some improvements. I can do that incrementally, caring
\nabout the test coverage and about who breaks: before a change lands I need to know which other
\nparts of the system consume the thing I’m touching, and whether the change is one they can
\nsurvive. Now, as a software engineer, I coordinate, I plan, and I create a path for the
\nimprovements. But at that point I don’t need to implement that by myself. The time is saved.<\/p>\n

<\/figure>\n

DDD as a fundament#<\/a><\/h2>\n

That leaves the strategic half, and it is worth exactly as much as the language it is written
\nin. This is where DDD comes in.<\/p>\n

DDD was always one of my choices for software I could still change a year later. The
\napproach presented by Eric Evans gave us a way to shrink the communication gap between the
\nbusiness and the technical side. Domain-driven design, based on ubiquitous language and bounded
\ncontexts, translates what the business needs directly into the technical part. Both sides talk
\nin the same language. With agents in the loop, that link matters even more: it is how we state
\nour needs to the model and how we read its reasoning back. That is why I build on it so heavily.<\/p>\n

What I do#<\/a><\/h4>\n

Every repository I own carries a .workflow.json<\/code> at its root. It is my own manifest, the place a repo tells my tooling what it is: which languages it holds, which directories an agent should read first, which checks have to pass before work in it can ship. One block in it is about the domain, and declaring that block is
\nthe only registration a repo needs. There is no second registry to drift out of sync.<\/p>\n

The block names the project, its bounded contexts, where each context’s glossary lives, its
\nsubdomain type, and every edge to a neighbouring context. The example comes from a project of mine, job-offer-box<\/strong>, a job application tracker built as two
\nrepositories, a Rust backend I keep under the hyperion<\/code> project and a web frontend. Here is
\nthe frontend’s manifest, trimmed to a single edge:<\/p>\n

\n
{<\/span><\/span>\n  \"domain\"<\/span>: {<\/span><\/span>\n    \"project\"<\/span>: <\/span>\"job-offer-box\"<\/span>,<\/span><\/span>\n    \"contexts\"<\/span>: [<\/span><\/span>\n      {<\/span><\/span>\n        \"name\"<\/span>: <\/span>\"job-box-web\"<\/span>,<\/span><\/span>\n        \"docs\"<\/span>: <\/span>\"CONTEXT.md\"<\/span>,<\/span><\/span>\n        \"subdomain\"<\/span>: <\/span>\"supporting\"<\/span>,<\/span><\/span>\n        \"edges\"<\/span>: [<\/span><\/span>\n          {<\/span><\/span>\n            \"to\"<\/span>: <\/span>\"hyperion\/job-offer-backend\"<\/span>,<\/span><\/span>\n            \"direction\"<\/span>: <\/span>\"outbound\"<\/span>,<\/span><\/span>\n            \"pattern\"<\/span>: <\/span>\"unclassified\"<\/span>,<\/span><\/span>\n            \"owner\"<\/span>: <\/span>\"supplier\"<\/span>,<\/span><\/span>\n            \"shape\"<\/span>: <\/span>\"codegen from the backend's document (scripts\/generate-api.ts:12) ... conformist on write (src\/lib\/api\/jobs.ts:37), ACL on read (src\/lib\/api\/adapters\/offer.ts:50)\"<\/span>,<\/span><\/span>\n            \"note\"<\/span>: <\/span>\"conformist on write and an anticorruption layer on read; two patterns hold at once, so neither name alone is true\"<\/span><\/span>\n          }<\/span><\/span>\n        ]<\/span><\/span>\n      }<\/span><\/span>\n    ]<\/span><\/span>\n  }<\/span><\/span>\n}<\/span><\/span><\/code><\/pre>\n<\/figure>\n
Read it in order. to<\/code> is the address: which context on the other end. direction<\/code> says who’s
\ncalling whom; the web repo calls the backend, so outbound<\/code> (the backend’s own manifest declares
\nthe same edge inbound<\/code>). owner<\/code> says whose model wins if the two sides ever disagree: the
\nbackend’s, so supplier<\/code>. pattern<\/code> is the relationship itself, picked from a closed vocabulary;
\nhere it’s unclassified<\/code>, because the web repo does two different things at once. It accepts the
\nbackend’s shape as-is when writing and translates it into its own shape when reading. The
\nnote<\/code> spells that out; a single label would be right about one case and wrong about the other.<\/p>\n
Beside the manifest sits a CONTEXT.md<\/code> per context, the living glossary with the precise meaning
\nof every term and the deliberately rejected synonyms. Two files per context, both owned by the repo that owns the code. Nothing
\nabove them is authored: the context map (the one document showing every context in the portfolio
\nand every edge between them) is derived. A generator, a script that walks every repo
\non disk, unions the domain<\/code> blocks and emits it as a single CONTEXT-MAP.md<\/code>. The map is
\ndisposable and regenerable.<\/p>\n
\"\"<\/figure>\n
Back to job-offer-box<\/strong>. hyperion\/job-offer-backend<\/code> owns the product language. It persists
\nJob Offer<\/strong>, Profile<\/strong>, Profile Variant<\/strong>, Resume<\/strong>, Cover Letter<\/strong>, under the rule
\nthat where two contexts author the same term, the one holding the durable state owns it.
\njob-offer-box\/job-box-web<\/code> owns only the screen vocabulary (View Model<\/strong>, Filter State<\/strong>,
\nFacet Stats<\/strong>) and marks everything else [published]<\/code>, arriving verbatim as generated
\nTypeScript from the backend’s OpenAPI document. That is the level of precision an agent needs.
\nPoint it at the web repo and it knows that renaming Job Offer<\/strong> there belongs to the backend,
\nthat the adapters on the read path exist on purpose, and which words it is allowed to invent.
\nWith the map the model knows which context it is in, and with the glossary it knows the words used there.<\/p>\n
Both sides declare, so disagreement is mechanical#<\/a><\/h4>\n
Every edge is declared twice, once from each side, and that duplication is the whole point. The
\ngenerator cross-checks the pairs, and it is careful about what counts as a disagreement: a
\nsupplier names its own stance (published-language<\/code>), a consumer names its own (conformist<\/code>,
\nanticorruption-layer<\/code>), so the check is a pairing table.<\/p>\n
\"\"<\/figure>\n
I run it as a skill, at three moments: when I have touched a manifest, when I am onboarding a
\nrepo, and before I change anything another context depends on. Each disagreement it reports is a
\nfinding<\/strong>: one edge, one way the two declarations fail to fit. With one flag, the skill files
\neach one as a DDD<\/code> issue on the repo that owns the wrong side. The issue carries a fingerprint
\n(the kind of finding plus the two addresses), so a re-run after a half-fix updates the same issue
\ninstead of opening a second one, and a finding that no longer appears closes its issue. From
\nthere it follows the same spine as everything else here: an issue, an agent, a PR, my review.<\/p>\n
\"\"<\/figure>\n
What comes next#<\/a><\/h2>\n
That is the strategic layer, and it is already in place. It settles where a context ends
\nand how it talks to its neighbours: the shape of the map. The inside of any single context is
\nstill ordinary code that lets you build a nonsense object and save it.<\/p>\n
With the context map in place and the glossary defined, I can focus on the codebase itself: taking one context at a time and migrating it to a real domain model built from DDD primitives (value objects, aggregates, domain services and others). That process makes the codebase
\nanswer the questions the model was guessing at: what this word means, who owns it, where this
\ncontext stops. I’ll share the whole system shortly, with the skills ready to use. Subscribe so you don’t miss it.<\/p>\n<\/div>\n
Source link <\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
I’ve been using LLMs heavily in the last years in coding, or more generally, in software engineering. I watched many times what productivity boost I could gain from it, and I used LLMs in more and more of my projects. It works well in greenfield projects, and small ones. The reality is that in day […]<\/p>\n","protected":false},"author":16,"featured_media":23610,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[143],"tags":[],"class_list":["post-23609","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai"],"_links":{"self":[{"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/posts\/23609","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/users\/16"}],"replies":[{"embeddable":true,"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/comments?post=23609"}],"version-history":[{"count":0,"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/posts\/23609\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/media\/23610"}],"wp:attachment":[{"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/media?parent=23609"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/categories?post=23609"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/scannn.com\/lv\/wp-json\/wp\/v2\/tags?post=23609"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}