Give your AI agent the note it needs, before it starts

Skip to the wizard Start with the basics

First, the words

Every abbreviation on this page is explained here, so you never have to guess. Come back to this list whenever a word trips you up; the glossary has more.

AI

Artificial intelligence. Here: software you talk to in normal sentences, such as ChatGPT, Claude or Gemini.

LLM

Large language model. The "brain" inside those AI tools. It has read a huge amount of text and predicts good answers.

Agent

An AI that doesn't just answer but does: it opens files, makes changes, runs them and checks the result, step by step.

Prompt

What you type to the AI: your question or instruction.

Context

Everything the AI knows about your situation when it answers. If it isn't in the context, the AI doesn't know it.

Markdown (.md)

Plain text with a few simple marks: # for a heading, - for a bullet, **bold** for bold. Files that end in .md are Markdown. Any text editor can open them.

AGENTS.md

A Markdown file with instructions for AI agents, placed in the top folder of a project. Many AI tools look for it and read it first.

CLAUDE.md

The same idea, under the name that Claude Code (Anthropic's agent) looks for.

Repository (repo)

The folder that holds a whole software project, usually with its full change history.

Git

The most common tool for keeping that change history, so every change can be seen and undone.

PR

Pull request. A proposed change that someone reviews before it's accepted into the project.

API

Application programming interface. A doorway that lets one program talk to another, for example your website asking a payment service to charge a card.

KPI

Key performance indicator. A number that shows whether something is working, such as "orders per week".

MVP

Minimum viable product. The smallest version worth putting in front of real people.

MCP

Model Context Protocol. A standard way to plug an AI into other tools, such as your calendar or documents. You don't need it to start.

Why use an agent, in six baby steps

1. You probably already use a chat AI. You ask a question, it answers, you copy the answer somewhere, try it, come back with the error, and repeat. You are the hands.
2. An agent is the same AI, given hands. It can open the files of your project, change them, run them and see whether it worked, without you copying anything back and forth.
3. So you describe the job once. "Add an order form to the website." The agent makes a plan, does the work in small steps, tests it, and tells you what it changed.
4. The catch: it starts out knowing nothing about you. Think of a skilled temp worker who arrives at your shop every morning with no memory of yesterday. Brilliant, but they don't know your customers, your rules or why the shop exists.
5. So you leave a note on the desk. That note is the context file. The agent reads it at the start of every session, before it touches anything.
6. You stay the boss. The note also says how much it may do on its own and what it must ask first. You check the result, just as you would with a new employee.

When an agent isn’t worth it: a one-off question, a single email, or anything you’d finish yourself in two minutes. Agents pay off when a job has many steps or touches many files.

The whole process in one flowchart

Follow the arrows from the top. “Yes” goes down to the next box; “No” sends you to the side. Print it or keep it open next to your agent.

1. 1

   You have a job for AI.

2. 2

   Does the job have several steps, or change the files of a project?

   A website, an app, a folder of documents.

   No

   Use a normal chat AI. Done.

3. 3

   Does the project's top folder have an AGENTS.md or CLAUDE.md?

   No

   Write one with the wizard below (about 10 minutes), save it there, then carry on with step 4.

4. 4

   Open the agent in the project's top folder.

5. 5

   Send the first message: "Read the file and tell me what you understood. Don't change anything yet."

6. 6

   Did it understand your project and rules correctly?

   No

   Fix the file, not the chat. Then back to step 5.

7. 7

   Give it one small job: "Add a pickup-date field to the order form."

8. 8

   Check the result yourself. Is it right?

   No

   Say what's wrong. Same mistake twice? Add one line to the file. Then back to step 7.

9. 9

   Keep it: save a restore point. Next small job? Back to step 7.

Why the note matters so much

An agent can’t ask around the office. A human developer who’s unsure walks over and asks. An agent fills the gap with a guess, and the guess is usually the most common answer on the internet, not the right answer for you.

Here is the same request, without and with a context file, for a fictional bakery:

Same agent, same request. The only difference is the note.

The four kinds of context

A good note answers four questions: why, what, how and where. The first two are business knowledge only you have. The last two are technical, and if you’re not a developer you can let the agent fill them in and check them. Each example below is for the same fictional bakery; copy the shape, not the content.

1. Why are we building this? (business context)

This tells the agent what “good” means, so it makes the trade-offs you would. Include the goal, how you’ll know it worked, and what matters most when two things clash.

## Why we're building this
Maple Street Bakery (fictional) is a small neighborhood bakery.
Customers phone in orders, and calls interrupt baking all morning.

Goal: let customers order cakes and bread online for pickup.
We know it works when: half of pre-orders come in online
instead of by phone, within three months.

When choices clash, in this order:
1. Customer privacy and safety
2. Easy to use on a phone, for older customers too
3. Cheap to run
4. Extra features (wait, unless they're free and simple)

2. What must it do? (functional context)

This describes the behavior: who uses it, what they can do, the rules, and what could go wrong. The “must never” list is the most valuable part, because no agent can guess your red lines.

## What it must do
- Customers pick items, a pickup date and a pickup time.
- Orders close at 2 pm the day before pickup.
- The owner gets each order by email.

## It must never
- Take card payments online (customers pay in the shop).
- Allow pickup on Mondays (we're closed).
- Ask for more than name, phone number and email.

## Things that could go wrong
- An item sells out: show "sold out" instead of hiding it.
- A customer orders 40 loaves: ask them to call us instead.

3. How is it built? (technical approach)

This keeps the agent from mixing styles and tools. If you don’t know, say so, and ask it to choose something common and explain the choice in plain words.

## How it's built
I'm not a developer. Suggest common, well-supported tools,
explain each choice in one plain sentence, and wait for my
OK before setting anything up.
- Prefer free or low-cost services.
- Ask before adding anything with a monthly fee.

A developer would write the actual tools here, such as “React front end, C# API, PostgreSQL database”, plus the commands to build and test.

4. Where do things go? (project map)

This saves the agent from searching through everything and stops it editing what it shouldn’t. For a new project, ask the agent to write this section once the first version exists.

## Where things are
- `site/` the pages customers see
- `site/menu.json` items and prices (the owner edits this)
- `docs/` notes and decisions
- `old-site/` the previous website: don't change anything here

How the pieces fit together

For most small projects, one file is enough. Put all four parts in a single AGENTS.md in the project’s top folder. When it grows past a couple of pages, move the long parts into their own files and link to them:

my-bakery-site/
├── AGENTS.md          ← the agent reads this first
├── docs/
│   ├── why.md         ← business context
│   └── what.md        ← what it must and must never do
└── site/

# AGENTS.md
Read these before starting any new feature:
- docs/why.md: goals and what matters most
- docs/what.md: rules, limits and edge cases

The wizard: write your file in six steps

Answer in plain words; the file builds itself below the questions as you type. Every question has an example. Skip anything you don’t know. Nothing you type leaves your browser. It’s also on a page of its own, the AGENTS.md generator, handy to bookmark or share.