2 Working With a Coding Agent
Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering
Simon Willison, a developer, has asked most major new models the same question since 2024: “Generate an SVG of a pelican riding a bicycle” (an SVG is a drawing written as text, so a model writes one as it writes code). Four Claude models, each at three effort levels (how long the model reasons before answering), answered it with 12 drawings, and every one is recognisably a pelican on a bicycle. The dearest cost 13.09 cents, about 93 times as much as the cheapest that was good enough, at 0.14 cents (Figure 2.2).
Choosing between those drawings is the first of many judgements this chapter teaches. A coding agent is a program that writes and edits files and runs commands at your request: you write the Prompt, it does the typing, and you Check whether the result is right. It can produce in a minute what would take an hour by hand, and it can produce plausible, confident, wrong work just as quickly. How do you get the first kind of work without being fooled by the second?
- Explain how a model and a harness divide the work, and which half to change when an agent disappoints.
- Choose a model and effort level for a task, and keep a session’s cost down with
/model,/clearand/exit. - Decide where to start an agent, which of its commands to approve and which rules belong in
AGENTS.md. - Write a prompt that names its files, asks for one step and ends in a check, and size a larger task by how it can be checked.
2.1 Model plus harness
A coding agent is two programs working together (Figure 2.1).
The model is a large language model, such as Anthropic’s Claude, OpenAI’s GPT or Google’s Gemini. It runs on the vendor’s servers. It reads text and writes text, and it can reply with a structured request to use a tool: “read this file”, “run this command”.
The harness is the program on your computer that surrounds the model. Claude Code, Codex and Antigravity are harnesses. The harness gives the model its tools (reading and writing files, running commands, searching), carries out the model’s tool requests, asks you before it does anything consequential, and sends the results back to the model. That loop repeats until the model replies with an answer instead of another request. That loop, run on your own files and commands, is what makes it an agent: it acts in your project folder, one tool request after another, until the step is done, where a web chat hands you text to copy.
A short way to remember the split: the model decides, the harness does, you direct and check. It has a practical consequence. Many harnesses can run several models, so the same harness behaves differently with a different model, and the same model behaves differently inside a different harness. When an agent disappoints you, the cause can be either half, and the fix is different: a stronger model for reasoning that falls short, better rules or permissions for a harness that does the wrong thing.
The model cannot touch your computer. Everything it “does” is a request that the harness carries out, and the harness can show you each request before acting on it. That is the basis of every safety habit in this chapter: you approve commands you have read, and you review files after they change.
2.2 Choosing an agent and a model
This book covers three agents. Each comes from the same company as its default models:
| Agent | You type | Made by | Default models |
|---|---|---|---|
| Claude Code | claude |
Anthropic | Claude |
| Codex | codex |
OpenAI | GPT |
| Antigravity | agy |
Gemini |
What “covers” means differs between them. For all three, the install command, the account it needs and how it reads project rules were checked against the vendor’s documentation (dated in Chapter 4 and Section 2.5). The first screens of Claude Code and Codex were captured for the workshop on 2026-11-07; Antigravity’s were not. Other agents exist; this book does not check them, so it does not list them. Every prompt in the book is written to work in any of the three. A vendor’s own pairing of harness and model is the easiest to set up, but it is not automatically the best fit for a task: the harness and the model are separate choices.
2.2.1 Pick a model by task, not by rank
Each vendor offers a family of models, from small and cheap to large and capable. They are not simply better and worse versions of one thing. Larger, more recent models usually follow longer instructions, plan multi-step work and recover from their own errors better. Small models are faster and cheaper, and often good enough for short, well-specified edits such as fixing a typo or reformatting a table. Joining two datasets or debugging a failed render rewards the stronger model.
The prompts in this book are short and specific, so a mid-sized model at a moderate effort setting is enough: Claude’s Sonnet on medium effort, or Haiku for small edits, or OpenAI’s Sol on low (checked 2026-11-12). For unfamiliar, hard work, the vendors’ own advice starts higher: Anthropic suggests starting with Opus 5.5 for most workloads, and OpenAI with GPT-6 Astra for complex reasoning and coding. The names change every few months, and Appendix K keeps the current ones; the advice does not. Start small, and move up only when a task keeps failing.
Models are priced by the token, a fragment of text of a few characters, with one rate for the text sent to the model (input) and another for the text it writes (output). List prices are API prices: what a program pays per token when it sends requests to the model directly, through the vendor’s programming interface (the API), rather than through a monthly subscription.
Prices change monthly; the principle does not. On 2026-11-12, the list prices of the eight models in Table K.1 ran from $0.50 to $50 per million output tokens, a 100-fold spread between the smallest and the largest. That table, with its sources, is in Appendix K, the one place this book keeps facts that change; read it as a snapshot of the spread, not as numbers to plan with. Subscriptions count usage differently, and which models you can choose depends on your plan and the agent’s version.
The pelican runs below used Fable 5.2’s predecessor, Fable 5.1, listed at 10 / 50 dollars per million tokens when they were made.
The cost of a fixed level of capability has been falling fast. Measuring the cheapest model that reaches a given benchmark score, the venture firm a16z found the price falling about tenfold a year, a thousandfold over the three years from November 2021, and Epoch AI found falls of between 9 and 900 times a year depending on the benchmark (both checked 2026-11-07). Both warn that the pace may slow, and neither measures the frontier, where the price of the most capable work may fall more slowly. The practical lesson is the same either way: choose by what the task needs, not by today’s price.
2.2.2 One prompt, four models, three efforts
The pelicans this chapter opened with make the trade-off concrete. Figure 2.2 shows one run of each of four Claude models at three effort levels, with each reply’s cost at API list prices.
| Model | low effort | medium effort | high effort |
|---|---|---|---|
| Haiku 5.5 | |||
| Sonnet 5.5 | |||
| Opus 5.5 | |||
| Fable 5.1 |
Read the grid in two directions. Down the rows, the model grows and the price per token rises, so costs climb from fractions of a cent to more than ten cents. Across the columns, effort rises: the model reasons longer and writes more, so the cost usually rises while the picture gains details rather than becoming correct. Haiku on low effort has the weakest frame; from medium effort up, the frames are sound, which is consistent with, though no proof of, the book’s advice of medium effort.
Keep the evidence in proportion. It is one run per cell of one small, self-contained task, not a benchmark: run it again and you get different birds, and Fable on medium effort even cost less than Fable on low. More effort is not always better, either: at their maximum effort, Sonnet 5.5 and Opus 5.5 each spent 128,000 tokens reasoning, the models’ output limit, and returned no drawing (Simon Willison’s transcripts, checked 2026-11-12). A drawing says little about a long job that joins datasets and recovers from errors, which is where stronger models earn their price. Whether a 93-fold difference in price is worth paying depends entirely on the task.
2.3 What a conversation costs
Whether you pay by subscription or by API, use is counted in tokens. Three things raise the cost of a session:
- A bigger model costs more per token.
- A higher effort setting makes the model write more reasoning tokens per reply.
- A longer conversation costs more with every turn, because the model keeps no memory between requests: the harness sends the whole conversation again each time. Everything sent with a request (the conversation so far, the files read, the project’s rules) is the model’s context. Prompt caching makes the repeated part cheaper, not free, and caches expire.
The habits that follow are simple: a mid-sized model at moderate effort, one task per conversation, and a fresh conversation as soon as a task is done. Three commands, typed into the agent itself rather than run in the terminal (Section 4.4.1), cover them:
/ alone to list your agent’s commands.
| Command | Claude Code | Codex | Use it when |
|---|---|---|---|
/model |
switches the model; arrows adjust the effort level where the model supports it | chooses the model and reasoning effort | a prompt keeps failing (go up) or the work is routine (go down) |
/clear |
starts a new conversation with empty context; the old one can be resumed | clears the terminal and starts a fresh chat | a task is finished and an unrelated one starts |
/exit |
exits; /quit is the same |
exits; /quit is the same |
you are done, or need to move to another folder |
/clear matters for quality as well as cost. Old instructions and files read earlier keep steering the model while they remain in the conversation; a fresh conversation drops them. Nothing on disk changes, and the project’s rules file is read again.
One task is finished and an unrelated one starts. Which command first, and what does it keep?
/clear. The new task needs none of the old conversation, and carrying it along costs tokens on every turn and can mislead the model. Your files stay as they are, and the project’s rules file is read again.
2.4 The root folder is the agent’s world
An agent treats the folder you start it in as its root: it reads and edits files there and in the folders below, and runs commands from there. The first time you start one in a new folder, it asks whether you trust it. Claude Code’s prompt, captured on 2026-11-07, warns that “Claude Code’ll be able to read, edit, and execute files here”; Codex asks the same question in a folder that is a Git repository, and says it can read, edit and run files “subject to your permission settings”.
That question deserves a real answer. Trust only a folder you created for the work. Never start an agent in your home folder, in Documents, or anywhere that holds other people’s projects, private documents or keys (such as ~/.ssh). Project instructions in a trusted folder are read and followed too, which is another reason to trust only your own folders.
Starting in a small project folder has three practical benefits. Paths in prompts stay short (data/attractions.csv), the project’s rules file is found, and a mistake stays inside one folder that you can restore. It is not a guaranteed boundary, though: a command can still name a path outside the folder, so read each command before you approve it.
Two agents writing the same files, or rendering in one folder at once, will collide; Section 8.2 shows the safe split. To work on another project, leave with /exit, change folder, and start the agent again there.
2.5 Rules that persist: AGENTS.md
Everything you tell an agent in conversation is forgotten when the conversation ends. Rules that must hold in every session go in a file: AGENTS.md, a plain Markdown file at the top of the project folder that the agent reads at the start of each session. A good one has three parts:
- Scope: what the project is, and what it is not.
- Rules: what must always hold (“every number comes from a cited file in
data/”). - Commands: how to build and check the project.
All three agents in this book read it (checked 2026-10-30). Codex reads AGENTS.md files before doing any work. Antigravity reads AGENTS.md or GEMINI.md in the project’s folders. Claude Code reads AGENTS.md when there is no CLAUDE.md in the working folder or above it, from version 2.1.277; a CLAUDE.md containing the line @AGENTS.md imports it, so one file can serve all three (Claude Code memory documentation, checked 2026-11-12). The repository behind this book works exactly that way: its CLAUDE.md imports its AGENTS.md.
AGENTS.md is context, not enforcement. The agent reads the rules and usually follows them, but it can still slip. Write rules that are concrete enough to check (“call ALVA counts ‘ALVA member attractions’”), and check them.
Yesterday you told the agent, in conversation, to say “ALVA member attractions”. Today it writes “top attractions”. Why, and what is the lasting fix?
The instruction ended with yesterday’s conversation: the model keeps no memory between sessions. Put the rule in AGENTS.md, which is read at the start of every session, and still check for it, because rules are context, not enforcement.
Part II writes the London guide’s rules in Chapter 6, and the water analysis writes its analysis’s in Chapter 17.
2.6 How to ask for work
A prompt is the request you type into the agent. Four habits make prompts reliable:
Be specific. Name the files, the columns, the chart type and the output. “Make a chart” invites guessing; “add a horizontal bar chart of visits_2025 by attraction from data/attractions.csv” does not.
One step at a time. One task per prompt keeps each change small enough to review, and tells you which step broke when one does.
Ask it to run and check. End with a check the agent can perform: “render it and tell me which file it wrote”, “check that the PDF is one page”. An agent that verifies its own work catches many of its own mistakes.
Check what changed. You are responsible for the result. Read the changed files (most agents can show you a diff, the lines added and removed) before moving on.
The prompts in this book were designed with AI assistance and refined to reduce errors, but they are not magic, and agents vary. When a prompt mentions something you do not understand (a YAML key, a Markdown construct, a Python call), ask before you paste:
Explain what a Markdown table is and when to use it. Then name the official docs page where I can verify your answer.Asking for the documentation page matters: it turns the answer into something you can check.
2.6.1 A web chat can draft your prompt
If you know what you want but not how to ask for it, a free web chat (Claude, ChatGPT or Gemini in the browser) can turn a rough idea into a prompt. Describe the goal in plain words, name your tools, and ask for a prompt of one to four lines, with one task, concrete file names and a check (Figure 2.3). The chat cannot see your files, so it guesses; the agent can see them, so it checks. Read the drafted prompt before you paste it, and fix any file name that does not match your folder.

