Chrysolites Tech Academy

Building with AI Coding Agents · Course book

Chapter 1: Working With a Coding Agent

Pairs with Lesson 1: Agentic Coding: Directing an AI 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.

Readfiles, errors, outputPlanchoose the next stepActedit, run a commandCheckdid it work? agent loop repeats until done you: set the goalyou: review the result
Figure 1.1 — The agent loop. The agent cycles through reading, planning, acting and checking; the person's work sits at the two ends, stating the goal and reviewing the outcome.

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.

5,00065,000110,000 window limit: 200,000 tokens reading 20 files30 working steps 0100k200k 02050steps taken in the session
Figure 1.2 — Context used over one task, following the worked example. Reading files costs the most; each later step adds a little more.

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.md is 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 requestVague versionSpecific version
Goal"Fix the login""Users who type a wrong password see a blank page; show an error message instead"
WhereNot stated"The form is in the login component and the check is in the auth service"
LimitsNot stated"Do not change the database or add new libraries"
Finished whenNot 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.
Keep secrets out of reach. Passwords and access keys belong in a separate environment file that is listed in .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.

LevelWhat the agent may do unaskedSuitable forRisk
Read onlyRead and search files; nothing elseExploring unfamiliar code, planningLowest
Ask every timeNothing; each edit and command needs approvalSensitive projects, learning how the agent behavesLow, but slow
Edit within the projectChange files in the project folder; asks before running commandsEveryday work under version controlModerate
Full autonomyEdit files and run commands freelyDisposable or isolated environments onlyHighest

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.

Install Chrysolites Tech Academy

Android / Chrome / Edge: open the browser menu and choose Install app or Add to Home screen.

iPhone / iPad (Safari): tap the Share button, then Add to Home Screen.