Section 3
AI assistants wander. Not because they're bad at their job — because they forget. A few small files fix this almost completely.
You'll have this experience within your first week:
You ask for a small change. You get the small change — plus three features you never mentioned, a library you didn't want, and your color scheme quietly redesigned. Everything works. None of it is what you asked for.
This isn't the AI being difficult. It's this:
So don't rely on it remembering. Write things down where it will find them.
Pilots call this a harness — the thing that holds you in a known position so you can't drift out of it. Same idea. A few plain text files in your project folder, and your AI reads them every time before it touches anything.
Two files do about 90% of the work:
| File | Who it's for | What goes in it |
|---|---|---|
README.md | Humans | What this is, what it does, how to run it |
AGENTS.md | AI | The rules. What to do, what never to do. |
The .md means Markdown — plain text with a couple of symbols for headings and lists. You already know how to write it. # makes a heading, - makes a bullet. That's most of it.
The README is the front door. It answers one question for anyone who opens your folder — including you, in six months, having completely forgotten: what is this?
Start with this and fill in the blanks:
README.md
# Project Name
One sentence saying what this is and who it's for.
## What it does
- The main thing it does
- The second thing
- The third thing
## How to run it
Step by step, from nothing. Assume the reader has
just downloaded this and has no idea.
## Where it lives
The web address, if it's online.
The server it's on, if there is one.
## Status
What works, what's half-finished, what's next.
| If you're building… | Add a section about… |
|---|---|
| A website | The address, where the files live, how to publish changes |
| A game | The rules, the controls, how to win |
| A tool or script | What to type to use it, and an example |
| Something with accounts or payments | What data it stores, and where secrets live (never the secrets themselves) |
| A school project | The assignment, the deadline, what's being graded |
This is the one that stops the wandering. The README says what the project is; AGENTS.md says how you want it worked on.
Here's a starter that works for almost anything. Copy it into any new project and edit the top part:
AGENTS.md
# AGENTS.md
Instructions for any AI working in this project.
Read this before making changes.
## What this project is
<One or two sentences. Be specific.>
## What this project is NOT
<List things you've decided against. This section
prevents more trouble than any other.>
## How to work with me
- Do exactly what I asked. Nothing extra.
- If my request is unclear, ask me before building.
- Explain what you're about to do before doing it.
- Make one change at a time so I can follow along.
- If you disagree with my approach, say so once,
then do it my way if I confirm.
## Technical rules
- Plain HTML and CSS unless the project genuinely
needs JavaScript.
- If JavaScript is needed, use Bun.
- No new libraries or packages without asking first.
- Keep it simple. Prefer boring and obvious over
clever and short.
## Design rules
- Mobile first: design for a phone, then make it work
on bigger screens.
- The page must never scroll sideways.
- Text no smaller than 16px.
- Tappable things at least 44x44px.
## Never do these
- Never delete files without asking.
- Never run `rm -rf`.
- Never commit passwords, API keys, or secrets.
- Never change files outside this project folder.
- Never redesign things I didn't ask you to touch.
## Commands
- Run it locally: <command>
- Publish it: <command>
| The rule | The problem it prevents |
|---|---|
| Do exactly what I asked | Three surprise features attached to a one-line fix |
| Ask if unclear | Confidently building the wrong thing |
| One change at a time | Forty files changed, no idea which one broke it |
| No new packages without asking | Projects that mysteriously stop working months later |
| Never delete without asking | Exactly what it says |
| Never commit secrets | Passwords published on the internet forever |
Claude Code looks for a file called CLAUDE.md first. If it doesn't find one, it reads AGENTS.md instead.
That ordering matters more than it sounds:
CLAUDE.md and an AGENTS.md, Claude reads only CLAUDE.md — and quietly ignores everything in the other one. People lose hours to this. They update the wrong file and wonder why nothing changed.
Simplest approach: keep one file, and make it AGENTS.md. Every tool reads it, including Claude.
If you ever do need both, don't write them twice — make one a pointer to the other:
ln -s AGENTS.md CLAUDE.md
That creates a signpost rather than a copy. Edit AGENTS.md and both stay in step automatically, because there's only ever one real file.
Most people will see what you build on a phone. Most people build on a laptop and forget. The result is a site that looks great to its maker and broken to everyone else.
Keep this and paste it whenever you start something visual:
Build this mobile-first:
- Design for a 375px-wide phone screen first, then make
it work on bigger screens.
- Use flexible units (%, rem, vw), not fixed pixel widths.
- The page must never scroll sideways. Wide things like
tables or code blocks scroll inside their own box.
- Body text at least 16px, or phones will zoom awkwardly.
- Anything tappable at least 44x44px.
- Check it at 375px, 768px and 1280px wide.
"Mobile first" means starting small and adding room as screens grow — not building big and squashing it down. Squashing is where things break. Growing is comfortable, because a phone layout usually looks perfectly good on a laptop with a little more space around it.
AGENTS.md sets the rules going in. QC.md checks the work coming out.
You need both, because an AI will tell you it's finished the moment it stops typing. It isn't lying — it genuinely believes it. It just has no habit of going back and looking, unless you give it one.
QC.md has three parts, because there are three different questions:
| Part | The question it asks |
|---|---|
| Design QC | Does it look right — on a phone, in the dark, with a thumb? |
| Code QC | Did it do what I asked, and only what I asked? |
| Bug hunt | How do I break this? |
That last one matters more than it looks. Building asks "does it work?" Bug hunting asks "how do I break it?" — and those two questions find completely different problems. Most people only ever ask the first one, which is why so much software falls over the moment a real person touches it.
Start a new conversation and paste this:
Run QC.md against what you just built.
Go through every item. For each one, say PASS or FAIL and
show me the evidence — the command you ran, the output you
got, or the line of code you're pointing at.
Do not fix anything yet. Report first. I'll decide what
gets fixed.
Two phrases in there are doing the heavy lifting:
For small changes, when the full checklist is overkill:
Before you say this is done:
1. Show me it running. Not a description — the actual output.
2. Tell me what you changed that I didn't ask for.
3. Tell me what you're least confident about.
4. Tell me one way a user could break this.
Question 3 is the sneaky one. Asking an AI "are you confident?" gets you a cheerful yes. Asking "what are you least confident about?" gets you an honest answer, because now it's ranking things instead of defending itself. Use that phrasing everywhere — it works on people too.
You'll see these in real projects. Here's what each one is actually for, so they stop looking like mysterious clutter:
| File | What it holds | Add it when… |
|---|---|---|
README.md | What this is, for people | Always. Day one. |
AGENTS.md | The rules, for AI | Always. Day one. |
QC.md | The checklist before calling it done | The moment anyone but you will see it |
DEPLOY.md | How it gets online, and how to undo that | It's live somewhere |
.env.example | Which secrets are needed — names only | The project needs passwords or keys |
CHANGELOG.md | What changed, and when | Other people rely on it |
TODO.md | What's next | You keep forgetting what's next |
STYLE.md | Colors, fonts, spacing | Looks matter and you keep re-deciding |
LICENSE | What others may do with it | You're making it public |
CONTRIBUTING.md | How to help | Other people are joining in |
.env.example
The real .env file holds actual passwords and never leaves your computer. The .example version lists only the names of what's needed, with the values left blank — so someone else knows what to fill in without you ever handing over a secret. If you take one habit from this table, take that one.
The moment something of yours is live on the internet, write down how it got there. Not because it's good practice — because you will forget, and you'll need it at the worst possible moment.
DEPLOY.md
# Deploying this project
## Where it lives
- Address: https://example.com
- Server: <IP address or hosting company>
- Files on the server: /var/www/example.com
## How to publish changes
<The exact commands. Copy-pasteable. No "you
probably need to..." — write the real thing.>
## How to check it worked
<What to look at. Which page to load.>
## If it breaks
<How to undo it. How to get the old version back.>
## Things that will bite you
<Anything you learned the hard way. Every project
has at least one.>
Having read that table, the temptation is to create all nine files immediately. Don't.
Empty files are worse than missing ones. A CHANGELOG.md that hasn't been touched since the day you made it is actively misleading — it tells your AI, and future you, that nothing has changed.
README.md and AGENTS.md. That's it.DEPLOY.md. Keep re-picking colors → write STYLE.md. The pain comes first; the file is the answer to it.
AGENTS.md and read a few from real projects. You'll notice they're short. Yours should be too.