클로드 코드 사용법을 잘못했는데, 이 워크플로가 해결했다

출처: Dev.to

저는 몇 달 동안 프로덕션 프로젝트에 Claude Code를 사용해 왔습니다. 코드 작성 능력이 정말 인상적입니다. 하지만 기술적으로는 정상 작동하고 아키텍처적으로는 잘못된 기능을 계속 배포했습니다.

문제는 코드 품질이 아니었습니다. 저는 AI에게 작업을 맡기고 구현 중(암묵적으로) 시스템이 실제로 해야 할 일을 스스로 결정하게 했습니다.那些决定은 커밋에 묻혀 있었고, 검토 대상이 되지 않았으며, 요구사항과 연결될 수 없었습니다.

저는 Claude Code를 개발자 대체 도구로 사용했습니다. 이는 정확한 사양을 받아 올바른 출력을 생성하는 컴파일러와 더 잘 맞습니다.

이 깨달음은 저에게 opsx라는 도구를 만들게 했습니다.

핵심 원칙: 사양 → 계획 → 코드
코드는 최종 산물이자 최초 생산물이 아닙니다. 구현이 시작되기 전에는 변경 문서가 있습니다. 이 문서는 제안(무엇이 어떻게 변하는지)과 왜인지 설명하고, 새로운 동작을 설명하는 델타 사양, 설계 섹션, 구현 작업 리스트를 포함합니다. 이 문서가 검토되고 승인된 후에야 에이전트가 단일 라인의 코드만 작성합니다.

이건 새로운 아이디어가 아니라 안전Critical 엔지니어링에서 하는 방식입니다. 흥미로운 점은 에이전트 AI 워크플로우에 적용하는 것입니다.

두 평면, 절대 혼동하지 않음
opsx는 다음과 같은 깨끗한 구분을 강제합니다:

• 관리 평면 (Jira) — 존재하는 작업과 담당자. 작업, 우선순위, 추정. 여기서 제품 결정이 이루어집니다.
• 거버넌스 평면 (OpenSpec) — 시스템이 어떻게 동작해야 하는지. 코드를 허가하는 진실의 출처입니다. Jira 티켓이 얼마나 상세하더라도 구현을 허가하지 않습니다. 검토된 OpenSpec 변경 사항만이 합니다.

이것은 관료적처럼 들립니다. 실제로는 코드에 디자인 충돌을 잡을 수 있게 해주며, 모든 커밋이 명시적인 결정을 추적합니다.

워크플로우 모습

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

Claude 코드 내부에서:

/opsx:propose speed-up-search    # write change: proposal + specs + design + tasks

워크플로우는 다음과 같이 안내됩니다: /start는 새로운 작업을 라우팅하고, /next는 분실했을 때 현재 위치를 알려줍니다. 모든 명령은 다음 단계를 제안합니다.

실제 사용에서 얻는 것

• 침묵적인 설계 결정을 없애며, 제안 단계는 에이전트가 어떻게 실행하기 전에 왜를 설명하도록 강제합니다.
• 스택 무관
• opsx는 Claude Code, opencode, 그리고 Codex와 동작합니다. workflow.yaml은 브랜치( git-flow 또는 trunk-based), 커밋 규칙, Jira 프로젝트 키를 설정합니다. 명령어는 .claude/, .opencode/, .codex/ 디렉터리의 Markdown 파일과 동일합니다 — 읽히고 편집 가능합니다.

시도해 보세요

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