Appendix H — Appendix H: Working alongside AI coding tools

By the time you read this, you almost certainly use an AI coding assistant: Claude Code, Cursor, GitHub Copilot, Aider, or one of their cousins. Pretending otherwise would mean writing for a world that no longer exists. But used as a substitute for understanding, when their proper role is to complement it, these tools quietly sabotage learning: you pass the lab, accept the working code, and then cannot answer the conceptual question that the next chapter assumes. The sensible approach is the one a math class takes with a calculator: the tool is welcome, and the aim of this appendix is to keep you in charge of it, able to say precisely what you want and to judge what comes back, while marking the moments where leaning on it would defeat the point.

H.1 The philosophy in one paragraph

AI coding tools are pair programmers, which means that you drive while the tool suggests; a common mistake is to treat them as tutors and let them lead. The tool excels at boilerplate, refactoring, generating variations, drafting tests, and explaining unfamiliar code. It is unreliable at the things this book is actually about: deciding what to build, choosing the metric, judging whether a number is good enough, and seeing the bug that comes from a wrong assumption. Rely on it for the first set of tasks, and reserve the second set for yourself.

Two properties of these assistants make the second set genuinely dangerous to delegate. First, they are trained toward answers that satisfy the person asking, so a response arrives confident and agreeable whether or not it is right, and pushback from the tool is rare exactly when you need it most. Second, they answer from what you typed, which captures only a fraction of what you know: every fact your request omits, including the ones you did not realize were relevant, gets replaced by an assumption the model never surfaces. The combination means a judgment delegated to the tool can go wrong invisibly, with no error message and no dissent, which is why the judgment tasks stay yours even when the typing does not.

H.2 The four rules

These hold in every chapter. The end-of-chapter exercises are built around them.

1. Read first, predict before you run. Before you open the assistant, read the chapter prose for the section you are on, look at the code, and predict what each cell will output. Then run it. If your prediction was right, the tool can safely speed you up. If it was wrong, that gap is the lesson, and the tool will paper over it if you skip past.

2. The Build lab is collaborative. Every chapter’s Build lab may be done with the tool. You must read every line you accept (if you cannot explain it to a non-coder colleague in one sentence, do not accept it), mark tool-drafted lines with a comment, and run the code to confirm it does what the lab asked.

3. The Evaluate lab is yours. The Evaluate lab is where the discipline of measurement lands, so you do not outsource the judgment: choosing the metric and defending why it matches the stake, choosing the test set and baseline, and reading the numbers to decide whether the variant actually beat the baseline. You may let the tool write the loop, the table, and the plot. The tool does the measuring; you do the judging.

4. Cite the tool. Mark tool-written code with a comment, the same hygiene you would apply to any library you did not write:

# Drafted with an AI assistant, reviewed and modified by hand.

H.3 Two callouts you will see throughout the book

With an AI coding tool

Marks a spot where handing work to the assistant amplifies learning: drafting a Pydantic schema from a JSON example and then reading every field, refactoring a function you wrote by hand, generating a test for an edge case you described. You cover more ground in the same time, and you still understand the result.

Don’t outsource this

Marks a spot where letting the tool decide would remove the thinking the chapter is teaching: choosing which model to route to, reading a confusion matrix, deciding whether a retrieval technique earned its cost. These are the moments the chapter exists for.

H.4 A recommended rhythm

Read the chapter prose once, end to end, with no tool. Form a mental model.
Open the notebook. Run each cell, predicting its output first.
At each lab, decide which rule applies: Build is collaborative, Evaluate is yours.
Use the tool freely on the Build lab; read and cite what you accept.
Do the Evaluate lab’s judgment yourself, even if the tool writes the loop.
Before the next chapter, predict how the running example (the support-ticket triage, the report corpus) will change. If you cannot, reread this chapter’s limitation before moving on.

H.5 Good use versus crutch use

Good use leaves you able to explain the result. Asking the tool to explain a line you do not recognize and checking it against the docs. Asking it to draft a docstring for a function you wrote. Asking it to draft the EarningsFacts schema in Chapter 5 and then reviewing each field’s type and tolerance.

Crutch use leaves a hole where understanding should be, and the hole has a tell. “Write me a RAG system for these PDFs,” pasted in without engagement: the tell is that you cannot say why the chunk size is what it is. “Which metric should I use?”: the tell is that you cannot defend why the metric matches the stake. “Fix this error” without reading it: the tell is that you have built no mental model of the error class. The conceptual questions at the end of each chapter are a check on exactly this: if they feel hard right after a smooth Build lab, that is your signal to back up.

