A lot of bad code starts with a shrug. The body appears first, then the excuses, then the comment if anyone remembers. `@Spec` flips that order. It makes the model say what the unit is for before the body starts improvising. That small sentence is not poetry. It is pressure. It narrows the corridor, sharpens the next move, and leaves behind a visible contract when somebody comes back later asking what this thing was supposed to do in the first place.
The Body Lies With Confidence
A method body can look clean and still be crooked. That is the danger. The code arrives dressed for court. Nice variable names. Neat indentation. A couple of responsible-looking conditionals. Meanwhile the actual behavior has already wandered three blocks away from the reason the method was born.
This gets worse when the main author is a model. A model is very good at producing something that feels finished. It can build a convincing staircase straight into a wall. If the language lets implementation speak first, plausibility takes the microphone and intent gets dragged in later as cleanup staff.
@Spec changes the order of operations. First say what this thing is for. Then earn the
right to write the body. It is a small act of discipline, which is usually how serious systems avoid
large acts of regret.
Name The Job Before The Hands Start Moving
In ordinary codebases, people pretend the purpose will reveal itself from the implementation. That is a lovely myth for anyone who does not have to maintain software. Real maintenance means opening a file six weeks later and asking one rude question immediately: what is this unit supposed to do, exactly?
If the answer lives only inside the body, you are already wasting time. Now the reader has to reverse-engineer intention from mechanics. Now review becomes archaeology. Now every change request starts with a séance.
A short spec does not solve everything. It does something more valuable. It establishes the job description in plain view. The body can still fail, but at least failure has an address.
Cheap Ceremony, Expensive Ambiguity
Humans hate extra structure when they have to type every line by hand. They call it ceremony. They call it friction. They call it all kinds of names because they can feel the cost in their wrists and in the clock.
Models do not have wrists. They do not get annoyed because you asked for one more line that states purpose explicitly. That changes the economics. Once AI becomes a major code producer, the old argument against visible discipline starts looking soft in the face.
The expensive thing is not the spec. The expensive thing is ambiguity. Ambiguity is what makes a code review go fuzzy. Ambiguity is what lets a method slowly collect side jobs like a crooked landlord stuffing extra tenants into the basement. Ambiguity is what turns maintenance into detective work with no witnesses.
Review Should Start With Intent, Not Guesswork
Good review is not just line-by-line nitpicking. Good review is comparison. Here is the stated purpose. Here is the implementation. Do these two belong to the same story, or did the code go feral halfway through?
Without that first sentence, reviewers end up grading confidence instead of correctness. They see motion. They see effort. They see something plausibly competent and let it through because the code looks like it already believes in itself.
A required @Spec gives review a blade instead of a flashlight. The question becomes sharper.
Not “does this seem reasonable?” but “does this body honor the contract it announced?” That is a much
nastier question. It is also much more useful.
Memory Decays. Contracts Age Better.
Most code does not become unreadable because the syntax is obscure. It becomes unreadable because context evaporates. The author forgets. The reviewer forgets. The project changes shape. The original pressure that created the method disappears, and all that remains is a body still performing old rituals for reasons nobody can quite explain.
This is where visible contracts pay rent. They do not preserve every historical detail, but they keep one crucial thing alive: the declared reason this unit exists. That is often enough to tell whether a proposed change is aligned, accidental, or quietly insane.
Software rots when intent becomes folklore. @Spec takes one piece of that folklore and
nails it to the front door.
Make Intent Cheap And Drift Expensive
That is the real point. Not decoration. Not moral purity. Pressure. In an AI-heavy codebase, you want the language to make good structure cheap and bad drift expensive. You want the compiler to keep asking the same unromantic questions before the project grows teeth.
What is this for? Is that purpose stated clearly? Does the body still match it? Can a reviewer tell the difference quickly? Can the next change happen without reopening the whole crime scene?
Put the spec first and the code has something to answer to. Leave the spec out and the body gets to narrate its own innocence. That arrangement works beautifully right up until it doesn't.
