iceberggymnast Skill Checkup — 스킬이 돌기는 하는지 잰다
스킬의 1차 실패 모드는 절차가 틀리는 것이 아니라 조용히 안 쓰이게 되는 것이다. 안 도는 스킬은 아무 신호도 안 보낸다 — 원장이 안 자라고, 지표가 0으로 예쁘고, 아무도 불평하지 않는다. 이 스킬은 그 침묵을 숫자로 바꾼다.
이 스킬이 다루는 것
| 상황 | 담당 |
|---|---|
| 함대 전체가 돌기는 하는지 · 트리거 수리 | 이 스킬 |
| 원장·프로필의 상태 점검과 정리 | 이 스킬 |
| 스킬 하나가 자기 성공 기준을 충족했는지 | 그 스킬 자신 ("이 스킬 의도대로 작동해?") |
| 로그에서 새 자동화 후보를 발굴 | session-audit |
CLAUDE.md·설정 파일 점검 |
claude-md-management 플러그인 |
개별 점검과 겹치지 않는다. 개별 스킬 점검은 "내 기준을 충족했나"를 묻고 그 스킬의 RATIONALE.md 관측 표에 남는다. 이 스킬은 "애초에 돌기는 했나"를 묻는다. 재는 대상이 달라서 한쪽이 다른 쪽을 대체하지 않는다.
session-audit과 방향이 반대다. 그쪽은 없는 것을 만들 근거를 찾고, 이쪽은 있는 것이 죽었는지 본다. 로그를 읽는다는 점만 같다.
측정 대상
판정은 RATIONALE.md를 가진 스킬에만 한다. 그 파일이 있다는 것은 성공 기준을 선언했다는 뜻이고, 선언이 없으면 발동률이 낮은 것이 문제인지 정상인지 판정할 근거가 없다.
단, 발동 수치는 전부 보고한다. RATIONALE.md가 없어도 계기는 스킬 이름을 가리지 않고 세므로 숫자는 나온다. 그 숫자를 빼면 "함대가 돌기는 했는지"라는 이 스킬의 목적 자체가 사라진다. 없는 스킬은 수치 옆에 **"판정 보류 — 기준 없음"**으로 적고 임의 기준을 지어내지 않는다.
RATIONALE.md를 찾는 순서: 스킬 폴더 안 → 없으면 <기준 폴더>/rationale/<스킬명>.md. 플러그인으로 설치한 경우 스킬 폴더가 캐시 디렉터리라 관측 기록이 /plugin update에 지워지므로, 그쪽 규약은 후자에 두게 되어 있다(BOOTSTRAP 2-7). 앞만 보고 "기준 없음"으로 처리하면 규약을 지킨 사람이 전부 측정 불가를 받는다.
전 스킬이 "기준 없음"으로 나오면 갓 설치한 상태다. 고장이 아니다. 그 사실을 그대로 알리고, 만드는 형식은 각 스킬 SKILL.md 끝의 "성공 기준 · 존재 의의" 절과 BOOTSTRAP 2-7에 있다고 안내한 뒤 발동 수치만 내고 끝낸다. 판정 없는 결과를 "고장"처럼 내면 첫 사용자가 이 스킬을 다시 안 부른다.
분모에서 빼야 하는 것
수치를 내기 전에 먼저 거른다. 안 거르면 정상인 것을 실패로 적는다.
스킬이 없던 기간. 스킬 폴더의 생성일이나 그 스킬의 첫 커밋보다 앞선 세션은 분모에서 뺀다. 없던 스킬의 발동이 0인 것은 당연하고, 그걸 발동률에 넣으면 최근에 만든 스킬일수록 나쁘게 나온다.
재실행이 드문 것이 정상인 스킬. 아래 둘은 발동률로 재지 않는다.
| 유형 | 왜 |
|---|---|
| 일회성 작업을 절차로 굳힌 스킬 | 한 번 돌린 결과가 이미 산출물이고, 절차는 다음에 같은 일이 생길 때를 위해 남긴 것이다. 안 도는 게 아니라 돌 일이 아직 없는 것이다 |
| 도입·설정용 스킬 | 한 번 쓰고 끝나는 것이 정상이다 |
이런 스킬은 **"필요한 순간에 찾아지는가"**로 본다. 로그에서 그 스킬을 썼어야 할 상황이 있었는데 다른 방식으로 처리한 흔적이 있는지 보고, 그런 상황이 아예 없었으면 판정하지 않는다.
어느 유형인지는 그 스킬의 RATIONALE.md가 정한다. 판단이 안 서면 사용자에게 한 줄로 묻는다 — 발동률이 낮은 것이 문제인지 아닌지는 만든 사람이 안다.
무엇을 재나 — 세 층
기회 (조건이 성립한 횟수)
↓ ← 여기서 새면 트리거 문제
발동 (스킬이 실제로 로드되거나 훅이 울린 횟수)
↓ ← 여기서 새면 절차 이탈
기록 (원장에 남은 항목 수)
누락이 어느 구간에서 났는지가 곧 진단이다. 두 구간을 합쳐서 "잘 안 돌아간다"고 하면 처방이 갈린다 — 앞은 트리거를 고치는 일이고, 뒤는 절차를 지키게 하는 일이다.
1. 발동 — 스크립트로 센다
python scripts/skill-usage.py --days 45
세는 신호는 둘이다.
- 스킬 파일 로드 — 세션 jsonl의
Base directory for this skill: <경로>. 명시 호출과 자동 발동을 모두 잡는다 - 훅 주입 — 각 훅이 내보내는 마커 문구(
[이해 확인 대상],[CS 복습]등 — 훅 파일에서 확인하고 넣는다). 훅은 스킬 파일을 로드하지 않고도 절차를 시작시키므로, 로드만 세면 훅으로 도는 스킬을 크게 과소평가한다
출력의 스킬별로드는 총 횟수, 스킬별발동세션수는 그 스킬이 한 번이라도 돈 세션 수다. 비율은 세션 수 기준으로 본다 — 한 세션에서 열 번 도는 것과 열 세션에서 한 번씩 도는 것은 다른 이야기다.
분석 전에 데이터 창부터 확인한다. --days로 준 값이 아니라 출력의 기간이 실제 창이다. cleanupPeriodDays 기본값이 30일이라 45일을 요청해도 30일치만 남아 있을 수 있고, 그러면 발동률이 조용히 3분의 1만큼 줄어든다. 분모를 실제 창에 맞춘다.
출력의 경고·거른것·쓴훅마커를 읽는다. 경고가 있으면 그 회차 수치로 아무것도 고치지 않는다 — 계기가 하네스와 안 맞는 상태다. 쓴훅마커는 어떤 문구로 셌는지 보여주므로 자기 훅과 대조할 수 있다.
플러그인으로 설치했으면 캐시 안의 스크립트를 고치지 말고 기준 폴더에 복사해서 돌린다. HOOK_MARKERS에 자기 훅 마커를 추가해도 /plugin update에 원복되고, 그러면 그 훅의 발동이 조용히 0으로 돌아간다.
2. 계기가 못 보는 것 — 결과와 함께 반드시 적는다
이 숫자를 그대로 "발동률"이라 부르면 안 된다. 아래가 분자에서 빠져 있다.
| 사각지대 | 왜 |
|---|---|
| 다른 하네스(codex 등)의 발동 | 스킬 폴더를 링크해 쓰면 그쪽 로그는 ~/.claude/projects에 없다 |
| 서브에이전트 레인 내부 | 메인 세션 jsonl에 안 들어온다 (--with-subagents로 일부 포함) |
| 삭제된 기간 | cleanupPeriodDays 설정에 따라 오래된 로그가 이미 없다 |
| 마커 없는 훅 | 마커 문구를 안 내보내는 훅은 안 잡힌다 |
| 감지 문자열을 인용한 세션 | 반대로 부풀린다. 로그를 분석·디버깅하면서 감지 문자열을 화면에 찍은 세션은 자기가 분자에 섞인다. 점검을 돌린 세션 자신이 다음 회차를 오염시킨다 — 회차 기록에 그 사실을 적고, 오염된 항목은 표에서 뺀다 |
"안 잡혔다"와 "안 돌았다"는 출력이 같고, "인용했다"와 "돌았다"도 출력이 같다. 낮은 수치를 보고 트리거를 고치기 전에, 높은 수치를 보고 안심하기 전에 이 목록부터 확인한다. 계기를 못 믿으면 그 항목은 "측정 불가"로 두고 넘어간다.
훅 마커는 추측하지 말고 훅 파일에서 확인한다. 첫 실행에서 마커 한 개를 추측으로 넣었다가 커밋 케이스가 통째로 빠졌고, 그 수치로 잘못된 진단을 한 번 냈다. 훅 문구가 바뀌면 HOOK_MARKERS도 같이 고쳐야 한다.
3. 기회 — 레포에서 센다
스킬마다 조건이 다르므로 한 명령으로 안 나온다. 해당 스킬의 발동 조건을 보고 그 조건이 성립한 횟수를 센다.
- 커밋 직후 도는 스킬 →
git log --since='45 days ago' --oneline | wc -l - PR에 붙는 스킬 →
gh pr list --state all --json number,author로 내 PR과 팀원 PR을 나눠 센다 - 세션마다 걸릴 수 있는 스킬 → 세션 수 자체
모든 레포를 다 세지 않는다. 그 스킬이 실제로 쓰이는 레포만 센다. 안 쓰는 레포를 분모에 넣으면 발동률이 인위적으로 낮아진다.
4. 기록 — 원장에서 센다
각 스킬의 RATIONALE.md가 ## 원장 위치에서 적재처를 가리킨다. 그 파일에서 같은 기간의 항목 수를 센다.
적재처가 없음이거나 칸이 비었으면 기록 층을 건너뛰고 기회 → 발동 두 층으로만 진단한다. 사람 관측치로만 재는 스킬(되묻는 횟수, 손으로 고친 빈도 같은 것)은 적재처가 원래 없다. 그런 스킬에 남의 원장을 대입하면 발동은 있는데 기록이 0으로 나와 정상 작동이 절차 이탈로 뒤집힌다.
진단
| 관측 | 진단 | 처방 방향 |
|---|---|---|
| 기회는 많은데 발동이 적다 | 트리거 문제 | 아래 "트리거 수리" |
| 발동은 하는데 기록이 적다 | 절차 이탈 — 발동해도 끝까지 안 간다 | 절차의 어느 단계에서 끊기는지 로그에서 확인하고, 그 단계를 가볍게 만들거나 훅이 그 단계를 상기시키게 한다 |
| 기록은 있는데 스킵이 누적 | 마찰 문제 | 한 번에 묻는 양을 줄이거나 발동 시점을 옮긴다. 3주 연속이면 그 스킬 자신의 재설계 조항을 따른다 |
| 셋 다 낮은데 기회 자체가 없다 | 문제 아님 | 그 스킬의 대상 작업을 안 한 것뿐이다. "발동 0"을 실패로 적지 않는다 |
| 발동 0인데 스킬이 최근에 만들어졌다 | 측정 기간 부족 | 다음 회차까지 판정을 보류한다 |
| 발동 0인데 일회성·도입용 스킬이다 | 문제 아님 | 위 "분모에서 빼야 하는 것" 참조 |
발동은 있는데 기록이 0이고 적재처가 없음 |
오진 주의 | 절차 이탈이 아니다. 기록 층을 빼고 두 층으로만 본다 |
트리거 수리 — 선택지와 판단 기준
BOOTSTRAP에서 사용자가 거부한 항목부터 본다. 도입 때 고른 발동 방식은 mentee-profile.md에 남아 있다(BOOTSTRAP 2-6). 그때 "명시 호출만"을 골랐으면 자동 발동 경로가 애초에 없는 것이고, 낮은 발동률은 고장이 아니라 그 선택의 결과다. 그 경우 먼저 물을 것은 트리거 수리가 아니라 "그때 결정을 지금도 유지할 것인가"다.
프로필 자체가 없으면 "거부 없음"이 아니라 "도입 안 함"이다. 상태가 셋이다 — 도입하고 자동 발동을 켠 것 / 도입하고 거부한 것 / 도입을 안 한 것. 셋째를 첫째로 읽으면 훅을 건 적도 없는 사람의 스킬이 "트리거 문제"로 진단되고, 훅으로 도는 스킬에 무효인 수리(description 보강)부터 적용된다. 프로필이 없으면 도입 여부부터 확인한다.
거부 항목이 아니라면 아래 순서로 본다. 위쪽이 비용이 싸다.
| 수리 | 언제 | 비용 |
|---|---|---|
| description 트리거 문구 보강 | 실제로 쓴 표현이 description에 없을 때. 로그에서 그 스킬을 불렀어야 할 발화를 찾아 문구를 그대로 넣는다 | 낮음 |
| 발동 시점을 옮긴다 | 지금 시점에 마찰이 커서 무시될 때. 작업 도중이 아니라 작업이 끝나는 자리로 옮긴다 | 중간 |
| 훅 추가·수정 | 사람이 말해야만 도는데 그 말이 구조적으로 안 나올 때. 자동 커밋 규약이 있으면 "커밋해줘"는 영영 안 나온다 | 중간 |
| 앞 세션을 읽고 묻는다 | 워크스페이스를 열었을 때 직전 세션에서 끝내지 못한 절차가 있으면 그것부터 확인한다 | 중간 |
| 스킬 병합·폐기 | 두 스킬이 같은 시점을 두고 경합해 둘 다 신뢰도가 떨어질 때, 또는 대상 작업 자체가 끝났을 때 | 높음 |
훅을 늘리는 것은 마지막에 검토한다. 부팅 시점 알림이 둘 이상이면 사용자가 전부 무시하게 되고, 그때 잃는 것은 새 훅 하나가 아니라 기존 훅까지다.
원장·프로필 상태 점검
이 절은 원장·프로필을 실제로 쓰는 환경에서만 돈다. 파일이 없으면 절 전체를 "해당 없음"으로 적고 건너뛴다 — 부재는 진단 근거가 아니다. 도입 절차를 안 돌린 것과 도입했는데 안 도는 것은 완전히 다른 상태인데, 파일만 보면 둘 다 똑같이 비어 있다.
측정과 별개로 데이터 자체가 썩고 있는지 본다.
| 볼 것 | 신호 |
|---|---|
| 미복습 항목의 나이 | 4주를 넘긴 것이 쌓이면 복습 경로가 안 도는 것이다 |
판별점이 빈 항목 |
나중 복습이 알던 층을 물어 통과 도장이 된다. 채우거나 항목을 접는다 |
| 닫히지 않는 항목 | 같은 항목이 세 번 이상 재대조에서 실패하면 출제 방식을 의심한다 |
| 스킵 기록의 빈도 | 그 스킬 자신의 재설계 조항에 걸리는지 |
| 원장 크기 | 커져서 매 리뷰 시작에 읽기 부담이면 닫힌 항목을 아카이브로 접는다 |
| 프로필 기재 | 아래 |
프로필 검증 — 새 문제를 내서 확인한다
mentee-profile.md가 있을 때만 한다. 없으면 이 절을 통째로 건너뛴다 — 프로필이 없다는 것은 그 사람이 멘토 계열 스킬을 도입한 적이 없다는 뜻이고, "스킬 잘 돌아?"라고 물었을 뿐인 사람에게 스택 숙련도 시험을 내는 것은 이 스킬이 할 일이 아니다.
mentee-profile.md의 주장(주력 스택, 영역별 숙련도 판정)이 지금도 맞는지 본다. 기재를 그냥 믿지 않는다 — 숙련도는 변하고, 원장의 판정은 그 스킬이 만난 코드에 한정돼 있다.
출제 규칙
- 기존 프로젝트 코드에서 꺼내지 않는다. 프로젝트 코드로 물으면 그 프로젝트를 아는지 재게 되고, 프로필이 주장하는 것은 스택 숙련도다
- 프로필이 명시적으로 주장하는 항목만 겨냥한다. 주장이 없는 영역은 검증 대상이 아니다
- 질문 품질 규칙은
senior-mentor의 "질문은 답을 몰라도 읽혀야 한다"와 "겨냥" 절을 따른다. 여기 옮겨 적지 않는다 - 한 번에 두세 문제. 그 이상은 시험이 되고, 시험은 다음 점검을 거부당하게 만든다
결과 처리
- 결과는
mentee-profile.md의 숙련도 기재만 갱신한다 comprehension-debt.md에 쓰지 않는다. 그 표는 AI 코드 이해도를 재는 지표라 프로필 검증 결과를 섞으면 분포가 오염된다cs-progress.md에도 쓰지 않는다. 그쪽은 "커리큘럼을 배웠나"를 묻고 이쪽은 "프로필 기재가 맞나"를 묻는다- 기재와 결과가 다르면 프로필을 고치되, 한 번의 결과로 등급을 바꾸지 않는다. 그 판정은 원장의 관찰 구간 규칙(첫 3회)을 따른다
적용 — 승인을 받고 고친다
이 스킬이 손대는 대상은 다른 스킬의 description, 훅, settings.json, 프로필이다. 전부 승인 게이트 뒤에 둔다.
- 측정 결과와 진단을 먼저 낸다
- 수리안을 근거와 함께 제시한다 — 어느 수치가 어느 처방을 부르는지
- 사용자가 고를 것을 고른다
- 고른 것만 적용하고, 무엇을 바꿨는지 파일 단위로 보고한다
측정하고 조용히 고치지 않는다. 함대 전체의 트리거를 자동으로 바꾸는 스킬은 그 자체가 가장 위험한 스킬이 된다.
플러그인으로 설치한 스킬은 파일을 고쳐도 /plugin update에 원복된다. description 보강이 가장 싼 수리인데 캐시 디렉터리에 하면 다음 업데이트에 사라지고, 그러면 다음 회차가 이미 없어진 수리의 효과를 재게 된다. 원본 레포에 고치고, 원본이 없으면 그 사실을 보고한 뒤 다른 수리를 고른다.
주기
명시 호출로만 돈다. 훅을 걸지 않는다.
로그 전수 스캔은 비싸고 함대는 천천히 변한다. 매 세션 도는 것은 낭비고, 부팅 알림을 하나 더 얹으면 기존 알림까지 무시된다.
점검이 끝나면 RATIONALE.md의 관측 표에 회차를 남기고 다음 점검 시점을 한 줄로 제안한다(기본 한 달 뒤). 그 표가 곧 주기 기록이다 — 별도 원장을 만들지 않는다.
하지 말 것
- 측정 결과로 다른 스킬 파일을 승인 없이 고치는 것
- 계기의 사각지대를 안 적고 수치만 내는 것 — "안 잡혔다"와 "안 돌았다"는 구분되지 않는다
- 기회가 없어서 발동이 0인 것을 실패로 적는 것
RATIONALE.md가 없는 스킬에 임의 기준을 지어내 평가하는 것 — 판정은 보류하되 발동 수치는 낸다- 원장·프로필이 없는 환경에서 그 부재를 진단 근거로 삼는 것
- 프로필이 없는 사람에게 검증 문제를 내는 것
- 프로필 검증 결과를 이해 부채 원장이나 CS 진도 원장에 적는 것
- 프로필 검증 문제를 진행 중인 프로젝트 코드에서 뽑는 것
- 한 번의 점검 결과로 숙련도 등급을 바꾸는 것
- 훅을 늘려 해결하려는 것 — 마지막 선택지다
성공 기준 · 존재 의의
RATIONALE.md를 만들어 아래를 시드로 옮기고, 점검 회차 기록도 그 파일의 관측 표에 쌓는다. 만든 뒤에는 이 절을 참조만 하고 두 벌로 두지 않는다.
없애려는 것 — 스킬은 절차가 틀려서 죽지 않고 안 쓰여서 죽는다. 그런데 안 쓰이는 스킬은 아무 신호도 안 보낸다. 원장이 안 자라고, 스킵 기록이 비어 지표가 깨끗해 보인다. 각 스킬의 성공 기준은 "발동했을 때 값을 냈는가"를 묻지 "발동하기는 했는가"를 묻지 않아서, 발동이 0이면 평가할 대상이 없어 조용히 통과한다.
재는 것 (1차) — 진단이 처방으로 이어졌는가. 산출물은 숫자가 아니라 고친 트리거다. 지난 회차 제안 중 적용된 것이 있는지, 적용한 수리가 다음 회차 수치를 움직였는지 본다. 수치를 냈다는 것만으로 성공으로 치지 않는다 — 읽고 아무것도 안 바꾸는 보고서는 노이즈 자산이다. 두 회차 연속으로 제안이 하나도 적용되지 않으면 제안이 실행 가능한 형태가 아니거나 점검 자체에 값이 없다.
재는 것 (2차) — 계기의 정직성. 수치와 함께 못 본 것을 적었는가. 사각지대를 안 적은 회차는 실패로 친다. 낮은 발동률을 근거로 트리거를 고쳤는데 실은 계기가 못 본 것이었다면 없는 문제를 고친 것이다.
사용자가 "이 스킬 의도대로 작동해?" 라고 물으면 RATIONALE.md를 읽고 지난 회차 관측과 대조한다.