← All sections

Section 3

Keeping your AI on track

AI assistants wander. Not because they're bad at their job — because they forget. A few small files fix this almost completely.

Why your AI wanders off

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:

Your AI starts every conversation with amnesia It doesn't remember yesterday. It doesn't remember what you decided, what you already rejected, or what this project is even for. Every session, it walks in fresh and fills the gaps with guesses — reasonable, confident, and frequently wrong.

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.

The harness: two files

Two files do about 90% of the work:

FileWho it's forWhat goes in it
README.mdHumansWhat this is, what it does, how to run it
AGENTS.mdAIThe 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.

AGENTS.md is a real standard, and it's new It isn't something one company invented for its own tool. It's an open format looked after by the Linux Foundation, used by more than 60,000 projects, and read by OpenAI's Codex, Google's Gemini CLI and Jules, GitHub Copilot, Cursor, Zed, VS Code and dozens more. Claude Code joined in September 2026.

Which means: write the file once, and whichever AI you use tomorrow already knows how to read it.

Writing your README

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.
The test for a good README Could someone who has never met you open this folder and get it running without asking you a single question? That's the bar. It's also, not coincidentally, exactly what your AI needs.

Adjusting it to what you're building

If you're building…Add a section about…
A websiteThe address, where the files live, how to publish changes
A gameThe rules, the controls, how to win
A tool or scriptWhat to type to use it, and an example
Something with accounts or paymentsWhat data it stores, and where secrets live (never the secrets themselves)
A school projectThe assignment, the deadline, what's being graded

Writing your AGENTS.md

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 most valuable section is "What this project is NOT" Every time you decide against something — "no user accounts", "no dark mode yet", "not using React" — write it there. Otherwise you'll rediscover the same argument with your AI every few days, and one day you'll lose it without noticing.

Why each rule is in there

The ruleThe problem it prevents
Do exactly what I askedThree surprise features attached to a one-line fix
Ask if unclearConfidently building the wrong thing
One change at a timeForty files changed, no idea which one broke it
No new packages without askingProjects that mysteriously stop working months later
Never delete without askingExactly what it says
Never commit secretsPasswords published on the internet forever

One wrinkle if you use Claude

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:

Don't keep both files If you have a 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.

The mobile-first rule

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.

Check it yourself in ten seconds In your browser, right-click the page → Inspect → click the little phone icon. Now you're looking at your site at phone size. If anything scrolls sideways, fix that before anything else.

Checking the work: QC.md

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.

The single most important rule about QC Checking is a separate job from building. Never ask for both in the same breath. The AI that just built something is the worst possible judge of it — it already thinks it did well. Open a fresh conversation and ask that one to inspect the work.

QC.md has three parts, because there are three different questions:

PartThe question it asks
Design QCDoes it look right — on a phone, in the dark, with a thumb?
Code QCDid it do what I asked, and only what I asked?
Bug huntHow 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.

How to run 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:

A QC pass with zero failures is a bad sign It almost never means the work was perfect. It usually means the checking was shallow. If everything passes first time, push back: "find me three things wrong with this." There are always three.

The thirty-second version

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.

Get the full QC.md →

The other files, and when to bother

You'll see these in real projects. Here's what each one is actually for, so they stop looking like mysterious clutter:

FileWhat it holdsAdd it when…
README.mdWhat this is, for peopleAlways. Day one.
AGENTS.mdThe rules, for AIAlways. Day one.
QC.mdThe checklist before calling it doneThe moment anyone but you will see it
DEPLOY.mdHow it gets online, and how to undo thatIt's live somewhere
.env.exampleWhich secrets are needed — names onlyThe project needs passwords or keys
CHANGELOG.mdWhat changed, and whenOther people rely on it
TODO.mdWhat's nextYou keep forgetting what's next
STYLE.mdColors, fonts, spacingLooks matter and you keep re-deciding
LICENSEWhat others may do with itYou're making it public
CONTRIBUTING.mdHow to helpOther people are joining in
About .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.

Writing your DEPLOY.md

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.>
The "if it breaks" section is the whole point Anyone can write down how to publish. The valuable half is how to un-publish — because you'll be reading it while something is broken in front of real people, and that is not the moment to be working it out from scratch.

Don't make all of them

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.

Start with two README.md and AGENTS.md. That's it.

Add another only when you feel the specific pain it solves. Put something online → write DEPLOY.md. Keep re-picking colors → write STYLE.md. The pain comes first; the file is the answer to it.

Things to try

  1. Write an AGENTS.md for something you already have. Even a school project. Notice how much you have to actually decide in order to write the "is NOT" section.
  2. Test that it's working. Ask your AI: "read AGENTS.md and tell me the rules in your own words." If it can't, it isn't reading it — check the filename and that it's in the top folder.
  3. Try to catch it drifting. Ask for something small and vague. See if it stays inside the lines. If it doesn't, add a line to AGENTS.md and try again — that loop is the skill.
  4. Look at a real one. Search GitHub for AGENTS.md and read a few from real projects. You'll notice they're short. Yours should be too.
  5. Shrink one. Take your AGENTS.md and cut it by a third. If a rule has never actually prevented a problem, it's noise — and a long file gets skimmed the same way you skim a long list of terms and conditions.