강의에서 들은 개념을 “판정 질문”으로 바꿔 제 유튜브 스킬에 대봤습니다 — 구멍 4개가 나왔습니다

에이전트하네스 스터디 2주차에서 지아코모님의 지식공유를 듣고, 다음 날 그 개념들을 체크리스트(렌즈)로 정리해 제가 쓰던 유튜브 요약 스킬에 대봤습니다. 이미 평가 문서까지 갖춰둔 스킬이었는데도 구멍이 4개 나왔고, 하루 만에 스킬을 둘로 나누고 구멍을 메우는 데까지 갔습니다. 검증 테스트 181개가 나누기 전후 동일하게 통과했고, 자동 교정 56건은 전부 근거를 확인했습니다.

이런 분께 추천

• 에이전트 스킬(또는 자동화 절차 문서)을 만들어 쓰다가, 자꾸 커져서 “이거 쪼개야 하나?” 고민 중인 분

• 강의·지식공유에서 좋은 개념을 들었는데 “그래서 내 것에 어떻게 적용하지?”에서 멈춰본 분

• 반대로, 스킬을 아직 안 만들어봤다면 이 글은 한 박자 이릅니다 — 만들고 커진 다음에 다시 만나요

유튜브 스킬의 문제점

저는 유튜브 강의 영상을 요약 아티클로 만들어주는 스킬(youtube-recap)을 몇 주째 키워왔습니다. 처음엔 “자막 받아서 요약”이 전부였는데, 쓰다 보니 요구가 계속 붙었습니다. 고유명사가 깨지니 교정 단계가 붙고, 요약이 미덥지 않으니 검증 단계가 붙고, 화면에만 나오는 내용이 빠지니 캡처 단계가 붙고. 결국 절차 문서 하나가 181줄이 됐습니다.

youtube-recap (스킬 1개에 전부)
├── 1  자막 확보
├── 2  자막 정제
├── 3  구간 나누고 요약
├── 4  md 조립(렌더)
├── 4b 고유명사 교정
├── 4c 전사물 보관
├── 5  보조 자료 교차검증
├── 6  자료 기반 내용 검증
├── 7  화면 캡처            ← 여기부터는 하는 일이 결이 다른데
└── 8  타임스탬프·캡처 검증  ← 같은 문서에 계속 붙어 있었습니다

문제는 “너무 길다”가 아니었습니다. 쪼갤지 말지 판단할 기준이 저한테 없었다는 게 문제였습니다. 파일이 길어서 쪼개면 파일 수만 늘어난다는 감은 있는데, 그럼 언제 쪼개는 게 맞는지는 감으로만 정하고 있었습니다.

그러던 중 스터디 2주차에서 지아코모님이 스킬 구조를 다루는 지식공유를 해주셨습니다. 커진 스킬을 단순히 자르는 게 아니라 역할 분담, 산출물 정의, 실패했을 때 어디로 되돌아가는지 같은 개념으로 보는 내용이었고, 듣는 내내 제 리캡 스킬이 떠올랐습니다.

판정 질문으로 개념 적용하기

다음 날 처음 한 일은 강의 내용을 요약해 두는 게 아니라, 제 스킬에 들이댈 수 있는 질문 형태로 바꿔 문서 한 장으로 만드는 것이었습니다. 요약은 읽고 끝나지만, 질문은 대답을 강제하니까요. 저는 이 문서를 “렌즈”라고 부르기로 했습니다. 들어간 항목은 다섯 묶음입니다.

특히 인터페이스 카드의 두 칸 — “다음에 뭘 넘기는가”와 “실패하면 어디로 돌아가는가” — 는 제가 그동안 스킬 문서에 한 번도 써본 적 없는 칸이었습니다. 결과적으로 이 두 칸이 이날의 수확 대부분을 만들어냈습니다.

판정 질문으로 발견한 구멍

렌즈를 처음부터 스킬 제작에 쓰는 건 무리다 싶어서, 순서를 바꿨습니다. 일단 기존 스킬 하나를 골라 손으로 렌즈를 대보고, 그 경험으로 나중에 검토용 스킬을 만들기로. 대상은 위의 유튜브 리캡 스킬과, 그 앞단에서 음성을 글로 바꿔주는 전사 스킬(media-transcribe)의 2단 체인으로 잡았습니다.

사실 이전에도 나름 평가 문서도 만들었었던지라 뭐가 더 비었을지 궁금했는데, 렌즈의 “다음에 뭘 넘기는가” 칸을 채우려는 순간부터 구멍이 나오기 시작했습니다.

재미있었던 건 구멍 2입니다. 나중에 확인해 보니 예전에 AI에게 파일 14개를 읽혀 기계 감사를 시켰을 때도 같은 갭이 잡혀 있었습니다. 렌즈 질문 하나가 파일 14개짜리 감사와 같은 지점에 도달한 셈이라, “질문을 잘 고르는 게 물량보다 세다”를 눈으로 봤습니다.

반대로 렌즈의 경고가 저를 말린 장면도 있었습니다. 전사 스킬은 안에 역할이 5개나 섞여 있어서 나누고 싶은 유혹이 있었는데, 렌즈의 기준은 “역할 수가 아니라 실패가 갈라졌는가”였고, 이 스킬은 실패가 경계를 넘은 적이 없었습니다. 판정: 그대로 두고 보강만. 파일 수가 늘어나는 걸 막아준 판정이었습니다.

AI 리뷰로 얻은 통찰

구멍 2의 처방으로 저는 “규격 정의를 정제 스크립트(vtt_clean.py) 한 곳에 넣고 양쪽 문서는 그걸 가리키자”고 정리했습니다. 깔끔해 보였습니다.

