Series contents

Series

Getting Started with Coding Agents

Part 2 of 10 · Brief

Brief your agent.

Tell your agent who it is working with, once, and see a brand-new conversation already know it.

By Ahmed Gadir6 min read

By the end of this part, a brand-new conversation with your agent will already know what to call you, which computer you use and how you like things explained, along with the rules of this project. You won’t have said any of it in that conversation.

You have the starting page running and a first checkpoint from Part 1. Here you’ll answer four short questions and look at one file. Nothing in the app changes.

1. Ask a new conversation what it knows

Start a new conversation in the same project:

  • Claude: choose + New session, or press Cmd+N on a Mac.
  • Codex: press Cmd+N on a Mac.

If you can’t find the control on your computer, open the project folder again as you did in Part 1 and start a conversation there. Then ask:

Ask what it knows

What do you know about me and this project?

Paste this into your project conversation.

About the project it has plenty to say: this is a reading-list app, it is built one stage at a time, and there are things the agent must never do. It will probably mention that your starting page ran and that you saved a checkpoint called “Starting point”. About you it has little or nothing, and it may say that a section about you is still empty.

Notice what is missing: anything you said in Part 1. This conversation can’t see that one. Everything it told you, it read a moment ago from files in your project folder. It knows about your checkpoint only because you asked for the outcome to be recorded in docs/progress.md.

2. Open the file your agent always reads

A conversation is temporary, and your project’s files are your agent’s memory. Whatever should still be true next week has to be written in a file.

What passes from one conversation to the nextTwo conversations sit side by side with no connection between them: an earlier one that has ended, and a new one that cannot see it. Beneath both are the project’s files: AGENTS.md and the docs folder. One arrow runs from the earlier conversation down into the files, labelled “what you asked it to write down”. Another runs from the files up into the new conversation, labelled “read as it starts, and as it works”. The files are the only route between the two.An earlier conversationEverything you said in itstays behind in it.what you asked itto write downYour project’s filesAGENTS.md and the docs folderread as it starts,and as it worksA new conversationIt can’t see the earlierone at all.
Nothing passes directly from one conversation to the next. What lasts is what was written into your project’s files, where the next conversation finds it.

One file matters most. AGENTS.md, at the top of your project folder, holds the project’s standing instructions, and your agent reads it at the start of every conversation without being asked. Because it sits at the top, or root, of the project, we’ll call it the root file from here on. That is how a conversation you had only just opened already knew the rules.

You may have started a chat with an AI tool by typing something like “act like a patient teacher”. AGENTS.md plays a similar role, except that it is saved in your project and read every time, so you never type it again. The comparison stops in one place: the file is guidance your agent follows, not a lock. An agent can still get something wrong, which is why you’ll check its work in every part.

Open AGENTS.md in your agent’s file view, or ask your agent to show it to you. It is ordinary text under five headings:

  • About the person is who the agent is working with. It is empty, and you’ll fill it in below.
  • How we work says to do one stage at a time, then stop and tell you what to try, in ordinary language.
  • Hard limits lists what the agent must never do, such as publishing without being asked.
  • Where things are is a map of the project’s documents.
  • Handbooks says which instructions to read before a particular kind of job.

You don’t need to read every line. If you use Claude, you’ll also see a file called CLAUDE.md. It holds one line that points Claude at AGENTS.md, so leave it as it is.

3. See where the rest is kept

AGENTS.md stays short because all of it is read every time. Anything longer lives in the docs folder, which works as your agent’s knowledge base: each file has one job, and the agent opens the one that the work in hand needs. This is what Where things are lists:

  • docs/brief.md says what the app must do and what it leaves out. Your agent checks your plan against it in Part 3.
  • docs/flows.md doesn’t exist yet. It will hold your plan, which you’ll write in Part 3.
  • docs/brand/ will hold how your app looks and what it says, which you’ll decide in Part 4.
  • docs/api.md and the src/server folder belong to the stand-in server your starting page mentioned. Part 5 explains them.
  • docs/epics/ holds one file for each piece of work, as tasks to tick off. You used the first in Part 1.
  • docs/handbooks/ holds instructions for one kind of job. You’ll write one yourself in Part 7.
  • docs/progress.md is the current state of the project. You saw it at work in step 1.

You don’t need to open any of these now. “Epic” and “handbook” are this project’s own words: your tool’s documentation calls an epic a plan or a spec, and has no special word for a handbook.

4. Tell your agent who you are

The prompt below asks your agent to interview you with four short questions, write your answers under About the person, and read them back until you agree with them. You can answer “skip” to any of them. Send it in the conversation you opened in step 1:

Brief my agent

Read docs/epics/01-setup.md and do Stage B only. Ask me your questions one at a time: what to call me, which kind of computer I use, whether I have programmed before and how I like things explained. I may answer "skip". Write my answers under "About the person" in AGENTS.md in two to four plain sentences, and change nothing else in that file. Read the new section back to me and change it until I agree that it describes me. Then show me the "Where things are" table and say in a sentence what each place is for. Record the outcome in docs/progress.md, then stop.

Paste this into your project conversation.

Answer as you would to a new colleague: “I’ve never programmed, I use a Windows laptop, and I like a short explanation with an everyday comparison.” Keep private details out, because the file goes wherever the project goes. Your agent will ask permission before it changes AGENTS.md; say yes.

When it reads the section back, have anything changed that doesn’t sound like you. Those few sentences shape every explanation you get from here on.

5. Check it in a new conversation

Start another new conversation, as you did in step 1, and ask the same question:

Ask again

What do you know about me and this project?

Paste this into your project conversation.

If it still doesn’t know you, open AGENTS.md and look under About the person. If it still says “Empty for now”, go back to the earlier conversation and say: “The About the person section in AGENTS.md is still empty. Write my answers there and show me the file.” If the section is filled in, the new conversation is probably open in a different folder: open the one that directly contains AGENTS.md, as in Part 1. On Claude, check too that CLAUDE.md is still beside it.

Claude Code and Codex have more ways to shape how an agent works, with names such as hooks, subagents and plugins. A project this size needs none of them, so you won’t meet them in this series.

You now have an agent that starts every conversation knowing who you are and how this project is run. Next, in Part 3, you’ll decide what your reading list does and save that plan as a file your agent builds from.

FAQ

Can I change what it says about me later?

Yes. Ask your agent to update the About the person section, read the result, then start a new conversation so that the change is picked up from the beginning.

Will my agent always follow what is in AGENTS.md?

Nearly always, and not guaranteed. The file is strong guidance that the agent reads first, and an agent can still overlook a line in a long piece of work. If it breaks one of the rules, tell it which one and ask it to put the work right. Your own check at the end of each stage is what catches the rest.

My agent mentioned a memory of its own. Is that the same thing?

No. Claude Code can also keep notes of its own, which it stores outside your project. Nothing here depends on them. What is written in your project’s files is something you can read, correct and take with you to a different tool.

Further reading

  • The Slash Commands I Use in Claude Code and CodexGadirLabs

    A short list of the commands that control the tool itself, including the one that starts a fresh conversation, with a prompt that saves a handoff note into your project before you clear one. It is written for people a little further along and mentions features this series leaves out.