A.D.D: A Guide to Clean, Evolvable Code in the AI Era

We stand on the brink of a new world, a world where artificial intelligence will be our co-pilot, writing much of the code that powers our applications. It’s a thrilling frontier, but it holds a hidden challenge. As AI generates vast amounts of code, how do we prevent our systems from becoming tangled, unmaintainable messes? How do we ensure the foundations we lay today are solid enough to build upon for years to come?

Enter Abstract Driven Development (ADD). It isn’t another complex, heavy framework demanding weeks of study. Think of it as a simple, elegant compass—a set of clear, minimalist rules designed to guide us through this new landscape. Its purpose is singular and profound: to draw a clean, uncrossable line between your business logic and the technology that powers it.

The Ghost in the Machine: Why Traditional Architectures Haunt AI

We’ve built incredible systems with architectures like Domain-Driven Design (DDD). They provide powerful strategic tools for understanding complex business problems. But when we hand these patterns to an AI, the tactical details often become a minefield, leading to a few familiar ghosts in the machine.

The Phantom of Ambiguity

DDD’s patterns—Aggregate, Factory, Saga—are powerful concepts, not strict blueprints. A human developer uses intuition to apply them. An AI, however, sees only the code. Ask it to create an Aggregate twice, and you might get two wildly different results. One could be a “fat” object, brimming with logic; the next, an “anemic” one, its intelligence scattered into a Domain Service. This inconsistency creates architectural drift, slowly pulling the system apart at the seams.

The Specter of Leaky Infrastructure

In theory, the core of your application—the business logic—should be a pristine, isolated sanctuary. In reality, the concerns of the outside world constantly seep in. Transaction management, message outbox patterns, or idempotency checks creep into the domain layer. An AI, asked to make an operation transactional, might dutifully weave database-specific commands directly into a business workflow, forever shackling your logic to a particular technology.

The High Cost of Change

This subtle, insidious coupling makes technology evolution a nightmare. Imagine migrating from a relational database to a document store. Suddenly, you realize your core Aggregate design was implicitly tailored to SQL. To move forward, you don’t just change the infrastructure code; you have to perform open-heart surgery on your core domain model. It’s a slow, expensive, and risky procedure.

ADD was born to exorcise these ghosts by providing a clear, unambiguous map for our AI partners to follow.

The Golden Rule of ADD

The philosophy of ADD is built on a single, golden rule that separates the “what” from the “how.” The business orchestration knows what needs to be done, but it depends only on abstract interfaces. The concrete technology, the how, lives in a completely separate neighborhood and is wired in at the very beginning. The two never speak to each other directly.

The Five Players on the Stage

To enforce this separation, ADD defines a cast of five “actors” in your system. Each has a fixed role and a strict set of rules for how they interact, ensuring a radical decoupling of concerns.

1. The Boundary: The system’s front door and back porch. This is where you define your public-facing contracts: Data Transfer Objects (DTOs), API Endpoints, and the events you broadcast to the outside world.
2. The Core Abstractions: The heart and soul of the system. This is the universal language everyone speaks. It contains only technology-agnostic definitions: interfaces (Ports) that define capabilities, thin Entities that hold data and validation rules, and internal Core Events for communication within the system.
3. The Operators: The choreographers of your business processes. They are the storytellers, orchestrating the flow of business logic. They map data between the Boundary‘s DTOs and the Core‘s Entities, and they depend only on the abstract interfaces from Core Abstractions.
4. The Implementations: The workshop where all the concrete tools are kept. This is where you’ll find your database clients, message queue adapters, and third-party SDKs. You can have multiple implementations for the same interface (a Postgres version and a Mongo version) living side-by-side.
5. The Bootstrap: The master assembler. This actor has one job and one job only: to wire everything together using Dependency Injection (DI). It contains absolutely no business logic. It’s the stage manager who connects the actors before the curtain rises.

The flow of conversation is strictly enforced. The Operators and Implementations both look to the Core Abstractions for their script, but they never, ever look at or talk to each other.

A New Dance: Developing with AI 🤖

ADD transforms the development process into a beautiful partnership, a streamlined dance between human and machine.

