Domain-Driven Agents

TL;DR Highlight

Putting a bounded-context map and glossary in each repo made agents guess less in legacy code

Who Should Read

A backend developer whose coding agent invents wrong names and structures in a legacy codebase

Core Mechanics

Why agents fail in legacy code
- In a four-year-old system the model invents a fourth spelling of a concept that already exists three times.
- It calls straight through where an adapter was needed, or adds an adapter where a call was fine.
- The system never answers these questions anywhere, so the model guesses and often guesses wrong.
Upgrade the code, not the model
- The author says the model is not what needs upgrading, the code is.
- Readiness can be built incrementally, piece by piece.
Humans strategize, agents execute
- Strategic work is reading the system and deciding what to change and why.
- Tactical work is carrying that decision into files, which the author says got cheap.
- The author files GitHub issues for the strategic part and reviews agent-made PRs.
A .workflow.json and CONTEXT.md per repo
- The domain block in .workflow.json lists the project, bounded contexts, glossary location, subdomain type, and edges to neighboring contexts.

Community Reactions

Per-entity md files were enough
- One commenter keeps Author.md next to Author.ts and gave agents a skill to read and write those files.
- It has been useful so far in a 350k LOC TypeScript monolith, with agent-written md updates appearing in PRs.
A per-folder docs.md is simpler
- A commenter had success having agents maintain a docs.md in each folder, reading and updating it on every change.
- They argued the article overcomplicates things and no special format or manifest is needed.
Early DDD boundaries kept agent development stable
- One commenter said defining bounded contexts and ubiquitous language early kept a growing service from getting messy while Claude kept developing it.
- They also worried that existing legacy services without DDD can't even be refactored.
Pushback on the greenfield premise
- One commenter's experience was the opposite: LLMs do better on existing projects thanks to established structure and conventions.
- They said new projects go worse unless it is simple vibe coding.

How to Apply

Create one CONTEXT.md glossary
- Pick a repo where the agent often goes wrong and add CONTEXT.md at the root.
- Write precise meanings of key terms and the synonyms not to use.
- Tell the agent to read this file before starting work.
Write your repo neighbors as edges
- Pick a calling repo and a called repo and write to, direction, and owner on each side.
- Set owner to decide whose model wins when terms conflict.
- Compare both declarations by hand and file issues where they disagree.
Split analysis into issues and implementation into agent PRs
- Analyze what needs to change and why, and record it as a GitHub issue.
- Hand implementation to a skill or sub-agent and focus on PR review.
- Check who consumes the code you touch before merging.

Try It

copy & run

# Paste into Claude Code or ChatGPT (simplified version of the article's method: glossary and edge check)

You are an assistant analyzing a legacy codebase. Read the code and docs below and draft a CONTEXT.md.

[Input]
- Target concept: {{concept name, e.g. job offer status}}
- Related code: {{file paths or code}}
- Integration code with neighboring systems: {{API client/adapter code}}

[Instructions]
1. Find every spelling that refers to the same concept and list them in a table.
2. Below the table, propose which spelling is canonical and which synonyms to reject.
3. Describe the relationship with the neighboring system as to, direction, owner, pattern, note. If unsure, set pattern to unclassified and explain in note.
4. Do not guess items without evidence in the code; mark them 'unknown'.

Next step: save the result as CONTEXT.md and tell the next agent run to read this file first.

Terminology

DDD (Domain-Driven Design)A design approach that shapes code around domain terms so business and engineering share one language. Think of it as applying a company-wide dictionary to the code.

Bounded contextThe boundary within which a term has one meaning. Like a word meaning different things in different departments.

Ubiquitous languageThe shared vocabulary used by business and developers. Here it's also how you state needs to the model and read its reasoning.

Anticorruption layer (ACL)An adapter layer that translates an external system's model so it doesn't leak into your code. Like an interpreter.

SkillA markdown procedure file the model loads when a task matches it. It works like a checklist that makes work run the same way each time.

Sub-agentA separate model session with fresh context and a narrow job that reports only its result. Like a contractor who hands back the deliverable, not the whole process.