세 개를 한꺼번에 고쳤더니 버그가 숨었습니다 — 이번엔 하나만 고쳤습니다

한 줄 요약

지난 사례글에서 만든 강의노트 Skill(v0.2)을 Skill Maker 구조로 다시 감사했더니, 잘 되는 경로가 아니라 판정 로직의 순서가 거꾸로 박혀 있었습니다.
정본이 말한 "한 번에 하나의 작은 patch" 원칙대로, 발견한 결함 3개 중 가장 큰 하나(F1)만 고치고 나머지는 일부러 남겼습니다.

시작 전 상태

기본과제에서 첫 실행이 막히자 v0.2로 세 곳을 한꺼번에 고쳤습니다(전제조건 절 신설 + 소스 사다리 + 실패 분리). 그때는 "많이 고쳤으니 좋아졌겠지"라고 생각했습니다.
확장과제 감사에서 그 생각이 깨졌습니다. 세 개를 한꺼번에 고치는 과정에서 오히려 새 모순이 하나 생겨 있었습니다.

분석 — Skill Maker 6질문 감사

• F1 — 캡처 판정 순서가 거꾸로. 03은 "프레임을 봐야 채택 결정", 절차 5는 "채택된 것만 프레임 추출". 안 뽑은 프레임은 볼 수 없으므로 순서가 성립 불가. 게다가 "확인"을 어떻게 하는지(이미지로 열어 눈으로 봄) 메커니즘이 빠져 있었음.

• F2 — 완료 기준과 실패 처리가 충돌. 완료는 "캡처 ≥1장" 필수, 실패 처리는 "0장도 성공". → v0.2에서 실패 표를 새로 넣을 때 기존 완료 체크리스트와 대조를 안 해서 생긴 모순. 세 개를 한꺼번에 고친 대가.

• F3 — 완료 기준이 주관적 ("노트만으로 이해되는가").

내가 직접 내린 판단

고칠 문제: F1 하나. 이유:

• 사용자(나)가 이 Skill에 가장 원한 기능이 "강사가 화면 가리키는 대목만 캡처"인데, F1이 바로 그 기능을 실행 불가로 만드는 결함이라 임팩트가 가장 크다.

• F2·F3은 실재하지만, 한 patch에 몰아넣으면 v0.2의 실수(세 개 동시 수정)를 그대로 반복하게 된다. 그래서 SKILL.md 상단에 "다음 patch에서 F2·F3"라고 명시하고 남겼다.

만든 것 — patch 하나 (v0.2 → v0.3)

Before (v0.2)

03-2 확인: 후보 타임스탬프의 실제 프레임을 확인해 … 있을 때만 채택
절차 5: 2단계 판정 → 채택분만 프레임 추출

After (v0.3)

03: 후보 시점 수집 → 후보 '전체' 프레임 추출(ffmpeg) → 이미지 시각 검사(vision) → 채택/폐기
절차 5: 후보 시점 수집 → 후보 전체 프레임 추출 → 이미지 시각 검사 → 채택분만 본문 사용

바뀐 것: (1) 순서를 뒤집음 — 추출이 판정보다 먼저. (2) "확인"의 메커니즘을 명시 — ffmpeg로 이미지 추출 후 실제로 열어서 봄.

증거 — 같은 입력 Before/After (스펙 추적)

같은 입력: 기본과제에서 쓴 그 영상 (17:51, 공식 챕터 12개, 자막 0건 → ASR로 전사 생성). 캡처 단계에서 두 버전이 어떻게 갈리는지:

실제 파이프라인 재실행은 하지 않았습니다(not_checked: live_rerun). 미디어 스트림 차단이 아직 미해결이라, 이번 비교는 스펙 레벨 추적입니다 — 정본 p.37이 허용하는 "실패 기록/Before-After" 범위.

실패·막힘·수정

가장 뜨끔했던 건 F2가 내 손으로 만든 모순이라는 점입니다. v0.2에서 실패 표를 "좋은 마음으로" 추가했는데, 기존 완료 체크리스트와 안 맞는 걸 못 봤습니다. 여러 개를 한 번에 고치면 이런 게 숨습니다.

회고 — 잘된 점 / 막힌 점 / 다음 한 가지

• 잘된 점: 이번엔 3개를 찾고도 1개만 고쳤고, 나머지는 버전 헤더에 "미룸"으로 남겨 추적 가능하게 했다. 규율이 문서에 박혔다.

• 막힌 점: Before/After가 스펙 추적까지만. 실제 캡처 이미지를 눈으로 비교하진 못했다.

• 다음 한 가지: venv로 미디어 차단을 풀고 같은 영상을 재실행해, F1 수정이 실제 캡처 결과를 바꾸는지 이미지로 확인한다. 그다음 patch는 F2 하나.

이번 주에 배운 한 줄: 개선은 "많이 고치는 것"이 아니라 "한 번에 하나를 고치고, 그게 뭘 바꿨는지 볼 수 있게 남기는 것"이었습니다.