If you're running claw code or really

any coding agent, there will be some

kind of init command. This promises to

initialize a new claw.md file or maybe

an agents.md file with codebased

documentation. I am going to recommend

that you never ever run this. And if you

find a claw.md file or an agent.mmd file

that you think has been created by an

agent, delete it. The file that this

creates will burn tokens, will distract

the agent, and will go out of date

faster than a pair on a hot day. This

paper evaluating agents.mmd are

repository level context files helpful

for coding agents. This actually put

this to the test and what they found was

we conclude that unnecessary

requirements from context files make

tasks harder and human written context

files describe only minimal

requirements. We'll get to what this

means and what you should actually use

claw.md files for in this video. If you

dig this kind of thing, then you should

check out my newsletter where I post my

new agent skills as I come up with them

and test them. And I'm also working on a

Claude code course which is going to be

an absolute banger. But let's actually

test this out and run in it inside my

work repository to see what happens. As

a bit of background, this is a fairly

large repo. It has a whole bunch of

package.json scripts, a whole bunch of

dependencies. It's a React router

application with an effect backend,

which is my favorite stack these days.

And there is currently no claw.md file

in here. But let's initialize one and

let's see what happens. We can see, by

the way, it's doing a explore step here.

And it's using sonet 4.6 for the

explore. So what this is doing is it's

calling a sub agent. I'm making that sub

agent explore the codebase and that sub

aent is going to report a summary back

to the orchestrator agent, the parent

agent. It's reading a bunch of files

here, doing a bunch of searches and just

getting an overall sense of the

codebase. Now this explore step is going

to be something that the LLM does or the

agent does every single time you do a

piece of work. It needs to explore the

codebase before it can feel confident

making changes to it. In fact, you can

think of there as being a few main tasks

that the agent does or a few main ways

that the agent uses up its context

window. The first chunk of usage is

going to be the system prompt. So,

anything that's inside the agent that it

has access to on every single request.

This would be things like, you know, MCP

servers and maybe uh any system tools

are going to be in here too. And

anything that you put in your claw.md is

going to make this bigger and bigger and

bigger. And if I just shift these up

here a little bit more, you can see

there's a little bit less available in

the context window for the other steps.

The other steps are exploration. So

exploring the codebase, understanding

what's there. Then we've got the actual

implementation, doing the thing, writing

the files. Then we've got testing,

running any feedback loops, unit tests,

any debugging goes in here, too. This

can absolutely balloon if something goes

wrong during implementation. Now, most

of these phases are fairly flexible. If

it's a very simple implementation, it

might only be very small like this. If

it doesn't need much testing, it might

be very small like this. But the thing

that's not flexible at all is going to

be the system prompt because that is

hardwired the moment that the uh agent

starts its work. So everything that you

can do to reduce this initial prompt

here to make this smaller is going to

first of all give you more space to do

your actual work, but it's also going to

reduce your costs. So for me personally,

I think of this as getting this the

lowest I can is the best possible

outcome. But when might you want to add

some information in the request that

helps the LM? Well, a common piece of

advice is if you notice something that

the AI agent is doing that you don't

like, then you put it in here. In other

words, if it tries to use the wrong

package installer or something, it uses

npm instead of pmpm, you can put it

inside claw.md and it will remember for

next time. Or if it's using a specific

pattern in React or something that you

don't like, then you can put it in

agents.mmd and it won't uh do it

anymore. So even if you're not running

claude in it, then it should like this

probably will grow over time and that is

a little bit annoying because this

little chunk here is global and that is

a killer because not all of it is going

to be relevant to every single request

that your agent makes. And so yeah, the

stuff you added in there about React is

going to be worth it there. This first

session might be like a front-end

session or something, but the next one

might be a purely API database session

where the stuff you added about React is

going to be completely useless. Even

more, you might have another session

that's just purely about documentation.

So, whenever you add something to

claw.md, you should be thinking about

all of these different use cases that

agents can have in your codebase because

anything you put into this global scope

here will affect everything you do and

cost you tokens every time you do

anything. So, with that in mind, let's

see the lovely init file that Claude

created for us. This file provides

guidance to Claude code when working

with code in this repository. Wow, what

a brilliant intro. Who is this for?

Like, what is going on here? Why would

you even print this? This is going to

cost me tokens on every single request,

Claude. It then gives us the commands.

Okay, these are unbelievably trivial to

discover. You literally just go into

package.json and they're all right

there. If you need to discover what

commands are available, you can actually

look at the source of truth, right? You

don't need this extra documentation. And

again, this is costing tokens on every

request. So, kill this. Don't like that

at all. Now, the architecture section.

Full stack React router SSR app for

managing course video publishing

workflows. React 19 with React compiler

enabled. Does it need to know this on

every single request? And how easy is it

to discover? Well, what it can do is it

can see that there's a React router

config file. So, it knows that it's in a

React router project. If it needs to

