The evergreen product spec

The most valuable thing you write is the product spec. Treat spec writing as the actual programming, and build the evergreen spec collaboratively with Claude.

The spec is the rigid end of the specification spectrum. Mockups and prototypes come and go; this document holds what must not drift.

What belongs in the spec

A well-formed spec covers:

• Invariants and core capabilities. The behaviors and guarantees that must survive any redesign or reimplementation: what the product promises, the capabilities it must always have, the rules it can never break. If a change to the product’s surface violates one of these, that’s a bug in the process, not a design choice. This is the most rigid part of the spec. Change it deliberately, never incidentally.
• Mission / vision. The durable why. Not the pitch, not the roadmap: the reason this thing should exist. This section changes least over the product’s life.
• Product marketing. Who it’s for, who else serves them, how you differ, the positioning narrative, the milestone arc you’re aiming at.
• Key user personas and flows. The specific people who will use this, what they’re trying to accomplish, the shape of their journey. Concrete, not generic.
• Core data concepts. The nouns and verbs of the system. Users, accounts, documents, sessions, whatever your domain names its objects. Define them once, here.
• Architecture choices. The load-bearing technical decisions and the rationale behind them. Database choice, auth model, deploy target. Include why, not just what.
• Hard requirements. Compliance (GDPR, SOC2, HIPAA), infrastructure constraints, contractual commitments. Things that can’t be broken regardless of what else changes.

Not every point needs a document. Some are a sentence. Some are a whole section. The shape of the spec reflects the shape of the work.

What deliberately doesn’t belong here: the fluid surface. Screen layouts, styling details, copy, and interaction niceties live in lower-ceremony artifacts (mockups, prototypes, the code itself) and are free to change as long as the invariants hold.

How to pair-write it with Claude

The best specs emerge from back-and-forth, not from you dictating or Claude inventing. A rough rhythm:

• Draft the skeleton together. Ask Claude to propose a section structure based on what you’ve described so far. Edit it until it matches how you think about the product.
• Go section by section. For each section, give Claude what you know and ask it to draft the rest, flagging assumptions.
• Push back on invented content. Claude will happily fill in plausible-sounding claims about your product. Catch those. Mark them as “TBD” rather than let them stand as decided.
• Calibrate to the work. Some architectural choices warrant three paragraphs of rationale. Others are a sentence. Don’t pad the obvious; don’t underwrite the load-bearing.

Over many sessions, you’ll develop a sense of when Claude knows enough to succeed and where it’s filling in blanks. Trust it on the former; catch it on the latter.

How to evolve it, without rewriting

The spec is not static. It changes as you learn. The discipline is evolving it surgically, not regenerating it.

• Patch the spec, don’t regenerate it. Insert a new section. Modify one passage. Keep the diff small. Large-diff regenerations lose nuance that was already captured.
• Separate the spec change from the code change. Have Claude propose the patch to the spec, then the corresponding targeted change to the code. Don’t let it rewrite everything downstream just because one paragraph moved.
• Treat invariant changes as events. Editing a flow description is routine. Editing an invariant is a product decision: make it explicitly, record why, and check what downstream artifacts it touches.
• When to start over. If the concept has shifted fundamentally (different users, different problem, different architecture), a clean restart is often faster than patching your way to an incoherent Frankenstein. Know the difference between “edit” and “new.”

The test of a good spec

A good spec can regenerate the product. Not byte-identically, since toolchains change, but structurally: if you wiped your codebase, handed Claude the spec, and said “build this,” the result should be recognizably the same product. The invariants and core capabilities must match exactly. The visual surface may differ, and that’s fine.

If that test fails, the spec doesn’t contain enough to rebuild from. Fill the gaps before the next real rebuild (version upgrade, tech migration, vendor change). You’ll face one eventually.

Resources

• The implementation loop: how spec and code stay in sync