22장 — 디버깅 흐름
CHAPTER 22
디버깅 흐름
막힘 5종류 + 5파일별 펼침
📑 이 챕터에서 다룰 내용

새 21장에서 협업 흐름을 봤습니다. 이제 "본인이 막혔을 때"의 흐름입니다.

1인 운영자가 1년 운영하면 막힘은 "매주 1~3회" 발생합니다. "이 코드가 왜 안 되지" / "이 결정이 맞나" / "어디서 시작하지". 막힘 자체는 정상입니다. 막힘에서 "빠르게 빠져나오는 도구"가 5파일+입니다.

📘 사전 지식 체크 + 이 장의 목적

사전 지식: 새 5~11장 5파일 작성 / 새 9장 BUILD.md + E4 LogOnTable

이 장의 목적: 막힘 종류 5가지 + 각각의 5파일 활용 흐름 + Junho 실전 사례 + 의식 인지

완료 후 결과물: 막힘 평균 해결 시간 60분 → 15분 (-75%)

💡 막힘 = 5파일이 작동하는 시점

5파일을 "막힘이 없을 때 만드는 자료"로 두면 가치가 작습니다. "막힘 시점에 펼치는 도구"로 활용하면 가치가 폭증합니다. 매 막힘이 5파일 + LogOnTable의 환류 입력값입니다.

22-1 막힘 종류 5가지 🔗

막힘은 5 종류로 분리됩니다. 각 종류마다 펼치는 5파일이 다릅니다.

막힘 종류 발생 빈도 펼치는 파일 평균 해결 시간
"이게 뭐였지?" (의도) 매주 1~2회 SPEC.md 5분
"어디 시작?" (순서) 매주 1회 PLAN.md 5분
"검증 의무?" (체크) 매월 2~3회 REVIEW.md 10분
"코드 의무?" (구현) 매주 2~3회 BUILD.md 10분
"이 X (왜)" 매월 1~2회 CLAUDE.md (Claude에게) 15분

5 종류의 공통 패턴

💻 공통 흐름 — 막힘 발생 시 6단계
[공통 흐름]
1. 막힘 발생 (인지)
2. 5 종류 중 무엇인지 5초 분류
3. 펼칠 5파일 결정
4. 5파일 + 해당 섹션 펼침
5. 답 인지 또는 다음 도구 결정
6. LogOnTable 1줄 트레이스 (재발 방지)
22-2 "이게 뭐였지?" — SPEC.md 펼침 🔗

가장 흔한 막힘입니다. "이 기능이 의도가 무엇이었지" / "사용자 정의가 무엇이었지" / "성공 기준이 숫자가 무엇이었지".

펼치는 흐름

💻 SPEC.md 펼침 흐름
[막힘 발생]
"줍줍 두 탭의 원래 의도가 뭐였지?"

[5파일 펼침]
SPEC.md §3 사용자 정의 + §회색지대 결정

[답 인지]
- §3: A (소상공인) + B (개인 복지) — 다른 페르소나 적용
- §회색지대: "줍줍 = 정보 격차 줄임, 신청 보장 X"

[5분 안에 답 완료]

Junho 사례 — Day 17 막힘

💻 Day 17 — 마이페이지 쿼리 결정 막힘
[Day 17 — 마이페이지 쿼리 결정 막힘]
- 사용자 "내가 줍줍한 지원금 총액" 표시 흐름
- 후보 A: SUM (benefits.total_jupjups WHERE jupjups.user_id = X)
- 후보 B: jupjups 테이블 직접 COUNT + 평균 days_taken

[SPEC.md 펼침 — §성공 기준]
- "7일 내 첫 줍줍 60%"
- "90일 누적 사용자 1만 명"

[결정]
- 사용자 핵심 = "내가 무엇 줍줍"
- B (직접 COUNT) → 빠르고 의미 명확
- 5분 결정

[BUILD.md Day 17 트레이스]
"마이페이지 쿼리 B (직접 COUNT) 채택. 사용자 핵심 '내가 무엇'
의식 → 의미 명확. 후보 A 누락."
22-3 "어디 시작?" — PLAN.md 펼침 🔗

