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

Source: Dev.to

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 @davidpv/opsx doctor # verify tooling Inside Claude Code: /opsx:propose speed-up-search # write change: proposal + specs + design + tasks 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. 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