EP1 How an AI coding agent works, and why your project needs a handbook for it

This series follows the path of coding with AI, from one Claude Code assistant in one project to a system where several AIs from several providers work together. There are eight episodes, each teaching one principle with examples from real work. The first covers the most basic step, and the one people skip most often.

How Claude Code works

Claude Code is an AI agent that works in the terminal. If the difference between an agent and a chatbot is new to you, read What is an AI agent first. In short, it works in a loop:

1. Read the files that matter for the task
2. Think about what needs to change
3. Act: edit files or run commands
4. Check the result, such as whether the build or tests pass, then go back to step 1 until the job is done

That sounds like having another programmer on the team, and it is, with one big weakness you need to know first.

The problem: a colleague on their first day, every day

Picture a very capable colleague who remembers nothing of yesterday each morning. They do not know how this project is deployed, which files must not be touched, or what the team agreed on.

That is the AI every time a session starts. It sees the code. What lives in people’s heads, like “other sites run on this server, be careful” or “this repo must stay private”, it does not know. If nobody tells it, it guesses, and sometimes it guesses wrong on something expensive.

First principle: what you want the AI to know has to be in a file, not in your head.

The fix: CLAUDE.md, a handbook it reads on its own

Claude Code reads a file called CLAUDE.md at the root of the project every time it starts. No need to ask, no need to paste it in again. Write it once and every session uses it.

There are two levels worth knowing:

File	Applies to	What goes in
CLAUDE.md in the project	that project	this project’s rules, committed to the repo
~/.claude/CLAUDE.md	every project on the machine	personal habits, such as reply language or code style

What to put in

Only what the code cannot show. These five cover almost every project:

# Project name — what it does, for whom (1-2 lines)

## Layout
- src/api/    ← all endpoints
- src/web/    ← the web pages

## Commands
npm run dev    # run locally
npm test       # must pass before a commit

## Rules
- Never edit a migration in migrations/ that has already run
- Money is decimal, never float

## Done means
- the build passes, tests pass, and it was checked on a phone screen

The last one matters more than it looks. Without a definition of done, the AI uses its own, which is usually just “the code looks right”.

A real example: this site

The site you are reading has one CLAUDE.md. It says “before calling it done, check at 375px wide in both languages”. That one line made the AI open the page and find an English headline overflowing the phone screen, something reading the code would never show. The full story is in the lab note on building this site in 22 minutes.

Another line says the site’s repo must always stay private. The AI could never work that out from the code.

What to leave out

• Passwords, keys and tokens. The file lives in the repo; anyone who sees the repo sees it.
• What the code already says, such as a list of every function. The AI can read the code.
• Everything you can think of. A file that is too long buries what matters and costs more on every read.

Try it in 10 minutes

1. Open a terminal in a project you already have and run claude
2. Type /init and let it read the project and draft a CLAUDE.md
3. Read the draft, delete what the code already says, and add what is in your head: the hard rules and what done means
4. Close the session, open a new one and ask “what must I never do in this project?” If it can answer, the handbook works

Where a person is needed

The AI can draft CLAUDE.md, but the rules belong to a person. What must not be touched, what needs care, and what counts as ready are decisions that come from experience with that project. AI can make them read clearly; it should not invent them.

Next episode

One handbook file works well at first, but over time everything gets stuffed into it until it bloats. EP2 separates three kinds of things: knowledge the AI should remember, procedures that repeat, and rules that have to be enforced for real.