"오늘 무엇 시작?" / "이번 주 우선순위?" / "다음 게이트가 언제?".

펼치는 흐름

💻 PLAN.md 펼침 흐름
[막힘 발생]
"오늘 무엇 시작? 어제 Day 14 G1 통과. 다음 무엇?"

[5파일 펼침]
PLAN.md Phase 1.0 후반 + G2 게이트

[답 인지]
- G2 = Day 28 (2주 후)
- Day 15~21: 통합 테스트 + 검수 큐
- Day 22~28: G2 통과 의식

[5분 안에 답 완료]

Junho 사례 — TSV Day 8 막힘

💻 Day 8 — SSOT 인터페이스 작성 시점 막힘
[Day 8 — SSOT 인터페이스 작성 시점 막힘]
- "SSOT 인터페이스를 어디까지 만들어야 G1 통과?"

[PLAN.md 펼침 — Day 14 G1 DoD]
- DoD 1: 페르소나 2개 (STAT + OBSERVER) 본문 출력
- DoD 2: 자동 일관성 테스트 5개 통과
- DoD 3: SSOT 인터페이스 (lib/match_facts.ts) + cache_control

[결정]
- Day 8 SSOT = "5경기 sample 데이터 + 인터페이스"
- Day 14까지 "100% 인터페이스 + 모든 stats 필드" X 의무

[5분 안에 답 + 7일 시간 절약]
22-4 "검증 의무?" — REVIEW.md 펼침 🔗

"이 게이트 통과 조건?" / "검증 항목 12개 중 어떤 게 막힘?" / "PASS 기준?".

펼치는 흐름

💻 REVIEW.md 펼침 흐름
[막힘 발생]
"G1 통과 의식. 12 체크 중 #7 SSOT 일관성의 PASS 기준이 뭐였지?"

[5파일 펼침]
REVIEW.md G1 §#7 SSOT 일관성

[답 인지]
- PASS: 자동 일관성 테스트 5개 모두 통과
- WARN: 1~2건 fail (수정 후 재테스트)
- FAIL: 3건+ fail (G1 통과 X)

[10분 안에 답]

Junho 사례 — 줍줍 G1 통과 직전 막힘

💻 Day 13 — G1 통과 의식 직전 막힘
[Day 13 — G1 통과 의식 직전 막힘]
- LLM 분류 confidence 임계값 결정 막힘
- 0.6 / 0.7 / 0.8 중 어느 것?

