S03E02 · Translating Intent into Agent Work: MEGA lesson video by Kent C. Dodds
Kent C. Dodds explains how concise repository guidance, architectural decision records, principles, and documented code primitives help agents make better implementation choices without a massive specification.
videoKent C. Dodds · hq.mega.dev · Saved Nov 19, 2026
mega course, context engineering, agent prompting, coding agents
Transcript of the lesson video for S03E02 of the MEGA.dev course, by Kent C. Dodds. Agenda: Intent · Context · Requirements · Specifications · Decomposition · Evaluation. The video plays on the lesson page in MEGA Student HQ (needs a login).
0:05 My agents get it right the first time, and it's not because of some giant prompt that I write or plan mode or some huge spec sheet or anything like that. It's actually a 20-line file, a few principles, some documentation, some ADRs, and a list of every primitive in the code base with associated documentation. And so I want to talk to you about how each piece of this works and how agents find the right piece at the right moment. In the last lesson, we talked about the three steps that you can have set up, and once you've got those, then you can get yourself out of the picture. And with these in place, you can just have a whole bunch of signals to trigger agents to get going and have agents do the work, and then they can flag you in when there's some sort of product decision or architectural decision that needs to be made.
So in this video, we're going to be talking about how you get the agents to write the right thing in the first place, and how to do that without giving some massive spec document or planning document or basically writing the whole feature yourself. But to instead create a system in which the agents can, uh, work effectively and find what they need when they need it, so that the result is a pull request that gets you the outcome you're looking for and is easy to review and get into production safely. So we're going to start with the quality in here. So if you remember from the last lesson, this is literally word for word an experience that I had with an agent.
I was just talking to it, and I said, "Hey, agents need to run code against their Cody stuff," et cetera, et cetera. You should remember this. But one thing that you'll notice here is that I didn't do a whole lot to steer the agent exactly how I wanted things to go. I did have the agent give me the options. We talked about this in the last lesson. It gave me the recommended answer, it gave me the right answer, and I, I went with one direction, and, and then off it goes to build the thing. So how do we make it so that the agent can find what it needs to so that it can get the right options and give a good recommendation?
And then once I have gone with a particular option, how do we make sure that the agent can find what it's looking for? That's what this lesson is about. So this is where the answers come from. Uh, in the repository, I have docs contributing decisions, and this is basically a s- uh, steering veto list. I've got a whole bunch of ADRs. They're architectural decision records. And so in here, you'll find all of the different decisions that I have made, and typically, when I'm having, like, a big architectural discussion with an agent, the result is an ADR. So here, we're going to, uh, need to add some sort of entitlements, um, feature or, like, we, we need to have some enablement.
So, like, we've got this package, and it, um, needs to have a trigger, but people need to be able to add multiple instance of triggers with different credentials or something like that. I recently had this conversation. And so we talked this over. Okay, how should that work? What are the edge cases we need to discuss? All of that feeds into what eventually becomes the ADR. So I just say, "Okay, this is what I'm thinking." The agent reads through all the other architectural documents and everything, and it says, "Okay, based on the way that things are now, here's what I think it should look like, and here are the open questions." And I say, "Yep, that looks good.
Let's answer those questions." And once it's all done, we've got an ADR. And that ADR can be used to feed into the decisions that future agents make and ensure that we don't go off a, a different path every single time we're going to make a significant decision. We have to revisit that, um, ADR in the future if we decide later that we want to change the decision. And here's what the template for that looks like. So every decision, once we've, uh, I've had this conversation with the agent, I say, "Okay, great. Let's make an ADR." It fills in this template. And so here's the status. It could be accepted or it can be superseded.
Sometimes we change our mind. You've got, uh, the date that it was made, and then you have the context. What was the situation in which we discussed this? What was the background? What was the use case? Who was the user? That-- Maybe not necessarily who the user was, but, like, what was their need? And then here's the decision that we went. We, we had these different options. We decided to go with this, and here's why. And then here are the consequences of making that decision, uh, including a revisit if. So here's the current state of the world, and if that state ever changes, we, like, the, the cost for this gets to be too much, or there's a, a new, uh, mechanism, or, or there's this future, uh, technology that we're waiting on bef- before we can actually adopt this, or there's a new framework that's coming out that we'll be able to do and that will solve a number of our problems.
Whatever it is, we can, uh, have that revisit in that situation, and then we can come back and revisit this decision, and that's okay. And so agents aren't just locked in as, like, a concrete thing, like every single one of these decisions is sacred, and we can't change anything. You do want to make sure that this is flexible, because one of the most consistent things in this industry is change. And so, um, having that be a flexible thing is valuable. But the, the key here is making sure that, um, you have a record that is well-documented to help you and your future agents make the right decisions based off of your past decisions, so you don't have to keep making the same decision over and over again.
But then the question comes, how does the agent find that? Well, the, the common thing is your agents.md file. But it became a really common thing for agents to just stuff a bunch of stuff in there. And in fact, I find that when I'm in new projects that I, I'm not being very careful, I notice that they just fill that agents.md file, like, huge. And so I actually have an enforcement in CI that says if the agents.md file is longer than 20 lines, then fail CI. So we keep it very tight on purpose, and what the agents.md file actually is, is it's just a bunch of links to all of the other pieces of documentation.
And so it says, "If you're doing this, that, or the other, here's where you can go and find that." So if you're contributing, uh, if you are, like, building out a new system or a new software, here's where the principles are, that sort of thing. And then those expand out to their own things. And agents actually do a pretty good job once they see the agents.md of just being like, "Oh, okay, that's where the principles are." It doesn't even bother looking at the index, uh, for the principles or index for contributing. It just lists the files, and it can find it pretty well. But, uh, I still like having the index. I think it's useful, um, for humans at least.
So, uh, yeah, agents just open the page that are relevant for the task it touches. That saves on context, and while, like, there's a, a cost benefit to that, it's also just what's in the agent's brain, uh, and what it's giving its attention to is valuable. So breaking that stuff out- Uh, and making it easily findable, uh, is useful. And agents are really good at finding these, so this is really not all that complicated. Uh, so if we take a look at specifically my Agents.md in Kodi, you can see it's really simple. It, it just has a couple of things in there, and, uh, there's not a whole lot to it. It's like what Kodi is, the, the one local gate that I think I want all of the agents to run as they're making changes, and leaks, links to everything else.
Um, and that is it. [laughs] It's pretty straightforward. Uh, and for the principles, that, as I said, this is an index. They often skip over the index, but these are really critical as well. So let's take a deeper dive in the principles. So each principle gets its own page, and it's actually really intentionally short. There's not a whole lot to it. Uh, so here's the cleanup principle. Hey, whenever a new way replaces an old one, the migration isn't done until the old one is gone. And th- this is... Anybody who's been working with agents for a while, uh, probably has this experience where it's like, "Oh, well, let's just add a fallback just in case."
And so that was one of the principles that I added here so that agents won't do that, and they will understand that, hey, we've got to clean up after ourselves. And so when, when we're, um, doing something, uh, where an old way replaces the new, uh, or the new way replaces the old, then it's going to follow the principles here, and, and it has references to related documentation and everything. And so agents do a pretty good job anytime I'm asking it to replace, uh, a way that we're currently doing it. And we've got a bunch of these. So like, delete the, uh, off the common path stuff and error prompt for agents. Uh, so like when there's an error, make sure that, uh, if it's user-facing, that the user can just copy a prompt.
Um, no breaking changes. That one, I just did that one today. We don't want to break the users of our system because they're writing code, and we want to make sure that, um, the code that is being written isn't broken, that sort of thing. Just lots and lots of princi- well, not a lot, but like very scoped and important principles that apply to our, um, code base specifically is, uh, just a super valuable thing to have to make sure that the agents are generating the kind of, uh, code that you would write if you were to have written it yourself, or at least get the outcome that you're trying to go for. So the primitives help the agent to know how to make different decisions, but it needs to know the pieces that are available.
And this actually takes me back to my PayPal days when I was working on a combo box. This is like a, a smart input you type in, and, and it's like auto-completing, that sort of thing. And I found that we actually had three combo boxes in place. They were completely different implementations using different libraries and everything. And so I built Downshift, and I said, "It turns out we can actually, uh, we actually had three implementations of combo boxes. We're going to implement a really good primitive for this." And that ended up becoming Downshift, which is a library that I published while I was at PayPal, and a ton of people ended up using it, and it was awesome.
It's a React thing, so there, there are still lots of people using it. But, uh, the, the key here is that once you've got a whole bunch of implementations of something, if you don't turn that into a common primitive, then you're just going to keep on getting a bunch of implementations of that thing, and it is not going to be great. And so your primitives, uh, whether those be UI primitives or backend primitives or whatever, uh, in any layer, um, those are really key, and you need to think about those significantly. So in the way that I have things set up in my project, I s- I have every primitive linked to its code and documentation.
Now, I actually have this specific- specifically laid out in a primitives YAML file that names 58 primitives in five groups, um, from the browser to how we do backups. And every one of them has its own entry point and documentation that explains what it's for, so the agent knows that it can compose existing primitives instead of inventing new ones. So let's take a look at that YAML file. It's, uh, yeah, it's, it's big. It's got a lot of things in here, but you've got stuff like, uh, memories and platform feedback and webhooks and email and MCP client servers and, uh, backup control plane and email reporting and artif- uh, artifacts repos, uh, user metering, mailbox, uh, the email delivery queue and platform feedback dispatch queue, the community activity dispatch queue, follows, uh, package events dispatch queue.
Like, there are so many. You should actually go into... And we've got actually some invariants in here too. Per org isolation, this is something that we want to make sure we don't break. Integration host allow list and canonical repo, uh, source. So many things. Feel free to dive into these specifically. Um, but the, the key here, I want to call out just a couple of interesting things, and your primitives are going to be different. I want to make this clear. Everybody's primitives are going to be unique to the software that they are building. Um, but, uh, here is a little look into what mine look like. So I've got 58, uh, primitives. There are five groups.
13 of them are invariants. There's 862 lines. Uh, so these are kind of separated into, uh, different groups. So there's the surfaces. So these are, um, what our users can interact with. This could be the API and the UI and the MCP server and all of that. Then there's identity, so authentication-related stuff, our MCP OAuth story and our login and providers that you can connect and all of that. Uh, and then there's the assistants, um, the user-facing assistant primitives, um, that's just full of stuff, and the runtime and the storage. Like, hopefully you get the idea. These, these are many different layers. You've got the user interface all the way down to authentication and email and that sort of thing.
So yeah, like, the... It's, it's pretty interesting how these all combine, and Kodi is, uh, at the, the time of this, um, video, is over a million lines of code. If you've got a code base that's 100 million lines, then you're probably going to have a lot of primitives, and frankly, if it's been around for a while, you'll probably have a lot of primitives that overlap. So you want to be thinking about, how can I combine primitives? How can we simplify this so that these things that are almost exactly the same actually are the same? Uh, or they... Like, sometimes you have to be intentional and be like, "Nope." It, it is a simpler system if we can keep these things independent, even if they share a couple properties.
Or, um, maybe we can ha- find a common parent. I actually did this recently with credentials. I said, "Okay, so, uh, you can save secrets that are, like, just encrypted, uh, private access tokens or whatever, personal access tokens, or you can have OAuth credentials." And I said, "You know what? Those are basically kind of the same thing in the way that they're being used, and so we're going to make a credentials parent, uh, primitive on top of that, and there will just be multiple kinds." So, like, that's... You can kind of think of this as, like, your data model as well. Like, a lot of the things that live in your data model, those are primitives as well, but then, of course, you also have the UI components, uh, are also primitives.
Oh, there's actually one other thing I just want to make sure I call out for you all, and that is that each one of these primitives lists the code and the docs for that relevant, uh, for that primitive. And so as the agent is going around implementing something and, and the prompt that started it out says that, "Here are the primitives that you need to worry about," it comes into the primitives file and it says, "Okay, great." Like, "Oh, here's the pieces of code that I need to, like, load up. Here's the documentation that I need to grab." And so there's no, like, searching around manually to find what it needs. It has it all right here, and if it decides, "Oh, I need to add something else," or, "I need to document this separately," or whatever, it can add those references to the primitives.
So I, uh, like, literally, of course, I'm not writing any of this stuff. [laughs] The agents are writing all of this, and, uh, so I... They're maintaining this, and it's going really super well. So primitives, you... Like, so much of developing a good system comes down to these primitives, so you definitely want to take this seriously. And once it has all the pieces that it needs to put together to create the pull request, you got to make sure that that pull request is quality, and this is so key. You need to give the agent a mechanism for verifying its work. Now, let's think about this. The way that we did this back before agents were a thing is we had tests, and some people would do test-driven development, and that was great.
That's awesome. Some people loved that, some people didn't. Uh, and you would have, like, unit tests and integration tests and all of that. But most of the time, lots of the time, you would actually pull the thing up and click around and experience it, or you'd run the command or whatever. You'd have some mechanism for, uh, actually manually testing things out. Uh, maybe you have, like, a, a script to seed the database so that you can get things in the right spot, or maybe you've got a storybook or something so you can see all your components. We need to give that to our agents as well. And yes, they have computer use, but there's so much more that you can give them, and so that's why I have this Control Cody, uh, skill.
Uh, and so there is a, uh, Control Cody CLI that's built in, um, that allows agents to verify all sorts of things with, uh, the CLI. And then it's built by the agent, so as the agent is using Control Cody, it's, uh, and trying to verify its own, um, implementation, it's, uh, finding problems and adding new features to this. And so we've got a doctor command and a dev and a login and a request to make a request to the app, uh, and, uh, a map waiting and map check. Honestly, I don't even know what most of these do because the agents are the ones that are, uh, filing friction and saying, "This was hard for me to test," and they go and, uh, implement improvements to Control Cody.
But the principle here is that you need to give your agents some mechanism to verify their work, and you need to make that an expectation. And so that's part of all the documents, uh, documentation as well, is that there is an expectation to verify your work, and here's how you do that. Uh, and then at, at the end of it all, let's, uh... And we'll talk about this later on, what this friction log thing that I keep on talking about. But at the end of it all, if you have any trouble, then file, uh, friction, and, and we can talk about that. Uh, there's also a feature map, uh, that's documented in here that helps the agent more easily find where different features are.
So as it's trying to build out this, uh, like, something on the account page, it knows where to find the code for that, uh, how it all works and how it's pieced together, how to test it manually. Uh, and even, uh, we're kind of skipping ahead here a little bit, but it even has a mechanism for testing the preview deploy on a particular PR. So once the PR has gone up and the preview deploy is there, the agent can, on its own machine, run, uh, and test things against the preview deploy to verify that things work when it's in a deployed state. So all of this stuff, like seeding the, uh, the database and all of that, super valuable.
Absolutely, you should have a... Not only instructions on that the agent should verify its work, but also tools to help the agent verify its work. And once it's verified all of its work, then it can push that up as a PR. And I've got a template that it follows to make sure that it's easy for us to understand and for AI reviewers to review the pull request that it creates. It's pretty simple, um, but it starts out with the intent. Uh, and this is, like, super, super key in, uh, building this sort of system where you can, uh, easily just quickly get up to speed on what's going on here. You say, "What is the intent?
What, what are we trying to accomplish here? What's the overarching goal?" And it makes it so much easier, um, like- Oh, man. Rather than just looking through the code or, or it's just listing, "Here's what I'm doing." It's like, "Why are you doing that? What, what is the intent? What is the outcome? What is the goal?" And as a part of that, I want to know whether this is a one-way or a two-way door. What that means is a two-way door, it's cheap to reverse. It's like you, you shift the wrong thing, uh, we really shouldn't have that page over there, we want to move it over here, whatever. Uh, so that's an easy thing to change.
A one-way door would be expensive to undo. So, uh, the, the things that you're storing in the database, uh, the, uh, public contracts, so like you publish an API and now you've got people using that API. Oh, shoot. That's a hard thing. That's, that would be considered a one-way door. Or actually a migration that deletes data. That's definitely a one-way door. So in that case, this is a high-risk change, and you definitely want to be reviewing this more carefully. And then also the cleanup, whether there's any cleanup needed. So if we're moving from one, uh, mechanism of connecting people to their, uh, Facebook account or whatever to another, uh, then, like, we need to get rid of that old code because you don't want just a code base that continues to grow, and agents are, they love to do that.
They just, like, make a growing code base. You need to find ways to cut out the fat, uh, as well. And there are mechanisms to do that intentionally too, and I will sometimes just have, uh, and in fact, I do this every week. I have an agent that goes through and tries to delete a whole bunch of stuff every week. But, uh, having an explicit cleanup, um, listed here is really useful. And often, uh, I, I even have the agents create an issue on GitHub so we can keep track of this if this is going to be a long-term migration sort of thing. And then I, um, say what to delete. So this is if cleanup is needed, then here's what we need to get rid of when cleanup is done.
And then we say why. Why is this change needed? What, what about this intent requires a change? And then a summary of what changed, just some short bullets, uh, summary of what actually is being changed here. And then referenced issues in PR. So, like, closes or fixes this, resolves this one, or, uh, you know, it's a, just a reference to this other, uh, thing. It's, it's related, but not, you're not going to close that issue, whatever. Uh, what testing was done to verify the work. So that verification piece is super critical. And then, um, and we'll talk about that too. And the system changes. So this is the most, it says optional for non-trivial work.
Pretty much every one of my issues will include a system visual recap. But here's what that ends up looking like here. So you've got your intent, here's what we're doing, here's the door, here's the cleanup, here's why this is happening, and, and the summary, referenced issues, testing. And so here, it's saying I did, uh, unit tests, ran, uh, all of this, and then we've got a local browser, uh, ran against these things, you know, because this was just a, uh, making a code block copy button half the size. So this was actually a pretty simple change. It still did, uh, get some review comments and iterate and all of that. So, um, having this PR, uh, template, uh, set up, super valuable to make sure that the agents are thinking about the right things when they create the, their pull requests.
And so for the last thing in the template is the system changes. So let's take a deeper dive on that because I think you'll be really interested in this. So the recap names the primitives that the PR adds or changes or deletes or whatever, and that's what the system changes is all about. So let's look at an example of this. Uh, so this is a PR where we're adding the enablements model and migration auto-enable step. So, um, when you create a, a trigger, so like this package in Kodi will respond when an email is sent to the user's Kodi email address, or it responds when this other package emits an event, or it responds on the, or it's got a schedule or something like that.
So the user has to say, "Yeah, I want to enable that trigger, and here are the credentials I want it to use when, uh, it's running." And you can have as many of those as you want to, uh, but the, it's called an enablement. So this trigger has now been enabled with these given credentials. So that's what it was adding here. That's, that was a pretty significant piece of work here. And so this is adding a new primitive. This is going to go up in the system recap. It's adding a primitive. This is high risk, and, um, this is the different primitives that were touched. So we're touching enablements. That's part of the auth group.
We're adding to that. Uh, we've got the D1 app database that's in storage. We're extending that, uh, with some new tables. Uh, we're touching RBAC, so our, uh, role-based access control. Uh, so that's authentication. It's composing that and, uh, so it's referencing that. Uh, org access grants, also composing that. And then it has a change flow. So here's the RBAC admin enablements migrate, dry run, notify, or apply, and it's going over to enablements, and it's just showing me this sequence diagram, uh, that's a way that I like to, to read these kinds of changes. So it makes it much easier for me to review because I'm not reviewing the code now. I'm reviewing the system, and the system is the thing that, uh, really makes the difference of the outcome that your agents can give to you.
That's is what you're always thinking about is, can my system satisfy the outcome that I'm trying to get for my users? And if it can, and if you've got the right primitives, then you can really let your agents just fly, and they'll do a really awesome job for you. They'll build the right thing the first time. And that's the whole point of this lesson, is making your system such that your agents build the right thing the first time. And when you've got that all set up, then you can just have a nice little conversation with the agent, make a decision, and then send your agents off and feel confident that they're going to build the right thing the first time.
Thank you so much for your attention.