The Pocock books

Plain example · no code

Moving house means updating the bank, the doctor, the car registration and five apps. Each one is easy. Together they're the problem, and you always forget one.

In code

// One color change = edits in many files.
button.style.color = "#b3261a"; // button.ts
link.style.color   = "#b3261a"; // link.ts

// One edit, one place.
export const BRAND_RED = "#b3261a"; // theme.ts

Plain example · no code

A light switch that also turns off the fridge (a dependency), with no label saying so (obscurity).

In code

// Obscure: what is 3? Who else knows?
if (user.status === 3) block(user);

// Clear: the meaning has a name.
const SUSPENDED = 3;
if (user.status === SUSPENDED) block(user);

Plain example · no code

A shop that only ever restocks the shelves and never tidies the storeroom. Fine for a month. In a year, nobody can find anything.

Say it to your agent

Once the feature works, do one more pass:
what would make the next change here easier?
If it's small, do it. If not, add it to the list.

Plain example · no code

A dishwasher: load it, press one button. A shallow dishwasher would ask you to set the water temperature, spray pressure and drying time every single load.

In code

// Shallow: the caller does the work, in the right order.
const f = open(path);
writeBytes(f, data);
flush(f);
close(f);

// Deep: one call. Buffering, retries and errors live inside.
save(path, data);

Plain example · no code

A restaurant kitchen. You order from the menu. You don't need to know the recipe, the supplier or which chef is on shift.

In code

// Leaky: every caller knows how dates are stored.
const d = new Date(row.created_at + "Z");

// Hidden: one place knows the format.
const d = readCreatedAt(row);

Plain example · no code

Buying one good kitchen knife instead of a tomato slicer, a bagel cutter and a cheese wire.

In code

// Special-purpose: one function per key.
deleteSelectionOnBackspace();
deleteSelectionOnDeleteKey();

// Somewhat general: one simple tool for both.
deleteRange(start, end);

Plain example · no code

A manager who only forwards your emails to their boss, unchanged. You'd be better off emailing the boss directly.

In code

// Pass-through: adds a layer, adds nothing.
function getUser(id: string) {
  return userStore.getUser(id);
}

Plain example · no code

A good hotel deals with your bags, your taxi and your late check-out. You don't have to arrange any of it.

In code

// Pushes pain up: every caller must handle "not found".
function remove(id: string) {
  if (!exists(id)) throw new Error("not found");
  // ...
}

// Defines the error away: the goal is "it's gone".
function remove(id: string) {
  if (!exists(id)) return; // already gone, done
  // ...
}

Plain example · no code

Before moving the furniture, you sketch two layouts on paper. The second sketch often shows you something the first one missed.

Say it to your agent

Before writing any code, give me two very different designs for this.
For each: the interface (function names and inputs), what it hides,
and what would be hard to change later. Then recommend one.

Plain example · no code

A recipe that says “add salt” versus one that says “add salt at the end, or the beans stay hard”. The second one tells you what matters.

In code

// Says nothing new:
// add one to count
count += 1;

// Says what the code can't:
// Timeout in milliseconds. 0 means wait forever.
timeoutMs: number;

Plain example · no code

A house with no blueprints. It might be fine, but before you knock down a wall you have no idea what's inside it.

In code

// Not legacy: a test says what it must do.
test("adds tax", () => {
  expect(withTax(100)).toBe(108);
});

Plain example · no code

A trapeze artist with a net can try a new move. Without one, they'd better never fall.

Say it to your agent

Before changing this function, write tests for what it does now.
Run them and show me they pass.
Then make the change and run them again.

Plain example · no code

Rewiring one room: find the circuit, find where to test it, cut power to just that room, test the wires, then rewire.

The recipe

1. Change point:  where does the change go?
2. Test point:    where can I check it?
3. Break deps:    what stops me testing it?
4. Write tests:   pin down what it does today.
5. Change:        make it, then tidy up.

Plain example · no code

Testing a smoke alarm. Sensing: you need to hear whether it beeps. Separation: you don't set the house on fire to find out. You use a can of test smoke.

In code

// Separation: swap the real mailer for a fake one.
class FakeMailer {
  sent: string[] = [];
  send(to: string) { this.sent.push(to); }
}

const mailer = new FakeMailer();
signUp("a@b.com", mailer);
// Sensing: now we can see what happened.
expect(mailer.sent).toEqual(["a@b.com"]);

Plain example · no code

A wall socket is a seam. You can swap a lamp for a phone charger without rewiring the wall.

In code

// No seam: the clock is welded in.
function isOpen() { return new Date().getHours() < 17; }

// Seam: pass the time in. Tests choose it.
function isOpen(now = new Date()) { return now.getHours() < 17; }

isOpen(new Date("2026-01-01T18:00")); // false

Plain example · no code