1. The Human Architect Defines the Contract: The architect lays the foundation, defining the DTOs in the Boundary and the crucial interfaces (Ports) in Core Abstractions. This is the blueprint.
2. The AI Builds the Business Logic: The developer turns to their AI partner and says, “Create an OrderOperator that uses the IOrderRepository and IMessageBus interfaces to process this CreateOrderDto.” The AI, working from a clear contract, builds the business logic without knowing or caring about the underlying technology.
3. The AI Implements the Technical Details: Next, the developer prompts, “Now, create a PostgresUserRepository that brings the IUserRepository interface to life.” The AI builds the concrete implementation, a perfectly encapsulated, technology-specific component.
4. The System is Assembled: Finally, the Bootstrap is updated to connect the abstract IUserRepository port to the concrete PostgresUserRepository implementation. The system is live.

ADD-Extended: Taming the Wildest Domains

For the most complex business landscapes, ADD-Extended offers a suite of powerful tools designed to replace the tactical patterns of DDD with clearer, more explicit alternatives.

• Bounded Context becomes a Scope Module: The system is partitioned into self-contained modules, each with its own full cast of the five actors.
• Aggregate Invariants become a RuleSet + Checkpoint: Business rules are modeled as pure, testable functions (RuleSet) that are chained together into a validation pipeline (Checkpoint), with a TGO (Transaction Group Operator) ensuring that a group of related data is saved atomically.
• Process Manager / Saga becomes a Coordinator Operator: This actor orchestrates long-running, multi-step workflows using Core Events, with a Compensator on standby to handle rollbacks if something goes wrong.
• Domain Events become Core Events: These internal messages are handled by robust mechanisms like the outbox pattern, which live safely inside the Implementations layer, not in the core logic.

Your First Steps on the Path

Ready to begin? Starting with ADD is a journey of small, deliberate steps.

1. Name the Neighborhoods: Create five folders: Boundary, Core Abstractions, Operators, Implementations, and Bootstrap.
2. Define Your Contracts: Identify the core interfaces your business logic relies on (like repositories or payment gateways) and move them into Core Abstractions.
3. Purify Your Operators: Go through your business logic. Ensure it only imports from Boundary (for DTOs) and Core Abstractions (for interfaces and entities). Remove every reference to a concrete technology.
4. Quarantine Your Tools: Move all your database drivers, SDK clients, and data mappers into the Implementations folder.
5. Wire it Up: In Bootstrap, use your dependency injection container to bind the interfaces to their concrete implementations. The decision of which database to use is now a configuration detail, not a code change.

Quick glossary:

• Boundary: System ingress/egress; defines public contracts such as DTOs, API endpoints, and Boundary Events.
• Core Abstractions: Internal common language; only abstractions: interfaces (Ports), thin Entities, and Core Events.
• Operators: Business orchestrators; map DTO ↔ Entity; depend only on Boundary and Core Abstractions; no tech details.
• Implementations: Concrete technical realizations (DB/MQ/SDK/3rd‑party adapters/ACL); multiple variants can coexist; depend only on Core Abstractions.
• Bootstrap: Composition root; configuration, logging, and DI wiring; contains absolutely no business logic.
• Port (interface): Capability contract published in Core Abstractions so other layers can use it without knowing underlying tech.
• DTO: Data structure exchanged at the system boundary (belongs to Boundary).
• Core Events: Internal events between Operators ↔ Implementations (belong to Core Abstractions).
• ACL (Anti‑corruption Layer): Adapter/translator layer for external integrations to keep the model clean.
• DI (Dependency Injection): Mechanism to wire Port ↔ Implementation in Bootstrap via configuration.

A longer, dedicated article will follow to describe A.D.D in depth and how to apply it in real projects.

A Word on Objections

• “But we already use the Dependency Inversion Principle!” Most teams do, with the best of intentions. But when a deadline looms, it’s easy to let a concrete class slip into an Operator. ADD makes the rule a physical part of your codebase—visible, explicit, and non-negotiable. That’s the difference.
• “Is this just more complexity for developers to learn?” Quite the opposite. The roles are intuitive, and the reward is immediate: cleaner separation, easier debugging, and the confidence to refactor and evolve your system safely.

A Foundation for the Future

ADD is more than an architecture; it’s a discipline. It provides the guardrails we need to navigate the future of software development with confidence. It empowers humans to focus on the grand design—the architecture and the business contracts—while freeing AI to do what it does best: rapidly and reliably implement well-defined tasks.

In a world where technology changes in the blink of an eye, the ability to swap out core components of your system isn’t a luxury—it’s your greatest strategic advantage. That is the promise of A.D.D.

This is the introductory article in a series about ADD. If you find this concept interesting and would like to contribute your feedback to a young idea for working more effectively with AI, please feel free to email vu.minh.quang@outlook.com.