Domain-Driven Agents: Reducing AI Hallucinations in Legacy Codebases

The primary bottleneck for AI-driven software engineering in large systems is not the intelligence of the model, but the lack of structured domain knowledge within the codebase. To solve this, a framework has been developed to integrate AI agents into complex 'brownfield' legacy systems using Domain-Driven Design (DDD) principles.

To reduce errors caused by technical debt, the framework bifurcates software development into two distinct phases: Strategic and Tactical. Strategic work involves reading the system and deciding what must change and why, while tactical work is the act of carrying those decisions into the files. In this model, LLMs are deployed specifically to handle the tactical implementation, while the strategic direction remains a human-led process.

The Infrastructure of Context

To prevent LLMs from guessing meanings or inventing terminology—a common failure in legacy projects—the framework implements a machine-readable domain manifest. Each repository utilizes a `.workflow.json` file that explicitly defines the project's bounded contexts, subdomains, and the "edges," or relationships, between different contexts.

Complementing the manifest is a `CONTEXT.md` file for each context. This file acts as a living glossary that defines the precise meaning of terms and explicitly rejects synonyms. By enforcing a ubiquitous language, the system prevents the AI from introducing inconsistent terminology into the codebase. To maintain a high-level overview, a generator script automatically creates a `CONTEXT-MAP.md` by unioning domain blocks from all repositories, ensuring the map is derived from actual data rather than being manually authored.

Execution and Implementation

The framework operationalizes these definitions through a system of "skills"—which are markdown instruction files—and "sub-agents." These sub-agents operate in separate model sessions with narrow, specific jobs, such as addressing individual issues or regenerating context maps. This implementation is demonstrated using a project called 'job-offer-box,' which features a Rust backend known as 'hyperion.'

Why It Matters

This shift in approach suggests that the "typing" phase of coding has become cheap due to AI, but the "deciding" phase remains slow and expensive. By formalizing the domain map and glossary, developers can transition from being mere implementers to coordinators. This allows agents to handle the mechanical aspects of refactoring and feature implementation with high precision, provided the codebase is "ready" for them.

What's Next

As AI agents move deeper into enterprise software, the focus is shifting from model upgrades to codebase readiness. The model is not what needs upgrading; rather, readiness is something that can be built into the code itself. Future adoption of this framework will likely depend on how easily these domain manifests can be integrated into existing CI/CD pipelines and whether other legacy architectures can be mapped with similar precision.