Bug Fix

문제

버그를 잡으려는데 증상이 가리키는 원인이 자꾸 빗나갑니다. 스킬이 안 걸리고, 테스트 결과 개수가 이상하고, 명령은 성공했다는데 파일이 없고, 파일이 삭제된 줄 알았는데 실은 안 보이는 것뿐입니다.

1. 증상 확인
2. 도구가 보고하는 신호부터 의심
3. 격리해서 재현
4. 원인 확정
5. 수정
6. 재검증

추천

도구가 내놓는 신호(exit code, 테스트 개수, git status)를 그대로 완료·성공의 증거로 쓰지 않습니다. 그 신호가 실제로 무엇을 확인했는지 한 단계 더 파봅니다.

이유

네 가지 실패 패턴은 원인이 같습니다. 신호를 만든 도구 자신이 신호를 왜곡합니다.

스킬이 안 걸릴 때 스킬 본문부터 고치지 않습니다. 진단 순서를 고정해 둡니다. ① skillOverrides, ② 프롬프트의 전제(참조하는 파일이 실제로 컨텍스트에 있는가), ③ 스킬 본문 순입니다. 본문을 먼저 고치면 ①·②가 원인이었을 때 헛수고입니다.

테스트 실패 개수가 소스 파일의 테스트 개수와 안 맞으면 의심합니다. vitest run <파일>이 “1 failed | 12 passed (13)“인데 그 파일의 테스트가 7개면, 다른 세션 워크트리의 옛 테스트 사본이 같이 수집된 것입니다. 신호는 세 가지입니다. 파일당 테스트 수가 기대보다 많고, 심어 둔 console.log가 안 찍히고, 축약 출력이 경로를 잘라 원인 파일을 숨깁니다. 축약 출력을 믿지 말고 전체 출력을 파일로 저장해 실패 헤더의 경로를 직접 봅니다.

exit 0이 성공을 뜻하지 않는 도구가 있습니다. sips -s format webp in.png --out out.webp는 exit 0에 경로까지 출력하고도 파일을 만들지 않는 경우가 있습니다. && 체인에 넣으면 이 실패를 알아채지 못합니다. exit 0이 성공을 뜻하는지는 도구마다 다릅니다. 실제로 확인한 도구에서만 exit code를 성공 판정에 씁니다.

파일이 git status에 안 보이면 삭제·이동 전에 git check-ignore -v부터 봅니다. 넓게 잡은 lib/ 무시 규칙이 새로 만든 skills/lib/를 중첩 경로까지 매칭해 삼키는 경우가 있습니다. git status에 안 보이는 파일은 삭제된 것이 아니라 무시된 것일 수 있습니다.

예시

스킬 진단은 순서대로 좁힙니다.

스킬이 안 걸린다
├─ skillOverrides에 걸려 있는가?
├─ 프롬프트가 참조하는 파일이 실제로 컨텍스트에 있는가?
└─ 여기까지 아니면 스킬 본문을 본다

exit code를 못 믿는 도구는 산출물 존재로 다시 확인합니다.

sips -s format webp in.png --out out.webp && test -f out.webp

파일이 안 보이면 무시 규칙부터 확인합니다.

git check-ignore -v skills/lib/newfile.ts

테스트 결과 개수가 의심스러우면 축약 출력을 버리고 전체 출력을 봅니다.

vitest run path/to/file.test.ts > /tmp/out.log 2>&1
grep -n "FAIL\|✓\|✗" /tmp/out.log

하지 말 것

exit code만 보고 && 체인으로 성공을 판정하기. 파일을 만들지 않고도 exit 0을 내는 도구가 있습니다. 산출물이 실제로 생겼는지 별도로 확인합니다.

스킬이 안 걸릴 때 스킬 본문부터 고치기. 원인이 skillOverrides나 프롬프트의 전제였으면 본문을 아무리 고쳐도 안 걸립니다.

git status에 안 보이면 파일이 없다고 넘어가기. 무시 규칙에 걸려 있을 수 있습니다. git check-ignore -v로 먼저 확인합니다.