Design

Code that is cheap to change correctly. Two programs can pass the same tests today and differ hugely in what next week's request costs. Working is the minimum, and how easily it changes is what separates them.

A codebase with an agent in it gets changed far more often, and each session starts by rereading it from nothing. Every change pays for the shape the last one left behind, and no test reports that price going up.

Choosing what to call things so a reader can guess what they do without opening them. unpaidInvoices tells you something. data tells you almost nothing.

An agent finds its way round a codebase largely by searching for words. If the thing it needs has a vague name, the search misses, and it may write a second copy of something that already exists. A name is also the cheapest context there is, since it arrives at every place the thing is used.

The advice that functions should be short, so each does one thing and has a name that says what. How short is where people stop agreeing. One famous book says very short. Another says too short makes code harder to read.

Splitting is mechanical, so an agent told to shrink functions can keep going without limit, and the numbers improve whether the code got clearer or not. Someone has to decide when to stop, and for now that is you.

How much the things inside one module belong together. High cohesion means that when one part changes, the rest tend to change with it, and nothing unrelated gets dragged along.

An agent tends to add code wherever it is already looking, so a file can grow by convenience rather than by meaning. Low cohesion makes it read a lot to change a little, and that reading comes straight out of its context.

How much one module has to know about another. If changing A forces you to change B, they are coupled. Modules have to talk to each other, so you can't get rid of it. The questions are how much, and whether you can see it.

The ripple of a change is what an agent has to hold in context and what a reviewer has to read. An import is usually the shortest way to a working change, so agents add them freely, and no test fails when the graph gets tangled. You need a separate sensor for this.

Keeping different kinds of decision in different places: what the tax rule is, how it is stored, how it is shown. Then you can think about one, and change one, without reading the others.

Asked to add a field, an agent will happily put reading the input, the business rule and the database code into one function, because that works. The next change to the rule then means reading all of it, and testing it means starting a server.

A simpler way to think about something complicated, leaving out what you don't need right now. save(user) lets you forget about disks and SQL. Every well-named function is a small abstraction.

A good one saves an agent reading: it needs the interface and not the inside, which keeps its context small. But agents create them for almost nothing, and a wrong one costs more than none, because everything then has to bend around it.

An abstraction whose hidden detail shows through anyway, usually at the worst moment. The interface promises something simple, and what sits underneath forces you to care about it after all.

An agent works from the interface it can see. If real behaviour depends on something the interface doesn't mention, it will write code that passes against a fake and fails against the real thing, with a clean diff and green tests.

Everything one module must know to use another: function names, what they take, what they return, what can go wrong, and any rule that isn't written down anywhere.

The interface is what an agent reads instead of the code behind it, so it is the part most worth getting right. Types make part of it checkable by machine. The unwritten part is where agents go wrong, because they can't read what nobody wrote.

A module that does a lot behind a small interface. A shallow one has an interface nearly as complicated as what it does, so using it spares you very little. The words are John Ousterhout's.

A deep module means less to hold in context per task, and one obvious place to make a change. Asking an agent for small pieces without asking for depth can get you the opposite: every helper correct, and the caller left doing the real work.

The rule that a module should have one reason to change. "Reason" is the word people miss: Robert Martin means one group of people whose requests cause the change, which isn't the same as doing one task.

Read as "do one thing", this rule can justify endless splitting. Read Martin's way, it tells an agent where a line belongs: between things that different people will ask to change.

Five design rules for code built from classes, under one acronym: Single responsibility, Open-closed, Liskov substitution, Interface segregation and Dependency inversion. They give you words for arguing about design.

Asking an agent to "apply SOLID" is a good way to get more classes. Ask for the one letter you need and say why. In a small codebase made of plain functions, several of the letters hardly apply.

Don't repeat yourself: each piece of knowledge should live in one place, so changing it means changing it once. It is about knowledge and not about text. Two lines can look alike and mean different things.

A session that doesn't know a helper exists may write it again. The classic result is a fix that lands in three of four copies, with the fourth going wrong months later. When a rule has one home, an agent can't miss a copy.

Put up with the first duplicate. When you are about to write the same thing a third time, extract it. By then you have enough examples to see what is really shared.

An agent told to value DRY may extract a shared helper at the second copy, and it won't be around to feel the result. A wrong abstraction is expensive to undo, since each new case bolts on another flag and the helper gets harder to read.

You aren't gonna need it: don't build something now because you guess you'll want it later. Build it when you do want it.

Speculative code used to cost you the typing, and that was the brake. An agent writes it for free, so the brake has gone and the rest of the cost hasn't. Every later session has to read it and work around it.

Keep it simple, stupid. Prefer the plainest design that does the job, because someone will have to fix it under pressure one day, without its author there to explain it.

An agent doesn't pay for cleverness when it writes, and the next session reads it cold. On its own this rule is too vague to enforce, so turn it into something specific that you can check.

Passing a function the things it needs, so it doesn't have to go and get them. isExpired(token, now) can be tested at any date. A function that reads the real clock inside can only be tested today.

Code that reaches for the real clock, network or database leaves an agent two choices: mock everything or skip the test. With injection, the honest test is also the easy one, so that is the one you tend to get.

