본문으로 건너뛰기

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

유피테르

2026.07.27

한 줄 요약

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

시작 전 상태

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

분석 — Skill Maker 6질문 감사

질문

상태

01 언제 / 02 입력 / 05 출력

✅

03 판단 · 04 순서

🔴 F1

06 완료 / 실패

🔴 F2

(공통)

🟡 F3

  • 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로 전사 생성). 캡처 단계에서 두 버전이 어떻게 갈리는지:

단계

v0.2 (Before)

v0.3 (After)

후보 시점

전사 신호로 후보 뽑음 (동일)

동일

프레임 판정

교착 — 채택하려면 프레임을 봐야 하는데 채택 전엔 프레임이 없음

후보 전체를 먼저 이미지로 추출

실제 동작

시각 검사 생략하고 자막 신호만으로 캡처 → 이 강의(터미널·코드 공유형)에서 강사 얼굴/전환 화면을 잘못 캡처할 위험

추출된 이미지를 열어 Claude Code 터미널·코드 화면만 채택, 얼굴 프레임은 폐기

결과

"화면 가리키는 대목만" 요구 미충족

요구 충족 (실행 가능한 순서)

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

실패·막힘·수정

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

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

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

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

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


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

3

함께 이야기해요 3

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

j
jiji2026.07.27

베스트 오브 베스트 유피테르님!
꾸준한 공부 하는 모습이 멋지십니다 😍😁😆
도움되는 글 많이 작성해주셔서 감사합니다!!

자연어회계처리 프로필 이미지

유피테르님 글 읽으면서 한 번에 하나씩만 고쳐야 한다는 원칙을 제대로 배우고 갑니다. 결함이 여러 개 보이면 욕심내서 다 손대고 싶기 마련인데, 가장 핵심적인 F1만 해결하고 나머지는 과감히 다음 패치로 미뤄서 문서에 명시해두신 절제력이 정말 대단하신 것 같아요. 좋은 마음으로 동시에 고치다가 모순이 생겼던 경험을 솔직하게 짚어주셔서 저에게도 큰 경각심이 되었습니다. '무엇이 바뀌었는지 볼 수 있게 남기는 것이 개선'이라는 마지막 회고 문장은 제 작업 방식도 깊이 돌아보게 만드네요. 👍

Giacomo 프로필 이미지
Giacomo2026.07.28

세 가지 결함을 찾고도 가장 중요한 캡처 순서 하나만 고친 선택이 좋았어요. 보지 않은 프레임을 먼저 채택해야 했던 모순을 후보 수집, 전체 프레임 추출, 이미지 확인, 채택·폐기의 순서로 바꾸고, 확인한다는 말도 실제 이미지를 여는 행동으로 구체화해 작은 수정이 무엇을 바꾸는지 또렷하게 남기셨습니다.

다만 이번 전후 비교는 사양 추적이고 실제 캡처 이미지는 아직 확인하지 못했으며, 완료와 실패 기준의 충돌도 남아 있어요. 다음에는 같은 영상으로 수정본만 재실행해 후보 프레임과 채택·폐기 결과를 나란히 남기고, 그 결과를 확인한 뒤 다음 결함 하나로 넘어가시면 한 번에 하나씩 검증하는 원칙이 더 단단해질 것 같습니다.

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

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