Skip to content
Linkdrop
Links

S01E03 · Building Knowledge Systems: MEGA lesson video by Theo Browne

Theo Browne explains how to help coding agents navigate a codebase by asking questions about where they struggle, then improving the skills and guidance that shape their behavior. Examples cover T3 Code, agent skills, tool selection, and preventing scope creep.

videoTheo Browne · hq.mega.dev · Saved Nov 19, 2026

mega course, context engineering, agent skills, coding agents

Transcript of the lesson video for S01E03 of the MEGA.dev course, by Theo Browne. Agenda: Files · Style Guide · Specifications · Tasks · Library · Research. The video plays on the lesson page in MEGA Student HQ (needs a login).

0:03 Now that we understand how context works, it's time to take advantage of it. If you want to get your agents to behave certain ways and do certain things and stop making silly mistakes, this is where we'll learn it. The concept that we're going to talk about mostly is the idea of memory systems, but more importantly, my spin on it. Your knowledge system should just be your code base. Throughout the years of building with agents, there's been a lot of back and forth in how we should encode our knowledge. Everything from docs to beads to rules to dot cursor files that we would have in our repos, all these different things. Instead of focusing on these specific implementation details, I want to focus more on how to work with a knowledge system and how to make your agents behave better by using them.

I want to start here with a simple exercise. Think back to the last time you were onboarded onto a big code base you hadn't worked on before. Whether this was at your job or you were trying to contribute to some open source project, I'm imagining pre-agents, obviously. But remember that feeling that you got when you first opened the repo, not understanding where anything was or what was going on? I used to give a lot of advice on how to get through this. There's a combination of techniques, mostly starting from the idea that learning the whole code base was never the right way to do things. Nobody ever contributed to a code base the size of Amazon or Google's by reading every single file in it line by line until they built that understanding.

We got it other ways, usually from seeing what was changing and how the pieces worked together, and that's what we want our agents to have too. Remember, every time you start a new thread, that agent is effectively having its memory wiped and it's starting from scratch. And our goal isn't to make sure everything it could ever possibly need is in its brain. Our goal is to make sure that the right paths exist to help our agent find what it needs when it's making real changes. Back in the day when I was trying to onboard our new hires to the code bases at Amazon and Twitch, I had a silly trick that I used to help get through a lot of the friction for the onboarding.

I called it the dumb questions rule. The point of this rule was simple. Everybody's kind of scared of seeming dumb, especially when they ask questions. Nobody likes feeling dumb. We've historically addressed this problem by trying to go the angle of there's no such thing as a dumb question. I think that's silly. Everybody has asked a question that's dumb. I would rather just have them ask it. So when I onboarded new employees at my other roles, I implemented the dumb question rule, which was meant to inverse this. The dumb question rule was simple. Every day you were on payroll, you had to ask me or one of the other leads at least one question that made you feel dumb for asking.

Until you had asked a question that made you feel kind of stupid, your workday wasn't done. Some people would do five in their first few hours. Some would wait until the end of the day to write like a really good dumb question. But I found that actively encouraging employees to ask these types of questions, especially new hires, was incredibly useful. So how does any of this apply to agents? Well, you're effectively hiring a world-class engineer that's never seen your code base before every time you click the new thread button. So one of the best things you can do is have them ask dumb questions or ask it dumb questions yourself. I'm gonna demo this in a pretty silly way.

I'm gonna take a real-world large code base, in this case, the T3 Code code base, and I'm going to delete the README, the CLAUDE.md, and the AGENTS.md, which is going to effectively lob off the context from the top of the repo. So now when I spin up an agent in it and ask it things, it's not going to have what it used to have. So I'm gonna ask it something simple like, "I want to work with you in this repo. I want you to ask me questions about what it is and how it works. What confusion arises as you start to explore the code base?" Sadly, this type of dumb question doesn't make a whole lot of sense to ask anymore, as I've just accidentally demonstrated.