그리고 실행 전에, 이 판정과 계획을 정리한 브리핑 문서를 만들어 별도의 AI 리뷰어 둘(codex, grok)에게 병렬로 읽혔습니다. 제가 만든 판정을 제가 통과시키는 걸 피하려는 절차인데, 여기서 둘이 같은 지점을 지적했습니다.

그 파일을 만드는 생산자가 하나가 아니다. 긴 영상을 조각내 전사하는 경로에서는 다른 스크립트(stitch_chunks.py)가 같은 파일을 직접 만든다. 정본을 한 스크립트에만 선언하면 나머지 생산자의 어긋남이 다시 숨는다.

맞는 말이었습니다. 머쓱하게도 저는 “정본을 한 곳에”에 꽂혀서 생산자가 둘이라는 사실을 놓치고 있었습니다. 처방을 고쳤습니다 — 정본은 한 곳에 두되, 다른 생산자 쪽에 “이 규격을 따른다”는 선언을 명시하고 양쪽 문서가 같은 곳을 가리키게. 서로 다른 AI에게 같은 걸 읽히는 비용이 아깝지 않은 순간이었습니다.

스킬 분리의 결과

판정이 끝났으니 실행입니다. 승인돼 있던 분리 계획에 이날 발견분을 덧붙여, 검증·캡처 부분을 별도 스킬(recap-qa)로 떼어냈습니다.

youtube-recap (요약 만들기 본선)         recap-qa (품질 보강·검증)
├── 1 자막 확보 + 정제                   ├── 1 화면 캡처 보완
├── 2 구간 나누고 요약                   └── 2 타임스탬프·캡처 검증
│    └ 교정된 사본(compact.txt)을 읽음        (전용 스크립트 5개가 이사)
├── 3 md 조립(렌더)
├── 4 고유명사 교정                       두 스킬이 주고받는 파일 규격은
└── 5 전사물 보관                         정제 스크립트 안 한 곳에만 정의

나누면서 이날 나온 구멍도 같이 메웠습니다. 죽은 참조는 실물 위치로, 계약 규격은 정본 한 곳으로, 계획서의 참조 갱신 목록에는 체인 반대편을 추가로. 덤도 하나 있었습니다 — 고유명사 교정을 요약 후가 아니라 요약 전에 적용하는 단계(compact.txt 생성기)를 새로 만들었는데, 요약 후 교정은 글자만 고칠 뿐 AI가 깨진 표기를 오해해서 내용을 잘못 요약한 것까지는 못 고치기 때문입니다.

숫자로 확인한 것들:

• 검증 테스트 181개 통과 — 나누기 전후로 테스트 목록을 이름 단위까지 대조해서 동일함을 확인했습니다 (개수만 세면 이름이 바뀐 걸 놓칩니다)

• 새 교정 단계를 실제 영상 1편(발화 2,410개)에 돌려 자동 교정 56건 — 전부 사전에 등록된 근거가 있는지 대조했고, 지어낸 교정은 0건이었습니다

• 원문 파일은 바이트 단위로 이전과 동일 — 교정은 사본에만 적용된다는 원칙이 지켜졌는지 해시값으로 확인했습니다

그리고 이 과정 전체가, 처음에 하고 싶었던 “스킬 검토용 스킬”의 리허설이 됐습니다. 서브 AI를 어떻게 나눠 투입할지(경계 담당 / 내부 담당 / 증거 담당)도 이 한 판에서 감이 잡혔습니다.

배운 점과 향후 계획

가장 크게 남은 건 판정 기준 두 개입니다. 쪼갤지는 역할 수가 아니라 실패가 갈라졌는지로 정합니다. 그리고 문서에 규격이 “적혀 있는가”가 아니라 “정본이 한 곳이고 양끝이 같은 곳을 가리키는가”를 묻습니다. 죽은 임시 폴더를 가리키던 그 문서 한 줄이 이 둘을 다 가르쳐줬습니다 — 고치는 사람은 코드를 옮기고 나서 문서까지 돌아보지 않고, 그걸 잡는 건 사람의 성실함이 아니라 좋은 질문이었습니다.

써볼 수 있는 프롬프트

아래 절차 문서(또는 스킬)를 "구조 검토"만 해줘. 고치지는 말고 판정 표만 만들어.

[여기에 문서 붙여넣기 또는 파일 경로]

각 단계(덩어리)마다 다음을 채워:
1. 이 덩어리는 언제 시작되나? 무엇을 받고 무엇을 내나?
2. 다음 단계에 넘기는 것이 무엇인가? 그 규격은 어디에 적혀 있나 — 적힌 곳이 한 곳인가, 여러 곳인가?
3. 실패하면 어디로 돌아가나? (처음부터? 직전 단계?)
4. 이 덩어리가 하지 않는 일은?

그리고 마지막에 종합 판정:
- 나눠야 할 곳: "실패 원인이 서로 다른 단계에서 나오는" 경계만 (파일이 길다는 이유는 제외)
- 보강할 곳: 정보가 부족해서 문제가 생기는 곳
- 참조가 죽은 곳: 문서가 가리키는 파일·경로가 실제로 존재하는지 전부 확인

부록

• 사용 도구: Claude Code(적용·실행), codex·grok CLI(교차 리뷰 — 브리핑 문서를 읽혀 판정을 검증)

• 렌즈의 원 개념: 에이전트하네스 스터디 2주차 지아코모님 지식공유 (Skill/Workflow/Umbrella 층, 유지·보강·분리·연결, 인터페이스 카드, 완료·증거 층)

• 검증 방식: 분리 전후 테스트 이름 목록 대조, 교정 결과 전수 근거 대조, 원문 해시 불변 확인