SpecGuard 소개: AI 코딩 전에 스펙을 먼저 검사하는 도구

SpecGuard 소개: AI 코딩 전에 스펙을 먼저 검사하는 도구

최근 Codex, Claude Code 같은 AI 코딩 도구를 사용하면서 개발 방식이 많이 바뀌고 있습니다.

간단한 기능은 설명 몇 줄만으로도 빠르게 구현되고, 익숙하지 않은 코드베이스에서도 에이전트가 생각보다 많은 작업을 처리해줍니다. 저 역시 이런 도구를 사용하면서 개발 속도가 빨라지는 경험을 했습니다.

그런데 여러 번 사용해보니 문제가 단순히 “AI가 코드를 잘 짜느냐”에만 있지 않았습니다. 오히려 더 자주 부딪힌 문제는 AI에게 넘긴 스펙 자체가 불완전하다는 점이었습니다.

---

문제는 코드가 아니라 입력물에 있었다

AI 코딩 도구는 주어진 입력을 바탕으로 구현을 진행합니다.

입력이 명확하면 꽤 좋은 결과를 만들 수 있지만, 스펙이 애매하거나 빠진 부분이 많으면 AI는 그 빈틈을 나름대로 추측해서 채웁니다.

처음에는 구현이 그럴듯해 보입니다. 하지만 개발이 진행될수록 문제가 커집니다.

• 코드의 품질과 구조가 점점 무너집니다.
• 스펙과 코드가 점점 맞지 않게 됩니다.
• 나중에는 코드가 틀린 건지, 스펙이 낡은 건지, 처음 요구사항이 애매했던 건지 구분하기 어려워집니다.

특히 권한, 소유권, 상태 전이, 재시도, 멱등성, API 계약처럼 나중에 고치기 어려운 부분이 스펙에서 빠져 있으면 문제가 더 크게 번집니다.

기존에는 이런 문제를 주로 구현 이후 코드 리뷰에서 잡으려고 했습니다. 하지만 AI 코딩에서는 구현 속도가 빠른 만큼, 잘못된 방향으로도 빠르게 진행됩니다. 그래서 저는 구현 이후 코드 리뷰만으로는 부족하다고 생각했습니다.

결함 있는 스펙이 구현 에이전트에게 넘어가기 전에, 스펙 자체의 빈틈을 먼저 드러내는 단계가 필요했습니다. 이 문제를 줄이기 위해 만든 오픈소스 도구가 SpecGuard입니다.

GitHub : https://github.com/KoreaNirsa/spec-guard

---

SpecGuard는 무엇인가

SpecGuard는 AI에게 구현을 맡기기 전에 스펙을 먼저 검사하는 CLI / Codex 플러그인입니다.

코드 생성기가 아닙니다. 프롬프트를 넣으면 코드를 만들어주는 도구도 아닙니다.
SpecGuard는 구현 전에 스펙 패키지를 검토하고, 이 스펙을 AI 구현 에이전트에게 넘겨도 되는지 판단하는 도구에 가깝습니다.

기본 흐름은 다음과 같습니다.

1. 사람이 제품 스펙을 작성합니다.
2. SpecGuard가 스펙을 검사합니다.
3. NOT_READY라면 스펙을 보강합니다.
4. READY 또는 READY_WITH_WARNINGS가 되면 Codex, Claude Code 같은 구현 에이전트에게 넘깁니다.
5. 구현 후에는 선택적으로 PR Review를 통해 코드가 승인된 스펙에서 벗어나지 않았는지 확인합니다.

저는 이 흐름을 Validation-First Workflow(VFW)라고 부르고 있습니다. 핵심은 “AI에게 코드를 더 잘 짜게 하자”가 아니라, “AI에게 넘기기 전에 입력물을 먼저 검증하자” 입니다.

 

A. 어떤 문제를 찾는가

SpecGuard는 주로 구현 전에 놓치기 쉬운 스펙의 빈틈을 찾습니다. 예를 들면 다음과 같은 것들입니다.

• 인증/권한 경계가 불명확한 경우
• tenant/user ownership 범위가 빠진 경우
• idempotency, replay, race condition 처리가 없는 경우
• 만료/철회/상태 전이 규칙이 애매한 경우
• webhook, background job, 외부 API 재시도 정책이 없는 경우
• API 계약은 있다고 했지만 실제 OpenAPI path가 비어 있는 경우
• 클라이언트 검증만 믿고 서버 측 검증이 빠진 요구사항

결과는 크게 세 가지로 나뉩니다.

• READY: 구현 에이전트에게 넘길 수 있음
• READY_WITH_WARNINGS: 넘길 수는 있지만 주의할 점이 있음
• NOT_READY: Critical/Major 문제가 있어 스펙 보강 필요

NOT_READY가 나오면 SpecGuard는 구현을 시작하지 말고 스펙을 먼저 고치라고 알려줍니다. 이 점이 중요합니다.
SpecGuard의 목적은 구현을 막는 것이 아니라, 잘못된 구현이 시작되기 전에 멈출 수 있는 지점을 만드는 것입니다.

 