So I'm gonna show you some examples that have actually been really beneficial to me. Here's a real example that I did just a few days ago. I was working on a video about Gemini 4 Argon, and I was getting a lot of data from my own real-world usage, and I was asking questions about it, like, "How does it behave? How is it acting s- compared to all these other models?" And I got this nice little visualizer that it wrote for T3 Code. There's a problem, though. I don't know how well this will come up when the video's encoded, but, uh, it's very clear to me right now, there is a strong black background around this embedded HTML that is different from the gray that we use in T3 Code.

This is because the model wrote HTML for this response and gave it a hard, true black background. It is hideous, and I had seen it doing this earlier the same day. And here is where it's important to start asking questions. "Why do you always add awful black backgrounds to your inline HTML? Whatever makes you do that, fix it here and push it to the fleet." This one was convenient because this repo, my fleet repo, is where I main- manage and maintain all of my skills for all of my harnesses. More about that in the next two lessons. But I could have just asked this first part, "Why do you always add these awful black backgrounds to your inline HTML?"

At the end here, it said why. "The global true black rule was too broad. I scoped it to product UI and added an explicit rule that inline HTML inherits the chat theme." This was a change it had made to my core file skill for this particular thing. And I'm gonna be real with you, it wasn't a very good fix. The agents are more than capable of telling you why they did something wrong, but they don't always make the right changes to fix it. So when I ask these questions, it isn't necessarily because I want it to go fix it itself. We might get to the point in the future where the models can write really good skills, write really good markdown to instruct themselves in the future, write really good prompts, those types of things.

I don't find they're good at it at the time I'm filming this, but I do find they're good at identifying what they're struggling with. It's the whole classic, you should trust your customers with their problems but not their solutions thing. I let it write the solution, not because I want to use the solution it wrote, but because whatever it goes to go change is a really good indicator of what needs to be adjusted. And you can bet your butt the first thing I did after this was go find that skill that it changed and edit it, uh, properly in order to push it across the fleet and fix this problem once and for all.

I do this a lot. Just in the last few days, I was able to find many examples. Here's one where I was analyzing between threads. This technique works with pretty much every harness now. You might not be able to get an ID easily, but you can just tell the agent what you were doing in the other thread, and it can usually look through the history and find it. So I had a thread I was working on in T3 Code that used the wrong tool. That really frustrates me when I have the right tools that are provided to the model, and it does something else. It uses the wrong thing, it edits the wrong file, it makes the wrong change.

I ask why. In this case, I said the thread used the wrong tool. Figure out why and update the skills to prevent it. If I should make changes to how the MCP stuff is described as well on the T3 side, let me know, and I'll spin up a thread for it. It pointed to the skill that caused the problem. Apparently, my Soul Loop skill, which we'll probably talk about in the future, instructed the agent to use my thread send command in T3 code, which caused it to create new threads when I wanted it to do sub-agents. That was the bug I was working on here. I didn't even write it in the prompt because it didn't matter.

I trusted the, the thread to be able to figure it out. Again, not telling the agents exactly what I want, what I'm trying to figure out what's up. Explicit instructions are great when you want the agent to make changes, but when you're exploring and trying to figure out what it knows and why it behaves certain ways, ask it questions and then make changes accordingly. One more quick example of a more generic type of problem that this way of thinking can solve. I noticed that one of my threads had massive scope creep. It should have been like a simple 100 or 200 line of code change, but I noticed the PR getting into the thousands of lines, and I was frustrated.

There is nothing I hate more than simple things being unnecessarily complex, and agents are more than happy to write a ton of complex code, even when they don't need to. So I called it out accordingly. I said directly, "The thread on..." or, "This thread on my particular machine, Cup2, in T3 code, ended up hitting massive scope creep." I think it was from the Soul Loops, because again, my skill Soul Loop, as powerful as it is, can cause some scope creep. I told it to audit it, figure out the causes of the scope creep and massive inflation of the PR size, fix it. It likely needs more guidance in the skills. Something like, and I gave an example of something I thought would work well, "Don't let these review loops constantly expand the size and scope of the changes.

