I was using Claude Code wrong — here's the workflow that fixed it

I've been using Claude Code on production projects for several months. It's genuinely impressive at writing code. But I kept shipping features that technically worked and architecturally misfired.

The problem wasn't the code quality. It was that I was handing the AI a task and letting it decide — implicitly, mid-implementation — what the system should actually do. Those decisions were buried in commits, invisible to review, and untraceable to any requirement.

I was using Claude Code as a replacement for a developer. It works better as a replacement for a compiler: something that takes a precise specification and produces correct output.

That realization led me to build opsx.

The core principle: Spec → Plan → Code

Code is the last artifact produced, never the first.

Before any implementation starts, there's a change document: a proposal that explains what's changing and why, delta specs that describe the new behavior, a design section, and an implementation task list. Only when that document is reviewed and approved does the agent write a single line of code.

This isn't a new idea — it's how safety-critical engineering works. The interesting part is applying it to agentic AI workflows.

/opsx init # scaffold the workflow on any existing project

npx /opsx init

Node >= 18, requires the OpenSpec CLI and at least one agent CLI.

GitHub: github.com/davidpv/opsx-spec-driven-development-toolkit

npm: @davidpv/opsx