Show DEV: my coding agents kept building against last week's spec, so I built a fix

I spend most of my day pairing with coding agents — Codex and Claude Code, mostly. They're genuinely good at writing code now. What they're bad at is knowing what to write, because they only know what I paste into the session.

This post is about the problem that kept biting me, what I built for it, and what is still rough. It's a beta, and I'd really like feedback from people who code with agents every day.

The problem: specs drift, agents don't notice

A typical week looked like this:

• The PRD lives in one doc. Architecture decisions live in another. A few "we changed our mind" notes live in Slack.
• A teammate updates the spec on Tuesday.
• On Wednesday I start an agent session, paste in the version of the spec I have open, and the agent happily builds against the old one.

AGENTS.md / CLAUDE.md files help with repo conventions, but they're not where product decisions live, and keeping them in sync with the real spec is one more manual step. The agent isn't wrong — it's just working from stale context.

What I built

Specify is a workspace for PRDs, specs, decisions and architecture docs. Specify for Desktop (Mac, beta) connects that workspace to the coding agents you already have installed.

Four ideas, nothing more:

1. Keep the agents you already use. The desktop app connects the Codex or Claude Code already on your machine. There's no new agent to learn. If you don't have one set up, a free local Codex option is included.
2. Live docs, shared with the team. PRDs and architecture docs update in real time and teammates see changes as they're typed — no "which version is current?" thread.
3. The same docs go to the agent, over MCP. Specify runs an MCP server, so the agent reads the workspace directly instead of relying on whatever you pasted. It builds against the current spec.
4. Search over the workspace (RAG). Docs are chunked and indexed, so both people and agents can retrieve the relevant section instead of dumping whole documents into the context window.

How the agent actually uses it

The MCP tools are the same ones Specify's own agent uses, so there's no "lite" version for external clients. Roughly:

• knowledge_search for semantic search ("how do we handle refunds?"), and knowledge_grep / search_files when you need an exact string like an error code or a field name.
• list_files and read_file to open the doc it found (optionally only a line range).
• write_document / edit_document when the agent should update the spec itself — e.g. recording a decision it made while implementing.

Writes are guarded: the agent passes the revision it read, and if someone edited the doc in the meantime the write is rejected and it re-reads. Read and write are separate OAuth scopes, and read-only is the default, so you can let an agent search your docs without letting it edit them.

In practice the loop I use is: write or update the spec with teammates → start the agent from the desktop app → the agent searches the workspace, reads the current section, implements, and (if I allow it) writes back what changed.

What's rough (honestly)

• Mac only, and it's a beta. Expect sharp edges.
• Indexing is asynchronous. A doc you edited a moment ago may not show up in search immediately. Reading the doc directly always gets the latest version; search catches up shortly after.
• Retrieval is simple on purpose. Default search is vector-based; exact matches go through the separate grep-style tool. I haven't turned on hybrid ranking by default yet.
• The value assumes you already code with an agent. If you don't use Codex or Claude Code, the "agents get the spec" part won't mean much yet.

Where I'd love feedback

1. How do you keep agents in sync with your specs today? AGENTS.md, a docs folder in the repo, copy-paste, something else?
2. Should the agent be allowed to write to the spec, or is read-only the right default?
3. If you try it: what broke or confused you first?

There's a 30-second demo on the download page, and the desktop beta is free:
👉 https://specify.app/download?utm_source=devto&utm_medium=blog&utm_campaign=desktop_launch

Thanks for reading — I'll be in the comments.