[REVIEW.md G1 펼침 — §#5 LLM 분류 신뢰성]
- PASS: 임계값 ≥0.7 + false positive ≤10%

[결정]
- 0.7 채택 (false positive 5%, 누락 5%)
- 0.6 (false positive 30%, 누락 15%) X
- 0.8 (false positive 0%, 누락 40%) X

[10분 안에 답 + LogOnTable 1줄]
22-5 "코드 의무?" — BUILD.md 펼침 🔗

"6개월 전 이 코드 왜 이렇게?" / "비슷한 흐름 이미 만든 적?" / "어제 막힌 그 결정이 뭐였지?".

펼치는 흐름

💻 BUILD.md 펼침 흐름
[막힘 발생]
"6개월 전 LLM 분류 임계값 결정한 트레이스 펼침"

[5파일 펼침]
BUILD.md Day 9 LogOnTable

[답 인지]
- Day 9 트레이스: "임계값 0.7 채택. 0.6 false positive 30%
  / 0.8 누락 40% / 0.7 균형"
- 태그: #분류임계값 #LLM #G1

[10분 안에 답]

Junho 사례 — TSV Day 250 막힘

💻 Day 250 — Phase 2.0 5번째 페르소나 추가 시점
[Day 250 — Phase 2.0 5번째 페르소나 추가 시점]
- "5 페르소나 결합 시 일관성 테스트가 어디까지?"

[BUILD.md 펼침 — 시리즈 14개월 누적 트레이스]
- Day 8   SSOT 인터페이스 결정
- Day 14  G1 통과 — 2 페르소나 일관성 5건
- Day 90  Phase 1.1 — 3 페르소나 일관성 8건
- Day 200 Phase 2 — 4 페르소나 일관성 11건

[결정]
- 5 페르소나 일관성 = 약 14건 (선형 누적)
- 추가 케이스: 5 페르소나 사이 사실 일치 5건 추가

[10분 안에 답 + 시리즈 14개월 누적이 결정에 환류]
22-6 "이 X (왜)" — CLAUDE.md + Claude에게 직접 설명 🔗

가장 깊은 막힘입니다. "왜 이게 안 되지" / "이 흐름의 충돌이 어디" / "이 결정이 맞나".

펼치는 흐름

💻 CLAUDE.md + Claude 협업 흐름
[막힘 발생]
"페르소나 출력에서 환각이 1주 누적. 자동 일관성 테스트는 통과
하는데 외부 사용자가 '틀림' 항의. 어디 막힘?"

[5파일 펼침 + Claude에게 설명]
CLAUDE.md §5 Project-Specific Rules + Claude Code에 막힘 설명

[흐름]
1. CLAUDE.md §5 8 규칙 모두 펼침
2. Claude Code에 "이 흐름에서 환각이 누적. 8 규칙 어디 함정?" 설명
3. Claude가 8 규칙 검토 → 함정 발견
   ([2] SSOT 의무 → 모든 페르소나 단일 인터페이스
   → 그러나 페르소나 5번이 stats 필드 추정 가능 인터페이스 사용 X
   → 환각 누적의 근본 원인)
4. 8 규칙 [2] 보강 → CLAUDE.md §5 갱신

[15분 안에 답 + 6개월 누적 함정 해결]

Junho 사례 — TSV Day 200 막힘

💻 Day 200 Phase 2.0 — 페르소나 환각 누적 발견
[Day 200 Phase 2.0 — 페르소나 환각 누적 발견]
- 자동 일관성 테스트 통과 (사실 일치)
- 그러나 외부 사용자 "통계가 틀린 것 같음" 항의 5건/주

[CLAUDE.md §5 + Claude 협업]
- Claude에게 8 규칙 + 환각 사례 5건 설명
- Claude 발견:
  "§5 [2] SSOT가 '모든 페르소나 단일 인터페이스'인데
  4 페르소나 system prompt에 'xG·점유율 추정 시 가능한 범위'
  표현 잠입. 인터페이스에 없는 stats를 페르소나 본인 추정.
  환각의 근본 원인."

- 해결:
  CLAUDE.md §5 [7] 환각 방지 강화 —
  "system prompt에서 추정 표현 금지,
  stats 필드 NULL 시 '통계 미공개' 명시 의무"

[15분 안에 답 + 6개월 누적 함정 해결]
[효과: 외부 사용자 항의 0건/주 회복]
22-7 의식 — 5파일 → 막힘 작아짐 🔗

5파일이 손에 들리면 막힘 자체가 작아집니다. 다음 4 의식이 누적되면 막힘 평균 해결 시간이 60분 → 15분으로 줄어듭니다.

의식 1: 5파일을 매일 펼침 의식

💡 의식 1 — 매일 펼침

[매일 의식]

  • BUILD.md 1줄 트레이스 의무
  • SPEC.md / PLAN.md / REVIEW.md / CLAUDE.md 매주 1회 펼침
  • 6개월 후 "어디 무엇" 답 5초 안

[효과]: 막힘 시점에 "펼칠 파일 결정" 5초 안 → 5분 검색 이후 답

의식 2: 막힘 종류 5초 분류 의식

💡 의식 2 — 5초 분류

[5 종류 분류 흐름]

  • "이게 뭐였지" → SPEC
  • "어디 시작" → PLAN
  • "검증 의무" → REVIEW
  • "코드 의무" → BUILD
  • "이 X (왜)" → CLAUDE + Claude 협업

[효과]: 막힘 시점에 "펼칠 파일" 5초 결정

의식 3: Claude에게 막힘 설명 의식

💡 의식 3 — Claude 협업

[흐름]: 막힘이 깊으면 Claude Code에 "막힘 흐름 + 펼친 5파일 영역" 설명

Claude가 5파일 + 본인 막힘을 결합해 함정을 발견합니다.

[효과]: 가장 깊은 막힘도 15분 안에 답

의식 4: LogOnTable 환류 의식

💡 의식 4 — LogOnTable 환류

[모든 막힘 종료 후]

  • BUILD.md에 1~3줄 트레이스 의무
  • 태그 박기 (#막힘 #영역)
  • 다음 동일 막힘 발생 시 5초 검색

[6개월 누적]: 약 50~150 막힘 트레이스 → 메타 가설: "이런 막힘이 매월 N회 발생 → 흐름 보강"

22-8 Junho 실전 — TSV 시리즈 약 15개월 누적 막힘 🔗

Junho 본인이 시리즈 약 15개월 운영하면서 누적된 막힘 종합입니다.

시리즈 누적 막힘 통계

💻 15개월 (450일) 누적 통계
[15개월 (450일) 누적]
- 매주 평균 1.5 막힘 = 약 100 막힘
- 평균 해결 시간:
  Day 1~30  : 60분 (5파일 손에 들기 시작)
  Day 31~150: 30분 (5파일 익숙)
  Day 151~450: 15분 (의식 4 누적)

[종류별 빈도]
- "이게 뭐였지": 35건
- "어디 시작":  20건
- "검증 의무":  15건
- "코드 의무":  20건
- "이 X (왜)":  10건

[★ 가장 가치 큰 막힘 5건]
1. Day 8   SSOT 인터페이스 결정
2. Day 14  G1 통과 의식
3. Day 90  Phase 1.1 페르소나 추가
4. Day 200 환각 누적 함정
5. Day 350 5번째 페르소나 결합
🎉 누적의 의미

각 막힘이 SPEC v2/v3 진화 · CLAUDE.md §5 보강 · 5확장 의식 강화의 입력값이 됩니다. 1년+ 누적은 "운영 매뉴얼 폭증"으로 돌아옵니다.

기간 평균 해결 시간 5파일 숙련도
Day 1~30 60분 손에 들기 시작
Day 31~150 30분 5파일 익숙
Day 151~450 15분 의식 4 누적 완성
📌 새 22장 정리

핵심 한 줄: 막힘은 정상. 5파일이 도구. 매 막힘이 5파일 + LogOnTable 환류 입력값.

막힘 5 종류:

  • "이게 뭐였지" → SPEC (5분)
  • "어디 시작" → PLAN (5분)
  • "검증 의무" → REVIEW (10분)
  • "코드 의무" → BUILD (10분)
  • "이 X (왜)" → CLAUDE + Claude 협업 (15분)

공통 흐름:

  1. 막힘 발생 (인지)
  2. 5 종류 5초 분류
  3. 펼칠 5파일 결정
  4. 5파일 + 섹션 펼침
  5. 답 또는 Claude 협업
  6. LogOnTable 트레이스

4 의식:

  1. 5파일 매일 펼침
  2. 막힘 종류 5초 분류
  3. Claude에게 설명
  4. LogOnTable 환류

Junho 시리즈 약 15개월 누적: 100 막힘 · 평균 해결 시간 60분 → 15분 (-75%) · 가치 큰 막힘 5건이 SPEC v2/v3 + CLAUDE §5 진화 입력

다음 장: 새 23장 — Agent Teams

막힘이 "두려움"에서 "5파일 도구로 15분 안에 답하는 사건"으로 바뀌었습니다. 5 종류 분류 · 펼침 흐름 · Claude 협업 · LogOnTable 환류 · 15개월 누적 메타 가설까지.

다음 장에서 Agent Teams를 다룬 후, 새 24장에서 AI 모델 선택 흐름을 펼칩니다.

준비되셨다면, 페이지를 넘기시지요.

💬
🤖 Vibe Coding 도우미
안녕하세요! 새 22장 디버깅 흐름에 대해 궁금한 것이 있으면 물어보세요 😊