Build behaviour by combining small parts, rather than stacking parent and child classes. Want a client that logs and retries? Wrap the client in something that adds each behaviour, rather than extending it.

To change an inherited class you have to read its parents, which spends context on files you aren't changing. Parts that are combined can be read, replaced and tested one at a time, including by an agent.

Dividing a program into layers, such as interface, rules and storage, where each layer may only use the ones beneath it. The rule about direction is what does the work.

This is one of the best kinds of rule for an agent, because a check can read every import and refuse, every time. A direction rule that only lives in a document gets broken the first time an import is the shortcut.

Robert Martin's version of layering: business rules sit at the centre and know nothing about databases or web frameworks. Those sit on the outside and depend inwards, so they can be replaced.

It hands an agent a rule simple enough to check: does this inner file import anything from outside? It also costs more files and more translating between shapes. For a small tool that price is usually too high, so ask for it when your rules will outlive your framework.

A line in the code where one part hands over to another: your code and the network, one module and the next, your code and a library. What crosses it should be checked and kept narrow.

A boundary tells an agent where its change should stop, and lets several agents work at once, one on each side. It is also where untrusted data comes in, so it is the one place that checking really has to happen.

Where data enters, turn it into a type that can only hold good data, rather than checking it and passing the original along. After that nothing needs to check again, and nothing can forget to.

An agent adding a new code path may not know a check is needed. If the function takes a parsed type, it can't be called with raw input, because the type checker says no. A rule held in the types holds in every session.

Design your data so that a wrong combination can't even be written down. An order that is both cancelled and shipped should be impossible to express, rather than something every function must remember to check.

Every check you have to remember is one an agent can forget. With the right data shape, the type checker catches the mistake in every session, including the ones nobody reads, and there are fewer branches to test.

Changing how code is organised without changing what it does, in small steps, running the tests after each one. If the behaviour changed, it wasn't refactoring.

Agents say "refactor" and may mean rewrite. A rewrite that also changes behaviour can't really be reviewed, and when something breaks you can't tell which line did it. Small green steps give an agent a way to know it is still safe.

A pattern in code that suggests a problem without proving one: a very long parameter list, one module reaching into another's data, the same switch in five places. It is a prompt to look, and it isn't a verdict.

Smell names are precise review vocabulary, so one word can replace a paragraph of instructions to an agent. Make it show what each one costs, though, because any model asked to find smells will find some.

A metaphor: taking a shortcut now is like borrowing. You get the feature sooner, and then you pay interest on every later change until you pay it back.

An agent can borrow faster than any person, and it pays interest in a new way: it rereads the mess each session, in tokens and in wrong turns. It can also repay cheaply, which changes the sums, so cleaning up may now be worth doing far more often.

A count of the separate paths through a function: one, plus one for each fork, such as if, a loop, a case or &&. More paths mean more to understand and more tests to cover them.

It gives an agent a fast fact in place of an opinion about "too complex". It also has a blind spot you should know about: a lookup table scores 2 where the same logic as a switch scores 13, and that can be either a real improvement or a dodge.

One number combining how complicated a function is with how little of it the tests run. Complicated and untested scores terribly. Simple or well tested scores low. The formula is complexity squared, times untested fraction cubed, plus complexity.

It is a gate an agent can run and act on, because the score offers two ways out: simplify or test. And an agent will reach any number you set by the cheapest route, which may not be the route you meant.

A tool that finds code repeated across a project, usually ignoring names so that a renamed copy still counts. It hands you candidates, and you decide whether they are really the same idea.

A session that doesn't find the helper writes another, and this is the cheap sensor for that. Treat what it finds as questions, since the rule of three says some duplicates are correct.

Agent output that works and that nobody would have chosen to keep: checks for cases that can't happen, comments that restate the code, helpers with one caller. The tests pass, which is how it gets in.

Each piece looks harmless, so each one gets through review. They add up, though, and the next session reads what is there and copies the style. You can't test this away, because nothing about it is failing.

An agent building more than you asked for: extra files, options and layers for a small job. Each addition is reasonable on its own, and the total is a bigger thing to carry for as long as the code lives.

Code costs an agent almost nothing to write, so nothing in its loop pushes back on size. That force has to come from you, which is why pstack and ub-mode, two published sets of agent instructions, both carry a rule about smallness.

A monolith is one program, deployed as one thing. Microservices split it into many small programs that talk over a network, each deployed by itself. One is simpler to run. The other lets teams move separately.

An agent does its best work when it can run and test the whole system from one place. Each network hop adds failures it can't see locally. Microservices mostly solve a problem of coordinating people. That is our judgement, and nobody has good data yet on how agents change the sums.

A short text file in the repo recording one design decision: the situation, what was decided, and what it will cost. You don't rewrite it later. A new record replaces the old one.

An agent has no memory of why. Without a record it will see something odd and tidy it away, or reopen an argument that was already settled. Code shows what was chosen, and only a record says what was rejected.

Easy means close at hand or familiar. Simple means not tangled together. The two are independent: a tool can be easy to start with and leave you a knot. Rich Hickey drew this line in a 2011 talk.

Agents make nearly everything easy. A working feature is one sentence away, whatever it tangles together. So "easy" has stopped telling you anything, and "simple" is what is left to judge. You still have to ask for it.