look that it's serverside rendered, it

can look in this tiny file, which might

even be less uh tokens than the actual

explanation, maybe comparable. If it

needs to, for whatever reason, know that

we're using React compiler, which it

probably shouldn't, then it goes into

v.config.ts and it can just see it

there. Right. Nice. So all of that

information is trivially discoverable uh

on its own. The only thing maybe is the

purpose of the thing. But then again the

whole project is called course video

manager. So I think I can safely delete

this too. Now we get to some stuff that

is a little maybe a bit more useful. All

backend logic uses effect for dependency

injection error handling composition

services defined with uh effect

services. And I really hate it when it

references actual files here. One thing

that makes me super nervous about this

is that this will rot really really

fast. As soon as we change any of the

implementation here, then this file is

going to go out of date and it's going

to conflict with the reality in our

codebase. Now again, this is trivially

discoverable that we're using effect

because we've got effect imports all

over the place. If we look for

effect.service, then there are eight

instances of it and they're all visible

in the file system too under DB service,

drizzle service, dump service. That's

not why not what it sounds like. repo

passer service. The file system is a

really nice way to tell claude what's

going on. And if you structure your file

system correctly, you can kind of give

it an impression of the overall

architecture which is defined in the

source of truth of your code, not in

documentation which can rot away. This

one especially key services, drizzle

services, DB function services, database

dump services. If I change the name of

any of the implementations here, I have

to go back and check this out. Tagged

errors go away again. Here I have a

video editor as part of this. So clip

operations go through a single post

endpoint API clip service. This is again

trivially discoverable from the code.

There's no reason to have this on every

single request because most of like the

actions that I take won't touch this

clip service. Again routting

configuration. I'm not going to need

this on every single request. Kill it.

Complex UI features use effect reducer.

I'm not going to use this on every

single request. And you get the idea

here. Too much is global. Too much is

going to go out of date and just rot

away. And it's just too freaking long,

man. I look at this and I think about a

key idea that I always have in the back

of my mind whenever I'm talking to LLMs,

which is that LLMs have a context

window, of course, but they also have a

budget for how many instructions they

can take on at one time. We can think of

this sentence, let's say, as an

instruction to use effect for dependency

injection, error handling, and

composition. This is another instruction

inside here. Services are defined with

this. This is another instruction. Roots

execute effect via runtime live.r run

promise. LLMs really only have a

realistic instruction budget of around

300 to 400 instructions. This increases

the kind of bigger model that you use,

but even then it only caps out at like

500. So if you're adding a bunch of

instructions into your claw.md file,

most of which are not even relevant to

the task at hand. You're just hamstring

your agent before it even gets started.

But this steering, like providing this

information to the LLM, should live

somewhere because there is useful stuff

in here that I do want to steer the LLM

towards in general. For instance, like

LLM seem really reluctant to use

reducers in their front-end logic, but I

find reducers are amazing with LLMs

because you can pull them out as a

testable unit and use that testable unit

to then drive the entire UI or at least

like reasonable size chunks of that UI.

So, I would be most likely to put this

stuff into skills that the LM can

discover, but don't burn their

instruction budget immediately. But

talking about that and talking about

skills is probably the topic for another

video. So if the steering stuff belongs

in skills and if the like uh basic setup

stuff doesn't belong here at all like

package.json script and all that kind of

thing, what should you actually put in

your claw.md? Well, the only thing I

actually have in any claw.md in my

entire setup is if I go into um memory

here and I've open the memory file here,

all I've got is a single line which is

six words saying you are on WSL on

Windows. And this is really just because

it's a kind of unintuitive setup and it

has some issues when it comes to path

resolution across the Windows Linux

divide. And I found that this single

instruction here just gives it a lot of

extra context that it needs. I've also

advocated in the past kind of using this

file to steer the agent itself. For

instance, I had this one for a while in

all interactions and commit messages be

extremely concise and sacrifice grammar

for the sake of concision. Instead, I

prefer now I think this is actually

better placed inside a skill. But even

then, I'm actually not running this yet.

I really just keep the global stuff down

to a minimum. So hopefully that makes

sense why you should never ever run

Claude in it. It's going to spill a

whole load of useless crap into your

global context where it simply won't be

relevant for most of the operations that

you will need to perform and it just

loves putting in specific patterns and

files into here which will rot away as

soon as the underlying code changes. So

either that means you need to burn

tokens to keep this up to date which

just feels crazy to me or you just

delete it. Bye-bye claude.mmd. And then

you rely on the built-in explore phase,

which every single agent should be doing

now to build up the needed context just

in time before you start the

implementation. But thanks for watching,

friends. I'll be covering this in even

more depth in my upcoming course and

I've already got some stuff on this on

the newsletter. So, thanks for watching

and what should I cover next? Let me

know if you have any questions about

LLMs, about anything around this kind of

AI coding area. And either way, thanks

for watching and I will see you very