The idea

Put a plain text file in your project describing how the project works. Agents read it
automatically at the start of a session.

That is the whole mechanism. It is not clever. It works extremely well.

What it is called

Different tools look for different names. CLAUDE.md and AGENTS.md are the two common
ones, and most tools now read one or both.

If you want to be safe with more than one tool, write one file and make the other a copy or
a pointer to it. Do not maintain two.

Why this beats settings inside a product

From Lesson 3.7: keep everything that describes your project inside your project, as
plain text, in git.

That gives you four things:

  • Any tool can read it, including tools that do not exist yet.
  • It is versioned. You can see when a rule was added and why.
  • Anyone who clones the project gets it.
  • Switching tools costs nothing.

What to put in it

Answer the questions you keep answering:

  • What is this project?
  • How do I run it? How do I test it?
  • What is the shape of the code? Where does what live?
  • What are the rules I care about?
  • What should you not do?

Recall’s file

Here is a real one. Notice how short it is.

# Recall

A spaced repetition study app. A student adds cards, and the app shows
each card just before they would forget it.

## Commands

    npm start     start the server on http://localhost:3000
    npm test      type check, lint, and run all tests

Always run `npm test` before saying a task is done.

## Layout

    src/db.ts         database connection and queries
    src/schedule.ts   the review scheduling rules
    src/routes/       one file per page
    tests/            tests, named after the file they test

## The scheduling rules

These come from the course plan and must not be changed without asking.

- A new card has a gap of 1 day.
- "forgot" sets the gap to 1 day.
- "hard" multiplies the gap by 1.2.
- "easy" multiplies the gap by 2.5.
- The result is rounded DOWN to whole days.
- The gap is never below 1 and never above 365.
- A card is due if next_review is today OR EARLIER. Overdue cards
  must never be skipped.

## Rules

- TypeScript only. `strict` is on and stays on.
- No new libraries without asking first.
- Plain HTML and CSS. No UI framework.
- Never change a test to make it pass. If a test looks wrong, stop and ask.
- Dates are stored as YYYY-MM-DD text.
- Must work on a 390 pixel wide phone screen.

## Not in this project

No logins, no accounts, no sharing between users, no images on cards.

Look at what that file is doing

Almost every line is something that already went wrong, or nearly did.

“Rounded DOWN” is there because of Lesson 4.4. “Today OR EARLIER” is there because of Lesson
4.5. “Never change a test to make it pass” is there because of Lesson 5.3. The “Not in this
project” section stops an agent helpfully adding a login system.

Your rules file is a record of every mistake you do not want to see again.

That is exactly how it should grow. Do not try to write the perfect one today.

Try this before the next lesson

  1. Create AGENTS.md in your Recall project. Start with commands and layout only.
  2. Add one rule for each mistake you actually hit in Modules 4 and 5.
  3. Start a fresh session and ask “what is this project?” See what it now knows.
PreviousNext