H.6 Three calibration tests

Small self-checks you can run on any chapter. They reference labs you have already done.

1. The cold-open test. Open a chapter’s notebook on a different machine, with no assistant, and redo its Build lab from the prose alone. If you did Chapter 3’s Build lab (adding a sentiment field to the triage schema) with heavy tool help, try reproducing it cold. If you cannot, the first pass was crutch use.

2. The wrong-output test. Take a working cell and change one line subtly, then predict the new output before running. In Chapter 6’s search function, change n_results from 3 to 1, or sort the similarity the wrong way. Predict what happens; run it. A correct prediction means you understood the cell.

3. The error-class test. When the next error appears, read it for thirty seconds before showing it to the tool, and name what kind of error it is and where it likely came from. The structured-output retries in Chapter 3 and the version-pinned extractor in Chapter 5 are good places to practice: most failures there are a schema mismatch or a dependency version, and recognizing which is half the fix. Those thirty seconds are where the understanding accumulates.

If two of the three fail on a chapter, redo it without the tool. The goal is keeping the discipline of understanding in your hands, which requires no abstinence from the tool.

H.7 The tools, briefly

The book is deliberately tool-agnostic, so every callout says “an AI coding tool,” a phrasing that leaves the choice of brand to you. Any of these works for the labs:

Claude Code (Anthropic). A terminal agent, strong at multi-file edits and project-aware work.
Cursor. A VS Code fork with strong inline suggestions and chat-with-codebase.
GitHub Copilot. Strong autocomplete; free for many students through the Student Developer Pack.
Aider. An open-source CLI that pairs with your editor and any model.

Pick one; the instructions are equivalent across them.

H.8 From using the tools to building them

There is a deeper payoff coming. These assistants, which can seem like magic, are the patterns we teach in this book, wired together. In Chapter 11 you build the orchestrator-worker workflow that an agent like Claude Code uses to break a task into pieces and farm them out. In Chapter 12 you meet the Model Context Protocol, the standard these tools use to reach your filesystem, your shell, and external services, and you write a tool of your own. By the end of Part IV, the assistant on your desktop, which began as a black box you consumed, has become a system you could build. That is the strongest possible answer to “is the tool making me worse”: you will understand it well enough to have built it.

