I've been working over 15 years with clients, written specifications with them, and let's just say I've learned a few tricks that seem to be very handy.
Nobody wakes up excited to write product requirements. We all love the ping-pong part: bouncing ideas, whiteboarding, arguing about edge cases over coffee. But the moment someone says "ok, write it down so the team can build it," the energy in the room drops to absolute zero.
Here's the thing though: in 2026, your "team" increasingly includes AI agents. And agents can't read the room. They can't absorb vibes from a Slack thread. They read tokens.
The economics are simple
A complete feature described in plain text: ~300 tokens.
The implementation of that same feature: ~10,000 tokens.
When your agent needs to understand a billing flow to fix a webhook handler, it can either read 300 tokens of spec, or crawl through 20k tokens of implementation spread across 14 files.
Less tokens in = less money spent. More context available = better output. Faster comprehension = speedier delivery.
This isn't theoretical. If you're running agentic pipelines right now, you already know: the quality of what goes into the context window determines the quality of what comes out. Garbage in, garbage out has never been more literally true.
Enter the Markdown Era of Specs... In Repos
So you get disciplined. You create a PRD.md, drop it in your repo, and start writing. The agent reads it before touching code. Output quality improves. You feel smart.
Six months later, that PRD.md is 70,000 tokens. Your agent is reading the entire authentication spec before fixing a typo in the billing email template. You're burning money and context window on irrelevant information.
So you do what programmers do. You divide and conquer.
You create a PRD_INDEX.md, split specs into modules — auth.md, billing.md, notifications.md — maybe sprinkle a nice little docs site on top that reads the markdown files. Now the agent reads a table of contents, picks the module it needs, and ignores the rest. It doesn't need to know about the logout procedure when it's working on an invoice calculation.
This works. For a while.
The rot sets in
Here's what happens next, and it happens faster than you expect:
Specs drift from code. Someone ships a feature, doesn't update the spec. Now the spec says one thing, the code does another, and the agent trusts the spec. It "fixes" working code to match outdated requirements. You spend an hour debugging a regression that was actually a compliance issue with a document nobody remembered to update.
Specs contradict each other. The billing spec says "free trial is 14 days." The onboarding spec says "free trial is 30 days." Both were correct at different points in time. The agent picks whichever one it reads first.
Nobody owns the specs. They were written by different people at different times with different assumptions. There's no validation, no schema, no way to know if a spec is current, complete, or consistent with everything else.
Scope creep hides in plain text. A client says "we agreed on X," your spec says Y, and the SOW says something else entirely. With markdown files in a repo, there's no mechanism to detect this. You find out when you're over budget.
The markdown-in-repo approach is a real improvement over having nothing. But it's still just files. It doesn't know what it contains. It can't tell you when something breaks.
Enter the Spec Harness Era
What if there's a tool that addresses all of this?
Not a "super-app" that tries to be your project manager, your IDE, your CI system, and your documentation platform all at once. Just a tool that focuses on one thing: getting your specs right and keeping them right.
That's .
Building agentic workflows and tired of your agents hallucinating requirements from vibes? Same. Let's talk about it in the comments.
SOCIAL SHARE CARD GENERATOR