Summary 👇🏻 One file that stops Claude from overbuilding, second-guessing, and editing code you didn't ask it to touch — based on Karpathy's observations, 43,000 GitHub installs in a week.
Hey thanks for watching! I'm Jay - spent my career in data and brand building, founded the ROBO Group to help forward-looking businesses grow with AI, and now teaching what I know through this channel and the RoboNuggets community.
What if one file can fix the biggest problems that every cloud code user deals with?
Well, Andrew Karpathy listed down the top mistakes that every AI agent makes,
and this single Claude.md file just codified the fixes for those mistakes,
and almost 43,000 people installed it just in the past week.
In this video, I'll break down what this magical Claude.md does,
how it improves your AI agent setup, so that you too can use Claude as good as how Karpathy does it.
And if you're new here, my name's Jay.
I spent over a decade working with brands you probably know,
have been in AI since my master's in data science,
and now I run our AI solutions practice in one of the largest AI communities globally.
Let's get started.
So some time ago, Andrew Karpathy, who previously headed Tesla AI,
and also part of the founding team of OpenAI,
made this now viral tweet where he provided a good analysis of how to work with agents better.
It's actually a pretty detailed one,
and you can see here at the bottom that it already garnered seven,
almost eight million views at this point.
Now, a lot of people took note of this tweet once again,
because over the past week, what happened was this repo called AndrewKarpathySkills
just shot up in popularity over at GitHub, now at over 43,000 stars,
and it was made and published by this developer, Forrest.
So credit where it's due.
And if you go to this skill, what it is, is basically a single Claude.md file
to improve Claude's behavior, which is derived from the observations from that tweet.
And I think the reason why it became so popular and viral over the past week
is simply because of how simple it is.
It's one Claude.md file that you just drop into your Claude code,
and also the solution that it provides here are boiled down to four key principles,
which I'll talk about in a bit.
And I think regardless whether you want to use this Claude.md file or not,
learning about these principles will level up how you use your AI agents
in order to make sure that you get the output that you want whenever you work with Claude.
But if you were looking to install this and try this out yourself,
what you can simply do is to provide your Claude code with this GitHub link.
But if you're already using Claude code,
most likely you already have a Claude.md file,
in which case it would be better for you to provide a more detailed prompt like this,
where you explain to your agent that you're giving it a set of guidelines
called Carpati skills, and more importantly, to suggest to you
how you can best integrate it to your specific setup.
So this more detailed installation prompt, I will link it down below if you need it.
But as I mentioned, the core of this Claude.md file are these four principles
that I think are worth learning no matter what AI agent you use.
So the first principle that it instills to your agent is that
it allows Claude code to think before coding.
And just to refer back to what Andre wrote here,
you can see he mentioned that the most common category of mistake that these agents make
is that the models make wrong assumptions on your behalf
and just run along with them without checking.
They also don't manage their confusion, they don't see clarifications,
and they don't surface inconsistencies.
And so the core idea for this principle is this.
Without this rule, Claude assumes what you want.
With it, Claude asks first.
And so if you were to boil down one key principle that you should follow
in order to upgrade how you should work with agents better, it is basically this.
It is almost always better to have your agent ask you questions
in order to clarify intent before it starts building and coding things for you.
And so just to illustrate this, what I have here are two Claude code sessions.
This one doesn't have the Carpati Claude.md,
and this one is where I loaded that Claude md we just talked about.
And what I'm going to do is just give each of these agents a copy of this rubric application
to illustrate the difference between the approaches of these agents
with one of the agents not having this Carpati principle baked in
and the other agent following the principle that we just talked about.
So now just to show the difference between these two,
if I send the same task to both of them,
or I'm simply requesting, let's say, to add a toggle for light mode to the rubric app.
If we send it to both with this one to recap,
has that Carpati skill and Claude.md already installed.
And so now that both of those sessions are done,
you can see this one without the Carpati Claude.md confirmed to me
that there is a light mode toggle.
But if I look at the application it's working on, it doesn't actually have it.
And if you compare that with this session,
which was working on this localhost 10001,
this also confirmed to me that the toggle is in the top right bar next to search.
And you can see that it is actually here.
And it was able to implement that
because it actually thought through the problem
and even was able to decide what are the right colors
across all of the other icons in here.
Which if you compare that to this one,
which was coming from the agent without that Claude.md file,
it thought that it was able to do the task, but not really.
And if you want to sort of peek under the hood
on why the Carpati Claude.md is more proficient with what it just did,
if you ask both to outline the steps that they just took,
you can see the vanilla Claude code.
It did do some detailed steps like finding the right files,
reading the CSS variables, and trying to add a light theme CSS.
But if you just compare that with the outline
of the steps of the Carpati Claude code,
you can see this is much more detailed
versus what the vanilla Claude code did.
And so the result of that is that with just one prompt,
it was able to one-shot this light theme for us without any issues.
Now, real quick, we just released the agentic AI masterclass
for our members at RoboNuggets,
which takes you from zero to mastery when working with agents.
There's a link to the community in the pinned comment below.
We've got founders in there who landed their first client in weeks,
live build sessions where we create this stuff together,
and the actual templates behind what I showed in this video.
The community is also the reason these lessons get made,
so see that below if that's for you.
The second principle that it implements is to put simplicity first.
And just going back to what Andre wrote here,
he mentioned that these AI agents by default
will implement an inefficient, bloated, and brittle construction,
which is sometimes over a thousand lines of code.
And it's up to you to challenge that,
and only then will they be able to realize
that they can actually cut it down to 100 lines or less.
And so without this principle, your AI agent tends to overbuild,
but with it, Claude is riding the minimum.
And the reason, by the way, why this is so important
is because you have to remember that these AI agents,
they are mostly trained on production code basis,
and so they default to production patterns,
which is mostly large-scale in nature.
And so when you ask for a simple feature add,
it tends to overthink, it tends to overbuild.
But what this Claude.md file does
is that it allows your agent to put simplicity first.
So now for our second test, what I'll be doing
is asking both of these agents to add a search bar
that filters the tab list.
So let's send that over,
and we'll see what the difference are between these two.
And once those two are done,
again, the vanilla Claude code confirmed to me
that the filter search bar is available.
But if I refresh this localhost 10,000,
it wasn't really able to implement that,
which in contrast to the Carpati-Claude code,
you can see it was able to successfully add this filter,
which I wanted, where if I just type in there,
it will be able to find the specific tab that I want.
And in fact, I was curious
because the vanilla Claude code
doesn't seem to be changing anything
in the app that it's working on.
But you can see here that it does know
exactly the application on port 10,000, which is this one.
But because it doesn't have the Carpati skill,
it tends to fall to the same agentic traps
that this Claude.md is hoping to address.
And so for the Carpati-Claude code,
I just ask it how it implemented principle two in that build.
You can see it made deliberate decisions
around not having complex logic
to track which separators are between visible tabs
and also didn't add other items, which I didn't ask for.
And what's even better is that the amount of lines
that it added is only 20 lines,
which is much more simple and lean
versus what the vanilla Claude code added,
which is more than 50% of that.
So you can imagine for bigger code bases and bigger builds,
then having this principle does really help.
The third principle is the ability to make surgical changes.
And the key observation
that you may have also seen these agents do
is this piece by Andre where he said
that they still sometimes change or remove comments in code
that they don't like or don't sufficiently understand,
even if it is orthogonal or not related to the task at hand.
And so without this rule,
Claude and your other agents tend to improve things
that you didn't ask for,
but with it, Claude changes only what it is that you want.
Now, what's interesting about this principle
is that it is actually one of the sneakiest failure mode
for agents because it does look helpful
if when let's say your agent writes multiple lines of code,
but it's sort of like productivity for productivity's sake.
If you can do the job in two lines of code,
then that not only simplifies your setup,
but it also consumes less tokens for you.
So now for this third principle,
the test that I'll do is to have them both update the font
from outfit to this font called enter.
And then let's see what they will actually do.
And so looking at those two sessions,
you can see this one is still working
because even though it confirmed to me
that it actually changed the fonts,
if you look at the dashboard here,
it is still the same font as what we started with.
And so this might be a common problem for you
where when you're working with AI agents,
because it doesn't have those best practices in mind,
you actually end up spending more tokens
because the bills and the changes that you want reflected
are not properly being updated.
And so right now this session
is basically just burning through my tokens
in order to just assess why this particular issue is present.
Meanwhile, if I go to this Carpati Claude code version,
the one with the light mode,
you can see that it was able to successfully change the font
into this new one called enter.
And again, that's just one command
was able to find every instance of outfit
and replace it within the code base.
And here you can see,
I just ask it how it implemented principle tree
in that whole build.
And you can see what it did here
is to only apply surgical changes
and not reformat or restructure
any of the font family declarations,
not reorganizing the Google fonts URL
and basically just leaving out
and not touching anything that it shouldn't touch.
Meanwhile, this vanilla Claude code
is still working through its errors
and it's just spending tokens left and right.
And the final principle that it implements
for your Claude code
is the ability to have goal driven execution.
And this now operates within the core concept
you need to understand,
which is defining what done looks like.
And just going back to the Carpati tweet,
you can see he mentioned here
that LLMs are exceptionally good at looping
until they meet specific goals.
And so instead of telling it what to do,
just give it success criteria
or a specific goal in mind
and just leave it to explore.
And that is how you can extract the most value
from these AI agents.
And he also mentions here
that changing your approach from imperative,
which is basically commanding agents
on how to do things,
to declarative,
which is you declaring what you want
out of these agents,
then you'll be able to get better results each time.
And to illustrate this principle,
you can see what I did here
is to ask our agent to make a version
of this skill trees view,
which is a nice visual view here in rubric
of each of our agents
and what are the specific skills
that they have access to would be.
But here I just ask a version
where the goal is for the user
to be able to select an icon for each agent here.
And so when it was done,
you can see that
when I click on each of these agents,
you now have the ability to change the icons,
which if I select, let's say this one
for the beta agent,
it will update that icon cleanly in the UI as well.
And you can see what I did for this prompt
is to just give it a goal, right?
So I just ask it to think of a way for the user
to be able to select an icon for each agent.
I didn't really specify
which part of the user interface here
should the icons live in.
And I also didn't specify
how many icon options it should provide
or what are the designs.
Now you can obviously be more imperative
or prescriptive to your agent
on where each icon should live.
But I think if you have this Claw.md
and there is that goal-driven mindset for your agent,
then if you provide a clear end in mind
and a definition of done,
then it'll be able to work through
pretty much the best course of action
for that build that you're giving it.
And there you go.
All the principles that Andrej Karpaty himself uses
to improve his Claw code setup
now publicly available to this repo.
I hope that was useful.
And if it is, then consider subscribing
because that helps us a lot
to put out more educational content like this.
And if you want to learn
how to automatically build slides with Cloud Code,
just like the one I showed in this video,
then you can watch this video next.
I'll see you guys next time.
Thank you.