Guide · 4 of 8

How to work with an agent

You have Claude Code or Codex installed. Now you need to know how to talk to it. This page is a handful of plain rules, each with a tiny example. At the end you build a small thing in six prompts, with git as your undo button the whole way.

You need

A terminal and git, from Set up your computer.
Claude Code (chapter 2) or Codex (chapter 3). Either works for everything here. We call it "the agent" when either will do.

Rule 1: say what you want and what done looks like

The agent can't read your mind. It can read a clear sentence. Say what you want, then say how you will know it is finished.

Vague:

make a timer

Clear:

Make a countdown timer in one file, index.html. I type a number of minutes and press Start. It counts down on screen in big numbers. When it hits zero the page turns red. Done means I can open the file in my browser and it works with no setup.

The second one takes ten more seconds to write. It saves you ten minutes of "no, not like that".

Leave saving, accounts and sharing out of the first version. Get the thing working, use it, then add the part that remembers. Every project brief on this site is ordered that way.

Rule 2: let it look around first

In a folder that already has files, ask the agent to read before it writes. It finds out what is there, and you find out whether it understood.

Read this folder and tell me what's here. Don't change anything yet.

If its answer is wrong, fix that now. A wrong picture of the project leads to wrong changes.

Rule 3: ask for a plan before a big change

For anything bigger than a small fix, get a plan first. You read it, change it, then say go.

Claude Code

Press Shift+Tab until the bottom of the screen says plan mode. Shift+Tab cycles between three modes: ask before edits, accept edits, and plan. In plan mode Claude Code reads and thinks but does not edit files. It shows you a plan and waits.

Codex

Just say it in your prompt:

Plan first, don't edit yet. Tell me which files you would change and why.

A good plan is a short list of steps. If a step looks odd, ask about it. It is much cheaper to change a plan than to undo a pile of edits.

Rule 4: small steps, and look after each one

Ask for one thing. Look at the result. Then ask for the next thing. Don't ask for the whole app in one go.

Add a Start button. Only that. Tell me when it's done so I can try it.

"Look" means open it and use it. Click the button. Refresh the page. The agent saying "done" is not the same as it working.

Rule 5: when it breaks, paste the exact error

"It doesn't work" gives the agent nothing to go on. The error message does. Copy the whole red text, from the terminal or from the browser's console (right-click the page, Inspect, then the Console tab), and paste it in.

When I press Start nothing happens. The console says:
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener') at index.html:42

Also say what you did just before it broke. "I pressed Start twice" is useful.

Rule 6: ask it to explain anything you don't understand

This is how you learn. The agent is a patient teacher. It won't mind the tenth question.

Explain line 42 of index.html to me like I've never written JavaScript. What does addEventListener do?

Do this often. After a few projects you will read the code yourself, and you will spot the agent's mistakes before it does.

Rule 7: git is your undo button

Git (the tool that saves snapshots of your project) lets you go back when a change goes wrong. You installed it in chapter 1. The agent knows git well, so you can run it in plain words. Three sentences cover most days.

Once per project, when you start:

Make this folder a git project.

Every time something works:

Save a snapshot with the message "timer counts down".

When the last change made a mess:

Throw away everything since the last snapshot.

And to see where you are: "show me the snapshots so far". Read the commands it runs. They are the same four every time, and soon you will type them yourself without thinking.

By hand, if you want to see what it ran

Turn the folder into a git project. Once per project.
```
git init
```
You should see: "Initialized empty Git repository in …"
When something works, save a snapshot. First pick up every change:
```
git add -A
```
Then save it with a short note:
```
git commit -m "works"
```
You should see: a line with your note and how many files changed.
If the agent's last change made a mess, throw away everything since your last snapshot:
```
git checkout -- .
```
You should see: nothing printed. Refresh the page and it is back to how it was at your last commit.
To see your snapshots, one per line:
```
git log --oneline
```
You should see: a short code and your note for each commit, newest first. Press q if it fills the screen.