--- title: "Appendix H: Working alongside AI coding tools" --- By the time you read this, you almost certainly use an AI coding assistant: Claude Code, Cursor, GitHub Copilot, Aider, or one of their cousins. Pretending otherwise would mean writing for a world that no longer exists. But used as a substitute for understanding, when their proper role is to complement it, these tools quietly sabotage learning: you pass the lab, accept the working code, and then cannot answer the conceptual question that the next chapter assumes. The sensible approach is the one a math class takes with a calculator: the tool is welcome, and the aim of this appendix is to keep you in charge of it, able to say precisely what you want and to judge what comes back, while marking the moments where leaning on it would defeat the point. ## The philosophy in one paragraph AI coding tools are pair programmers, which means that you drive while the tool suggests; a common mistake is to treat them as tutors and let them lead. The tool excels at boilerplate, refactoring, generating variations, drafting tests, and explaining unfamiliar code. It is unreliable at the things this book is actually about: deciding what to build, choosing the metric, judging whether a number is good enough, and seeing the bug that comes from a wrong assumption. Rely on it for the first set of tasks, and reserve the second set for yourself. Two properties of these assistants make the second set genuinely dangerous to delegate. First, they are trained toward answers that satisfy the person asking, so a response arrives confident and agreeable whether or not it is right, and pushback from the tool is rare exactly when you need it most. Second, they answer from what you typed, which captures only a fraction of what you know: every fact your request omits, including the ones you did not realize were relevant, gets replaced by an assumption the model never surfaces. The combination means a judgment delegated to the tool can go wrong invisibly, with no error message and no dissent, which is why the judgment tasks stay yours even when the typing does not. ## The four rules These hold in every chapter. The end-of-chapter exercises are built around them. **1. Read first, predict before you run.** Before you open the assistant, read the chapter prose for the section you are on, look at the code, and predict what each cell will output. Then run it. If your prediction was right, the tool can safely speed you up. If it was wrong, that gap is the lesson, and the tool will paper over it if you skip past. **2. The Build lab is collaborative.** Every chapter's Build lab may be done with the tool. You must read every line you accept (if you cannot explain it to a non-coder colleague in one sentence, do not accept it), mark tool-drafted lines with a comment, and run the code to confirm it does what the lab asked. **3. The Evaluate lab is yours.** The Evaluate lab is where the discipline of measurement lands, so you do not outsource the judgment: choosing the metric and defending why it matches the stake, choosing the test set and baseline, and reading the numbers to decide whether the variant actually beat the baseline. You may let the tool write the loop, the table, and the plot. The tool does the *measuring*; you do the *judging*. **4. Cite the tool.** Mark tool-written code with a comment, the same hygiene you would apply to any library you did not write: ```python # Drafted with an AI assistant, reviewed and modified by hand. ``` ## Two callouts you will see throughout the book ::: {.callout-tip title="With an AI coding tool"} Marks a spot where handing work to the assistant *amplifies* learning: drafting a Pydantic schema from a JSON example and then reading every field, refactoring a function you wrote by hand, generating a test for an edge case you described. You cover more ground in the same time, and you still understand the result. ::: ::: {.callout-warning title="Don't outsource this"} Marks a spot where letting the tool decide would remove the thinking the chapter is teaching: choosing which model to route to, reading a confusion matrix, deciding whether a retrieval technique earned its cost. These are the moments the chapter exists for. ::: ## A recommended rhythm 1. Read the chapter prose once, end to end, with no tool. Form a mental model. 2. Open the notebook. Run each cell, predicting its output first. 3. At each lab, decide which rule applies: Build is collaborative, Evaluate is yours. 4. Use the tool freely on the Build lab; read and cite what you accept. 5. Do the Evaluate lab's judgment yourself, even if the tool writes the loop. 6. Before the next chapter, predict how the running example (the support-ticket triage, the report corpus) will change. If you cannot, reread this chapter's limitation before moving on. ## Good use versus crutch use Good use leaves you able to explain the result. Asking the tool to explain a line you do not recognize and checking it against the docs. Asking it to draft a docstring for a function you wrote. Asking it to draft the `EarningsFacts` schema in Chapter 5 and then reviewing each field's type and tolerance. Crutch use leaves a hole where understanding should be, and the hole has a tell. "Write me a RAG system for these PDFs," pasted in without engagement: the tell is that you cannot say why the chunk size is what it is. "Which metric should I use?": the tell is that you cannot defend why the metric matches the stake. "Fix this error" without reading it: the tell is that you have built no mental model of the error class. The conceptual questions at the end of each chapter are a check on exactly this: if they feel hard right after a smooth Build lab, that is your signal to back up. ## Three calibration tests Small self-checks you can run on any chapter. They reference labs you have already done. **1. The cold-open test.** Open a chapter's notebook on a different machine, with no assistant, and redo its Build lab from the prose alone. If you did Chapter 3's Build lab (adding a `sentiment` field to the triage schema) with heavy tool help, try reproducing it cold. If you cannot, the first pass was crutch use. **2. The wrong-output test.** Take a working cell and change one line subtly, then predict the new output before running. In Chapter 6's `search` function, change `n_results` from 3 to 1, or sort the similarity the wrong way. Predict what happens; run it. A correct prediction means you understood the cell. **3. The error-class test.** When the next error appears, read it for thirty seconds before showing it to the tool, and name what *kind* of error it is and where it likely came from. The structured-output retries in Chapter 3 and the version-pinned extractor in Chapter 5 are good places to practice: most failures there are a schema mismatch or a dependency version, and recognizing which is half the fix. Those thirty seconds are where the understanding accumulates. If two of the three fail on a chapter, redo it without the tool. The goal is keeping the discipline of understanding in your hands, which requires no abstinence from the tool. ## The tools, briefly The book is deliberately tool-agnostic, so every callout says "an AI coding tool," a phrasing that leaves the choice of brand to you. Any of these works for the labs: - **Claude Code** (Anthropic). A terminal agent, strong at multi-file edits and project-aware work. - **Cursor**. A VS Code fork with strong inline suggestions and chat-with-codebase. - **GitHub Copilot**. Strong autocomplete; free for many students through the Student Developer Pack. - **Aider**. An open-source CLI that pairs with your editor and any model. Pick one; the instructions are equivalent across them. ## From using the tools to building them There is a deeper payoff coming. These assistants, which can seem like magic, are the patterns we teach in this book, wired together. In Chapter 11 you build the *orchestrator-worker* workflow that an agent like Claude Code uses to break a task into pieces and farm them out. In Chapter 12 you meet the Model Context Protocol, the standard these tools use to reach your filesystem, your shell, and external services, and you write a tool of your own. By the end of Part IV, the assistant on your desktop, which began as a black box you consumed, has become a system you could build. That is the strongest possible answer to "is the tool making me worse": you will understand it well enough to have built it.