Transcription
This 20-year-old software engineering book called The Domain-Driven Design. It's a methodology that helps bring clarity to business complexity when building software products. The thesis behind it is pretty straightforward. Software must reflect a shared understanding of the domain it serves, and I think this method matters now more than ever, and this video explores that.
I've been rebuilding some important parts for the past few weeks in one of our main products inside a genative stack that is Klarq, our AI analytics and experimentation platform. Now this product went from a vibecoded PoC to a six apps, 30+ packages and hundreds-of-files monster in a little over 6 months, mostly written by AI. And we knew the problems we want to solve, what we wanted to build and how it was supposed to work. We had the big picture, but we've fallen into the speed trap, the AI honeymoon phase of adding and adding and adding. We had no map, not the proper blueprint. And as a technical co-founder on this project, I was in the fog navigating the next 100 m while the forest was growing around me. And when the AI honeymoon phase ended, which is usually around the 5-6 month mark, I realized I couldn't put something like that out there. So I started looking for methods to create better blueprints, proper blueprints for building with AI. And I found one that helps create this blueprints in an approach to software engineering that's 20 years old. And it could be more relevant now than ever when building with AI.
In this video, I talked about one skill more important than prompting and typing code these days. I was talking about systems thinking, about how important it is to hold the big picture when AI builds your stuff, how you need to become the conductor of your own orchestra. Now, lots of you came through with lots of comments and many of you asked about the how. How to put this into practice. If comprehension debt or cognitive debt is the problem and system thinking is the skill, we still need a method, a way to actually practice it day-to-day, session to session. Like I said, I found mine in a place I did not expect. This 20-year-old software engineering book called Domain Driven Design written by this guy Eric Evans back in 2003. If you don't know it, it's a methodology that helps bring clarity to business complexity when building software products. The thesis behind it is pretty straightforward. Software must reflect a shared understanding of the domain it serves. And I think this method matters now more than ever.
So, I've been building with AI exclusively for over a year now. We have a few products in the pipeline, but Klarq is the big project, and yes, using AI helped us build things that would have otherwise taken a bigger team and way more time. But while I see its powers, I also see its trade-offs. I talked about them in the previous videos, and we'll touch on them more in other upcoming videos. Now, the problem I usually encountered wasn't necessarily code quality. That's a topic for another video. No, the problem almost all the time was that there was no shared vocabulary between me and the AI coding agents inside the system. And this is something that happened in every product I started, not just Klarq. For example, when I say "change", do I mean a code commit or a set of DOM mutations applied to a customer website or maybe a feature request from a user? Well, in Klarq, it's the second one. Change means a DOM mutation applied to a customer's website. A very specific thing with a very specific life cycle. But my coding agents don't know that unless I tell them every single session. If I say user, do I mean the person browsing a website that's being tracked or the developer installing our SDKs or maybe the admin in the dashboard? That is one word with three completely different concepts. Now, the AI guesses and sometimes it can guess right, but sometimes does it wrong. And when it's wrong, it can build you the wrong thing with the right name, and you don't catch it until a week later because it can look correct. And yes, it can even slip through your reviews. It happens. And there's this trap I see a lot of builders fall into, which also happened to me. AI feels most impressive in the areas where you know the least. When you're in your own domain, you can see the gaps. And the gaps in your knowledge become its free space to drift. And by the time you find the bug, the AI doesn't remember what it did. It's a different session with different context. Sometimes a different agent altogether, and you find yourself just burning through tokens and context. You're holding a bug. Nobody on your team remembers writing.
And this is not a new problem. This is something we had even before AI coding was a thing. I went through it and I'm pretty sure most engineers went through it at some point. Five years ago, I worked for a startup as a contractor on a team of 10 engineers building this healthcare digital platform. 10 different people with 10 different backgrounds and different assumptions. Very common in engineering teams, right? The most expensive bugs we had never came from bad code. They always came from misunderstanding from a lack of proper communication and misalignment which is in fact a problem in many other areas not just engineering. So the lead architect back then introduced us to domain driven design. Now a quick sidebar because I want to head off a push back. When I first encountered DDD on that team, I thought it was overkill. And honestly, the way we did it back then on that project, I still think it was. We had 44 bounded contexts with separate modules even for things like invoice and invoices and three layers of nesting inside each. The lead architect was a brilliant guy. Very, very technical. But he built this beautiful architecture that most of us could not navigate which kind of misses the point of DDD. So we build a structure of DDD without the substance and that whole experience put this approach off for me for a few years but then I came back to it for AI coding and working solo mostly with these coding agents because the principles still hold I think more than.
So today, if we put it simply and strip it down to what actually matters when building with AI, DDD is three things. One. A shared language, a glossary, every important term in your system defined clearly in one sentence. What it is and what it does. For example, in Klarq, we have 50 over 50 terms written down organized by area. A visitor is a unique user identified by device ID. A session is a sequence of events bounded by 30 minutes of inactivity. A change is a persistent set of DOM mutations applied to a customer's website. These are all written down, one sentence each with no ambiguity. Without something like this, every other AI coding session would build the wrong thing on the wrong assumption of meaning. This is what DDD calls a ubiquitous language. That shared language, which is a contract between you and your AI and your teammates, after all. Two. Clear boundaries. Your system isn't one monolithic thing, even if it seems that way. It has several distinct areas, even a small project. Each area has its own rules and its own data. Each one has its own reason for existing. For example, I mapped Klarq into six areas so far. We have analytics, experimentation, goals, SDKs, billing, and organizations. Each one owns specific concepts. When I tell the AI we're working in experimentation today, it knows that we'll only touch AB tests, variance, and statistical analysis. We'll not touch billing, O, or event injection. In DDD, these are called bounded contexts. Think of them as rooms in the building. The kitchen has different rules than the bathroom. You don't need to understand the plumbing of every room to cook your dinner. You just need to know which room you're in. The power here is the scope. The AI doesn't need to understand your entire system each time if you have the right map in place. Just the slice of that map you're working on. And you don't need to hold everything in your head all at once. Just the boundaries. Three. Documented contracts. This refers to where the boundaries touch. That handshake written down. Our analytics system writes events to a database. The experimentation system reads those events to figure out which AB test variant is winning and suggest new ones. That's a contract. If I change how events are structured, the experimentation system breaks. That dependency is now documented. This is the what breaks if I delete this test I mentioned in the systems thinking video, except now it's written down available both to me and to the AI agent.
Now, this is the starting ground. Of course, there are many more things to dive into when it comes to DDD and we'll probably address more in future videos. You can find many free resources around it and Eric Evans's original book is probably a solid starting point. So these three artifacts are not some kind of magic bullet. It's just that each AI conversation now starts from a shared understanding instead of a blank slate. None of this is revolutionary. It's just context and documentation. We all know we should be doing it more. The thing is we're not, not really. And I know it's so easy to fall into oneshot prompting and ship the next thing fast. I've done it a lot in the past and I still find myself reaching for it on the small stuff. But for the parts that matter like architecture, contracts, data, anything that future me or future AI or future teammates will need to read, I slow down. I open the glossary. I check the boundary. I update the doc when something changes. And again, it comes down to discipline I mentioned in previous videos. Just because we can ship something 10 times faster now doesn't mean we should. At the end of the day, we're responsible for what we put in our products, not the AI. So, three artifacts, one discipline. That's the shift.
Now, like I said, these are not new ideas. In fact, they are cousins of practices most engineers have known for decades. Things like a PRD, product requirements document, which specs the what and the why before anyone writes a line of code or ADR, an architecture decision record that captures why the technical decision was made. So future you or future AI, future teammate can understand the trade-off and the classical TDD, test driven development, which forces you to define behavior before you code or your AI codes. All of this used to feel like overhead most of the time because senior devs carried the context in their heads. But AI doesn't carry anything between sessions. So that "overhead" is now the cheapest insurance you can buy. These are decades old practices but with new urgency. And each one probably deserves its own video and we'll probably get there. But across the AI coding space, engineers are arriving at this conclusion independently. That when AI generates your code, the most important thing you can produce is not more code. It's that shared understanding of the system. DDD was designed for a problem more relevant now than ever. How to maintain a coherent mental model of a complex system when the people working on it keep changing. Back then, the people changing were new hires joining the team. Today it's a new AI session every time.
I've put this into a set of skills that I now use cross projects which helps me to automate parts like specking features, slicing work, and testing new plans against the domain model and the whole project. They're open source and free to use. Link below. I've been doing this for the past few weeks. And using these skills and this approach and I have to say it's working better than every other workflow I've tried so far. But I'd be lying if I told you it's the definitive answer. Honestly, I think we're all still figuring this out as we craft. We're taking methodologies and approaches that are 20, 30 years old and applying them to tools that are two or three years old that keep changing at an incredible speed. That fit isn't always clean. And something else that the AI hype cycle won't tell you. Almost no one shipping serious software is letting agents write 100% of the code. At least not the founders I talk to, not the engineering teams I follow. Every builder I respect is still steering, still reading, and still pushing back. Maybe they're not coding like they used to, but the push back is still there. And I think that's our new responsibility as builders and engineers. The agents do accelerate the work, but they don't replace the judgment. Hard problems are still hard. The scaffolding, the refactors, their smaller fixes, that's where AI shines today. But the trade-offs, the architecture calls, the should this even exist question, which I think is very underrated these days, these are still on us, the humans. So no, we don't throw out the old playbook. Quite the opposite actually. A lot of what worked before still works. We just need to translate it into this new way of building and engineers aren't going anywhere. They just have new responsibilities. The job is shifting but the thinking matters more than ever now.
And another quick note, if this is your world, we're putting together a community called Agentive Build. It's for builders experienced and new technical and nontechnical who want to ship AI build products responsibly and learn these new ways of doing things. Inside we will go deeper on this stuff the artifacts I just walk you through and many many more link below if you want to get on the ways list. So to recap comprehension debt or cognitive debt told you the cost of not understanding your code in your system. Systems thinking told you the skill you need. Now DDD or not, you need these three artifacts when building with AI. You need a shared language, clear boundaries, and documented contracts. I'm not saying domain driven design is the solution, but it's one solution. It's not a magic shortcut. It's just a craft slightly translated because in a world where everyone can shoot fast now, I think quality becomes the differentiator. Craft is what separates you from the vibe coded slop. And I guess in this new agentic coding landscape, engineers are pushed to do something most of them used to hate. Documentation. Thanks for watching. I'm Hak. See you in the next one. Cheers.