Paste only what you would be happy to publish. Web chats and agents send your text to the vendor: no passwords, keys, unpublished data or personal information.
2.7 Vocabulary, specification, verification
With an agent doing the typing, you will rarely write a theme’s stylesheet, a slide deck’s options or a PDF template by hand. What you need instead is three skills, and every chapter from here on teaches a format through them rather than through its syntax:
- Vocabulary: knowing what is possible and what it is called, so you can ask for it. “Speaker notes”, “a cross-reference”, “a reference document for Word”, “a parameter”: an agent can produce any of them, but only if you know to ask, and a name gets you the real feature where a description gets an improvisation.
- Specification: writing a request the agent can carry out and you can check. It names the files, the settings and the result, and it ends with a check. Rules that must hold in every session, such as “every number comes from
outputs/”, go inAGENTS.md(Section 2.5), so you state them once. - Verification: knowing what good output looks like, and confirming it three ways. Read the diff, to see what changed; inspect the render, as its reader would; and run the checks that can run without you, such as tests and guards, lines that stop the render when a sentence no longer matches the data (Section 23.4).
An agent tells you it “added a citation style”. Which of the three skills tells you whether it did what you needed?
Verification: open the rendered reference list and compare one entry with the style’s own example, and read the diff to see which setting changed. Vocabulary helped you ask for a citation style by name; only verification shows that it is the right one.
2.8 A step or a task?
This book’s prompts mostly ask for one small step, because a small change is quick to check. Experienced readers will soon want to hand an agent a larger task: “add a model card”, not five prompts that build one. Size the work by how it will be checked, not by how much typing it saves.
| Hand over a larger task when | Keep to single steps when |
|---|---|
| you can state the finished result and how to check it | you will only know it is right when you see it |
| the checks run without you: tests, guards, a render | each step needs your judgement before the next |
| the work is on a branch, so undoing it is one command | the change touches data, publishing or other people’s work |
| a failure would be loud: a red test, a stopped render | a failure would be quiet: a plausible wrong sentence |
A larger task needs a larger check. Ask for a short plan first and read it before the agent starts; have it work on a branch; require it to run the tests and render every output; and ask it to end by listing what it changed and anything it could not verify. Then review the whole change as you would a colleague’s pull request, file by file, before it reaches the main line. The professional chapters show this at work: one prompt adds a whole report to an existing repository, and its checks are a test suite, a guard and a fresh-clone rebuild.
When a larger task goes wrong, do not fix it with a longer conversation. Undo it (git restore, or delete the branch), split it into the steps whose checks failed, and ask for those one at a time.
2.9 How to read the agent boxes
Every hands-on step in this book uses the same three-part box. Here is a simpler version of the first one you will meet in Part II:
Create london.md with a level-1 heading "Visit London" and one welcome paragraph.writes london.md · may run quarto render london.md
approve its commands · open london.html in your browser
Ask your coding agent holds the exact prompt to paste into the agent (in the HTML edition, with a copy button). Expect it to run lists what the agent will probably do, so you recognise it when it asks for approval; you do not type these yourself. You do lists the few things only you can do: start the agent, sign in to accounts, approve commands, run a live preview, open results. The agent occupies the terminal tab it runs in, so commands in a You do box go in a second terminal tab opened in the same folder (Section 4.4.1).
Together the boxes are one turn of the loop in the book’s title. Ask your coding agent is the Prompt. Expect it to run and You do are where you Check, recognising each command before you approve it and opening the result yourself. The render is the Publish. Each exercise closes the loop with You’re done when: the check, stated so that you can see whether it passed.
Approving a command without reading it. Most commands in this book run a tool the prompt named (quarto, uv, git, gh) on files in the project folder. Stop and ask the agent what a command does before you approve one that deletes files (rm), runs as the administrator (sudo), or touches a folder outside the project that the prompt did not name.
The prompts are examples, not transcripts. Agents vary from version to version and run to run, so the files they write will differ in detail from the ones shown. What should not vary is the result you check. Figure 2.4 shows what a session looks like.

