Claude Code를 쓰면서 CLAUDE.md와 스킬을 계속 쌓아왔다면, 그중 상당수는 이미 일을 안 하고 있을 가능성이 큽니다. 제 경우 스킬 49개 중 13개가 아예 죽어 있었고, 살아있는 것들끼리는 서로 반대되는 지시를 하고 있었습니다.
이 글은 그걸 어떻게 찾아냈는지의 기록입니다. 각 단계마다 그대로 복사해 칠 수 있는 명령어를 넣었으니, 읽으면서 자기 환경도 같이 점검해보셔도 됩니다.
발단 — 규칙을 지웠는데 성능이 그대로였다
앤트로픽의 Thariq Shihipar가 2026년 7월 24일에 The new rules of context engineering for Claude 5 generation models를 올렸습니다. Claude 5 세대 모델(Opus 5, Fable 5) 기준으로 Claude Code의 시스템 프롬프트를 80% 넘게 지웠는데, 자체 코딩 평가에서 측정 가능한 성능 손실이 없었다는 내용입니다.
"AI한테 규칙을 촘촘히 적어줄수록 좋다"는 통념과 정반대죠. 모델이 좋아질수록, 예전 모델의 약점을 막으려고 쌓아둔 규칙들이 오히려 비용이 된다는 겁니다.
실제로 앤트로픽은 자기네 사용 기록에서 "문서를 적절히 남겨라"와 "주석은 절대 달지 마라"가 한 요청에 동시에 들어간 충돌을 발견했다고 합니다. 모델은 결국 맞는 답을 찾지만, 그 전에 이 모순부터 중재해야 합니다. 판단하지 않아도 될 일에 판단을 쓰는 거죠.
원문이 제시한 원칙은 여섯 가지입니다.
- 딱딱한 규칙 대신 모델의 판단에 맡기기
- 사용 예시를 붙이는 대신 인터페이스를 잘 설계하기
- 전부 미리 넣지 말고 점진적 공개로 필요할 때 로드하기
- 지시를 반복하지 말고 도구 설명을 단순하게 하기
- 수동 CLAUDE.md 항목보다 자동 메모리를 활용하기
- 마크다운 설명보다 코드·스펙·평가 기준 같은 실물 레퍼런스 주기
이번 점검에 직접 쓴 건 1·3·4번입니다. 나머지는 다음 라운드에 다룹니다.
그래서 궁금해졌습니다. 내 세팅은 어떨까? 스킬 49개, 프로젝트 12개를 굴리는 환경을 이 기준으로 전수 점검해봤습니다.
점검 1 — 스킬 49개를 열어보니: 좀비 13마리
먼저 숫자부터 쟀습니다. 매 세션 무조건 로드되는 건 스킬 본문이 아니라 설명문입니다. 이게 상시 비용이죠.
# 스킬 개수와 설명문 글자 수 (매 세션 상시 비용)
ls -d ~/.claude/skills/*/ | wc -l
grep -h "^description:" ~/.claude/skills/*/SKILL.md | wc -m
당시 결과는 **49개 / 10,769자(약 3,600토큰)**였습니다.
그런데 목록을 하나씩 검증하다가 이상한 걸 발견했습니다. 스킬 13개가 깨진 심링크였습니다.
# 화살표가 가리키는 원본이 사라진 링크 = 좀비
find ~/.claude/skills -maxdepth 1 -type l ! -exec test -e {} \; -print
얼마 전 맥을 옮기면서 링크가 가리키던 원본 폴더가 사라졌는데, 목록에는 계속 "있는 척" 떠 있었던 겁니다. 호출하면 조용히 실패하는 좀비들이죠.
웃긴 건, 제가 "디자인 스킬이 너무 많아서 겹치는 것 같은데"라고 걱정하던 스킬들의 절반이 애초에 이 좀비 목록에 있었다는 점입니다. 정리를 걱정하기 전에, 뭐가 살아있는지부터 확인해야 했던 거죠.
→ 13개 삭제. 49개 → 36개.
점검 2 — 살아있는 스킬끼리의 진짜 충돌
살아남은 스킬 중에서 앤트로픽이 말한 "규칙 충돌"의 실물을 찾았습니다. 웹디자인 스킬 두 개가 정면으로 부딪히고 있었습니다.
| 주제 | 스킬 A (taste) | 스킬 B (high-end) |
|---|---|---|
| Inter 폰트 | 조건부 허용 (미니멀 브리프일 때) | 전면 금지 |
| 세리프 폰트 | 기본값으로는 비권장 | 디스플레이로 권장 |
둘 다 "AI 티 나는 디자인을 막자"는 같은 목적의 스킬인데, 각론이 반대입니다. 두 스킬이 같이 잡히는 순간 모델은 디자인 대신 규칙 중재부터 해야 합니다.
같은 주제를 다루는 스킬이 있는지는 이렇게 훑을 수 있습니다.
# 특정 키워드를 다루는 스킬이 몇 개인지 (폰트, 주석, 커밋 등으로 바꿔가며)
grep -rl "폰트\|font" ~/.claude/skills/*/SKILL.md
더 정교한 조건부 규칙을 가진 쪽 하나만 남기고 삭제했습니다.
→ 최종 35개.
점검 3 — CLAUDE.md 9개 등급 판정: 반전이 있었다
프로젝트를 전수 조사하니 CLAUDE.md는 9개였습니다.
# 흩어져 있는 CLAUDE.md 모두 찾기
find ~/Documents -name "CLAUDE.md" -not -path "*/node_modules/*" | xargs ls -la
하나씩 열어 채점했습니다. 기준은 단순합니다 — "열어보면 알 수 있는 것"은 감점, "겪어봐야 아는 것"은 가점.
반전 1: 제일 큰 파일이 제일 건강했습니다. 7.3KB짜리 앱 프로젝트 CLAUDE.md는 용량만 보면 다이어트 1순위인데, 내용이 전부 함정이었습니다. "Xcode GUI로 설정 만지지 마라(생성 파일이라 날아간다)", "유료 계정 없으니 시뮬레이터 검증만", "이 아키텍처 결정은 재논의 금지", 그리고 복붙하면 바로 도는 검증된 빌드 커맨드. 전부 코드를 열어봐도 알 수 없는 것들입니다. 삭제 대상이 아니라 모범 사례였습니다.
반전 2: 제일 작은 파일에 버그가 있었습니다. 1.4KB짜리 가장 가벼운 CLAUDE.md에서, 오픈소스 저장소를 클론하면서 딸려온 원저자의 맥 경로가 그대로 남아 있는 걸 발견했습니다. 이 지시를 따르면 무조건 실패합니다.
# 내 것이 아닌 사용자 경로가 박혀 있는지 (결과 없으면 정상)
grep -rn "/Users/" --include="CLAUDE.md" ~/Documents | grep -v "/Users/$(whoami)/"
미리 써둔 글은 환경이 바뀌는 순간 거짓말이 됩니다. 죽은 심링크와 정확히 같은 병입니다.
점검 4 — "없는 것"도 점검 대상이다
CLAUDE.md가 없는 프로젝트 9개도 판정했습니다. 결론은 셋으로 갈렸습니다.
- 없는 게 정답 (4곳) — 잡일함, 에셋 전달 폴더 등. 억지로 문서를 만드는 것 자체가 새 규칙 위반
- README로 충분 (3곳) — 코드 프로젝트들. 셋업 문서가 이미 제 역할
- 있는데 연결이 안 돼 있던 곳 (3곳) — 여기가 진짜 수확이었습니다
세 번째가 재밌습니다. 한 디자인 프로젝트에는 "AI agents: 이렇게 생성해라"라는 지시문까지 적힌 브랜드 가이드가 있었는데, 어떤 세션도 그 파일을 자동으로 읽지 않고 있었습니다. 열심히 써놓고 연결을 안 한 거죠.
처방은 원칙 그대로. 본문을 복사하지 않고 가리키기만 하는 781바이트짜리 CLAUDE.md를 만들었습니다. "브랜드 규칙은 DESIGN.md, 폴더 지도는 구조.md" 두 줄에 함정 세 줄. 끝.
다른 두 프로젝트는 README가 이미 함정 문서라서 심링크 한 줄로 해결했습니다.
# 같은 내용을 두 파일에 복사하지 않는다 — 한쪽만 고쳐지면 그게 충돌이 된다
ln -s README.md CLAUDE.md
결과 정리
| 항목 | Before | After |
|---|---|---|
| 스킬 | 49개 (좀비 13 포함) | 35개 |
| 스킬 규칙 충돌 | 1건 (폰트 규칙 정면충돌) | 0건 |
| CLAUDE.md 버그 | 1건 (남의 경로) | 0건 |
| 자동 로드 안 되던 문서 | 3곳 | 0곳 (포인터/심링크로 연결) |
| 메모리 | 6.7KB — 통과 | 그대로 |
claude doctor도 문제 0건이었습니다.
결론 — "지워라"가 아니라 "성격을 가려라"
이번에 지운 건 좀비·충돌·중복이었고, 제일 크고 규칙 많은 파일은 오히려 만점을 받았습니다. 기준은 용량이 아니라 딱 하나였습니다.
열어보면 알 수 있는 것은 지우고, 겪어봐야 아는 것만 남긴다.
그리고 하나 더 — 모델이 한 세대 올라갈 때마다 이 점검은 다시 해야 합니다. 지금 제 일을 하고 있는 규칙도, 다음 모델에서는 비용이 될 수 있으니까요.
5분 자가 점검
위에 나온 명령어를 순서대로 모았습니다. 복사해서 그대로 쓰시면 됩니다.
# 1. 좀비 — 목록엔 있는데 실제로는 죽은 스킬
find ~/.claude/skills -maxdepth 1 -type l ! -exec test -e {} \; -print
# 2. 비용 — 매 세션 상시 로드되는 설명문 글자 수
grep -h "^description:" ~/.claude/skills/*/SKILL.md | wc -m
# 3. 충돌 — 같은 주제를 다루는 규칙이 두 곳 이상에 있나
grep -rl "폰트\|주석\|커밋" ~/.claude/skills/*/SKILL.md
# 4. 버그 — 내 것이 아닌 경로가 박혀 있나
grep -rn "/Users/" --include="CLAUDE.md" ~/Documents | grep -v "/Users/$(whoami)/"
# 5. 전수 — CLAUDE.md가 어디에 몇 개 있나
find ~/Documents -name "CLAUDE.md" -not -path "*/node_modules/*" | xargs ls -la
여기에 명령어로는 확인이 안 되는 두 가지를 더하면 점검이 끝납니다.
- 성격 확인 — CLAUDE.md에서 "폴더 열어보면 아는 것"(구조 나열)을 지우고 "겪어봐야 아는 것"(함정·제약·확정사항)만 남기기
- 날짜 확인 — "다음 할 일" 같은 시점 스냅샷이 박제돼 있지 않은가? 그건 CLAUDE.md가 아니라 메모리나 이슈로
다음 글에서는 이 점검 결과를 바탕으로 CLAUDE.md를 처음부터 어떻게 쓰면 되는지 정리해보겠습니다.