B. 기본 검사는 API 키 없이 동작한다

SpecGuard의 기본 검사는 로컬 휴리스틱 기반이며 OpenAI API Key 없이도 실행할 수 있습니다.

pip install spec-guard
specguard run specs/your-feature-name --no-llm --no-follow-up

기본 경로를 LLM 기반 리뷰가 아니라 휴리스틱 검사로 둔 이유는 단순합니다.

CI나 PR Review에서는 결과가 빠르고 재현 가능한 것이 중요하기 때문입니다. LLM 기반 리뷰는 비용, 속도, 설정, 모델 변화의 영향을 받을 수 있기 때문에 현재 기본 경로는 빠른 로컬 검사입니다.
더 깊은 리뷰가 필요할 때만 OpenAI Platform 또는 Codex 기반 상세 리뷰를 선택적으로 붙이는 방향으로 두고 있습니다.

 

C.  SpecGuard가 만드는 결과물

SpecGuard가 스펙을 검사하면 사람이 읽을 수 있는 리뷰와 기계가 읽을 수 있는 JSON 결과를 함께 만들며 대표적으로 다음과 같은 결과물이 생성됩니다.

• readiness-review.md: 사람이 읽는 스펙 준비 상태 리뷰
• readiness-review.json: 플러그인이나 CI가 읽을 수 있는 구조화된 결과
• implementation-output.md: 구현 에이전트에게 넘길 수 있는 핸드오프 문서

여기서 중요한 파일은 implementation-output.md입니다.
SpecGuard가 스펙을 READY 또는 READY_WITH_WARNINGS로 판단하면, 구현 에이전트에게 넘길 입력을 정리한 핸드오프 문서를 만들 수 있습니다.
즉, Codex나 Claude Code에게 바로 “알아서 구현해줘”라고 넘기는 대신, SpecGuard가 검토한 스펙과 구현 경계, 테스트/계약 정보를 바탕으로 구현을 시작하도록 만드는 흐름입니다.

 

D.  Codex 플러그인을 추가한 이유

v0.4.0 작업에서는 Codex 앱 플러그인 MVP를 추가했습니다.
기존에는 사용자가 CLI 명령어를 직접 알고 실행해야 했지만 Codex를 쓰는 사용자는 자연스럽게 이렇게 말하고 싶을 수 있습니다.

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

SpecGuard Codex 플러그인은 이 흐름을 돕기 위한 것이며 Codex 플러그인은 SpecGuard 엔진을 새로 구현하지 않습니다. 기존 specguard CLI를 호출하고, 생성된 구조화 결과를 읽어서 현재 상태와 다음 행동을 요약합니다.

설치 흐름은 대략 다음과 같습니다.

pip install spec-guard
specguard --help
codex plugin marketplace add KoreaNirsa/spec-guard --ref main

이후 Codex 앱 플러그인에서 Bulit by OpenAI → SpecGuard Plugins 소스를 선택하고 설치하면 됩니다.

다만 중요한 제한이 존재하는데, 플러그인 설치가 specguard CLI 설치까지 자동으로 처리하는 것은 아닙니다.

현재 MVP는 CLI-backed 구조입니다. 따라서 Codex가 실행되는 환경에서 specguard 명령이 동작해야 합니다.

앞으로는 사용자가 직접 명령어를 몰라도 Codex에게 “SpecGuard CLI가 설치되어 있는지 확인하고, 없으면 설치한 뒤 실행해줘”라고 요청할 수 있는 흐름을 더 자연스럽게 만들어 가려고 합니다.

 

E. PR Review도 지원한다

SpecGuard에는 GitHub Actions 기반 PR Review 흐름도 있습니다.

구현 PR이 올라왔을 때, 승인된 스펙 패키지와 구현 diff를 비교해서 advisory comment를 남기는 방식입니다.

여기서 목표는 “AI가 만든 코드 리뷰”가 아니라, 목표는 구현 결과가 승인된 스펙에서 벗어났는지 확인하는 것입니다.

예를 들어 팀에서 다음 같은 규칙을 두고 싶을 때 사용할 수 있습니다.

• NOT_READY 스펙은 구현으로 넘기지 않기
• Critical/Major finding을 PR에서 먼저 노출하기
• 구현 결과물이 아니라 요구사항 입력 품질을 먼저 관리하기
• 구현 PR이 승인된 스펙과 어긋나는지 확인하기

설치는 CLI에서 다음 명령으로 사용할 수 있습니다.

specguard actions install-pr-review

또는 Codex에게 아래와 같이 요청할 수 있습니다.

@specguard SpecGuard PR Review 워크플로우를 설정해줘.

 

다만, PR Review가 실제로 OpenAI 기반 리뷰를 수행하려면 GitHub Actions Secret에 SPECGUARD_OPENAI_API_KEY를 등록해야 합니다.

