Your spec was right on day one. By day 30 it's lying to your agent.
Loading...
Loading...
Join JS Mastery Pro to apply what you learned today through real-world builds, weekly challenges, and a community of developers working toward the same goal.
The argument about whether to write a spec before you build is over. Spec-first won. GitHub's Spec Kit has over ninety thousand stars. Amazon shipped a whole IDE, Kiro, built around the idea. BMAD hands you an army of planning agents. Write the plan before the code, make the AI agree on what "done" means first. Settled. Good advice. Do it.
So let's talk about the part that isn't settled, because it's the part that actually bites you. It doesn't happen on day one. It happens on day thirty.
Here's how it goes. You write a clean spec. It's accurate. You start building against it. Then reality shows up, the way it always does. You rename a field. You drop a feature that felt important on Monday and pointless by Thursday. You swap the auth approach halfway through because the first one fought you. Small, normal, correct decisions. Every one of them nudges the code a little further from the document.
And nobody reopens the document.
Why would they? Writing the spec felt like real work, because it was. Going back a week later to reconcile it against what you actually shipped feels like nothing. Like tidying. It's the first thing that gets skipped when you're busy, which is always. So the code keeps moving and the spec sits frozen on the day you wrote it.
Thirty days in, you have a document that confidently describes an app that no longer exists.
A stale spec sounds harmless. It's the opposite.
When a human reads an out-of-date spec, they skim it, notice it's off, and shrug. Their eyes tell them the truth. An agent doesn't have that. It reads the spec as ground truth, because that's the whole reason you gave it one. Then it builds your next feature against the app the spec describes, not the app you actually have.
You get work that's confident and wrong, built on a map of a place that changed. That's harder to catch than a plain bug, because nothing errored. The agent did exactly what the document told it. The document was lying.
The tools are starting to admit this out loud. The honest write-ups on spec-driven development now say the quiet part: static specs drift from the real code within hours, and most tools still treat the spec as something the agent reads once, not something anyone keeps true. Writing the spec was the easy ninety percent. Keeping it honest is the ten percent nobody built for.
The usual answer is "just be more disciplined, update your docs." That never works, because willpower loses to a deadline every single time. If keeping the spec true depends on you remembering to do a chore you hate, it will rot. Count on it.
The move that actually works is to stop treating the spec as a monument you carve once, and start treating it as something you reconcile. A cheap, regular pass with one question: does this document still match what actually shipped? And the answer comes from the code and the git history, not from your memory of what you meant to build. You update the doc from reality, on purpose, as a step in the loop, not as a someday-cleanup that never comes.
State living in files is the right instinct. Just remember files rot too, unless something keeps them honest.
This is the exact problem the Agentic Engineering Course is built around. Not "here's how to write a spec," everyone teaches that now. The workflow has a reconcile step that reads your real git diff and updates the scope and the specs to match what shipped, so day thirty looks like day one instead of a slow slide into fiction.
And here's the honest part. That step is a free skill on GitHub. You can grab it today. What the course actually teaches is the judgment around it: when to trust the reconcile, what a healthy spec even looks like at day thirty, how to run this on a real build without it turning into ceremony. The procedure is free. Knowing when and how to run it is the whole job.
A spec you never reconcile isn't documentation. It's a rumor your agent believes.
