{"slug": "i-was-using-claude-code-wrong-here-s-the-workflow-that-fixed-it", "title": "I was using Claude Code wrong — here's the workflow that fixed it", "summary": "A developer built opsx, a workflow tool that enforces a spec-first approach to AI-assisted coding, requiring a reviewed change document before any code is written. The tool separates management and governance planes, providing traceability from requirements to commits, and works with Claude Code, opencode, and Codex.", "body_md": "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.\n\nThe 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.\n\nI 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.\n\nThat realization led me to build opsx.\n\nThe core principle: Spec → Plan → Code\n\nCode is the last artifact produced, never the first.\n\nBefore 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.\n\nThis isn't a new idea — it's how safety-critical engineering works. The interesting part is applying it to agentic AI workflows.\n\nTwo planes, never confused\n\nopsx enforces a clean separation between:\n\nManagement plane (Jira) — what work exists and who's doing it. Tasks, priorities, estimates. This is where product decisions live.\n\nGovernance 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.\n\nThis 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.\n\nWhat the workflow looks like\n\nbashnpx [@davidpv](https://dev.to/davidpv)/opsx init # scaffold the workflow on any existing project\n\nnpx [@davidpv](https://dev.to/davidpv)/opsx doctor # verify tooling\n\nInside Claude Code:\n\n/opsx:propose speed-up-search # write change: proposal + specs + design + tasks\n\n/review-change speed-up-search # spec-reviewer audit before any code\n\n/opsx:apply # implement task by task, traced to specs\n\n/git-commit # semantic commit with Change:/Task:/Jira: footers\n\n/ship # validate + archive specs + merge\n\nThe 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.\n\nWhat you get in practice\n\nNo silent design decisions. The proposal step forces you to articulate why before the agent executes how.\n\nReviewable specs. Delta specs are Markdown files in your repo. They go through your normal code review process.\n\nFull 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.\n\nDrift detection. If you make a hotfix that doesn't match the spec, /opsx:sync surfaces and resolves the conflict explicitly.\n\nStack-agnostic\n\nopsx 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.\n\nTry it\n\nbashnpx [@davidpv](https://dev.to/davidpv)/opsx init\n\nNode >= 18, requires the OpenSpec CLI and at least one agent CLI.\n\nGitHub: github.com/davidpv/opsx-spec-driven-development-toolkit\n\nnpm: [@davidpv](https://dev.to/davidpv)/opsx", "url": "https://wpnews.pro/news/i-was-using-claude-code-wrong-here-s-the-workflow-that-fixed-it", "canonical_source": "https://dev.to/davidpv/i-was-using-claude-code-wrong-heres-the-workflow-that-fixed-it-3o07", "published_at": "2026-06-18 08:45:48+00:00", "updated_at": "2026-06-18 08:51:47.553541+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["opsx", "Claude Code", "OpenSpec", "Jira", "Codex", "opencode", "davidpv"], "alternates": {"html": "https://wpnews.pro/news/i-was-using-claude-code-wrong-here-s-the-workflow-that-fixed-it", "markdown": "https://wpnews.pro/news/i-was-using-claude-code-wrong-here-s-the-workflow-that-fixed-it.md", "text": "https://wpnews.pro/news/i-was-using-claude-code-wrong-here-s-the-workflow-that-fixed-it.txt", "jsonld": "https://wpnews.pro/news/i-was-using-claude-code-wrong-here-s-the-workflow-that-fixed-it.jsonld"}}