# Coding Agents

Course: [Harness Engineering](https://www.devtutorials.ai/learn/harness-engineering) · Section: Foundations
Source: https://www.devtutorials.ai/learn/harness-engineering/foundations/what-is-a-coding-agent

> What an AI coding agent is, the read, plan, act, observe loop it runs, how you approve or deny its tool calls, and the two-line rules file that turns a guessing agent into a careful one.

## What a Coding Agent Is

A **coding agent** is an AI model that can work on your project. It reads files, changes them and runs commands. In this lesson, you will learn how an agent works and how one small file makes it careful.

An AI model on its own only reads text and writes text. It cannot open your files or run your tests.

So when you ask it to fix a bug, it guesses.

For example, a ticket says:

- "The ticket count shows 1250 instead of 1,250. Fix it."

A model that only sees these words changes the file that sounds right. It says "Done!". The bug is still there.

**Simple lesson:** a model that cannot look at your code can only guess.

### A Real-World Example

You call a plumber because the kitchen tap drips.

A bad plumber does not look. He changes the bathroom tap. The kitchen tap still drips.

A good plumber watches the kitchen tap drip. He replaces the worn part. Then he turns the tap on again to check.

A coding agent should work like the good plumber. Look first, fix one thing, then check.

Click the button and watch the steps in the Harness Lab.

- **Step 1:** it edits a file it never opened.
- **Step 2:** it says it is done.
- **The tests:** they still fail. Nothing checked the claim.

**Simple lesson:** an agent that does not look and does not check is just guessing.

## What You Will Learn

In this lesson, you will learn:

1. What a coding agent is.
2. The four steps of the agent loop: read, plan, act, observe.
3. Why one answer is not the same as an agent.
4. How to approve or deny each action the agent wants to take.
5. Why every run needs a step limit.
6. How two lines in a rules file change what the agent does.

**About the Harness Lab**

- The **Harness Lab** sits at the bottom of every page in this course.
- It holds a small starter project and a **simulated agent**.
- The simulated agent follows fixed rules, so it gives the same result every time. That is how your work can be checked.
- In Settings, you can also try a small real AI model in your browser. It is optional, and it never grades your work.

## The Agent Loop

### Tools

**Tool** = an action the app runs for the model.

Examples of tools:

- list the files in the project
- read a file
- edit a file
- run a command, such as the tests

The model asks for a tool. The app runs it and gives back the result.

### Four Steps

A coding agent works in a loop of four steps:

1. **Read.** It looks at files.
2. **Plan.** It decides on one next step.
3. **Act.** It edits a file or runs a command.
4. **Observe.** It looks at the result.

What it observes feeds the next read. Then it goes around again.

The loop ends when the agent says "done", or when a limit stops it.

### See the Loop Run

Watch the agent fix the same ticket, one step at a time:

Press **Play**, or use **Next** to go one step at a time.

- **The list on the left:** every tool call, and what came back.
- **The "What this shows" panel:** which of the four steps is happening.
- **The red line:** the failing test. It points at the bug.

The agent changed nothing until it had read the test and the code. It said "done" only after the tests passed.

Click the button to run the same loop in the Harness Lab.

**Simple lesson:** "done" should mean "I checked, and it works", not "I made a change".

## One Answer vs an Agent

### Same Ticket, Two Ways

**One answer** = the model replies once, from the words in your message. It never looks at the project.

**Agent loop** = the model reads, plans, acts and observes, again and again.

Here are both, on the same ticket:

Step through all three frames.

- **Frame 1:** one answer takes 2 steps. The loop takes 9.
- **Frame 2:** the same four checks. Only the loop passes them all.
- **Frame 3:** one answer patched the screen. The loop fixed the cause.

### When to Use Which

| | One answer | Agent loop |
|---|---|---|
| Looks at your files | No | Yes, before it changes anything |
| Runs the tests | No | Yes, before and after the change |
| Knows when it is done | No, it just stops | Yes, when the tests pass |
| Good for | Questions and explanations | Changing code |

**Simple lesson:** the loop takes more steps, because every extra step is a look or a check.

## You Stay in Charge

### Approving Tool Calls

An agent acts on its own. But most tools can stop and ask you first.

Before each **tool call**, you see what the agent wants to do. You press **Approve** or **Deny**.

Some calls are safe, because they change nothing:

- reading a file
- running the tests

Some calls are dangerous:

- deleting files or folders
- switching off a failing test, so the run looks green
- changing settings for the live system, called **production**

Click the button. The agent stops before each call and asks you.

- **Two of its ideas are dangerous.** Deny those, approve the rest.
- **The result:** the lab tells you if each choice was right.

**Important:** approving every call by hand is slow.

It also trains you to click Approve without reading.

Use it while you learn. Later lessons move these checks into files, so the tool enforces them for you.

### A Step Limit

Sometimes an agent never reaches "done". It tries the same thing again and again.

Without a limit, it would run forever and cost money.

**Step limit** = the most steps one run may take. When the agent reaches it, the run stops.

A limit does not fix the problem. It turns "runs forever" into "stops and asks a person".

**Simple lesson:** read every call before you approve it, and give every run a step limit.

## Your First Harness

### What a Harness Is

The agent in the first demo guessed, because nothing told it not to.

You could type "please read the code first" in every chat. But you would have to remember it.

Instead, you write it down once, in a file in the repo. The tool loads that file at the start of every run.

**Rules file** = a short file in your repo that tells the agent how to work there. Examples are `AGENTS.md` and `CLAUDE.md`.

**Harness** = everything around the model that guides it and checks it. The rules file is the first part.

The model reads text in small pieces.

**Token** = a small piece of text the model reads, about 4 characters.

**Context window** = everything the agent can see at once: your message, the files it read, the rules file and the chat so far. It has a size limit, counted in tokens.

The rules file sits in the context window on every run. So keep it short.

### Vague Rules Do Nothing

The starter rules file says "Write clean code" and "Be careful".

These sound good. But they do not say what to do.

Watch what the simulated agent does with them, and then with two clear rules:

Step through all four frames.

- **Frames 1 and 2:** vague rules. The agent guesses and fails all 3 versions of the bug.
- **Frame 3:** two clear rules, each with a note on what the agent will do.
- **Frame 4:** the same agent passes all 3 versions.

Only the rules file changed.

### What a Good Rule Looks Like

A good rule names two things:

- **an action:** read, run, never edit
- **a moment:** before you edit, before you say done

Here are the two rules from the animation:

```markdown
- Read the failing test and the file you plan to change before you edit anything.
- Run `pnpm test` after every change, and before you say you are done.
```

"Be careful with tests" has no action and no moment. "Run `pnpm test` before you say you are done" has both.

### Where Your Rules Live

Each tool reads a rules file from the root of your repo. Only the file name changes.

The tab starts on the tool you picked in the quiz at the top of the page.

### Lab Exercise: Write Two Rules

Now write your own first harness.

Click the button to open the rules file in the lab.

1. Replace the two vague lines with two clear rules.
2. Press **Check my harness**.
3. The check runs the agent on **3 versions** of the bug. Your rules must work on all three.

**Stuck?** Open the **Inspector** tab.

- It shows what the agent took from each line.
- A line under "Lines that gave no fact" is one the agent cannot act on.
- Rewrite that line with an action and a moment.

**Simple lesson:** write each rule as an action plus a moment. Two clear lines turn a guessing agent into a careful one.

## TL;DR

1. **Coding agent** = an AI model in a loop that uses tools to read, change and check your project.
2. **Tool** = an action the app runs for the model, such as read a file or run the tests.
3. **Agent loop** = four steps, again and again:
   - read
   - plan
   - act
   - observe
4. **Done** = the tests ran after the last change, and they passed.
5. **Approve or deny** = you check each tool call. Deny deletes, switched-off tests and production changes.
6. **Step limit** = the most steps one run may take. It stops a stuck agent.
7. **Rules file** = a short file in the repo, such as `AGENTS.md`, that the tool loads every run.
8. **Harness** = everything around the model that guides it and checks it.
9. **Token** = a small piece of text, about 4 characters.
10. **Context window** = everything the agent can see at once. It has a size limit.
11. **Good rule** = an action plus a moment.

## Common mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| Calling one answer an agent | "I asked the model, so it worked on my code." | An agent reads files, uses tools and checks. | It edits the wrong file, and nobody notices. |
| Trusting "Done!" | "It said fixed, so it is fixed." | Done means the tests ran and passed. | A broken change ships. |
| Approving without reading | "The AI knows best." | Read every call. Deny deletes, switched-off tests and production changes. | The agent deletes work or hides a failing test. |
| No step limit | "It will stop when it is done." | Always set a limit. | A stuck agent loops and wastes time and money. |
| Vague rules | "Write clean code" will help. | Name an action and a moment. | The rule changes nothing. |
| Fixing it in the chat | "I will remind it next time." | Write the rule once, in the rules file. | The same mistake comes back in the next session. |

## Check Your Understanding

## Exercises

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

**New to Markdown?**

Rules files like `AGENTS.md` and `CLAUDE.md` are written in Markdown. If Markdown is new to you, start with [Markdown for AI-Native Development](/learn/markdown/fundamentals/markdown-basics).

## What to Remember

- A coding agent is an AI model in a loop: read, plan, act, observe.
- "Done" means the tests ran and passed.
- Approve safe calls. Deny deletes, switched-off tests and production changes.
- Every run needs a step limit.
- A rule works when it names an action and a moment.
- Write your rules once, in the rules file. That file is the start of your harness.

## Further Reading

- [Agent Harness Engineering, by Addy Osmani](https://addyosmani.com/blog/agent-harness-engineering/): where the formula "Agent = Model + Harness" comes from.
- [Harness engineering for coding agent users, on martinfowler.com](https://martinfowler.com/articles/harness-engineering.html): guides, sensors, and the part of the harness that you own.
- [awesome-harness-engineering, by walkinglabs](https://github.com/walkinglabs/awesome-harness-engineering): a map of the whole field.
- The **AI Agents** course on this site goes deeper into how agent loops work inside.

Next: **Failure Gallery**. You will watch six ways agents fail and learn which part of the harness fixes each one.