예전에는 AI 코딩 도구를 활용해 구현 속도를 높이는 데만 집중했다. 지금은 구현 에이전트에게 작업을 맡기기 전, SpecGuard(스펙 검사 도구)를 통해 요구사항의 빈틈을 먼저 찾아내는 단계가 도입됐다. 달라진 건 결함 있는 스펙이 그대로 구현 단계로 넘어가 AI가 임의로 내용을 추측하고, 결과적으로 코드 품질이 무너지는 악순환을 끊으려 했다는 점이다.

AI가 코드를 못 짜는 것보다 더 무서운 건, AI에게 넘긴 스펙 자체가 불완전한 상태였다. 스펙에 빈틈이 있으면 AI는 그 공간을 나름대로 추측해서 채우는데, 처음에는 그럴듯해 보이지만 시간이 갈수록 코드 구조가 무너지고 요구사항과 실제 구현물이 따로 노는 현상이 발생했다. 결국 나중에는 코드가 틀린 것인지, 스펙이 낡은 것인지, 혹은 처음 요구사항이 애매했던 것인지조차 구분하기 힘든 상황에 이르게 된다.

이런 문제를 해결하기 위해 등장한 SpecGuard는 구현 이후의 코드 리뷰가 아니라, 구현 이전의 '스펙 리뷰'에 집중한다. AI가 코드를 생성하기 전, 입력값인 스펙의 품질을 먼저 검증해 READY 상태가 되었을 때만 구현 단계로 넘기는 안전장치 역할을 수행하며 AI 코딩의 신뢰도를 높이는 데 목적을 둔다.

v0.4.0 업데이트와 SpecGuard의 핵심 기능

이번 업데이트에서 먼저 바뀐 건 도구 연결 방식이다. SpecGuard는 v0.4.0 버전에서 Codex(AI 코딩 도구) 앱 플러그인 MVP(최소 기능 제품)를 추가하며 개발 환경과의 밀착도를 높였다. 사용자는 CLI(명령줄 인터페이스)를 통해 도구를 설치하고 마켓플레이스에서 플러그인을 추가하는 방식으로 기능을 활성화할 수 있다. 설치 과정은 다음과 같다.

bash
pip install spec-guard

bash
codex plugin marketplace add KoreaNirsa/spec-guard --ref main

이렇게 설정하면 Codex 내부에서 직접 SpecGuard를 실행해 스펙의 완성도를 확인할 수 있다.

SpecGuard의 핵심은 AI가 코드를 짜기 전 단계에서 스펙(제품 요구사항 명세서)의 결함을 먼저 찾아내는 것이다. 비유하자면 건물을 짓기 전에 설계도에 치명적인 오류가 없는지 검토하는 설계 감리 과정과 같다. 설계도가 부실하면 아무리 숙련된 건축가라도 추측해서 집을 지을 수밖에 없고 이는 결국 부실 공사로 이어진다. SpecGuard는 이러한 추측성 구현을 막기 위해 스펙의 상태를 세 단계로 판별한다. 구현 에이전트에게 바로 넘겨도 좋은 READY, 주의 사항이 있지만 진행 가능한 READY_WITH_WARNINGS, 그리고 치명적인 결함이 있어 보강이 필수적인 NOT_READY가 그것이다. 쉽게 말하면 AI에게 일을 맡기기 전 이 설명서가 충분히 친절한지를 먼저 검증하는 안전장치인 셈이다.

판별 과정에서는 기본적으로 --no-llm 옵션을 통한 휴리스틱(경험적 규칙 기반) 검사를 적용한다. 휴리스틱 검사는 거대 언어 모델의 추론에 의존하는 대신 숙련된 개발자가 흔히 겪는 실수나 필수 체크리스트를 규칙으로 만들어 빠르게 대조하는 방식이다. 이는 CI(지속적 통합) 환경이나 PR(풀 리퀘스트, 코드 변경 요청) 리뷰 단계에서 결과의 재현성과 속도를 확보하기 위한 선택이다. AI의 응답은 매번 조금씩 다를 수 있지만 규칙 기반 검사는 항상 동일한 기준을 적용하기 때문이다. 물론 더 깊은 분석이 필요할 때는 AI 기반의 상세 리뷰 경로를 선택적으로 사용할 수 있다. 이러한 검증 체계는 개발자가 요구사항의 빈틈을 미리 메우게 함으로써 결과적으로 코드의 품질을 높이는 결과를 가져온다. 전체 소스 코드와 상세 내용은 GitHub 저장소에서 확인할 수 있다.

'사후 코드 리뷰' 대신 '사전 스펙 검사'가 작동하는 방식

개발자가 AI 코딩 도구를 사용할 때 겪는 가장 큰 문제는 코드의 품질보다 입력값인 스펙의 불완전함이다. 예전에는 AI가 짠 코드를 사람이 일일이 검토하는 사후 리뷰 방식이 일반적이었다. 하지만 스펙에 빈틈이 있으면 AI는 이를 임의로 추측해 구현하고, 나중에는 코드를 통째로 뜯어고쳐야 하는 상황이 반복된다. SpecGuard(스펙가드, AI 구현 전 요구사항의 결함을 찾아내는 검사 도구)는 이 순서를 완전히 뒤집는다. 비유하자면 건물을 다 지은 뒤에 설계도가 틀렸음을 깨닫고 벽을 허무는 대신, 착공 전에 설계도의 오류를 먼저 잡아내는 사전 검수 단계라고 할 수 있다.

