if you build with ai agents, you know this one. you explain your colors, your rules and what not to touch. next chat, it's all gone.
the fix is one file in your project. every agent reads it before it touches anything. i've built with this for about a year, and you can set it up in 10 minutes.
what you need
- claude code, codex, or both
- a project folder, new or old
what you're building
one file called CLAUDE.md at the root of your project. each step adds a section to it. the finished file is at the bottom if you'd rather copy the whole thing.
01make the file1 minute
cd path/to/your/project touch CLAUDE.md ln -s CLAUDE.md AGENTS.md
claude code reads CLAUDE.md. codex reads AGENTS.md. the link gives them one set of rules, so you only edit once.
02say why it exists1 minute
## why i'm building ___ because every time i ___, i ___.
if you can't finish that sentence, stop here. you're about to build something nobody needs, including you.
03set the working rules2 minutes
a rule in a prompt lasts one chat. a rule in this file starts every session.
## how to work - one clear primary action per screen - never invent data, numbers or "proof". say what you didn't check - ask before touching payments, auth, migrations or anything that deletes data - before you say "done", run it and show me the result
04write your taste down2 minutes
without this, every new app gets new buttons. open three apps you like and write down what they have in common, or start from this and change the colors.
## design - one main surface per screen, sections split by thin dividers, not a card for everything - dark background #09090b, surface #18181b, borders #27272a - one accent color per product - outlined secondary buttons, one filled primary button - controls at least 40px tall on desktop, 44px on touch - every dropdown matches the theme and works with the keyboard - visible focus states, reduced motion respected
05fix how feedback works1 minute
vague feedback gets guesses. "ew looks ugly" has never fixed anything for me. name the element and point at something real.
## feedback - if my feedback is vague, ask which element and what to compare it to before changing anything - change only what i named
the sentence to use yourself: "change [the exact element] from [what it is now] to [what you want], like [a real app you can point at]."
06make it check numbers first1 minute
a wrong number explained well still reads right.
## numbers - before explaining a number, say what's being counted: who, what, which time window - pull the raw count once and check it against one other source - if they disagree, say so and stop
07limit what it can reach1 minute
## keys and data - read-only unless it truly needs to write - scoped to one project - expires on its own - send only the data the answer needs - secrets never go in the repo
08define done1 minute
passing on your laptop only tells you it runs. and once other people use your app, they need to know when it changes.
## done and shipping - test it where it will actually be used - watch one real person do the main task. don't help - one file holds the version number - every release gets a git tag and a changelog entry - only list a bug once you've reproduced it - the app tells people when a new version exists - a failed update leaves the old version working
check it worked
open a new chat and ask: "what are the rules in this project?" if it can't list them, the file isn't in the root.
three ways this breaks
- the file gets too long. keep it to about a page. if a line doesn't change what the agent does, cut it.
- you never update it. when you correct the agent twice on the same thing, add a line.
- you trust it with things that can really hurt. a rule is a strong default, and it can still be ignored. a key that can't delete can't delete, so use step 7 for anything that matters.
the whole file
## why i'm building ___ because every time i ___, i ___. ## how to work - one clear primary action per screen - never invent data, numbers or "proof". say what you didn't check - ask before touching payments, auth, migrations or anything that deletes data - before you say "done", run it and show me the result ## design - one main surface per screen, sections split by thin dividers, not a card for everything - dark background #09090b, surface #18181b, borders #27272a - one accent color per product - outlined secondary buttons, one filled primary button - controls at least 40px tall on desktop, 44px on touch - every dropdown matches the theme and works with the keyboard - visible focus states, reduced motion respected ## feedback - if my feedback is vague, ask which element and what to compare it to before changing anything - change only what i named ## numbers - before explaining a number, say what's being counted: who, what, which time window - pull the raw count once and check it against one other source - if they disagree, say so and stop ## keys and data - read-only unless it truly needs to write - scoped to one project - expires on its own - send only the data the answer needs - secrets never go in the repo ## done and shipping - test it where it will actually be used - watch one real person do the main task. don't help - one file holds the version number - every release gets a git tag and a changelog entry - only list a bug once you've reproduced it - the app tells people when a new version exists - a failed update leaves the old version working
built this way
s8vr (invoicing), scrollback (a menu bar app for your ai chats), cassette (voice messages as gifts) and watchtower (analytics in plain english).