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

David Perez Vicens — Thu, 18 Jun 2026 08:45:48 +0000

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.

Two planes, never confused

opsx enforces a clean separation between:

Management plane (Jira) — what work exists and who's doing it. Tasks, priorities, estimates. This is where product decisions live.

Governance plane (OpenSpec) — how the system must behave. This is the source of truth that authorizes code. A Jira ticket, no matter how detailed, does not authorize implementation. A reviewed OpenSpec change does.

This sounds bureaucratic. In practice, it means you catch design conflicts before they're in the code, and every commit traces back to an explicit decision.

What the workflow looks like

bashnpx @davidpv/opsx init # scaffold the workflow on any existing project
npx @davidpv/opsx doctor # verify tooling

Inside Claude Code:

/opsx:propose speed-up-search # write change: proposal + specs + design + tasks
/review-change speed-up-search # spec-reviewer audit before any code
/opsx:apply # implement task by task, traced to specs
/git-commit # semantic commit with Change:/Task:/Jira: footers
/ship # validate + archive specs + merge

The workflow is guided: /start routes new work, /next tells you where you are if you get lost. Every command ends by suggesting the next step.

What you get in practice

No silent design decisions. The proposal step forces you to articulate why before the agent executes how.
Reviewable specs. Delta specs are Markdown files in your repo. They go through your normal code review process.
Full traceability. Every commit has footers pointing to the change, the task step, and the Jira ticket. /ship archives the delta specs into the living spec.
Drift detection. If you make a hotfix that doesn't match the spec, /opsx:sync surfaces and resolves the conflict explicitly.

Stack-agnostic

opsx works with Claude Code, opencode, and Codex. workflow.yaml configures branches (git-flow or trunk-based), commit convention, and Jira project key. The commands are just Markdown files in .claude/, .opencode/, or .codex/ — readable and editable.

Try it

bashnpx @davidpv/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

DEV Community: David Perez Vicens

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