@bassam.cz
Free guide · SETUP

The setup I use to build apps with AI

Copy it in 10 minutes.

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

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

Copy this
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

Copy this
## 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.

Copy this
## 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.

Copy this
## 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.

Copy this
## 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.

Copy this
## 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

Copy this
## 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.

Copy this
## 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 whole file

Copy this
## 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).