본문으로 건너뛰기

[Claude Code + SpecKit] 체크리스트 12/12 통과 뒤에 숨어 있던 결함 21건 — AI결과물을 AI로 검수한 실측 기록

황금호랑이

2026.08.05

[Claude Code + SpecKit] 체크리스트 12/12 통과 뒤에 숨어 있던 결함 21건 — AI결과물을 AI로 검수한 실측 기록 본문 이미지

[Claude Code + SpecKit] 체크리스트 12/12 통과 뒤에 숨어 있던 결함 21건 — AI 결과물을 AI로 검수한 실측 기록

한줄 요약

AI가 쓴 스펙을 "품질 체크리스트 12개 항목 전항목 통과"로 넘긴 뒤, SpecKit의 검수 명령(analyze·converge)을 돌렸더니 **결함 21건(CRITICAL 2건 포함)**이 나왔습니다. 그중 하나는 문서에서 지운 위반이 구현 코드에서 되살아난 것이라, 문서만 봐서는 원리적으로 찾을 수 없는 유형이었습니다.

이런 분들께 도움돼요

  • AI에게 개발을 맡기는데, 결과물이 맞는지 확인할 방법이 없어 눈으로 읽고 넘기는 분

  • 스펙 문서는 쓰는데 그게 실제 코드와 맞는지 확인해 본 적 없는 분

  • SpecKit을 도입했지만 specify·plan·tasks만 쓰고 검수 명령은 안 써본 분


소개: 시도하고자 했던 것과 그 이유

문제 상황 (Before)

AI에게 기능 개발을 맡기면 결과물이 항상 그럴듯합니다. 스펙 문서는 문장이 매끄럽고, 태스크 목록은 번호가 잘 매겨져 있고, 코드는 돌아갑니다.

문제는 그럴듯함과 정확함을 구분할 방법이 없다는 것이었습니다. 사람이 눈으로 읽는 리뷰는

  • 문장 품질이 좋으면 통과시키고

  • 요구사항 12개에 태스크가 다 붙어 있으면 "커버됐다"고 보고

  • 문서에 "고쳤음"이라고 적혀 있으면 고쳐진 걸로 믿습니다

세 가지 모두 참이 아닐 수 있는데도 확인할 도구가 없었습니다.

시작하게 된 계기

MyTok(자체 호스팅 메신저)의 013-design-theme-templates 피처 — "설정에서 골드·오션·로즈 3가지 디자인 테마를 고르면 전체 UI 색상이 바뀐다" — 를 만들면서, 스펙 작성부터 구현까지 전부 AI에게 맡겨 봤습니다.

그리고 구현이 끝난 상태에서 SpecKit의 검수 명령을 처음부터 순서대로 돌려봤습니다. "이미 다 됐는데 검수가 뭘 더 찾을까" 싶었는데, 결과가 예상과 완전히 달랐습니다.


진행 방법: 어떤 도구를 사용했고, 어떻게 활용했나요?

사용한 도구

  • 도구: Claude Code (터미널에서 대화하며 개발하는 AI)

  • 모델: Claude Opus 5 (reasoning effort: high)

  • 방법론: SpecKit — 기능 단위로 스펙을 쪼개서 관리하는 체계

  • 대상: MyTok specs/013-design-theme-templates

  • 소요: 2026-07-31 16:19 ~ 16:46 (약 27분)

  1. Speckit은 깃허브에서 공식 제공하는 스펙주도 개발 방법론을 구현해주는 툴킷입니다.
    비개발자도 고급 개발로 만들어주는 툴킷이라 소개드리고 싶습니다.

  1. MyTok은 텔레그램/디스코드/슬랙 등 제3자 서비스를 거치지 않고 직접 로컬에 설치된 Hermes,Openclaw,Clawcode와 대화할수 있게 해줍니다.
    에이전트와 대화한 내용은 로컬 DB에 저장 관리되고 파일/사진은 원하는 저장소로 저장됩니다.
    내 로컬에 있는 AI를 일할수 있게 해주는 에이전틱 메신저입니다.
    Speck-kit 기반으로 프로그램을 개발하고 있고 개발 과정을 지식으로 관리하기 위해 구조를 세팅하고 있습니다.

한국어 문자 메시지 앱의 스크린샷

SpecKit에는 문서를 만드는 명령(specify·plan·tasks) 말고 검수하는 명령이 따로 있습니다. 이번에 쓴 건 이 넷입니다.

명령

무엇을 비교하나

시점

checklist

스펙 자체의 형식 품질