SpecGuard가 집중적으로 살피는 항목은 AI가 추측하기 쉽지만 틀리면 치명적인 결함들이다. 우선 인증과 권한 경계가 명확한지, 특정 데이터가 어떤 사용자나 테넌트(tenant, 소프트웨어 서비스에서 고객 단위로 분리된 독립적인 환경)의 소유인지 확인한다. 쉽게 말하면 누구에게 어떤 문을 열어줄지, 이 방의 주인이 누구인지를 명확히 규정하는 작업이다. 또한 멱등성(idempotency, 동일한 요청을 여러 번 보내도 결과가 같은 성질)이나 리플레이, 경쟁 상태(race condition, 여러 프로세스가 동시에 데이터에 접근해 충돌하는 현상) 처리 여부도 검사한다. 엘리베이터 버튼을 여러 번 눌러도 한 번만 작동해야 하듯, 시스템이 중복 요청에 어떻게 반응할지 미리 정의했는지 보는 것이다. 여기에 더해 상태 전이 규칙이나 웹훅(webhook, 특정 이벤트 발생 시 서버가 다른 서버로 알림을 보내는 방식), 백그라운드 작업의 재시도 정책, 클라이언트 검증에만 의존하는 위험한 설계 등이 검사 대상에 포함된다.

실제 작동 흐름은 단순하지만 엄격하다. 사람이 제품 스펙을 작성하면 SpecGuard가 이를 검사하고, 결과가 NOT_READY라면 스펙을 보강해야 한다. 모든 결함이 해결되어 READY 상태가 되었을 때만 Codex(코덱스, OpenAI의 코드 생성 모델)나 Claude Code 같은 AI 코딩 에이전트에게 구현을 맡긴다. 이 과정에서 Codex 플러그인은 중간 다리 역할을 수행한다. 플러그인이 내부적으로 기존 specguard CLI(명령줄 인터페이스)를 호출해 결과를 읽어온 뒤, 현재 스펙의 상태와 다음에 해야 할 행동을 AI에게 요약해서 전달한다. 개발자는 AI에게 다음과 같이 요청하며 이 흐름을 제어할 수 있다.

bash

@SpecGuard specs/your-feature-name에 대해 SpecGuard를 실행하고, READY/NOT_READY 상태와 주요 finding을 요약해줘.

이러한 구조는 AI가 추측으로 채우던 빈틈을 사람이 명확한 스펙으로 메우게 함으로써, 구현 단계에서의 시행착오를 획기적으로 줄인다.

GitHub Actions 연동과 AI 실무 워크플로우의 변화

개발자가 코드를 다 짠 뒤에 동료에게 검토를 받는 과정은 이제 익숙한 풍경이다. 보통 풀 리퀘스트(PR, 변경한 코드를 메인 코드에 합쳐달라고 요청하는 단계) 단계에서 코드의 버그나 효율성을 따진다. 하지만 AI 코딩 도구를 쓰면서 문제는 다른 곳에서 터지기 시작했다. AI가 코드를 못 짜는 게 아니라, 사람이 준 요구사항인 스펙이 부실해서 AI가 제멋대로 추측해 코드를 짜는 상황이 빈번해진 것이다. 비유하자면 완성된 집을 보고 설계도가 틀렸다고 한숨 쉬는 격이다. SpecGuard는 이 순서를 완전히 바꾼다. 집을 짓기 전, 설계도 단계에서부터 결함을 찾아내어 통과된 설계도만 AI에게 넘기도록 강제한다.

이를 위해 SpecGuard는 깃허브 액션(GitHub Actions, 특정 이벤트가 발생했을 때 정해진 작업을 자동으로 수행하는 도구) 기반의 PR 리뷰 워크플로우를 제공한다. 개발자가 스펙 파일을 수정해 PR을 올리면, AI가 자동으로 스펙의 빈틈을 검사해 리뷰를 남기는 방식이다. 설치는 간단하게 터미널에서 다음 명령어를 입력하면 된다.

bash
specguard actions install-pr-review

다만 자동화를 위해 깃허브 시크릿(GitHub Secret, API 키 같은 민감한 정보를 안전하게 저장하는 설정 창)에 몇 가지 필수 항목을 입력해야 한다. OpenAI API 키를 넣는 SPECGUARD_OPENAI_API_KEY와 사용할 모델을 지정하는 SPECGUARD_PR_REVIEW_MODEL, 그리고 검사할 스펙 파일의 경로를 지정하는 SPECGUARD_REVIEW_SPEC_PATHS가 그것이다. 예를 들어 모델 설정값에 SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano와 같은 형태로 입력해 사용할 모델을 결정한다.

실무 관점에서 이 변화의 핵심은 제어권의 이동이다. 기존의 AI 코딩이 결과물을 보고 수정하는 사후 처리 방식이었다면, 이제는 입력물의 품질을 관리하는 사전 예방 방식으로 바뀐다. 팀 내에서 스펙 상태가 NOT_READY인 경우에는 아예 구현 단계로 넘어가지 못하게 규칙을 세울 수 있다. 이는 개발자가 AI의 결과물을 일일이 검수하며 겪는 피로도를 획기적으로 줄여준다. 요구사항의 빈틈을 AI가 먼저 지적해주므로, 개발자는 구현 자체보다 더 정교한 설계를 고민하는 데 집중하게 된다. 결과적으로 구현 결과물이 아니라 요구사항 입력 단계부터 품질을 관리함으로써 AI가 추측으로 코드를 짜는 리스크를 원천적으로 차단하는 구조가 완성된다. 프로젝트의 전체 저장소는 https://github.com/KoreaNirsa/spec-guard 에서 확인할 수 있다.