Rule 8: write the rules down in a memory file

Each session starts fresh. The agent doesn't remember yesterday. So you keep a note in the project that it reads every time it starts. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Both sit in the top folder of your project.

You can have the agent write a first draft: type /init inside Claude Code or Codex. Then edit it yourself. Put in three things:

How to run it. "Open index.html in a browser" or "run python3 -m http.server and open localhost:8000".
What not to touch. "Don't change the images folder." "Don't add any libraries."
The style you want. "Plain JavaScript, no frameworks. Short functions. Comments for anything tricky."

Keep it short. A page of clear rules beats ten pages it has to wade through. If you use both agents, the two files can hold the same text.

Rule 9: think with the big model, type with the small one

Each agent has several models (the brain behind it). The big one thinks better and eats your allowance. The small one is quick and cheap. So plan and review with the big one, do the work with the everyday one, and switch up when you are stuck. Both agents switch with /model. Which is which, and what your plan gets, is on one page: Which model, and when.

A worked example: a tiny thing in six prompts

Here is a whole small build: a "what should I eat" picker. Make an empty folder, open a terminal in it, start the agent, then send these one at a time. Look at the result after each.

Look around and set up the rules.

This folder is empty. I want to build a small web page that picks a random meal from a list. Make this folder a git project. Then write an AGENTS.md (and the same text in CLAUDE.md) that says: one file, index.html, plain HTML, CSS and JavaScript, no libraries, works by opening the file in a browser.
Ask for a plan.

Plan first, don't edit yet. How would you build this? Keep it to five steps or fewer.
First small step. Then open index.html and look.

Do step 1 only: a page with a big "Pick for me" button and a list of eight meals I can see. When I press the button, one meal shows in large text.

You should see: a button. Pressing it shows a meal. Now tell the agent: "save a snapshot, message: picker works".
Add a feature.

Add a text box and an Add button so I can add my own meals to the list. Keep everything else the same.
Something breaks. Paste the error.

When I add a meal and refresh, it's gone. I want my meals to stay after a refresh. Also the console shows this: [paste the exact text here]

You should see: your added meal still there after a refresh. Commit again.
Learn something.

Explain how my meals are kept after a refresh. Which lines do it? Explain like I'm new to this.

That last prompt will probably mention localStorage. That is the simplest place to keep data. Chapter 7 covers the rest.

What it gets wrong

The agent is good. It is not always right. And it sounds just as sure when it is wrong.

Confident mistakes. It says "fixed" and it isn't. It says a test passes and never ran it.
Old versions. It learned from code written over many years. It may use a way of doing things that a library changed since, so the code looks fine and then fails.
Made-up things. Now and then it refers to a file, a setting or a function that doesn't exist.

The fix is always the same: run it and look. If it fails, paste the error (rule 5). If it mentions a file, check the file is there. If something sounds too neat, ask "how do you know that? show me".

Keep your secrets secret

A secret is anything that lets someone act as you: a password, an API key (a long code that lets a program use a paid service on your account), a login token.

When a project needs a key, the usual way is:

Put it in a file called .env in the project folder, one per line, like WEATHER_KEY=…. Type it in yourself, not through the agent. No editor needed: run nano .env in the terminal, type the line, press Ctrl + O then Enter to save, and Ctrl + X to leave.
Tell git to ignore that file. Make a file called .gitignore and put this line in it: .env. Git will now act as if that file isn't there.
Tell the agent: "the key is in .env as WEATHER_KEY. Read it from there. Don't print it and don't commit it."

If you think a key leaked, go to the service that gave it to you and make a new one. That turns the old one off.

What you just did

You learned to say what done looks like, get a plan, and build in small steps you check yourself. You used git to save and undo. You set up a memory file and kept your secrets out of chat and out of git.

Next: put your project somewhere safe, on GitHub.