AI가 추측하지 않게
— diagnose · Spec Kit, 두 도구의 구현을 깊게 뜯어본다

diagnose · Spec Kit — "쓰면 이렇게 됩니다"가 아니라 "이런 프롬프트·룰·코드라서 그 결과가 나옵니다"를 실제 소스로 확인

"이 버그 고쳐줘" → AI가 재현도 안 해보고 코드 세 군데를 바꾼다.
됐는지 물으면 "고친 것 같아요." …정말?

우리가 매일 겪는 장면. AI는 똑똑한데, 빈칸을 만나면 그럴듯하게 추측하고 밀어붙인다.

관통하는 한 가지: "추측 대신 구조·근거"

기본 상태의 AI는 빈칸을 만나면 그럴듯하게 추측한다. 두 도구는 추측이 들어갈 자리에 각기 다른 장치를 끼운다 — 같은 원리, 다른 구현.

각 도구를 같은 틀로 봅니다: 막는 추측 → 실제 구현 한 조각 → 왜 통하나 → 내 직군 적용.

구현 해부: SKILL.md가 "신호부터"를 강제하는 문구

🚫 막는 추측: "에러 보니 여기겠지" → 재현 없이 바로 수정

diagnose엔 코드가 거의 없다 — 구현체는 SKILL.md(프롬프트/룰). 그 텍스트가 어떻게 행동을 바꾸나. 실제 원문(skills/engineering/diagnose/SKILL.md):

# Phase 1 — Build a feedback loop  (원문 인용)
"**This is the skill.** Everything else is mechanical.
 ... no amount of staring at code will save you."
"Spend disproportionate effort here. Be aggressive.
 Be creative. Refuse to give up."
"Do not proceed to Phase 2 until you have a loop you believe in."

👉 이 코드 한 마디로: "믿을 만한 재현 루프가 없으면 다음 단계 금지."

출처: mattpocock/skills — skills/engineering/diagnose/SKILL.md (Phase 1 원문)

6단계 규율 + "피드백 루프 만드는 10가지 수"

각 단계엔 관문이 있다(추측-수정엔 없는 "넘어가도 되나?" 체크). "재현 안 됨"은 끝이 아니라 시작 — diagnose는 10가지를 순서대로 시도하라 한다:

직군 매핑: SRE=트레이스 재생·차분 · FE=헤드리스 브라우저 · BE=실패 테스트·bisect · Mobile=차분·HITL.

출처: diagnose SKILL.md — "6 Phases" + "10 ways to construct a feedback loop"

구현 해부: 10번째 수단이 실제 .sh 파일이다

"사람이 클릭해야만 재현되는 버그"조차 구조화하려고, diagnose는 bash 템플릿을 번들로 넣어둔다(scripts/hitl-loop.template.sh). 실제 코드:

step() {    # 지시를 띄우고 Enter를 기다림
  printf '\n>>> %s\n' "$1"; read -r -p "[Enter when done] " _
}
capture() { # 질문을 띄우고 사람 답을 변수에 담음
  local var="$1" q="$2" a; printf '\n>>> %s\n' "$q"
  read -r -p "> " a; printf -v "$var" '%s' "$a"
}
step "http://localhost:3000 열고 로그인하세요."
capture ERRORED "'Export' 클릭 → 에러 났나요? (y/n)"
# 끝에 ERRORED=... 를 출력 → 에이전트가 파싱해 루프에 피드백

👉 이 코드 한 마디로: 사람의 클릭·확인을 read로 받아 변수에 담고, KEY=VALUE로 뱉어 에이전트가 읽게 한다.

나머지 단계도 같은 결: 가설 3~5개(반증 예측) · 한 변수씩 계측 + [DEBUG-a4f2] 태그 · 회귀는 올바른 seam에만("seam 없음=발견"). 전부 SKILL.md에 글로 박힌 룰.

🧪 실제로 난 버그를 /diagnose로 잡은 과정

이 발표 자료 만들다 진짜 난 버그. 디버깅은 전 직군 매일 작업이라 실습 대상으로 골랐다. 가짜 데모가 아니라 이 세션에서 실제로 일어난 일.

상황 — 카드 삭제 스크립트가 HTML을 깨뜨림

week7-topic-candidates.html에서 카드를 지우는 파이썬 스크립트를 돌렸다. 로직: "<div class="card">부터 첫 단독 </div>까지를 한 카드로 보고 삭제." 돌린 뒤 페이지 레이아웃이 깨졌다.

출처: 실제 진단 대상 ~/Desktop/study/week7-topic-candidates.html · 방법론 diagnose SKILL.md — Phase 1

구현 해부: /speckit-specify는 사실 "마크다운 프롬프트"

🚫 막는 추측: "대충 말하면 알아서 만들겠지" → AI가 요구사항을 멋대로 채움

"명세→코드"가 마법 같지만, 커맨드 정의(templates/commands/specify.md)를 열면 그냥 구조화된 프롬프트 파일이다:

# 설치본: .claude/skills/speckit-specify/SKILL.md (실측)
---
name: "speckit-specify"
description: "Create or update the feature specification..."
metadata:
  source: "templates/commands/specify.md"   # ← 빌드 원본
user-invocable: true
---
## User Input
```text
$ARGUMENTS              # ← 사용자가 친 기능 설명이 여기로
```
## Pre-Execution Checks  # extensions.yml 훅 검사 → Outline → ...

👉 핵심: $ARGUMENTS로 내 말을 받아 정해진 지시문에 끼우고, Pre-Execution Checks로 훅을 검사한 뒤 단계를 진행한다.

출처: github/spec-kit — templates/commands/specify.md · 설치본 .claude/skills/speckit-specify/SKILL.md (직접 설치 실측)

무엇(spec)과 어떻게(plan)를 분리하는 이유

specify는 요구사항·유저스토리·엣지케이스(무엇)만, plan은 스택·데이터모델·API 계약(어떻게)만. 섞으면 AI가 "어떻게"를 추측하며 "무엇"을 흐린다.

출처: github/spec-kit · GitHub Blog — Spec-driven development with AI

설치 & 한 번에 보는 사용 흐름

diagnose — 설치 1줄, 호출 1줄

npx skills@latest add mattpocock/skills   # 130k★·MIT, 구독 안에서 무료
# → .claude/skills/ 에 diagnose 등 스킬 설치됨. 추가 API 키·과금 없음

Spec Kit — CLI 설치 후 슬래시 커맨드로

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify init my-project --integration claude   # 현재 docs는 --integration (구 --ai)
# 현재 폴더에 바로:  specify init .   또는   specify init --here

출처: mattpocock/skills · github/spec-kit (설치·슬래시 커맨드 현행 docs, 2026-06 확인)

두 도구가 가르치는 한 가지

좋은 AI 도구는 마법이 아니다.
사람의 방법론을, AI가 매번 따르도록 구조로 굳힌 것이다.

감사합니다 🙏

질문 / 각자의 "추측이 만든 사고" 공유

참고 자료

• mattpocock/skills — diagnose (skills/engineering/diagnose/SKILL.md)
• github/spec-kit (공식 레포)
• GitHub Blog — Spec-driven development with AI