Adding Spec-Driven Workflow to an Existing Project Without Burning Months

You inherited a codebase with no specs: three years of decisions buried in code, Slack threads, and one person's memory. The agent you bring in guesses at everything and drifts within an hour. Spec-driven workflow sounds like months of archaeology. It is not, if you spec going forward, not backward.

Spec the next change, not the whole system

Pick the next change from your backlog. That change becomes the first spec: what behavior it adds, modifies, removes, three sections at two paragraphs each. When the change archives, the spec merges into your source-of-truth directory. Over months the spec directory grows exactly where change happens most, which is where documentation pays.

The thirty-minute setup

Install OpenSpec globally and initialize it in the project; you get specs/ for source of truth, changes/ for proposed modifications, config.yaml for settings. Pick a one-day change from the backlog and tell your agent to propose it. The agent reads project context, asks a few clarifying questions, and produces a folder with proposal, specs, design, and tasks. You review before any code exists: match proceeds, mismatch corrects and re-proposes.

The propose-apply-archive loop

Three commands cover most work. Propose creates the change folder with proposal, specs, design, and tasks. Apply works through the task checklist; if the work shows the design was wrong, you update the artifact file and continue, no restart. Archive merges delta specs into the main specs directory and moves the change to a dated archive, preserving the why and the trade-offs for future readers.

What changes about review

Without specs, review is guessing intent from a diff. With specs it splits into two questions: does the code match the spec, and does the spec match the intent. The first is mechanical and fast. The second is where real review happens, before code instead of after.

The trade-off

Three adoption patterns fail the same way: spec-ing the existing system first (a month of writing, no features), letting the agent write specs unreviewed (subtly wrong specs spread into implementation), and applying the ceremony to throwaway work. Spec only work that will outlive the week; review every spec; skip the workflow for typos and experiments.

The smallest test

Install OpenSpec, initialize it in your current project, and run propose on the next item in your backlog. A matching proposal means the workflow runs; a mismatch you just caught before code.