Building with AI Coding Agents · Course book
Chapter 1: Working With a Coding Agent
A coding agent is an AI system that does more than suggest code: it reads your project, edits files, runs commands and checks its own results. Used well, it can do in minutes what would take hours. Used carelessly, it produces confident changes that nobody understands. The difference is rarely the model. It is how the person directs it. This chapter explains how a coding agent works and the habits that make its output dependable, whichever product you use.
What a coding agent actually does
A chat assistant answers a question and stops. An agent works in a loop. Given a goal, it decides on a step, carries the step out with a tool, looks at what happened and decides what to do next, and it continues until the goal is met or it needs your help. The tools are ordinary developer actions: read a file, search the project, edit a file, run a command in the terminal.
This loop explains both the power and the danger. The agent can recover from its own mistakes, because it sees the error message and tries again. But every step builds on the last, so a wrong assumption early on is carried through everything that follows. Working this way is called agentic coding, and your role shifts from writing each line to directing and reviewing.
Context: the agent's working memory
A model has no memory of your project. Everything it knows in a session must fit inside its context window, the fixed amount of text it can consider at once, measured in tokens (a token is roughly three-quarters of an English word). Your instructions, every file it reads, every command's output and its own replies all occupy that window.
The window fills faster than people expect. Suppose a window holds 200,000 tokens. The standing instructions take 5,000. The agent reads 20 files averaging 3,000 tokens, which is 60,000. It then takes 30 further steps, each adding about 1,500 tokens of commands and output, which is 45,000. The total is 5,000 + 60,000 + 45,000 = 110,000 tokens, or 55 percent of the window, in one ordinary task.
As the window fills, quality falls: early instructions get less attention and the agent begins to contradict itself. Three habits keep context healthy.
- Start a fresh session for each task. Leftover material from the previous job is noise.
- Point to what matters. Naming the two relevant files is better than letting the agent read forty to find them.
- Write down what never changes. Most agents read a project instruction file automatically at the start of every session;
AGENTS.mdis a common name for it. Put there the things you would tell a new colleague: how to run the tests, the conventions the project follows, what must not be touched. Keep it short, since it is spent from the window every time.
A specific request also saves context and guesswork. Compare two versions of the same request in Table 1.1.
| Part of the request | Vague version | Specific version |
|---|---|---|
| Goal | "Fix the login" | "Users who type a wrong password see a blank page; show an error message instead" |
| Where | Not stated | "The form is in the login component and the check is in the auth service" |
| Limits | Not stated | "Do not change the database or add new libraries" |
| Finished when | Not stated | "The existing tests pass, and there is a new test for the wrong-password case" |
Plan first, then build
The costliest mistakes happen when an agent starts editing immediately on a misunderstanding. Many agents therefore offer a plan mode, in which the agent may read and think but not change anything. It investigates, then presents a plan: what it believes the problem is, which files it will change and in what order. You correct the plan, which takes seconds, instead of unpicking the wrong code, which takes an hour.
A good plan review asks three questions. Has it understood the goal? Is it touching only what it needs to? Does the plan include a way to prove the change works? For small, obvious edits, planning is unnecessary overhead. For anything touching several files, it is the cheapest safeguard there is.
Work that recurs can be packaged. A skill is a saved set of instructions, sometimes with scripts, for a particular kind of task, such as "how we write a database migration" or "how we prepare a release". The agent loads a skill only when a task calls for it, so the knowledge is available without occupying the context window all the time. Skills are how a team turns hard-won lessons into something the agent applies consistently.
Trust, but verify: tests and version control
An agent's claim that "the fix is complete" is not evidence. Evidence is a test that passes. Tests give the agent's checking step something objective to check against, which makes the whole loop more reliable.
The safest sequence for changing existing code starts with a characterization test. Before altering anything, you have the agent write tests that record what the code does now, even where that behaviour is odd. Then the change is made. If those tests still pass, existing behaviour has been preserved; if one fails, you learn at once what was disturbed. This matters most with older code that has no tests and that nobody fully understands.
Version control is the second safety net. With Git, every commit is a checkpoint you can return to.
- Commit your own work before the agent starts, so its changes stand apart from yours.
- Have it work on a separate branch, never directly on the main line.
- Read the diff, the line-by-line list of what changed, before accepting anything. Reviewing a diff is the core skill of agentic coding.
- Commit after each completed step. If the next step goes wrong, you discard that step and nothing more.
.gitignore so it is never committed. An agent reads whatever is in the project, and anything committed to a shared repository is effectively public for ever. Give the agent placeholder values when it needs to see the shape of a configuration.Permissions and connections
An agent that can run commands can also run harmful ones, by mistake or because it was misled by text it read. Agents therefore have permission settings that decide what happens without your approval. They are normally set in a configuration file and can differ from project to project.
| Level | What the agent may do unasked | Suitable for | Risk |
|---|---|---|---|
| Read only | Read and search files; nothing else | Exploring unfamiliar code, planning | Lowest |
| Ask every time | Nothing; each edit and command needs approval | Sensitive projects, learning how the agent behaves | Low, but slow |
| Edit within the project | Change files in the project folder; asks before running commands | Everyday work under version control | Moderate |
| Full autonomy | Edit files and run commands freely | Disposable or isolated environments only | Highest |
The guiding principle is to grant the least that the task needs. Many agents can also run inside a sandbox, a restricted environment from which they cannot reach the rest of your computer or the network, which makes higher autonomy much safer.
It is sensible to begin strict and loosen gradually. Watching an agent ask permission for each command for a day or two teaches you what it tends to do, and you can then approve the harmless, frequent commands, such as running the tests, while keeping a prompt for anything that deletes files, installs software or reaches the network.
Agents can be given more tools through the Model Context Protocol, or MCP, a standard way of connecting an agent to outside systems. A server might provide access to a database, a design tool or a library of ready-made interface components that the agent can install correctly instead of inventing its own. Each connection adds capability and also adds something that must be trusted, so connect only what a project needs and only from sources you have reason to trust.
Practice tasks
- Take a vague request such as "make the page faster" and rewrite it with a goal, a location, limits and a definition of finished, as in Table 1.1.
- A window holds 128,000 tokens. Instructions take 4,000, the agent reads 15 files of 2,000 tokens, and it takes 20 steps of 1,000 tokens. How much is used, and what share is that? (Answer: 4,000 + 30,000 + 20,000 = 54,000 tokens, about 42 percent.)
- Write five lines you would put in a project instruction file for a project of your own.
- Choose a small function you did not write. Describe two characterization tests you would want before letting an agent change it.
- For each of these, pick a permission level from Table 1.2 and say why: exploring a project you have just downloaded; renaming a variable across your own project; running an agent overnight on an experiment.
- Explain why committing before the agent starts makes its work easier to review.
This course book is available to read online only at tech-academy.chrysolites.org.