AI로 개발하면서 스펙을 통제하지 못했던 이유와 해결
기존 개발 방식
회사에서는 JIRA 티켓을 기반으로 일해왔다. 티켓에는 요약, 설명, 의도/목적, 할 일, 하지 않을 일, Acceptance Criteria, Technical Notes를 작성한다. AC를 만족하는 코드를 작성하면 끝이다.
팀에 혼자 남아 업무를 수행할 때도 이 방식을 동일하게 유지했다. 티켓이 곧 작업 범위고, 범위 밖의 일은 별도 티켓으로 분리하는 게 당연했다.
원칙이 무너진 배경
오랫동안 지켜온 방식도 무너지는 데는 한순간이다.
새로운 환경에 적응하는 과도기였고, 팀원 각자 업무를 진행하며 소통이 적었다. 기존 원칙을 지키지 않아도 별 문제되지 않는 분위기가 이어졌다. 이런 환경이 아니었다면 쉽게 해이해지지 않았을 것이고, 주변에서도 제어가 있었을 것이다.
하지만 근본적인 원인은 따로 있다. OpenSpec 기반으로 작업하면서 Explorer와 Propose 단계에 많은 시간을 들이게 되었다. AI 에이전트가 코드를 작성하기 전에 프로젝트의 구조와 맥락을 파악하고, 어떤 파일을 어떻게 고칠지 구체적인 계획을 만드는 탐색 과정이다. 이 과정에서 이전에 JIRA 티켓을 작성할 때 수준의 고민과 정리를 먼저 하게 되었고, JIRA 티켓 작성은 자연스럽게 뒤로 밀렸다.
문제의 본질
스펙 문서 기반으로 AI와 함께 개발하면서 실행 비용이 크게 낮아졌다. 이전에는 리팩토링이 필요하면 별도 티켓을 만들어 처리했다. 지금은 다르다. 구현 중간에 떠오른 리팩토링이나 개선 사항을 스펙 문서에 반영하고 즉시 실행한다.
결과적으로 JIRA 티켓의 범위를 넘어서는 변경이 계속 쌓인다. 스펙까지 그에 맞춰 수정되면서 작업 범위를 벗어난 변경이 누적된다. 실행 비용이 낮아진 만큼 "지금 같이 해버리자"는 유혹이 커졌고, 작업을 분리하지 않고 한 번에 처리하려는 경향이 생겼다.
핵심은 의지의 문제가 아니라 구조의 문제다. 실행이 쉬워지면 범위가 늘어나는 건 자연스러운 현상이고, 이를 시스템으로 막아야 한다.
해결 방법 1: 설계 확정 시점에 범위 고정
Explorer와 Propose 단계가 완료되어 기술적 설계가 확정되면, JIRA MCP(Model Context Protocol)를 호출해 미리 정의된 템플릿에 따라 JIRA 티켓 본문을 자동 업데이트하는 OpenSpec 커스텀 커맨드를 추가했다.
설계에 대한 합의가 끝나고 구현에 들어가기 직전에 JIRA를 확정한다. 이 시점이 해당 설계 범위를 명확히 고정하는 체크포인트로 작동한다. "JIRA에 정의되지 않은 작업은 수행하지 않는다"는 원칙을 시스템적으로 강제하기 위한 출발점이다.
해결 방법 2: 구현 중 가드레일
Later 섹션으로 분리
구현 중 발견된 리팩토링 포인트나 확장 아이디어는 현재 작업 중인 스펙 문서 하단의 ## Later 섹션에 기록한다. AI가 새로운 제안을 하면 "좋은 아이디어지만 지금은 Later에 적어둬"라고 지시해서 현재 작업 범위에서 분리한다.
작업 완료 후 openspec archive를 실행하면, Later 섹션의 내용을 추출해 다음 작업의 스펙 초안으로 자동 전환한다. 좋은 아이디어를 버리지 않으면서도 현재 작업의 범위를 지킨다.
명세 범위를 보호하는 가드레일
현재 JIRA에 반영된 스펙 범위를 벗어나는 수정 요청이 들어오면, 이를 감지하고 별도 처리하도록 강제한다. Claude Code의 PreToolUse 훅을 활용해 실행 단계에서 개입하는 가드레일을 구성할 수 있다.
AI가 스펙에 없는 코드 수정을 시도하면, PreToolUse 훅이 실행되어 변경 내용을 분석한다. 분석 결과가 OpenSpec 명세 범위를 벗어난 경우, 즉시 실행을 막기보다는 사용자에게 선택을 요구한다.
- Later 섹션으로 이동 (기본)
- 현재 스펙 수정 (필요한 경우에 한해)
- 예외적으로 허용 (스펙 수정이 필요 없는 작은 변경)
이 구조를 통해 작업 범위를 벗어난 변경은 분리되고, 현재 작업의 범위를 유지한 채 개발을 진행할 수 있다.