2.10 Using AI in research: say it, own it
If your work is research, using an agent raises obligations beyond getting the code right. Journals and funders differ in detail, so read your venue’s own policy, but the International Committee of Medical Journal Editors (ICMJE), whose recommendations many journals follow, states a common core (checked 2026-11-12):
- An AI tool is never an author. Chatbots and other AI-assisted tools “should not be listed as authors because they cannot be responsible for the accuracy, integrity, and originality of the work”.
- You are responsible for what it produced. Humans are responsible for any submitted material that used AI-assisted technologies, and should review and edit AI output, which “can be incorrect, incomplete, or biased”. That includes references: AI-generated material is not an acceptable primary source.
- Disclose the use. Authors describe their use of AI-assisted technologies at submission, in the cover letter and in the appropriate section of the work.
Two further rules follow from ordinary research ethics rather than from any one policy. Keep unpublished manuscripts, participant data and other confidential material out of public AI tools. And never let a tool generate or alter primary data or images: presenting generated data as observed is fabrication.
A useful disclosure names the tool and version, the tasks it performed and the checks you made. The statement for this book, on its copyright page, is written that way. Where it goes depends on the use: code and analysis belong in the Methods, with enough detail to reproduce them, which in a Quarto project means the code itself and the project’s AGENTS.md.
Which needs a statement: fixing a typo, or computing a table?
Computing a table is analysis: describe it in the Methods, in enough detail to reproduce. Venues differ on whether language editing needs a statement; ICMJE’s recommendations make no exception for it, so when in doubt, disclose.
Summary
- The model decides, the harness does, and you direct and check; when an agent disappoints, either half can be the cause.
- Choose a model by the task, not by rank: a cheaper model at medium effort is often enough for a small step, and since the whole conversation is sent again each turn, start a fresh one for each unrelated task.
- Start an agent only in a folder you created for the work, and read each command before you approve it.
- Rules that must last go in
AGENTS.md, which is context, not enforcement, so write them concretely enough to check. - Good prompts are specific, ask for one step and end in a check; in research the agent is never an author, and its use is disclosed.
- Learn each format as vocabulary, specification and verification, and hand over a larger task only when its checks can run without you.
All of this assumes a computer on which an agent, Quarto and Python are installed and working together. Is yours? Chapter 4 gets it there in six checked steps.
Further reading
- Claude Code, commands reference and memory and
AGENTS.md(checked 2026-11-12). - OpenAI, Codex CLI and
AGENTS.md(checked 2026-11-12 and 2026-10-30). - Google, Antigravity rules (checked 2026-10-30).
- Anthropic, models overview and pricing; OpenAI, models (checked 2026-11-12).
- Free plans for web chats: Claude, ChatGPT and Gemini (checked 2026-11-12).
- Gemini CLI, installation, on its replacement by Antigravity CLI (checked 2026-11-12).
- Guido Appenzeller, LLMflation, a16z, 2024; Epoch AI, LLM inference price trends, 2025 (checked 2026-11-07).
- Simon Willison, pelican riding a bicycle series (checked 2026-11-06).
- ICMJE, Use of AI by authors (checked 2026-11-12).