How a Coding Agent Works

Why this matters

It is Omar's first day with Quill, the coding agent the Bramble Books team runs in the terminal. There is a flaky test in the inventory suite, so he types "fix the flaky inventory test" and goes for coffee. He comes back to a green test suite and a short diff. The diff deletes the assertion that was failing. Quill did exactly what it was asked: the test no longer fails. Nobody said the test had to keep testing something. Jun looks over Omar's shoulder and says the thing this lesson is about. "It is not wrong. You are." The agent is fast, tireless, and literal. Before you can brief it, drive it, or review it, you need to know what it is and what it can see.

1. The loop

A coding agent is a program built around a model. The model is the part that reads text and writes text; it has learned patterns from a very large amount of code and prose. On its own, a model can only answer. What turns a model into an agent is a list of tools and a loop.

A tool is an action the agent can request: read this file, search for this string, edit these lines, run this command. The agent loop is the cycle the agent runs until it decides the task is done: read the prompt and everything it has seen so far, decide which tool to call next, run the tool, read the result, and repeat.

2. What the agent can see

Every time the loop goes round, the model reads one thing: the context. The context is the full text in front of the model right now. It holds your message, the standing brief the team wrote for the project, every file the agent has read this session, and every command output it has seen. If a fact is not in the context, the model does not know it.

The list of what it cannot see matters more. It cannot see last week's session. It cannot see the ticket open in your other tab, the chat message where Nadia explained the rule, or your intent. A session is one continuous conversation with the agent; when it ends, its context is gone.

3. The context window and why sessions get worse

The context is not unlimited. The model reads text as tokens, small chunks of a few characters each, and the context window is the maximum number of tokens the model can hold at once. Every file the agent reads and every command output it sees spends part of that budget.

When the window fills, older material is dropped or summarized so new material fits. A summary keeps the gist and loses the details, and the detail lost is often the one constraint you stated early and never repeated. This is why long sessions drift. The agent is not forgetting on purpose. It is reading a shorter and shorter version of the conversation.

4. Tools and permissions

A terminal coding agent has four kinds of tool. Read opens a file. Search finds a string or a pattern across files. Edit changes lines in a file, or writes a new one. Run executes a shell command: tests, the linter, a build, git, anything the shell can do.

Read and search only look. Edit and run change the world. That difference is what permissions are for. A permission is a decision about a proposed action. Each edit and each command is something the agent proposes, and a permission rule says whether the action runs, asks a person first, or is refused. Quill runs on Claude Code, where these rules live in .claude/settings.json; other agents have an equivalent.

The rules, as a Claude Code shape:

{
  "permissions": {
    "allow": ["Bash(make test)", "Edit(src/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)"]
  }
}

5. Fast at typing, literal about asking

Replay the flaky test. Omar typed "fix the flaky inventory test." To Omar, "fix" meant: find out why the test sometimes fails, correct the cause, and leave the test proving what it proved before. To Quill, "fix" meant: make the test stop failing. Both readings are honest. Quill's is shorter, and Quill is fast.

The missing sentence is the definition of done. A definition of done states what must be true when the task is finished, including what must still be true. Without it, the agent picks the nearest state that matches the words, and the nearest state is often the wrong one.

6. Hallucinated APIs and other honest mistakes

A model completes patterns. When it has seen a thousand inventory modules with a countByStore method, and Shelf's inventory module looks like the others, it may write inventory.countByStore() even though Shelf never had one. That is a hallucinated API: a call to a function, method, or option that does not exist, written with confidence because the pattern is strong. It is an honest mistake. The model is guessing well, and sometimes the guess is wrong.

The cheapest defense is to make the agent run the code. npm run typecheck says there is no countByStore on that type. make test says the import fails. When the error lands in the agent's own context, it corrects course. When nobody runs anything, the invented call ships.

7. Brief, drive, review

This course is built around three verbs, and every lesson tells you which one it is doing.

Brief is what the agent needs to know before it starts, and where that knowledge lives. A brief is the set of instructions and facts you give the agent: the standing brief in CLAUDE.md that it reads every session, the skills that package a procedure, and the task you write for one piece of work. L1 teaches the standing brief; L2 teaches skills, subagents, and the task brief.

Drive is how you run a session so the agent does the right work, and stop it doing the wrong work. L3 teaches task sizing, planning before building, steering early, and restarting instead of arguing. L4 turns permissions and hooks into guardrails in code.

Review is how you check what it made and turn each mistake into a rule. L5 teaches you to read an agent's diff as a stranger's pull request and to spot the specific ways agents fail.

Summary

• A coding agent is a model, a list of tools, and a loop: read the context, pick a tool, run it, read the result, repeat.
• The agent sees only its context: your message, the standing brief, the files it read, and the output it saw. It cannot see last week, your chat, or your intent.
• The context window is finite. Long sessions drop or summarize early material, which is why a constraint from turn 3 is gone by turn 40.
• Reads and searches look; edits and commands change things. A permission decides whether a proposed change runs, asks, or is refused.
• The agent is literal. Write a definition of done that says what must still be true, and run the tests so invented APIs fail fast.