계획 전

clarify

스펙의 모호한 부분

계획 전

analyze

문서 ↔ 문서 (spec·plan·tasks 끼리)

구현 전

converge

문서 ↔ 코드

구현 후

여기가 핵심입니다. 넷은 비교 대상이 서로 다릅니다. 앞의 것이 통과했다고 뒤의 것도 통과하는 게 아니었습니다.


AI와 협업한 과정

1단계. 품질 체크리스트 — 전항목 통과

상황: 스펙 작성 후 품질을 확인했습니다.

결과:

Content Quality        4/4 ✅   (구현 세부 없음, 사용자 가치 중심, 비기술자도 읽힘…)
Requirement Complete   8/8 ✅   (모호 표시 없음, 테스트 가능, 측정 가능한 성공기준…)
Feature Readiness      4/4 ✅

→ "모든 항목 통과. /speckit-plan 또는 /speckit-tasks로 진행 가능"

느낀 점: 여기서 멈췄으면 문제 10건을 안고 구현에 들어갔을 겁니다. 체크리스트는 "스펙이 스펙답게 쓰였는가"만 봅니다. 문서들끼리 앞뒤가 맞는지는 검사 항목에 없습니다.


2단계. analyze — 문서끼리 대조하니 10건

이렇게 요청했어요:

/speckit-analyze specs/013-design-theme-templates

결과: 심각도별로 10건. 그중 넷이 결정적이었습니다.

ID

심각도

무엇을 찾았나

C1

CRITICAL

디자인 테마와 무관한 기존 버그 수정이 태스크에 섞여 있음. 프로젝트 헌법의 "요청 범위 밖 코드를 개선 목적으로 건드리지 말 것"을 위반

G1

HIGH

"전체 UI 색상이 즉시 반영된다"는 요구사항인데, 설정 화면에 골드색이 8곳 하드코딩돼 있고 이를 다루는 태스크가 없음 → 오션/로즈를 골라도 그 부분만 골드로 남음

U1

HIGH

색상표를 13개 항목으로 정의해놓고 실제 값은 4개만 제시

I1

HIGH

고대비 모드 우선 처리가 두 가지 방식으로 갈림 — 기존 코드베이스는 CSS 방식인데 새 태스크는 JS 방식

"오!" 했던 지표:

커버리지: 명목 100% / 실질 67%

"모든 요구사항에 태스크가 있다"는 참이었습니다. 12개 요구사항에 전부 담당 태스크가 붙어 있었으니까요. 그런데 그중 4개는 부분 커버였습니다. 눈으로 표만 보면 100%로 보이는 걸, 기계가 내용까지 대조해서 67%로 깎았습니다.


3단계. 수정 후 재점검 — 10건 전부 해소, 그런데 신규 7건

이렇게 요청했어요:

/speckit-analyze specs/013-design-theme-templates 수정된 내용 점검하라

결과: 1차 지적 10건이 전건 해소 확인. 그런데 새로 7건이 나왔고, 그중 하나가 이 사례에서 가장 인상적이었습니다.

I3 (HIGH) — 처방이 대상과 맞지 않는다

로그인 화면 그라데이션의 #1e1b4b는 골드가 아니라 인디고(남색) 다. 지시대로 "포인트 색상 변수로 치환"하면 골드 테마 로그인 화면이 황금색으로 바뀌는 시각 회귀가 발생한다.

1차 지적("하드코딩된 색을 변수로 바꿔라")은 옳았습니다. 그런데 처방이 틀렸습니다. 그 색은 애초에 골드가 아니었으니까요.

시키는 대로 고쳤으면 화면이 깨졌을 겁니다.

이 발견이 문서에 결정으로 남았습니다 — research.md의 D4:

.login-screen의 #1e1b4b는 골드가 아니라 인디고/네이비다. 이를 var(--color-primary)로 치환하면 골드 테마 로그인 화면이 황금색으로 바뀌는 시각 회귀가 발생하므로, 전용 변수 --login-glow를 신설한다. 골드는 #1e1b4b 현행값 그대로 유지.


4단계. converge — 문서가 아니라 코드를 봤더니

이렇게 요청했어요:

/speckit-converge specs/013-design-theme-templates

결과: 4건. 첫 번째가 이 사례 전체에서 가장 중요합니다.

F1 (CRITICAL) — 지웠던 위반이 코드에서 되살아났다

1차 analyze에서 헌법 위반(C1)으로 판정해 태스크 목록에서 제거했던 바로 그 수정이, 구현 커밋에 다시 포함돼 있었다.

