1115줄 스킬을 나눠 보니 5토막 전부 "실제로 불리는 크기"에 들어왔습니다: 1주차에 잰 63줄이 기준이 됐습니다

소개

1주차 사례글에서 제 스킬 27개를 세어 보고 세 가지를 확인했습니다.

그리고 "2주차에 배울 우산 구조로 긴 스킬을 나누겠다, 1115줄짜리 citation-management가 첫 대상"이라고 적었습니다.

이번 주 강의가 정확히 그 내용이었습니다.

간이 흔들리면 국물 스킬만 다듬으면 되고요. 면이 덜 익으면 면 스킬만 다듬으면 되고요. 예전에 다 한 덩어리에 있으니까 여기저기서 다 문제가 터지고, 그 문제가 어떻게 해야 해결되는지 명확하지 않을 때도 있었거든요.

그래서 이번 주에는 선언한 것을 실제로 해 봤습니다. 다만 나누기 전에 확인하고 싶은 것이 있었습니다. 나눈 조각이 정말 불릴 크기가 되는가. 1주차에 잰 63줄이 그 판정 기준이 됩니다.

진행 방법

사용 도구: Claude Code, Python 3

Step 1. 나눌 자리가 이미 있는지 확인

강의에서 스터디장이 짚은 대목입니다.

저희가 원래 스킬이 없었던 게 아니고, 원래 이런 스킬이 있었는데 이거를 쪼개는 거라서.

citation-management의 헤딩 구조를 뽑아 봤습니다.

grep -n '^#\{1,3\} ' SKILL.md

Phase 1: Paper Discovery and Search
Phase 2: Metadata Extraction
Phase 3: BibTeX Formatting
Phase 4: Citation Validation
Phase 5: Integration with Writing Workflow

끊을 자리를 새로 찾을 필요가 없었습니다. 라면 비유의 국물, 면, 재료, 마무리가 이미 문서 안에 있었습니다.

Step 2. 부속물도 이미 나뉘어 있었다

폴더를 열어 보니 이렇습니다.

본문만 한 덩어리로 남아 있었습니다.

Step 3. 나눈 뒤 크기를 계산 (첫 시도는 틀렸다)

Phase 헤딩을 경계로 각 조각의 줄 수를 셌습니다.

Phase 5만 733줄이 나왔습니다. 이상해서 확인했더니, Phase 5가 마지막이라 그 뒤의 Best Practices와 Examples 섹션까지 한 덩어리로 잡힌 것이었습니다. 경계를 ###만 보고 있어서 생긴 문제입니다.

##도 경계에 넣어 다시 셌습니다.

Step 4. 정정한 결과

1주차에 잰 "실제로 불린 스킬"의 중앙값이 63줄, 범위가 39~107줄이었습니다. 나눈 다섯 조각이 전부 그 안에 들어옵니다.

Step 5. 남는 것을 어디에 둘지

1115줄에서 Phase 다섯 개(합계 379줄)를 빼면 736줄이 남습니다. Overview, When to Use, Best Practices, Examples입니다.

강의의 구조에 대 보면 자리가 정해집니다.

        [ citation 엄브렐러 ]   ← Overview + 라우팅
         ↓    ↓    ↓    ↓    ↓
    검색  추출  포맷  검증  통합     ← 각 67~86줄
         ↘    ↘    ↓    ↙    ↙
            references/ (배경지식 5개)
            scripts/    (코드 게이트 8개)

결과와 배운 점

측정 결과

배운 점

1. 나눌 자리는 이미 문서 안에 있었습니다. Phase 1~5라고 제가 직접 써 놓고, 그것을 한 파일에 두고 있었습니다. 강의가 "원래 스킬이 없었던 게 아니라 쪼개는 것"이라고 한 말이 정확했습니다. 구조를 만드는 일이 아니라 이미 있는 구조를 파일 경계로 옮기는 일이었습니다.

2. 1주차의 측정이 2주차의 판정 기준이 됐습니다. "얼마나 잘게 나눠야 하나"를 감으로 정할 뻔했는데, 1주차에 잰 63줄이 있어서 나눈 조각이 불릴 크기인지 계산으로 확인할 수 있었습니다. 다섯 개 전부 들어왔습니다. 한 주 전의 측정이 이번 주의 자를 만들어 줬습니다.

3. 코드 게이트가 이미 8개 있었습니다. 1주차에서 "코드 게이트를 붙인 스킬은 한 번도 안 불렸다"는 것이 문제였는데, 나눠 놓고 보니 그 8개는 scripts/에 그대로 있습니다. 게이트가 없어서가 아니라 게이트가 1115줄 뒤에 숨어 있어서 안 불린 것에 가깝습니다.

4. 적재적소가 중요하다는 경고를 새겨듣게 됐습니다. 스터디장이 "게이트를 너무 많이 쓰면 작업이 말도 안 되게 오래 걸린다, 아무 데나 많이 설치한다고 완벽해지는 게 아니다"라고 했습니다. 저는 게이트를 더 붙일 생각이었는데, 먼저 있는 것을 불리게 만드는 쪽이 순서입니다.

시행착오

• Phase 5를 733줄로 잰 것이 이번 주 가장 큰 실수였습니다. 그대로 썼으면 "다섯 조각 중 하나는 아직 너무 크다"는 틀린 결론이 나왔을 것이고, 그 조각을 또 나누려 했을 것입니다. 원인은 마지막 항목의 경계를 다음 같은 레벨 헤딩으로만 찾은 것입니다. 뒤에 상위 레벨 헤딩이 오면 거기서 끊어야 합니다. 목록의 마지막 항목은 항상 뒤를 다 삼킵니다.

• 숫자가 이상할 때 다시 본 것이 맞았습니다. 다른 넷이 73~86줄인데 하나만 733줄이면 열 배 차이입니다. 한 항목만 크게 튀면 측정을 의심할 자리입니다.

앞으로의 계획

• 나눈 다섯 개를 실제 파일로 만들고 엄브렐러를 얹겠습니다. 이번 주에는 어떻게 나뉠지와 나눈 크기가 맞는지까지 확인했고, 파일 분리는 아직 하지 않았습니다.

• 나눈 뒤 다시 세어 확인할 계획입니다. 1주차와 같은 방법으로 호출 이력을 집계하면, 나눈 것이 실제로 불리는지 다음 주에 숫자로 나옵니다. 가설을 세웠으니 검증이 남았습니다.

• 강의에서 소개한 인덱서와 내비게이터를 참고하려 합니다. 스터디장은 스킬이 400~500개가 되며 뭐가 있는지 모르게 됐다고 했습니다. 저는 27개인데도 4개만 씁니다. 개수 문제가 아니라 찾아가는 길의 문제로 보입니다.

• 확장 과제의 프루프 아티팩트를 인용 검증에 붙여 보겠습니다. 인용이 맞는지 검증하는 스킬에 증거 파일이 없으면, 검증했다는 말만 남고 근거가 안 남습니다.

도움 받은 글 (옵션)

• 23기 에이전트 하네스 2주차 강의 (지아코모): 스킬을 단계로 나누는 라면 비유, 엄브렐러와 라우팅 스킬 구조, 나누는 순서(잘 쓰면 그대로, 부족하면 보강, 그래도 안 되면 분리), 프루프 아티팩트와 코드 게이트, 게이트를 적재적소에만 두라는 경고

• 23기 에이전트 하네스 1주차 사례글 (본인): 스킬 27개의 호출 이력과 줄수 측정. 이번 주의 판정 기준이 된 63줄이 여기서 나왔다