Context Is the Interface

You cannot change the model, and in the middle of a task you can change very little about the tool. What you control is what the agent sees: which files, which errors, which constraints, which examples. Every other lever you might reach for, the wording of the request included, matters less than that one.

The same request with a different context produces a different change. Cragmoor's refund task, run twice with one sentence of difference between the runs, shows how different: one run edits a single file and leaves members reading the wrong deadline, the other finds a duplicate nobody mentioned and stops to ask a business question before touching anything.

What Context Is

Context is everything the model has in front of it on a given turn. That includes the tool's own instructions, the project instructions file from Chapter 3, every message you have sent, every file the agent has read, every command it has run with its output, and its own earlier replies. It is bounded by the context window, and it starts empty at the beginning of every session, as Chapter 1 showed.

In this book "context" always means exactly that, and nothing else counts as what the agent knows about your project. The agent has no background knowledge of Cragmoor, no memory of last week's session and no view of the repository beyond the files it has opened. If a fact about the codebase is not in the window, the agent is working without it, however obvious the fact is to you.

Part of the window is spent before you type anything. The tool's own instructions, the project instructions file, your personal instructions and the names or descriptions of any connected tools load first, in every session. What remains is shared between your messages and everything the agent reads and runs while it works. That is why the files it opens matter more than the words you choose: on most turns, the files are most of what it is looking at.

The Refund Task Without Context

Your first real task arrives: the full-refund window shrinks from 24 hours before a class to 12. You type one sentence, "change the refund window from 24 hours to 12", and the agent goes to work. It searches the repository for words from your request, finds the window constant in refunds, changes 24 to 12 and runs that module's tests. One test fails, the deadline shown for a gym in the second time zone, so it updates that test's expected value from 09:00 to 21:00, runs the tests again and gets a green result.

you    Change the refund window from 24 hours to 12.

agent  search  "refund window"   → refunds: FULL_REFUND_WINDOW
       read    refunds
       edit    refunds: 24 hours → 12 hours
       run     refunds tests     → 1 failed, 2 passed
               second-zone deadline: expected 09:00, got 21:00
       edit    refunds tests: expected deadline → 21:00
       run     refunds tests     → 3 passed

agent  Changed the refund window to 12 hours and updated
       the deadline test to match. All refunds tests pass.

Every line of that transcript is true, and the change is still wrong. The agent never opened booking, where the cancellation screen computes its own "free cancellation until" deadline from a second copy of 24 under a different name. After the change, a member who books a Saturday 09:00 class is told on screen that free cancellation ends at 09:00 on Friday, while the refund code would pay out until 21:00 on Friday. The screen and the money now disagree by 12 hours, and no test noticed, because no test compares them.

# src/cragmoor/refunds.py
# Full refund for a cancellation at least this long before the class.
FULL_REFUND_WINDOW = timedelta(hours=24)

# src/cragmoor/booking.py
# Members can cancel free of charge until this long before the class.
FREE_CANCELLATION = timedelta(hours=24)

def cancellation_notice(booking: Booking) -> str:
    """The line the cancellation screen shows."""
    start = schedule.localize(booking.starts_at, booking.gym.time_zone)
    until = start - FREE_CANCELLATION
    return f"Free cancellation until {schedule.as_shown(until, booking.gym.time_zone)}"

// src/refunds.ts
// Full refund for a cancellation at least this long before the class.
export const FULL_REFUND_WINDOW_MS = 24 * HOUR_MS;

// src/booking.ts
// Members can cancel free of charge until this long before the class.
const FREE_CANCELLATION_MS = 24 * HOUR_MS;

/** The line the cancellation screen shows. */
export function cancellationNotice(booking: Booking): string {
  const start = schedule.localize(booking.startsAt, booking.gym.timeZone);
  const until = new Date(start.getTime() - FREE_CANCELLATION_MS);
  return `Free cancellation until ${schedule.asShown(until, booking.gym.timeZone)}`;
}

// Refunds.java
  // Full refund for a cancellation at least this long before the class.
  public static final Duration FULL_REFUND_WINDOW = Duration.ofHours(24);

// Booking.java
  // Members can cancel free of charge until this long before the class.
  static final Duration FREE_CANCELLATION = Duration.ofHours(24);

  /** The line the cancellation screen shows. */
  public String cancellationNotice() {
    ZonedDateTime start = Schedule.localize(startsAt, gym.timeZone());
    ZonedDateTime until = start.minus(FREE_CANCELLATION);
    return "Free cancellation until " + Schedule.asShown(until, gym.timeZone());
  }

The code above is the state of the repository before the task. Neither copy mentions the other. A search for "refund" finds the first and not the second, which is how the agent's run stayed inside one module and still reported success honestly.

The Same Task With Three Files

Run it again from the same starting commit with a request that names three things: refunds, where the rule lives; booking, where the cancellation screen shows the deadline to members; and the refunds tests. The agent reads all three before it edits anything. It notices that both modules hold 24, proposes one shared value that the screen and the refund both use, and asks the question the first run never reached: does the new 12-hour window apply to bookings made before the change ships, or only to new ones?

The second run did not need a smarter model or a sharper request. It needed one file the first run never opened. The question it raised has an answer only Ines can give, and Chapter 5 records her ruling: the new window applies to every cancellation from the day the change ships, whenever the booking was made.

Why Selection Beats Volume

Handing the agent the whole repository would not have helped. Cragmoor's booking service is about 60,000 lines, and past what the task needs, every extra file competes with the relevant ones for the model's attention, fills the window sooner and costs tokens on every later turn. Chapter 14 counts that cost, and the next pages of this chapter show what a crowded window does to a long session.

The skill is choosing the three files a colleague would open first. For the refund change that is the rule, the place the rule is shown to members, and the tests that pin it. Knowing which files those are is knowledge of the codebase, and it grows as you work in it. Chapter 11 shows how to build it faster in code you did not write.

Finding the three is worth a minute before the session starts. Search the repository yourself for the rule's number and for the words the code would use for it, not only the words of the ticket. At Cragmoor a search for 24 shows both copies of the window in the first screen of results, one in refunds and one in booking, before the agent has touched either. The request then names both, and the agent starts from the answer instead of from a guess.

Debugging Through Context

When a change surprises you, read what the agent read before you rephrase what you asked. The transcript lists every file it opened and every command it ran, and the list explains most surprises. Run one's change is missing booking because its context was missing booking.

That makes the fix specific. A wrong change from a context missing a file is fixed by adding the file, not by asking more firmly or in capital letters. "Make sure you update everything that uses the window" sends the agent searching from the same words it searched from before, and the words still do not lead to booking. Naming the file does.

Reading what the agent read takes a minute. Most tools show every file read, every search and every command with its output; scan that list before you open the diff and ask three things. Did it open the files you would have opened? Did its searches use the words the code uses, or only the words of your request? Did it run the tests that cover what it changed? A no to any of the three predicts what the diff is missing, and it usually predicts it correctly.

The Rest of the Chapter

The next four topics are four ways of controlling the same thing. Pointing at material instead of paraphrasing it decides how accurately a fact arrives. Keeping a long session from drifting decides whether early facts keep their weight. Persistent instructions decide what every session starts with, and outside sources decide what enters the window from beyond the repository, along with what leaves it.