Keep an eye out for unnecessary tests, guarding for edge cases that don't matter, unnecessary levels of integration or compatibility, et cetera. Keep changes simple wherever you reasonably can." I got a pretty useful response here from Claude. "I fixed the skills and installed them on all 11 boxes. You were right that the Soul Loop caused part of it. The other part came before any review." And it went through and described where these problems came from. It started with this PR that had 271 lines added and 13 removed. The fix it needed was only about 15 lines. When delegate task gets provider unavailable, should recheck the one provider and try once more. Very useful description of what happened there.

The first version was small before Soul saw it, then the agent's own review brief asked for more scope. It asked Soul whether any other path should be covered and about probe storm risks. The skills brief template also asked Soul to look for, quote, "missed cases." So it got 90 more lines after the first round of review, and then it kept going more and more until the PR got way too big. What I'm trying to say here is to start from a core of what is the problem. So step one should always be ask an agent to make the change in the code base without giving it access to anything special and see what it does, see where it struggles, see what goes wrong.

This is similar to how I worked at Amazon, where I would give a ticket to a new hire who didn't know where anything was yet, and then set them off to see where they ended up and have them ask me a bunch of questions on things as they go to do it. If you've somehow literally never fired off an agent in your code base or you don't have any, like, AgentMD, ClaudeMD, stuff like that there, this is a great example of a first prompt to send. "I want you to work on ticket number," whatever. "Explore the code base and propose a fix. If you struggle to find anything or you find something confusing, let me know.

Don't be afraid to ask dumb questions." This type of prompt can get you a lot of good insights on how your agent sees the code base. And then from there, if it has questions, you can answer them, or if it has a proposed fix that you think is good, you can tell it to go implement it, and then you can see what it does. And if it does something confusing, you can go read through the transcript piece by piece, or you can just ask. And if you notice that your threads are consistently falling into the same holes, maybe they are wasting all of your CPU when they try to run a dev server they shouldn't and it's causing the machine to crash.

Maybe they're running the type check command at the wrong time and it's making builds take way longer than they should. Maybe they're pushing a pull request, but in the wrong format, and they're getting auto-closed because they're not following the rules that you have for your templates properly. Whatever it is, ask why. Just ask the agent why it did a thing, and you will find surprisingly useful answers when that happens. And then from there, you can start micro-adjusting to get it the right way. If it's something simple like it didn't use the right template when it filed a pull request, you can make a small change to the global agents MD or Claude MD to fix that.

Just tell it, "Hey, when you make PRs, make sure they use this template. Always start here." If you have a more complex process like I do, where I want it to verify itself and babysit pull requests in a specific way, then you can graduate up to a skill. And with the skill, you can indicate when the model should use it with a simple description that says, "Use this when X, Y, or Z." And then that is, again, bringing in certain context that the model doesn't have to generate itself. I think people are a little too fixated on the idea of helping the model get somewhere slightly faster, but generally speaking, it can read your package JSON.

It can read the hierarchy of files and folders in the code base. It can look for the specific string that was in the screenshot you gave it and figure out where in the code base that lives. If you try to give it a map of the code base in your guidance and in your knowledge system, you are giving the model an outdated, broken version of a thing that it can already find itself. What you need to do is steer it away from the scary parts. Stop thinking of your knowledge system as the only way someone can figure things out. Instead, think of it as, like, guardrails and walls of a bouncy house. You just wanna make sure it's not going to hurt itself as it gets to where you want it to go.

I wanna jump in front of a lot of the mistakes I see people making when they start going down this rabbit hole. If you think the solution to the mistakes your agents are making is leaving a bunch of comments all over your code base, writing a manifesto of where everything lives in the code base, or trying your hardest to add so many unit tests the agent can never make a mistake, you're very far from the way things are going right now. The best solution is almost always to make the code base simpler and easier for both you and your agents to understand. The vast majority of the problems I have run into with agents making mistakes aren't because I didn't have the right knowledge in the system.

