Improve your AI code output with AGENTS.md (+ my best tips)

A good agents.mmd file can make a pretty

substantial difference in the quality of

AI coding output that you get. Let me

show you an example. I've got this

dashboard design in Figma that I want to

convert to code. I'll export it using

the builder.io plugin and then paste it

here and say add this as an appwide tab.

So you'll see from the Figma design, the

first thing the agent has to do is

explore the codebase. That's because we

didn't give any instructions on where to

find what. So for this really massive

codebase for every new chat, it's got to

start from scratch. And here's the

result. At a glance, it's not bad. It's

got our interactive chart. Styling

generally looks right. Buttons are

interactive. Let's go to the code. So, I

like it's pretty well structured with

multiple components using our design

system, but I'm seeing a few small but

annoying issues. First, while we use

emotion CSS, we don't use it in this

format. You could add another prompt

clarifying this, but it's annoying to

repeat yourself. We also usually use

Mobex for state. And while I really like

that it used apex charts like we do, it

figured that out. It tried to match the

design a little too perfectly, providing

this big HTML string for the tooltip UI

to try and match exactly what our

designer gave us, but I'd much rather

not do overrides like this and use with

out of the box, even if it's a little

bit different. I noticed one other issue

is the AI is assuming we're using a

slightly different version of material

UI and some of these styles won't work

as expected. I can also see that it's

mostly using our design tokens, but when

I go and test and dark mode, I see oo it

missed a few spots. This is the type of

stuff I would normally just tell the AI

and it'll fix. But there's a much much

better way. An agents.mmd file file you

add to your code lets you add these

critical clarifying rules so your AI

output doesn't just look right. It more

deeply is right every time. Let's go

through my top tips for improving your

AI coding outputs by adding a few key

things to your agents.mmd file. Now the

first thing that's really nice about

agents.mmd is that more and more tools

are standardizing on respecting the

agents.mmd file. So, one of the simplest

ways you can start approaching this is

literally just listing the things that

matter to you. You don't have to

overthink this or get over fancy. For

example, you could literally just say do

and list bullets. Use mui v3. Use

emotion CSS. Use mobx for state

management. Use design tokens. Use apex

charts for charts. Maybe you have some

don'ts. Don't hard code colors. Don't

use divs. We have a component already.

You can be as detailed as you want. And

I'd encourage you to be as iterative as

you like. Try prompts. Look at what you

like and don't like and fill out the dos

and don'ts accordingly. Now, there's a

few other things I found can go a long

way. One really annoying thing agents

can do is try and run a full build of a

huge project where it just wants to know

if a specific file passes prettier or

type check. The thing about agents is

they know what file path they just

updated. So, they don't have to run a

full build just to check that file. We

can tell how to check and format

specific files by path. You can say use

the above commands when possible to do a

full build do yarn build app. Sometimes

I like just telling the agent run a

build and fix everything until the build

passes. Now one thing we talked about

too is having the agent having to

refigure out the same things over and

over. If we supply just a little bit of

project structure, then it'll know where

to go for things automatically and not

have to reinvestigate every time. Agents

can explore and look up other files. So

in a lot of cases, you can just point it

to files like see app.tsx tsx for our

routes. Agents can do basic file

searches by name. So I don't even need

the full path. C app sidebar for our

sidebar. Most components are in app

components. Whatever else you like.

Again, the agent will figure it out if

you don't supply it. You get faster

responses if it just automatically knows

where to look. Another big one I like to

give it is explicit good and bad file

examples. This is a large codebase. It's

got plenty of examples of outdated

patterns like using React class

components. So, let's be explicit and

give it good and bad patterns. Void

class-based components like get

admin.tsx. Instead, use functional

components with hooks like projects.tsx.

AI is great with examples. See if you

have good examples of using your design

system or state management or patterns

like forms. Being very explicit about

the good patterns and what to replicate

really helps. So, when you ask for

things like forms or dashboards or

tables to be generated, make sure the AI

knows well what patterns we want to do

and maybe what we want to avoid. And

remember, the key to all of this is

trial and error. Run prompts, see what

you like, append information to better

guide the AI based on what you learn.

Now, if you want help from AI to

generate these rules, there's a couple

tools that might help. Claude Code has a

really cool command for this called

/init that will scan your codebase and

generate a claw.md file. You can just

rename that from claw.md to agents.mmd

to support more tools. Now, what I have

seen go wrong with this though is it's

looking at your whole codebase. And if

only some of your codebase is modern and

some is more legacy, it's probably going

to write a lot of rules reflecting the

legacy parts. And so you're going to

want to go in and refine what it

generates for you. No tool can perfectly

just replace the most important work,

which is trial and error and appending

new rules to make sure things get

better. Another common challenge people

have is they depend on an internal

design system. That code probably comes

from a separate package. You may or may

not even have access to that code base.

And so if you're trying to get AI to

generate things using that design

system, but it doesn't have thorough

knowledge of it, your results may not be

great. To solve for that, a builder

rebuilt something called design system

indexing. You run it in your design

system. It finds all the code, examples,

and patterns and generates specific and

LLM optimized instructions on how to use

the design system correctly and can

improve your results a lot. Now that

we've got our new rules, let's go back

to Figma, part the design, paste, tell

it to add a new sidebar tab. Let's see

how the results look. And there we go.

This is looking much better. The select

menus are correct. Styling's improved

because it's not trying to do things

that this version of the design system

doesn't support. Looking at our tool tip

basically looks the same, but it's using

what's out of the box, which is what I

wanted. Let's test dark mode. Much

better. I love it. This is what I

wanted. Looking at the code, I'm seeing

us using the correct CSS format, correct

design tokens, and no weird HTML tool

tip overrides. We're using what's out of

the box, and I like it. And all this

took was clarifying a little bit of dos

and don'ts and best practices. This is

36 lines of markdown and I'm way happy

with my results. And if I go and add

more, like add a table of code accepted

by user, I also know it's going to

follow the right conventions and can

breathe a sigh of relief. It's also not

going to need to explore broad parts of

the codebase just to know what I want

here. And now that code output I got was

not only a lot faster, it's also a lot

better. This is correct. Let's check

dark mode. I love it. One other really

cool bonus tip you can do is point the

agent to other docs. For example, I like

to point to API docs so that if I'm

hooking up a new dashboard, the agent

can automatically find the API docs and

or source and know what requests to make

and how to make them so they can hook up

to real data from the start. Check out

my full blog post for additional tips

that can increase your AI agent coding

output quality as well as design and UI

quality. And let me know in the

comments, what have you found that can

work really well to add to your

agents.mmd or rules files.