선택적으로 아래 repository variable도 설정할 수 있습니다.

SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name

이 부분도 앞으로 Codex 플러그인에서 더 잘 도와주고 싶은 부분입니다. 예를 들어 사용자가 "@SpecGuard PR Review를 설정해줘"라고 요청하면, Codex가 다음을 순서대로 확인해주는 흐름입니다.

1. 현재 저장소와 브랜치 상태 확인
2. specguard CLI 설치 여부 확인
3. 없으면 설치 안내 또는 설치 실행
4. PR Review workflow 생성 전 사용자 확인
5. specguard actions install-pr-review 실행
6. 필요한 GitHub Secret과 Variables 안내
7. GitHub 연결이 되어 있으면 안전한 secret 등록 경로 안내 또는 보조
8. 연결이 없으면 수동 설정 방법 안내

API Key를 플러그인이 임의로 만들거나 저장해서는 안 됩니다. Secret은 GitHub Actions Secret으로만 다뤄야 하고, 저장소에 커밋되어서는 안 됩니다. 이 보안 경계는 앞으로도 유지할 생각입니다.

---

설계하면서 중요하게 본 것

SpecGuard를 만들면서 중요하게 본 기준은 아래와 같습니다.

첫째, CLI가 기준이 되어야 합니다.
Codex 플러그인, GitHub Actions, PR Review는 모두 같은 SpecGuard CLI 결과를 읽어야 합니다. 플러그인 안에 별도의 리뷰 엔진을 만들면 동작이 갈라지고 유지보수가 어려워집니다.

둘째, 기본 검사는 재현 가능해야 합니다.
그래서 기본 게이트는 API Key 없이 동작하는 휴리스틱 검사입니다. LLM 리뷰는 더 깊게 보고 싶을 때 선택적으로 붙이는 보조 경로에 가깝습니다.

셋째, 스펙 수정은 사용자가 결정해야 합니다.
SpecGuard는 finding을 보여주고 개선 방향을 제안할 수 있지만, 제품 요구사항 자체를 자동으로 바꾸는 것은 조심해야 합니다. 스펙을 바꾸는 것은 곧 제품 의도를 바꾸는 일이기 때문입니다.

넷째, 구현 에이전트에게 넘기는 입력을 명확히 해야 합니다.
AI 구현 에이전트에게 애매한 요구사항을 던지고 결과를 기다리는 대신, 검토된 스펙과 핸드오프 문서를 넘기는 방식을 지향합니다.

---

현재 한계와 앞으로 할 일

SpecGuard는 아직 초기 버전입니다.
모든 스펙을 완벽하게 판별하지 못합니다. 특히 휴리스틱 기반 검사는 빠르고 재현 가능하지만, 모든 도메인 문제를 다 잡아내지는 못합니다.

현재 가장 먼저 개선해야 할 방향은 아래와 같이 잡았습니다.

• 불필요하게 깨지는 테스트 줄이기
• 핵심 로직 중심의 안정적인 테스트 유지
• 휴리스틱 리뷰의 미탐/오탐률 개선
• Codex 플러그인 사용 흐름 개선
• @SpecGuard 기반 PR Review 설정 UX 개선
• GitHub Secret/Variables 설정 안내 개선
• 한국어 스펙에서의 finding 품질 개선

특히 OSS 프로젝트로 운영하려면 테스트가 너무 많은 구현 세부사항에 묶이면 안 된다고 보고 있습니다.
핵심 동작은 지키되, 문서 문구나 내부 구조가 조금 바뀔 때마다 CI가 깨지는 형태는 줄이려고 합니다.

---

마무리

AI 코딩 도구는 앞으로 더 많이 쓰이게 될 것 같습니다.
하지만 AI에게 무엇을 만들지 알려주는 스펙이 약하면, 구현 속도가 빨라질수록 잘못된 방향으로 더 빠르게 갈 수 있습니다. SpecGuard는 그 전에 한 번 멈춰서 묻는 도구입니다.

이 스펙을 정말 구현 에이전트에게 넘겨도 되는가?

이 질문을 자동화된 게이트로 만들고 싶었습니다.

아직 초기 단계의 OSS 프로젝트지만, AI 코딩을 사용하면서 “스펙이 약해서 구현이 틀어지는 문제”를 겪고 있다면 한 번 사용해보셔도 좋을 것 같습니다.

GitHub 저장소: https://github.com/KoreaNirsa/spec-guard

피드백과 기여도 환영합니다.
현재 이슈와 PR은 주로 영어로 관리하고 있지만, 한국어로 작성해주셔도 괜찮습니다.

특히 아래 피드백이 있으면 많은 도움이 될 것 같습니다.
- 어떤 종류의 스펙에서 잘 맞는지
- 어떤 finding이 과하거나 부족한지
- Codex 플러그인 흐름이 실제로 쓸 만한지
- PR Review 방식이 팀 워크플로우에 맞는지
- 한국어 스펙에서 어색하거나 부족한 부분이 있는지