DurableSpec

One spec. Every person, every AI session, the whole picture.

Every AI session starts from zero.

You spend the first part of it re-explaining the system, the customer, and what was decided last week. When the session ends, what you worked out together goes with it. With several people each running their own sessions, the loss multiplies: nobody's agent knows what anyone else's agent learned.

DurableSpec keeps a small folder of plain documents next to your code: what the system is for, how it is shaped, and why it was built that way. Every session reads it first. The work that matters gets written back before the session ends. The knowledge carries forward, from one session to the next and from one person to the next.

Start with the problem. Read. Talk it through. Write it down. Build.

It sounds obvious. Most people don't do it. Here is the habit that makes it work.

1. Start with the problem, and have the agent read the spec first.

   Technical or purely about the business, either way the agent begins from what was actually decided, not from guesses. It reads the index and the few documents that matter, not the whole codebase.

2. Brainstorm.

   Let the agent push back, raise consequences you hadn't considered, and suggest alternatives. It's a better partner when it knows why things are the way they are.

3. Update the spec.

   Once you've settled on an approach, the agent records the decision and why, while the reasons are fresh, before any code is written.

4. Build it.

   With the agreed design written down in front of it.

5. Check the spec before you commit.

   Usually nothing more needs to change. Sometimes building taught you something the spec should know.

The next session, yours or a teammate's, starts with everything this one learned.

The people who know the business can write it down too.

Some of the most valuable knowledge in a spec isn't technical: who the customers are, what problem the system solves for them, what a word means in this business, which constraints come from contracts or regulation. Product owners hold that knowledge.

DurableSpec is plain language that anyone can read and edit, especially its purpose section, where the business context lives. That matters more every year, as more of the people building software with coding agents are business people, not career engineers. The spec is how their knowledge reaches every session, including the ones they never see.

A few folders, and one rule about when to write.

The rule that keeps it short enough to read at the start of every session:

Touch the spec only if a reader tomorrow would form a materially different picture of the system without the change.

The default answer is no. Bug fixes and refactors almost never qualify. New components, reversed decisions, and a new customer's requirements usually do.

Architecture pictures that change with the code.

The spec draws your system with the C4 model, the diagrams architects already know how to read, in Mermaid, so they show up as pictures on GitHub and live as plain text beside the code.

Your agent draws them when it creates the spec. On every change it checks whether an app, service, database, user or outside system was added, removed or reconnected, and if so it redraws the picture in the same commit. No separate drawing tool, and no diagram that went stale a year ago.

We leave the thinking to the model. We keep what it can't know.

Tools such as GitHub's spec-kit walk the model through a fixed process: specify, plan, break into tasks, implement. That scaffolding helps weaker models, and it gets in the way as models improve.

DurableSpec doesn't tell the model how to plan or think. It manages what your team knows: the purpose, the shape, and the decisions behind your system. No model, however capable, can recover a decision that was never written down. And the better models get at writing, the more a project needs a rule about when not to write.

Our test for every feature: would it still be useful if models were ten times smarter?

Spec tools plan the next change. DurableSpec keeps the whole picture.

GitHub Spec Kit, OpenSpec and Kiro are built around a unit of work: specify a feature or propose a change, plan it, build it. They are good at steering an agent through new work. DurableSpec is built around the system: one current account of what it is for, how it is shaped and why, kept accurate on every commit, whoever made the change and however.

They work well together. See the detailed comparison →

Your team uses different AI tools. The spec doesn't care.

It's plain Markdown in your repo. DurableSpec adds a short section to AGENTS.md, which most coding agents read, and two skills in the open Agent Skills format. Claude Code reads the same files through a one-line pointer; nothing is written twice.

• Claude Code
• Codex
• Cursor
• GitHub Copilot
• Gemini CLI
• Windsurf
• whatever comes next