It's because the thing itself was confusing. Even if I did write up how it worked somewhere where the agent could access, it would still be confusing, it would still be unnecessarily complex, and the vast majority of the time, whether this is at a big Fortune 500 company or a small startup or a side project, you can almost always simplify things so that both the humans and the agents can understand it better. Potato from Cursor and now SpaceX AI has had some really good commentary on what's going on right now. This is a post she made about how to trust your agent's work more. She also says you can just copy the post or link and give it directly to your bot.

Highly recommend doing that. You'll be surprised what it can find. In fact, I will do that now. I'm literally just grabbing the tweet, post, pasting the link, screenshots, 'cause I know that GPT models aren't as good at accessing X 'cause, uh, somebody wants to keep them from doing that, and just telling it, "Use the principles from this tweet to audit the code base and suggest improvements." And while that runs, we can read it. "The first step to making sure you can trust your agent's work more is to improve the code base itself. This is just good software engineering. Better architecture, stronger types and invariants, clear boundaries. Agents love to copy what exists and take the shortest path, so make the easy thing the right thing."

This is one of the most important pieces. I find everyone is trying to cover up the absolute shit shows that are their code base by having these complex knowledge systems that re-encode all of the complex spaghetti they wrote. There is no excuse for spaghetti anymore. Agents can go through that spaghetti and trim it down to be way simpler if you guide them there to do it. So if you have your agents doing stupid things or pushing spaghetti all across your code base or making obviously bad decisions, you need to fix your code base. Categorically eliminate the problems through the code, and you won't need to think about this again. After you have exhausted all of the things you can do to make the code base itself simpler, then you can go into these other layers, but you should think of each one of these as a bigger failure.

The more you can do at the top level, the better. If you somehow fail to make things behave better there, then go to the next layer, like static analysis. This is where things like lint rules, tests, CI, and verification all come in. It's a token-efficient way to catch the, these types of issues ahead of time. If you have CI that will test that the app behaves when a user clicks a certain place, that it hits the database and shows them the right result, that can be verified without an agent having to do it, which can be cheap and also help the agent make better decisions. Generally speaking, you should just make it so it writes the code correctly the first time, but these tools help prevent it from making those types of mistakes.

If those two things are not enough, then you must begrudgingly go into the pros layer. This is where a lot of the knowledge system stuff lives, and that's why I'm so against it, because the knowledge system is two layers of failures deep. Putting something about your code base in your knowledge system means that you're admitting that your code is so bad and that your linting and CI is so bad that they can't steer the agent the right way, so now you have to do it through unnecessary comments, rules, agent MD file changes, skills, all those types of things. They can't be enforced. They require the agent itself to do its own judgment around these things.

Use them minimally, but if you do need to, you can. And then the final layer, the one that slows you down the most, human review. "At the rate agents are landing code, it's pretty much impossible to thoroughly review every PR, so spend the effort you would have on the highest leverage points. Design environments where the agents will do the right thing by default." I was just gonna at the bottom here of looking through your Slack and chat messages and code review comments to find places where you're giving PR feedback code, architecture stuff, recalling all the past things, and then going through the code base and auditing to clean it up to prevent these mistakes going forward.

Great advice. Highly recommend it. It already called out useful things for me to go adjust in my own code base. Apparently, we already have good rules, but we need to make them more automatic so they apply more often and more correctly. We need to increase visibility on missing provider coverage, give agents a single command for doing things like selecting the right local checks, convert mechanical reviews into lint, and then reduce repeated pros. We have a whole set of guidelines for how to review things that change our effect service layer, for example. That's all markdown-based guidance that this believes we can actually lint for, which is cool to see. Definitely should go do those things afterwards.

I have one last prompt to show you before we wrap up. "What are the most common issues my agents run into while contributing to a given repo for the last week? Go through my real history on this machine and across my fleet to find common hiccups, wrong tool calls, et cetera." My fleet is just the set of computers I do my work on. You don't have to pay attention to that part. If you do most of your work on one computer, you can just tell it to go through the history on that one computer. You will find some really cool stuff when you run a prompt like this. But now I think it's time to talk about where this all runs, the harness.

[static noise]