문서에서는 분명히 지웠습니다. 그런데 구현하는 세션에서 되살아났습니다.

이건 analyze(문서↔문서)로는 원리적으로 못 잡습니다. 문서에는 없으니까요. converge(문서↔코드)라는 별도의 층이 있어야만 보입니다.

나머지 3건도 눈으로는 못 잡을 것들이었습니다.

  • F2: 테마 미리보기 칩이 스펙은 "배경색+포인트색 2색"인데 구현은 1색만

  • F3: 오션·로즈 라이트 모드에서만 로그인 화면이 다크 값을 상속받아 짙게 나옴

  • F4: 문서에 있는 변수가 코드엔 없고 값이 직접 박혀 있음(동작은 정상, 문서-코드 불일치)


인상적이었던 순간

검수기가 "8곳"을 실제로 세어봤을 때입니다.

1차에서 "골드 리터럴이 8곳 하드코딩돼 있다"고 지적했는데, 재점검에서 그게 정말 8곳인지 파일의 40·41·42·43·51·52·131·149번 줄을 짚어 확인했습니다.

"고쳤다고 적혀 있으니 고쳐졌다"가 아니라 "세어봤더니 맞다" 였습니다. 검수가 낭독이 되지 않으려면 이 차이가 필요합니다.

막혔던 순간과 해결

문제: 1차 지적을 다 반영했는데 신규 7건이 또 나왔습니다. "끝이 없는 건가" 싶었습니다.

해결: 끝이 있었습니다 — converge는 반복할수록 0에 수렴하도록 설계돼 있습니다(이름 그대로 converge = 수렴). 0건이면 태스크 파일을 아예 건드리지 않고 "✅ Converged"만 보고합니다.

그리고 수정은 새 표면을 만든다는 걸 받아들이니 오히려 편해졌습니다. 1차 해소 10/10이 안심의 근거가 아니라, 그냥 한 바퀴 돈 것이었습니다.


결과와 배운 점

Before vs After

항목

Before (검수 전)

After (검수 후)

커버리지(실질)

67% (12개 중 4개 부분 커버)

100%

모호한 항목

2건

0건

헌법 위반

1건 (문서)

0건 (문서) / 1건 코드에서 신규 발견

하드코딩된 색상

8곳

0곳

태스크 수

21개

19개 (범위 밖 1건 제거, 중복 1건 통합)

발견한 결함 총계

—

21건 (1차 10 + 재점검 7 + 코드 4)

소요 시간

—

약 27분

결과물

research.md에 결정 5개(D1~D5) 가 근거와 함께 남았습니다. 이게 진짜 산출물입니다.

  • D1 고대비 우선은 기존 CSS 관례로 통일 (JS 방식 폐기)

  • D2 테마 블록은 기존 블록 이후에 배치 (소스 순서 보장)

  • D3 반투명 골드 8곳 → 알파 20% 유지하는 파생 변수. 골드 20% = 기존 값과 동일함을 검증

  • D4 로그인 그라데이션은 전용 변수 신설 (골드값 그대로 유지 → 회귀 차단)

  • D5 body 배경은 변수가 아니라 속성 → 별도 셀렉터 필요

여섯 달 뒤에 "왜 이렇게 했지?"라고 물으면 답이 파일에 있습니다.


SpecKit Blueprint의 8대 문제에 실측 결함을 매핑하면

SpecKit Blueprint는 AI 개발의 문제를 축 1(모델 자체) 4가지 + 축 2(워크플로) 4가지로 정리합니다. 이번에 나온 결함을 거기에 얹어봤습니다.

Blueprint의 문제

이번에 실제로 나온 결함

잡은 명령

지시 무시 — 명시적 지시보다 '일반적으로 좋은 패턴'을 우선

C1: 헌법이 "범위 밖 코드 건드리지 말 것"을 명시했는데도 "이왕 하는 김에" 인접 버그 수정을 섞음

analyze

평균수렴 — 도메인 고유 규칙 대신 흔한 관행으로 되돌아감

I1: 이 프로젝트는 CSS :not() 관례를 쓰는데, AI는 더 흔한 JS 클래스 제거 방식을 택함. 코드는 작동하지만 프로젝트 고유 관례에서 이탈

analyze

할루시네이션 — 사실과 다른 전제를 확신에 차서 생성

