Show GN: SpecGuard - AI 코딩 전에 스펙을 먼저 검사하는 CLI/코덱스 플러그인
(github.com/KoreaNirsa)안녕하세요. SpecGuard라는 오픈소스 도구를 만들고 있습니다.
Codex, Claude Code 같은 AI 코딩 도구를 쓰다 보면 구현 속도는 확실히 빨라집니다. 그런데 몇 번 반복해서 써보니, 제가 실제로 자주 부딪힌 문제는 “AI가 코드를 못 짠다”보다 “AI에게 넘긴 스펙 자체가 불완전하다”에 더 가까웠습니다.
스펙에 결함이 있으면 AI는 그 빈틈을 나름대로 추측해서 구현합니다. 처음에는 그럴듯해 보이지만, 개발이 진행될수록 다음 문제가 커졌습니다.
- 코드의 품질과 구조가 점점 무너집니다.
- 스펙과 코드가 점점 맞지 않게 됩니다.
- 나중에는 코드가 틀린 건지, 스펙이 낡은 건지, 처음 요구사항이 애매했던 건지 구분하기 어려워집니다.
그래서 구현 이후 코드 리뷰만으로는 부족하다고 생각했습니다. 결함 있는 스펙이 그대로 구현 에이전트에게 넘어가기 전에, 스펙 자체의 빈틈을 먼저 드러내는 단계가 필요했습니다.
SpecGuard는 이 문제를 줄이기 위해 만든 CLI/코덱스 플러그인입니다. 코드 생성 후 결과물을 검사하는 도구가 아니라, AI에게 구현을 맡기기 전에 스펙을 먼저 검사하는 도구입니다.
제가 의도한 기본 흐름은 이렇습니다.
- 사람이 제품 스펙을 씁니다.
- SpecGuard로 스펙을 검사합니다.
- NOT_READY면 스펙을 보강합니다.
- READY가 되면 Codex/Claude Code 같은 구현 에이전트에게 넘깁니다.
SpecGuard는 주로 이런 종류의 빈틈을 찾습니다.
- 인증/권한 경계가 불명확함
- tenant/user ownership 범위가 빠짐
- idempotency, replay, race condition 처리가 없음
- 만료/철회/상태 전이 규칙이 애매함
- 외부 부작용, webhook, background job 재시도 정책이 없음
- 클라이언트 검증만 믿는 요구사항
결과는 크게 세 가지입니다.
READY: 구현 에이전트에게 넘길 수 있음READY_WITH_WARNINGS: 넘길 수는 있지만 주의할 점이 있음NOT_READY: Critical/Major 문제가 있어 스펙 보강 필요
기본 경로는 --no-llm 휴리스틱 검사입니다. CI나 PR Review에서는 결과가 빠르고 재현 가능한 것이 중요하다고 봤기 때문입니다. OpenAI Platform 또는 Codex 기반 상세 리뷰도 붙일 수 있지만, 현재는 더 깊게 보고 싶을 때 선택적으로 쓰는 보조 경로로 두고 있습니다.
v0.4.0에서 추가한 것
이번 v0.4.0에서는 Codex 앱 플러그인 MVP를 추가했습니다.
pip install spec-guard
specguard --help
codex plugin marketplace add KoreaNirsa/spec-guard --ref main
Codex 앱에서 SpecGuard Plugins 소스를 선택하고 SpecGuard 플러그인을 설치하면, Codex 안에서 SpecGuard 실행을 요청할 수 있습니다. 예를 들어 샘플 스펙을 만든 뒤
specguard example copy specs/your-feature-name --force
Codex에서 해당 폴더를 열고 이렇게 요청할 수 있습니다.
1. @SpecGuard specs/your-feature-name에 대해 SpecGuard를 실행해줘.
2. @SpecGuard specs/your-feature-name 스펙 패키지에 대해 SpecGuard를 실행하고, READY/NOT_READY 상태와 주요 finding을 요약해줘.
3. @SpecGuard specs/your-feature-name에 대해 SpecGuard를 실행해줘. 기본 휴리스틱 검사로 진행하고, 결과 상태와 다음에 해야 할 일을 요약해줘.
플러그인은 SpecGuard 엔진을 새로 구현하지 않습니다. 기존 specguard CLI를 호출하고, 생성된 결과를 읽어서 현재 상태와 다음 행동을 요약합니다.
SpecGuard가 READY 상태를 만들면 구현 에이전트에게 넘길 수 있는 핸드오프 문서를 만들고, 그 다음 Codex가 구현을 시작하는 흐름을 의도하고 있습니다.
PR Review도 지원합니다
GitHub Actions 기반 SpecGuard PR Review 워크플로우도 제공합니다.
PR에서 스펙 패키지가 바뀌었을 때 SpecGuard Review를 실행하고, 결과를 PR에 남기는 흐름입니다. 해당 기능은 OpenAI를 호출하여 진행됩니다.
목표는 “AI가 만든 코드 리뷰”가 아니라 “AI에게 넘기기 전 스펙 입력물 리뷰”입니다.
팀에서 다음 같은 규칙을 두고 싶을 때 사용할 수 있습니다.
- NOT_READY 스펙은 구현으로 넘기지 않기
- Critical/Major finding을 PR에서 먼저 노출하기
- 구현 결과물이 아니라 요구사항 입력 품질을 먼저 관리하기
설치는 CLI에서 specguard actions install-pr-review를 사용하거나, Codex에게 @specguard SpecGuard PR Review 워크플로우를 설정해줘.를 요청하여 설정할 수 있습니다.
다만, 아직 시험기능이기에 자동화 셋팅은 지원하지 않아 GitHub Secret에 아래와 같이 셋팅을 해주어야 합니다.
SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name
현재 상태와 한계
아직 초기 버전이라 모든 스펙을 완벽하게 판별하는 도구는 아닙니다.
다만 AI 코딩을 쓰면서 “스펙이 약해서 구현이 틀어지는 문제”를 겪고 계신 분이라면, 구현 전에 한 번 걸러보는 안전장치로 써볼 수 있을 것 같습니다.
피드백을 받고 싶습니다. 특히 아래가 궁금합니다.
- 어떤 종류의 스펙에서 잘 맞는지
- 어떤 finding이 과하거나 부족한지
- Codex 플러그인 흐름이 실제로 쓸 만한지
- PR Review로 강제하는 게 팀 워크플로우에 맞는지
현재는 베타 버전 이전의, 이제 막 개발이 진행 중인 수준이지만 앞으로 실무에서 충분히 사용할 수 있을만한 프로젝트로 만들어가려 합니다.
관심 있으신 분들의 이슈/PR도 환영합니다. 현재 저장소의 이슈와 PR은 주로 영어로 관리하고 있지만, 한국어로 작성해주셔도 괜찮습니다.