Writing CLAUDE.md That Agents Actually Follow

# Transcript — ai-coding-setup ep 02 _Auto-generated with mlx-whisper (mlx-community/whisper-base.en-mlx). Lightly readable; not edited._ It's six months in. You've written 800 lines of rules. Your AI agent still outputs console logs. It still reaches for a default export instead of a named one. Every single time. Right. It still creates a barrel file that you explicitly told it not to create. You add more rules to fix it. And somehow, you know, the problem actually gets worse. It is the single most common failure mode in AI developer tooling today. And I mean, it has absolutely nothing to do with the underlying model being battery lazy. It is purely an architectural mismatch between how developers think rules work and how large language models actually process them. Welcome to your deep dive. Looking at the notes and the source material you sent over today, it is clear you've been wrestling with, well, a deeply frustrating issue. Oh, definitely. Because if you're building software right now, you're probably relying on an AI agent. And you're almost certainly fighting with how to make it behave consistently across your repository. So today we're dissecting a really fascinating engineering document titled, One Canonical Answer, engineering effective Claudia dot MD rules. Our mission today is to completely deconstruct this failure mode. We're going to look at why a bloated rules file actually violates the core mechanics of how these models distribute their attention. Right. And more importantly, how to re-engineer your approach so the agent works with you deterministically. And just to set the tone up front, we are keeping this strictly pragmatic engineer to engineer. Yeah, no hype. Exactly. No hype about AI taking over the world. No corporate buzzwords. Just a highly technical breakdown of how to shape your environment so your agents actually do what you want them to do. Let's start with the trap almost every engineering team falls into. The massive sprawling rules file. Yes, the sprawling rules file. So the fundamental misunderstanding here is treating a claud.mb file or really any system prompt file like it's a traditional policy document. Right. Like an employee handbook or something. Exactly. We write them as if they are stored in a database. Yeah. Easily referenced chapter by chapter, but they're not. That text is loaded directly into the LLM's context window at the very start of a session. And that architectural reality changes everything about how you need to write it. It really does. Because every single line of that rules file is a line the agent isn't spending looking at your actual code base. Right. Right. It's just eating up the working memory. Precisely. I mean, let's look at the math of the context window. If you have an 800 line rules file, you have just consumed roughly 10,000 tokens before the agent has even read a single line of your actual code. Or even the specific issue you want it to fix. Right. And here is where the probabilistic nature of transformer models becomes a massive problem. How so? Well, as that file grows, the model's attention mechanism, its ability to hold fine grain distinctions and apply strict weights to every rule. It gets diluted. OK, let's unpack this because this is a huge mental shift. When you write something like never use a console log in your rules, you aren't issuing a strict compiled command like you would in a traditional programming language. No, you are establishing a probabilistic prior. You're shifting the token distribution. So there is, I don't know, maybe a 95% chance the next generated token complies with that rule. OK. But the agent isn't just reading your rules in a vacuum. It is reading your repository. Its context window is flooded with your existing code. Oh, I see. So if it scans your code base and finds 50 files that contain a console.logs statement. It is going to assume your rule is basically just a nice aspirational suggestion. Right. It's like handing a new hire, an 800 page employee handbook on day one, telling them we never eat at our desks. And then they walk out to the engineering floor and see 50 developers eating sandwiches over their keyboards. Yeah, they're going to copy their desk mate, not the handbook. The empirical example right in front of their face beats the written instruction every single time. That is exactly what happens. The LLM essentially treats your code base as the training data for its current context. You can call this the empirical override. The empirical override. Yeah. If your prompt says one thing, but your code base says another, the code wins. Always. Every single time. And that is exactly why long rules files are completely impossible to debug. Because there are too many variables. Right. If a 50 line rules file produces a bad output, you can pinpoint exactly why. But when a 1200 line file generates bad code, you have absolutely no idea which rule it ignored or how the attention weights shifted or which internal contradiction tripped it up. I've seen this exact thing in so many repositories. You write a rule online 200 that says, you know, prefer functional hooks over higher order components. Yeah. But then online 650, someone else on the team added a rule that says always use this specific higher order component for the authentication layer. And what do the agent do? It picks one. And usually it picks the one that matches the closest surrounding code, which makes the developer think, oh, we need to add another rule to clarify. Exactly. So the developer's natural instinct is to go back into the rules file and add yet another clarifying rule to explain the contradiction. The file grows, the token count goes up, the attention gets further diluted, and the problem just recurs. So if the code base always wins, if this empirical override dictates the agent's behavior, how do we actually align our rules with our code? Well, the source material introduces this core concept called one canonical answer. OK. And what does that mean in practice? It's the foundational principle to internalize before you write another prompt. For any technical decision in your stack, you have to ask yourself, is this the only place this question is answered? Meaning is the Claude D dot MD file the absolute sole source of truth for this specific pattern? Right. Let's say you have a specific way you handle data fetching. If that architectural question is answered one way in your Claude dot MD, a slightly different way in a steel design document in your repo and a completely third way in the actual implementation of your legacy components. The agent now has three competing answers loaded into its context. Exactly. It has no deterministic way to rank them. It will simply guess based on the highest volume of nearby examples. And that guess is rarely the idealized pattern you actually wanted. Almost never. But hold on. Let me push back on this a bit because I am looking at real world scenarios here. What if you are in the middle of a massive migration? Say you are a team moving your state management from Redux to Zu stand or moving from the next dot JS pages router to the app router. Yeah. Very common. There are legitimately two valid working patterns existing in the code base right at this exact moment. You need the agent to know which one is the future and which one is deprecated. This raises an important question. And the source material is brutally honest about the hard truth here. The rules file simply cannot fix that situation for you. Wait, really? It can't. You can't just tell it ignore the Redux stuff. Only write Zu stand. I mean, you can try, but asking the agent to navigate that level of architectural nuance via a text prompt across a massive repository is just setting yourself up for probabilistic failure because of the context window. Right. The LLM's attention mechanism will constantly be pulled towards the vast amount of legacy Redux code it sees in the surrounding files. So what's the solution? You have to shake the code base first. You have to isolate those patterns, maybe by strictly separating them into different directories or by completing the migration in a focused sprint. Got it. Only after there is one dominant, undeniable truth in the code. Does the rule pointing to it become enforceable rules only work when they reflect the reality of the code base. That is a tough pill to swallow for teams who are hoping AI agents will just magically clean up their migrations while they sleep. It is. But technically it makes perfect sense. You can't fight the attention mechanism. The code is the ultimate ground truth. OK, so assuming we do have a relatively clean, consistent code base, how should we actually structure this rules file so we don't just mechanically recreate an 800 line monster? The author suggests throwing out the traditional sprawling list completely. You move to a conceptual, highly constrained structure. Like a strict template. Yeah. Instead of treating it like a table of contents, you need to think of the prompt as fulfilling only three strict purposes. Defining the environment, locking in undeniable human judgments and providing a routing map to deeper knowledge. Let's break those down. Defining the environment. I'm assuming we're talking about the tech stack here. Exactly. The stack overview. Yeah. But here is the critical constraint. It should be 10 lines maximum and it must be nouns only. No pros. Nouns only. Why nouns only? Because developers naturally want to explain their choices. It feels weird not to write. We use react because it integrates well with our specific internal component library and state management approach. It comes back to how the transformers attention mechanism allocates weight. Every word of that justification because integrates. Well, that all consumes tokens and deludes the attention vectors. Oh, I see. The agent does not care about your feelings on react. It already has the entire internet's knowledge of what react is. It just needs the constraint. So you just write react. You write TypeScript. Exactly. Keep the attention vectors entirely concentrated on the actual technologies. That makes a lot of sense. Strip away the narrative. What about the second bucket? The undeniable human judgment. These are your conventions. The five to 10 most important. Always do this or never do that. Architectural decisions. OK, but they must be things that represent pure human architectural taste. And crucially, they must be things that are not enforced by your automated tooling. Here's where it gets really interesting. The source explicitly states that if your convention section has more than 10 items, your file is fundamentally broken. Yes, it is. It introduces a paradigm shift that is completely counterintuitive to how most developers currently prompt. You should intentionally blind the AI prompt to anything a linter can catch. Absolutely. We are going to get into the mechanics of enforcement just a minute, but keep that rule of 10 in mind. If a machine can check it, the LLM prompts should not mention it. OK, so we've defined the stack with nouns and we've locked in a handful of human judgments, but this brings up an obvious friction point regarding that third bucket, the routing map, right? Because what happens when a concern actually does require more depth than a single noun or a bullet point? Like what? Well, for example, testing conventions. You simply cannot capture how a specific team handles mocking API interception and snapshot strategies in a single sentence. No, you can't. And that is where the routing layer comes out. How does that work? The answer to a complex domain specific concern is never to expand the main cloudy.md file. The answer is to use a specific directory, typically dot claud slash rules slash and create dedicated isolated markdown files for separate concerns. But how does the agent actually know what to do without bloating the initial context? I mean, if I strip all the testing rules out of the main file, isn't the agent flying blind when I ask it to write a test? What's fascinating here is how this leverages the agent's tool calling capabilities to dynamically load context. You don't put the testing rules in the main file. You put a pointer. The main cloud.md simply says before writing tests, read dot claud slash rules slash testing dot MD. Ah, so it's literal routing. Exactly. Let's look at a concrete before and after from the source. The before state is a bloated 50 line paragraph sitting right in the root rules file. Just taking up space. Yeah, it's pleading with the agent to use just telling it to avoid snapshot tests because they're brittle, giving detailed naming conventions for describe blocks and dictating assertion message readability. And because it's in the root file, those 50 lines are consuming tokens and diluting attention every single time a session starts. Exactly. Regardless of whether the agent is actually writing a test that day or just updating a CSS file. Right. It's a massive waste of the working memory. Now look at the after state in the main cloud.md. It is literally just that one line for testing conventions. Use your file reading tool to read the testing mark down file and then inside that dedicated testing file. It is tightly focused, maybe 20 lines describing the testing approach. And critically, it includes a reference implementation. Well, it's an example. Yeah, a specific file path to an idealized test in the code base that the agent can actually go search for and mimic. So when you ask the agent to write a test, it reads the main file, sees the pointer, realizes it needs more context and actually uses its internal tool execution to fetch the dedicated testing file and load it into context dynamically. Yes. It gets highly specific, highly useful information exactly when it needs it. While consuming drastically fewer total tokens across the lifespan of the project, you are keeping the main context window incredibly lean while still giving the agent a massive structured brain to tap into on demand. That is a brilliant way to handle complex architectural rules. But what about the simple stuff? Like what? The syntax preferences, the endless list of don't use console log use strict types always use named exports, that kind of thing. This brings us to the most important technical shift in the entire source material. We call it the enforcement principle. You have to draw a hard impenetrable boundary between a probabilistic rule and a deterministic gate. Walk us through the technical difference between those two things for the listener. Sure. A rule written in plain text and a markdown prompt only shifts probability. It hopes the LLM's attention mechanism favors it. Right. A gate on the other hand, like a git pre commit hook, a TypeScript compiler check, or an ES lint configuration that enforces an outcome deterministically. The code either compiles or it doesn't. Exactly. The commit either passes or it fails. The principle is absolute. Any rule that can be converted into a deterministic gate must be converted and then script entirely from your prompt. So let's put this in developer terms. Instead of begging the agent in plain English to never leave console logs in the code, you just go into your ES lint configuration, set no console to error and hook it up to Husky. Exactly. Instead of writing a paragraph asking for strict typing, you go into your TS config.json, set no implicit any to true and let the compiler violently reject implicit types. You stop treating the LLM prompt as a linter. Let's say you have a strict policy that every new React component must have a sibling dot test dot TS X file. Right. You do not write, please always write a test alongside new components in your markdown. You write a pre commit Baskript that scans staged files, checks for the existence of that sibling test file and exits with a non zero code. If it's missing. And there is a massive hidden advantage to doing it this way. When you're working with autonomous agents, it isn't there. It fundamentally changes the feedback loop. Huge advantage. When an agent writes code and then attempts to commit it, that pre commit gate fires. Yeah. If the gate rejects the code, the agent actually sees the terminal output from standard error. It reads the ES lint violation or the compiler error or your custom bash script output. It parses exactly what went wrong and it fixes it. Usually on the very first try, because the error message is deterministic and explicit. You as the human developer do not even have to intervene. You don't have to review the pull request and say, Hey, you forgot the test file. The pre commit hook acts as an automatic seamless reprompt. It catches the error, feeds the exact context back to the agent and the agent issues an edit command to correct it before you even review the diff. So what does this all mean? It means your clog.md file should be incredibly sparse. Right. It should only contain matters of architectural taste, routing and high level human judgment calls. It should contain absolutely zero rules related to syntax, naming conventions or import paths. If a machine can check it, a machine should enforce it, which totally shifts how a team maintains these agent tools over time. The source lays out a very specific timeline for how this should feel in practice. Let's talk about day one of setting this up. On day one, you write those constrained sections. The nouns only stack the directories, the routing pointers and the handful of architectural judgments. The goal is to keep the entire file under 80 lines, 80 lines total for a production code base. Yes. And the author explicitly notes that it should feel incomplete. You will feel an overwhelming urge to add more edge cases and explain more nuances, resist it. Let the deterministic tooling do its job. Okay. And then we quantum beyond you're working. The code base is evolving and the agent inevitably makes a mistake. You write something you don't like. What is the protocol? Because the old way was just opening the markdown file and adding a new bullet point. The new protocol is to ask one question. Can I add a gate for this? If the agent used the wrong import path, can you add an ES lint rule to restrict imports? If yes, you add the linter rule, you never touch the prompt. Right. If the answer is no, if it is truly an unlintable human judgment call, then and only then do you add a one line rule to the markdown file? But here is the catch, the forced constraint. Every time you add a new rule, you must actively delete or consolidate an old one. Oh, a forced constraint. The file isn't allowed to just continually creep up in token count. Exactly. It forces you to prioritize what actually deserves the attention mechanisms focused. And an author introduces a fantastic metric here called the two minute rule. Yes. If a rule has been sitting in your prompt file for a month and it hasn't actively prevented an error in that time, you delete it. Because it is no longer earning its key. Right. It's just sitting there, silently consuming your context window tokens, diluting the attention weights for absolutely no tangible benefit. The ultimate test of your rules file is incredibly simple. If it takes you, a human developer, longer than two minutes to read it from top to bottom, it is too long for the agent. That two minute read, that is a radically different vision than the 800 line monoliths we see in so many repos right now. It is the difference between an agent that works seamlessly with your deterministic tooling and an agent you are constantly fighting probabilistically. This has been incredibly practical, but before we wrap up, the source material left a little teaser at the end that we have to mention, a glimpse into where this agent architecture is actually heading in the near future. Yes. The concept of life cycle hooks. Because we have spent this entire time talking about optimizing the context window at the very start of a session, the root collati.md initializations. But there is an emerging concept in the agent framework of using dynamic triggers, things like session start, pre tool use and post tool use. The idea being, what if you could give the agent instant hyper specific orientation at the exact millisecond it needs it at zero ambient context cost? Exactly. Think about the pre tool use hook. Imagine a hook that automatically runs a script to inject the current up to date of a schema into the context window, only milliseconds before the agent executes a SQL query tool. Oh, wow. And then it drops that schema from the context immediately after the query returns. The attention mechanism is perfectly focused for the exact task and then immediately freed up. It pays for itself instantly. But as the source notes, building up that kind of dynamic life cycle architecture is a deep dive for another day. Definitely something we will be keeping a close eye on as these frameworks evolve. All right. As promised, we want to leave you with one concrete. Try this tomorrow takeaway, something you can act on before your very next coding session to make your agent more consistent. It's very simple. Open up your clauie dot and D your dot cursor rules or whatever agent prompt file you are currently using in your main repository. Read through it and find just one always or never rule that relates to syntax, naming conventions or imports. Find that rule, highlight it and delete it from the text file completely. Then open your terminal, go into your configuration, whether that's ES lint, TS config or a Husky pre-commit hook and configure your tooling to enforce that exact rule deterministically instead. Shift that constraint from probabilistic hope to compiler hardware. Take that first step toward a rules file that is actually enforceable. Let the LLM focus on architecture and let your linters focus on the syntax. Think back to our new hire with the 800 page handbook. Stop asking them to memorize the rule about not eating at their desk and just physically remove the desks from the floor. Make the right way the absolute only possible way. Thank you for joining us on this deep dive. We will catch you on the next one.