9.6KB
Spec Driven Development — Chapter-07: 2c - The Scope of a Spec: How Much Fits in One Specification
- Source: /library/Spec Driven Development/source-file.pdf
- PDF pages: 57–63
- Pages without text: none
2c - The Scope of a Spec: How Much Fits in One Specification The Question That Comes Before Writing You know what parts a spec has and you know how to shape each sentence inside it. What is missing is the decision that comes before both: how much goes into a single document. It looks administrative and it is not. A spec that is too big produces a tasks.md of sixty items that the agent runs for three hours before you find out the third decision was wrong. A spec that is too small produces ceremony: seven artifact files for a change that was two lines. Both fail the same way, delivering late something nobody can review in one sitting anymore. The To-Do became five specs, not one and not twenty. None of that was accidental, and the criterion that produced that number is what this chapter is about. The Criterion: A Spec Is What Fits in One Lap The unit is not the screen, nor the database table, nor the “module”. The unit is one capability the user can exercise from start to finish, and that you can review whole before approving. Three questions settle most cases.
Can you state it in one sentence, with no “and” in the middle? “The person creates a task and sees their list” passes, because creating without seeing the result is no capability at all; the listing is what makes creation observable. “The person creates a task and gets an email reminder” does not pass: those are two independent capabilities that share a sentence only because they were remembered together. If you shipped only this, could anyone use it? The To-Do's first feature shipped an app that already served a purpose: you can write down what needs doing and look at the list later. The second shipped completing and reopening. Neither depended on the other existing to be worth something. Can you read the whole spec and disagree with it in ten minutes? This is the test that shows up least in books and decides the most in practice. The spec exists to be reviewed by you before it turns into code. A document you cannot finish in one sitting is a document you will approve by skimming, and approving by skimming is the same as not having written it. Notice what those three questions do not ask: how many hours it takes, how many files it touches, how many lines of code come out. Implementation effort is a terrible slicing criterion, because anyone estimating effort before the plan exists is guessing, and because a capability that is small to describe can be expensive to build without ceasing to be a single capability. Completing and Reopening Fit Together; Creating and Deleting Do Not Watch the criterion work on the case it settled itself.
The To-Do's second feature is “complete and reopen a task”. Two actions, one document. They stayed together because they are the same capability seen from both sides: the same state field, the same transition rule, and one without the other leaves the person stuck. A task that gets completed and never comes back is a task you cannot have checked off by mistake. The pair is the capability; each half alone is half a feature. Creating and deleting, on the other hand, are actions that touch the same place and do not form a pair. You can ship creation without deletion and the app works. That is exactly what happened: deleting became the fourth feature, three laps later, with a spec of its own that brought in subjects creation never had, such as confirmation before an irreversible effect. The quick test for cases like this is to look at state. If the two actions write to the same field with rules that depend on each other, they are probably one capability. If each touches a different place, or if one makes sense alone, they are two. When the Feature Is Too Big Sometimes you look at what has to be done and none of the three questions answers yes. The sentence has three “and"s, the spec takes more than ten minutes to read, and there is no way to ship half of it without shipping all of it. Time to split, and splitting well is the hard part. The wrong cut is the cut by layer. One spec for the database, another for the logic, another for the screen. Each passes the size test and none of them delivers any capability: you get three complete laps of the cycle before anybody can use anything, and
the first one can only be validated by someone who can read a database schema. It is the waterfall of Chapter 1, now sliced horizontally. The cut that works is by complete path, from shallowest to deepest. You take the whole capability and pull out of it the leanest version that still crosses every layer. Then the next spec fattens that version up. The To-Do is the example, because it started big. The initial request was a single sentence, “I want a to-do list app”, and that fits in no lap at all: it holds creation, listing, completion, filtering, deletion and editing inside it, with rules that did not even exist when the sentence was spoken. The cut by complete path is what the whole book walks. First create and list, and the app already serves for writing things down. Then complete and reopen, and it starts serving for keeping track. Then filter, delete, edit. Each of those five crosses domain, storage and screen, and each leaves one more thing the person can do. You can stop after any of them and still have a whole app, just a smaller one. The cut by layer, applied to the same request, would give three specs: the Task entity with localStorage persistence, then all the use cases, then all the screens. Add the three up and the result is the same app. The difference is that in the first two laps there is nothing to open and look at. Manual validation, which in the real lap closed the first feature with somebody typing a repeated title and checking the error message on screen, would have no way of existing before the third spec. And manual validation is always what catches whatever slipped past the automatic steps. There are three signs that you cut in the wrong place: One of the parts is not demonstrable. If you cannot open the app and show what changed, that part turned into a chunk of
implementation instead of a slice. The order between the parts is mandatory in both directions. A dependency in one direction is normal. If A needs B and B needs A, you cut through the middle of one thing. The same rule appears in both specs. A duplicated rule is a badly drawn boundary, and the two copies will diverge by the third week. A spec that is too big is almost always more than one slice, and where to draw the boundary between slices is where this book stops. The criterion that holds that cut up, the one that decides a responsibility belongs on this side and not that one, is the subject of FOCUS Architecture (2026, https://books.kodel.com.br/en/books/focus/), the second volume in this trilogy, which answers where each rule lives and why dependencies point inward. For slicing the To-Do, the three questions in this section were enough, and they will be enough for most of what you are going to write. When the Method Does Not Pay Off A book that argues for a way of working owes you the places where that way is a waste. SDD costs time before it saves time, and there are situations where the arithmetic does not work out. A throwaway script. Renaming two hundred files, converting a spreadsheet, scraping a page once. If the program dies after it runs, specifying is writing documentation for a corpse. Ask directly and read the result. Real exploration. You do not know what you want and you are going to find out by poking around. The spec is hostile here, because it asks you to declare up front what you will only know afterwards. Explore freely, throw away what you made, and write
the spec when you know what the question is. Nobody errs by exploring. The error is keeping the exploration's code after you found the answer. A one-off fix with a known cause. An inverted condition, a field missing from the screen, a wrong label. If you know which line it is and you know what it should say, the spec adds nothing. The warning sign is when the “one-off fix” is the third one in the same place: at that point the cause was never known at all, and it is worth stopping to specify. A proof of concept with an expiration date. A prototype for Friday's meeting that nobody will maintain. Same as the throwaway script, with one extra caution: a prototype that survives the meeting becomes a product without ever having had a spec, and that is how half the unmaintainable software in the world gets born. In three other cases the method is misapplied for a different reason: it is not the size of the task that gets in the way, it is the absence of someone who decides. A spec written by someone with no authority to answer “is this behavior really the one we want?” turns into a document of questions. If you cannot get the answers, the problem is not the method. Outside those situations, the arithmetic tends to work out on the very first lap, and for a simple reason: the cost of writing the spec is yours, once; the cost of not writing it is the agent's, every time, multiplied by every assumption it has to make on its own. What You Take From Here One spec per usable capability, reviewable in one sitting. Splitting by complete path, never by layer. And the honesty not to specify what dies in an hour.
With the blueprint drawn, the handwriting settled and the size of the sheet decided, what is missing is the tool that turns all this into a repeatable process. That is what comes next.