# How agents work

## What an agent is

A chat AI answers you. An agent does things. You give it a goal, it takes a step, looks at what happened, and takes the next step until it's done or stuck.

Say you ask: "Make a one-page site about my dog walking business." A chat AI writes you some code and stops. An agent creates the file, opens it, spots that the text runs off the edge of a phone, fixes that, and tells you it's finished.

## The five parts

Most agents, in any tool, have the same five parts.

1. **A model.** The AI brain that reads and writes. In Claude Code that's a Claude model.
2. **Instructions.** What it should do, and the rules to follow while doing it.
3. **Tools.** The things it can touch: read a file, write a file, run a command, search the web.
4. **A loop.** Think, use a tool, look at the result, think again. It repeats until the goal is met.
5. **Memory.** What it can still see. Inside one session that's the conversation so far. Between sessions it's whatever you wrote in a file.

Here's the whole thing as a picture:

```text
        you: "build X"
              |
              v
   +----------------------+
   | MODEL + INSTRUCTIONS |<----------------+
   +----------------------+                 |
              | picks a step                |
              v                             |
   +----------------------+     result      |
   | TOOLS: read, write,  |-----------------+
   | run, search, MCP     |   (the loop)
   +----------------------+
              |
              v
   files on your computer  <---->  MEMORY (CLAUDE.md, notes)
```

The model never "does" anything by itself. It asks for a tool, the tool runs, and the result goes back in. That's the loop.

One limit to know early: the model can only hold so much in view at once. A long session gets crowded and the agent starts to forget things from the start. Memory in files fixes most of that.

## Claude Code's parts

Claude Code is Claude working inside a folder on your computer. It reads your files, writes them, and runs commands in your terminal. You need a paid Claude plan to use it. Check Claude's pricing page for which plans include it, because that changes.

Here is what each part of it is for.

**CLAUDE.md.** A plain text file in your project folder that Claude Code reads at the start of every session. Put in it what the project is, how you like things done, and what to never touch. If you find yourself repeating an instruction, it belongs here. Typing `/init` in a project gets Claude to draft one for you.

**Skills.** A saved method. A skill is a folder with a `SKILL.md` file that says how to do one job well, for example "check a site on a phone-sized screen before calling it done". Claude Code reads the short description first and loads the full steps only when the job comes up. Once you've done something the same way twice, make it a skill.

**Subagents.** A helper with its own fresh session, its own instructions, and a single job. You hand it a task, it works on its own, and it sends back a summary. Because it starts with a clean view, it doesn't carry your main session's assumptions. That's why I use one as a reviewer.

**MCP servers.** MCP stands for Model Context Protocol. It's a standard plug for connecting an agent to a service, such as a database, your calendar or a website's API. Claude Code can already work with your files, your terminal and the web. An MCP server adds that service's tools. Add them one at a time and only when you need them. The `/mcp` command shows what's connected.

**Hooks.** A rule that runs by itself when something happens. For example, "every time you finish editing a file, run the checks". An instruction in CLAUDE.md is a request the model might forget. A hook is run by Claude Code itself, so it happens every time. Skip hooks until you've got a habit worth automating.

**Plan mode.** Claude Code looks and thinks but doesn't change anything. It reads your files, asks questions and writes a plan for you to approve. In the terminal, press Shift+Tab until it says plan mode. I start anything bigger than a small fix here, because a bad plan is quick to fix before the build and slow to fix after it.

**Permissions.** Claude Code asks before it does things like running commands or editing files. Read what it's asking. Say yes to what you understand and no to the rest.

## Chat or Claude Code

If the answer is only words, use chat. If Claude needs to go and do something on your computer or your project, use Claude Code.

I plan and ask questions in chat. Then I move to Claude Code to build.

## Keys and passwords

Never paste a key or password into any chat, including Claude Code. Secrets go in a file that's listed in `.gitignore`, or in the secret store of the platform you're using, such as Cloudflare's. Ask Claude Code to set that up for you and to tell you where to type the value yourself.

## What to do with this

Open a project folder, start Claude Code, and run `/init`. Read the CLAUDE.md it drafts and change anything that's wrong. That's your first piece of memory.

**Next:** [How I run agents](how-i-run-agents.md)
