Meet Cragmoor

Cragmoor runs four indoor climbing gyms in two time zones: members, day passes and classes of 16 climbers. Its booking service is three years old, was written by people who have since left, and is now owned by the team you have just joined. Some of its modules have decent tests and one has none at all.

This page introduces the codebase, the two colleagues you will work with, the first task you will be given and how to follow along with whatever assistant you use. Every later example in the book is built on what is here, so the names and the numbers are worth keeping in your head.

The Booking Service

The service has five modules, and the book names each one in plain words wherever a page needs it. booking reserves and cancels a place in a class. waitlist decides who is next when a class is full and calls back into booking to hand the place over. pricing handles members, day passes and discounts. refunds decides what a cancellation gets back. schedule holds the classes, their start times and each gym's time zone.

The code is uneven in the way three-year-old code usually is. booking and refunds have decent tests. pricing has none, which is why Chapter 11 starts there. The service is written in whichever of the three languages you choose, Python, TypeScript or Java, and the prose never says which. The rules, the bugs and the habits are the same in all three.

In numbers, the service is about 60,000 lines with about 900 tests, and the full suite takes about three minutes to run. Money is held in whole cents throughout. Every class time is supposed to go through the time-zone helper in schedule, and most do. Nobody on the current team wrote the original version, and the commit history from the early days is a long run of messages like "fix" and "wip" that explain nothing.

Rules That Are Easy to State

A class holds 16 climbers, and a full class has a waitlist. When a place frees up, the next person on the waitlist is offered it, and the offer is held for 15 minutes before it passes on. A booking cancelled up to 24 hours before the class gets a full refund. The four gyms sit in two time zones, one hour apart.

Each of those sentences is simple, and each has an edge. The 16th place is the last one, and the code that checks it is the code that lets in a 17th. A 15-minute hold can expire in the middle of a request that is accepting it. A class that starts at 19:00 at one gym is at 18:00 in the other time zone, and any code that builds that time by hand instead of asking schedule gets one of the two wrong, along with the cancellation deadline that hangs off it. Chapter 7 shows the ways generated code gets these edges wrong, and Chapter 8 shows how to test them.

Two conventions sit underneath the rules and are not written in any of them. Money is held in whole cents, never in fractional amounts, so a refund of a $24 class is 2,400 and a rounding rule never has to be invented. And every class time passes through the time-zone helper in schedule, so that only one piece of code needs to know which gym is in which zone. An agent that has not been told either convention will cheerfully break both, and Chapter 3 is where you tell it.

Ines and Kai

Ines is the senior engineer who leads the team. She reviews carefully, and the questions she asks of a change are the ones Chapter 6 teaches: what behaviour changed, who else calls this, what was removed, and which test shows it works. She is not hostile to the tools. She simply expects the author of a change to be able to answer for it.

That expectation is the whole contract this book teaches. Ines uses an agent herself, every day. What she will not accept is a pull request whose author cannot say why a line changed, and she will ask, in review, until the answer is either a reason or a revert.

Kai is a capable teammate who built the waitlist with an agent in one afternoon, about 1,400 lines of it. What happened to that feature in its third week is the story of Chapter 2, and Kai learns the discipline in this book alongside you. You are the newest engineer on the team. Nobody else recurs.

The First Task

In your first week the business sends one sentence: cut the full-refund window from 24 hours to 12. It sounds like a one-line change. It is not, and finding out why is most of the book's middle. The rule might live in more than one place. Somebody has to decide whether bookings made before the change get the old window or the new one. "Up to 12 hours" has to mean something exact at the boundary.

Ines will answer each of those questions when you ask them, in Chapter 5. The point of the task is that an agent will not ask them unless something in its context makes it. Given only the sentence, it will find the obvious 24, change it to 12, update the tests that asserted 24 and report success.

Chapters 3 to 5 prepare the repository, the context and the task for that change. Chapters 6 to 9 review it, test it and commit it, including what the agent got wrong along the way. By the end of Chapter 9 the refund change has gone through every stage of the loop the book teaches.

Following Along

There is no companion repository. Practise on a codebase you know, at work or of your own, with whichever assistant you have. From Chapter 3 on, every chapter ends in something you can do to that codebase, and doing it on real code you understand teaches more than a prepared exercise would.

A good practice codebase has three properties. It has tests you can run with one command, because half the habits in this book lean on them. It is under version control, because the other half lean on git. And it is code you would be embarrassed to break, because that is the condition under which the habits stop being theory.

Every code sample on these pages exists in Python, TypeScript and Java. Choose your language once with the tab on any code block, and every block on every page switches with it. The prose is the same for every reader. Chapter 15 is the setup reference for particular tools, and the only chapter that names them; set up your assistant from it and come back.