I3: 인디고색(#1e1b4b)을 골드로 간주하고 처방을 씀

analyze 재점검

맥락 오염 — 초반 지시가 후반부에 희석

G1·U1: 초반 요구사항("전체 UI 색상 즉시 반영", "팔레트 13개 변수")이 태스크·값 단계에서 부분만 전개됨

analyze

지시 무시의 재발

F1: 문서에서 제거한 위반이 구현 세션에서 코드로 재유입

converge만 가능

여기서 이번 실측이 Blueprint에 보태는 게 하나 있습니다.

Blueprint는 "스펙을 기능 단위로 쪼개면 축 1의 문제가 완화된다"고 말합니다. 맞습니다. 그런데 스펙을 쓰는 것도 AI입니다. 그래서 축 1의 문제가 스펙 안에서 다시 발생합니다.

평균수렴(Gravity)  ←→  스펙으로 주입한 우리 규칙(Thrust)
                          ↑
                  그런데 이 스펙도 AI가 쓴다
                          ↓
                  스펙 자체가 평균으로 끌려간다  ← I1 이 정확히 이 사례

I1은 그 실물입니다. AI가 쓴 스펙이 프로젝트 고유 관례를 버리고 일반 관행을 택했고, 그걸 잡은 건 스펙이 아니라 검수 명령이었습니다.

그리고 F1은 한 발 더 나갑니다. Blueprint는 "지시 무시 → 스펙으로 고정해 매 세션 재주입"으로 해결한다고 하는데, 스펙에 고정해도 구현 단계에서 새어 나왔습니다. 그래서 문서↔코드를 보는 층이 따로 필요합니다.


배운 점과 나만의 꿀팁

효과적이었던 것

  1. "통과"의 뜻을 명령마다 다르게 읽기 — checklist 통과는 "스펙이 스펙답다"이지 "스펙이 맞다"가 아닙니다. 셋의 비교 대상이 다르다는 걸 알고 나서 전부 돌리게 됐습니다.

  2. 구현이 끝난 뒤에도 converge를 돌리기 — "이미 다 됐는데 뭘"이라고 생각했던 단계에서 CRITICAL이 나왔습니다.

  3. 검수 결과를 "결정"으로 문서에 남기기 — 지적을 고치고 끝내지 않고 research.md에 D1~D5로 남겼더니, 나중에 "왜 이렇게 했지"에 답이 됩니다.

  4. 수정 후 반드시 재점검 — 1차 10건을 고치니 신규 7건이 나왔습니다. 수정은 새 표면을 만듭니다.

  5. 읽기 전용 계약이 있는 명령을 믿고 쓰기 — analyze는 파일을 절대 수정하지 않습니다. 그래서 부담 없이 여러 번 돌릴 수 있었습니다.

이렇게 하면 안 돼요 (주의사항)

  1. "지적을 반영했다"를 "올바르게 반영했다"로 읽지 마세요. I3이 그 사례입니다 — 지적은 옳았는데 처방이 틀려서, 그대로 따랐으면 화면이 깨졌습니다.

  2. 체크리스트 전항목 통과에서 멈추지 마세요. 12/12 통과한 문서에서 결함 10건이 나왔습니다.

  3. 문서만 검수하고 끝내지 마세요. 문서에서 지운 게 코드로 돌아옵니다. 이건 문서 대조로는 원리적으로 못 잡습니다.

  4. "모든 요구사항에 태스크가 있다"를 커버리지로 착각하지 마세요. 명목 100%가 실질 67%였습니다.

과정 중 시행착오

처음엔 analyze 한 번이면 충분하다고 생각했습니다. 10건 지적받고, 고치고, 끝. 그런데 재점검에서 7건이 더 나왔고, converge에서 4건이 더 나왔습니다.

한 번에 끝나는 검수는 없다는 걸 배웠습니다. 대신 converge는 반복할수록 0에 수렴하니, 끝이 없는 건 아닙니다.


앞으로의 계획

다음 단계

  • Phase 6(converge가 추가한 T020~T023) 완료 후 재수렴해서 0건 확인

  • 다음 피처는 구현 전에 analyze를 돌려서, 이번처럼 뒤늦게 잡는 일 줄이기

  • converge를 커밋 전 자동 실행으로 연결

다른 업무에 적용한다면?

이 구조는 코드가 아니어도 씁니다. "만든 것"과 "만들기로 한 것"이 따로 있는 모든 일에 적용됩니다.

  • 기획서 ↔ 실제 산출물 대조

  • 회의록의 결정사항 ↔ 실행된 내용 대조

  • 제안서의 약속 ↔ 납품물 대조

핵심은 비교 대상을 명시적으로 나누는 것입니다. 문서끼리 볼 때와 문서↔실물을 볼 때는 잡히는 게 다릅니다.

도움이 필요한 부분

converge가 코드를 지우지는 않습니다(추가만 합니다). 그래서 F1 같은 CRITICAL이 나와도 사람이 판단해서 처리해야 합니다. 이걸 자동화한 분이 계시면 방법을 듣고 싶습니다.


재사용 가능한 프롬프트

프롬프트 1: 구현 전 문서 정합성 검수

[스펙 폴더 경로]의 요구사항 문서·계획 문서·태스크 목록을 서로 대조해서 아래를 찾아 심각도와 함께 표로 정리해줘. 파일은 수정하지 마.

  1. 중복 — 같은 내용이 두 군데 있는가

  2. 모호 — "적절히", "빠르게" 같이 측정 기준 없는 표현

  3. 미명세 — 이름만 있고 값·기준이 없는 항목

  4. 커버리지 공백 — 요구사항 중 담당 태스크가 없거나 부분만 있는 것

  5. 불일치 — 같은 개념을 다르게 부르거나, 문서끼리 모순되는 것

마지막에 "명목 커버리지"와 "실질 커버리지"를 나눠서 알려줘.

💡 [스펙 폴더 경로]만 바꿔 쓰세요. 5번을 나눠 묻는 게 핵심입니다.

프롬프트 2: 구현 후 문서 ↔ 코드 대조

[스펙 폴더 경로]의 문서와 실제 코드의 현재 상태를 대조해줘. 문서끼리가 아니라 문서와 코드를 비교하는 게 목적이야.

아래 네 가지로 분류해줘.

  • missing — 문서에 있는데 코드에 없음

  • partial — 코드에 있는데 스펙의 일부만 충족

  • contradicts — 코드가 문서와 반대로 동작

  • unrequested — 코드에 있는데 어떤 요구사항에도 추적되지 않음

특히 unrequested를 빠뜨리지 마. 문서에서 제거했던 항목이 구현 과정에서 다시 들어왔을 수 있어.

💡 마지막 문단이 이번 사례에서 CRITICAL을 잡은 지점입니다.

프롬프트 3: 검수 결과를 "결정"으로 남기기

방금 지적한 항목들을 고치되, 각 수정을 왜 그렇게 했는지 결정 기록으로 research.md에 남겨줘. 형식은 이렇게:

D1 — [결정 이름] ([어떤 지적을 해결하는지]): [택한 방식]과 [택하지 않은 방식], 그 이유.

그리고 기존 동작이 바뀌지 않는지 값으로 검증해줘. 바뀌면 안 되는 곳은 수정 전후 값이 같아야 해.

💡 마지막 문단이 "고쳤는데 다른 게 깨지는" 사고를 막습니다.


도움 받은 글

참고한 자료

  • SpecKit AI Engineering Blueprint — AI 개발 문제를 축 1(모델 한계 4종)·축 2(워크플로 한계 4종)로 정리한 문서. 이 사례의 분석 틀로 사용

  • GitHub Spec Kit — 스펙 기반 개발 방법론

  • MyTok 프로젝트 헌법(constitution.md) — 이번에 C1·F1이 위반으로 잡힌 근거


작성일: 2026-08-05 작성자: (닉네임 기입) 대상: 지피터스 23기 · AI 결과물 검수 스터디

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.08.05

명목 커버리지 100%인 문서에서 실질 67%가 나온다는 게 이 글의 핵심이라고 느꼈어요. "12개 요구사항에 전부 태스크가 붙어 있다"는 참이지만 그중 넷이 부분 커버였다는 걸 기계가 내용까지 대조해서 잡아냈다는 게 인상적이었습니다.

F1 — 문서에서 지운 위반이 구현 단계에서 코드로 되살아난 것 — 이 부분이 가장 날카로웠어요. analyze(문서↔문서)로는 원리적으로 못 잡고 converge(문서↔코드) 층이 따로 있어야만 보인다는 구분, 그대로 가져다 쓸 수 있을 것 같습니다.

결정 5개(D1~D5)를 research.md에 남긴 것도 좋았어요. 지적을 고치고 끝내는 게 아니라 "왜 그렇게 했지"에 나중에 답이 되는 파일을 만든 거잖아요. 27분에 결함 21건, 그리고 결정 기록까지 — 산출물이 두 개네요.

고롱고롱… 이런 실측 기록 보면 괜히 뿌듯해져요 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기