Before renovating, you photograph every room. You're not judging the decor. You just want a record in case something goes missing.

In code

// 1. Write a test you expect to fail.
expect(shippingCost("AK", 5)).toBe(0);
// 2. Run it. It says the real answer is 23.5.
// 3. Lock in what the code actually does.
expect(shippingCost("AK", 5)).toBe(23.5);

Plain example · no code

Adding a sunroom to an old house, instead of knocking through walls you don't understand.

In code

// Sprout: the new rule is a new, tested function.
export function dropDuplicates(items: Item[]) {
  const seen = new Set<string>();
  return items.filter((x) => {
    if (seen.has(x.id)) return false;
    seen.add(x.id);
    return true;
  });
}

// The only change inside the old, untested code:
const toPost = dropDuplicates(entries);

Plain example · no code

A mechanic's manual: a list of standard moves, each with steps, for freeing a stuck part without breaking the engine.

In code

// Before: the class builds its own database.
class Report { db = new Database(); }

// Parameterize Constructor: hand it in.
class Report {
  constructor(private db: Db = new Database()) {}
}
new Report(fakeDb); // tests use a fake

Plain example · no code

All the streams in a valley run under one bridge. To measure the water, you stand on the bridge, not at every stream.

An effect sketch

price ──► applyDiscount ──► subtotal ──► invoice.total
                               │
                               └──► emailReceipt

Pinch point: subtotal. One test there covers both.

Plain example · no code

Crossing a stream on stepping stones. Test each stone before you put your weight on it.

In code

// Lean on the compiler: rename the field,
// then let every error point to a place to fix.
type User = { fullName: string }; // was: name

// error: Property 'name' does not exist on type 'User'
// error: Property 'name' does not exist on type 'User'

Plain example · no code

A bakery famous for its sourdough perfects the bread. It buys its till, its paper bags and its accounting software off the shelf.

Say it to your agent

What makes this business different is: [your core].
Spend design effort there.
For login, payments and email, use the simplest standard option. Don't customize.

Plain example · no code

A kitchen designer sits with a family and walks through a normal morning: who's up first, where the coffee is, where the kids drop their bags. The design comes out of that, not out of a form.

Say it to your agent

Interview me about this feature, one question at a time.
Use real examples. When my answers conflict, point it out.
At the end, sum up the rules you learned.

Plain example · no code

A hospital where everyone means the same thing by “admitted”. If the nurses, the billing team and the computer system each mean something different, mistakes follow.

In code

// Three words for one thing. Which is it?
reservation.confirm();
order.cancel();
booking.total;

// The business says booking. So does the code.
booking.confirm();
booking.cancel();
booking.total;

Plain example · no code

A map that matches the streets. If the city adds a road and nobody updates the map, people get lost.

In code

// Code that reads like the business rule:
// "A booking can be cancelled up to 24 hours before."
class Booking {
  canCancel(now: Date) {
    return hoursUntil(this.start, now) >= 24;
  }
}

Plain example · no code

“Table” means one thing to a carpenter and another to an accountant. Both are right, in their own workshop.

In code

// sales/customer.ts
type Customer = { name: string; leadSource: string };

// support/customer.ts: same person, different model
type Customer = { name: string; openTickets: number };

Plain example · no code

An interpreter at a meeting. Each side speaks its own language, and the interpreter makes sure nothing gets mangled.

In code

// Anti-corruption layer: translate their shape into ours.
function fromOldCrm(raw: OldCrmRow): Customer {
  return { name: raw.CUST_NM.trim(), email: raw.EMAIL_ADDR };
}

Plain example · no code

Your passport is an entity: it's still yours if the photo changes. A $20 bill is a value: any $20 bill will do.

In code

// Entity: identity matters.
type Customer = { id: string; name: string };

// Value object: only the values matter. Never changes.
type Money = Readonly<{ amount: number; currency: "USD" | "EUR" }>;

Plain example · no code

A bank account. You don't edit the balance directly. You go through the account, which checks the rules: enough money, daily limit.

In code

class Order { // the root: the only way in
  private lines: Line[] = [];
  addLine(item: Item, qty: number) {
    if (this.lines.length >= 50) throw new Error("too many lines");
    this.lines.push({ item, qty });
  }
}

Plain example · no code

A good screwdriver does what its name says, doesn't secretly drill holes, and works with any screw of the right size.

In code

// Says what it does, no side effects:
const total = cart.totalWith(discount); // just returns a number

// Hidden side effects: surprises later.
cart.apply(discount); // also saves? emails? who knows

Plain example · no code

Learning a new city, you first memorize routes. One day you notice the river runs through the middle, and suddenly every route makes sense.

Say it to your agent

We now call this a subscription, not a recurring order.
Rename it everywhere: code, tests and the glossary.
Show me the plan before you change anything.