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 CrystalSpec.
The idea is straightforward: your specs aren't just documents, they're declarative contracts that govern system behavior. They live alongside your code, connected to your existing workflow (GitHub, ClickUp, Linear, wherever you already work), and they're designed from the ground up for the agentic era.
Here's what that means in practice:
Specs stay alive. When code changes, specs surface the drift. When specs change, the system knows what's affected. This isn't a wiki that someone might update. It's a harness, it grabs things before they fall.
AI edits go through human approval. Your agents can propose spec changes, but a human signs off. This sounds obvious, but it matters: the spec is the source of truth, and you don't want an agent autonomously rewriting the contract it's supposed to follow.
Scope integrity is built in. SOW says X, spec says Y? You see that. Before it becomes a billing dispute or a missed deadline, not after.
Agents read what they need. Structured specs mean the agent gets the billing context for a billing task. Not the entire system's history. Not someone's stream-of-consciousness product notes from six months ago.
"But we already have Notion / Confluence / Google Docs"
You do. And those tools are great at storing text that humans write and other humans read. They're not designed for machines to consume, they're not connected to your codebase, and they have no concept of spec integrity.
The question isn't whether you have a place to put documents. The question is whether your specs are working actively, structurally or whether they're just sitting there hoping someone reads them.
Who this is actually for
If you have a small project, you probably don't need this, but if you're a builder, juggling multiple projects, trying and breaking things, this might be the thing that removes the boredom our of crafting good specifications.
CrystalSpec is in early access right now. It's bootstrapped, it's opinionated, and it's focused. No pitch deck mythology about "revolutionizing the SDLC." Just a tool that makes specs actually work in a world where machines read them as much as humans do.
Check it out at crystalspec.com.
Building agentic workflows and tired of your agents hallucinating requirements from vibes? Same. Let's talk about it in the comments.
Top comments (0)