Claude Code 도메인 스킬로 코드 탐색 효율을 올릴 수 있다

요약

• Claude Code에 도메인 참조 스킬(파일 맵, pitfall, 시스템 흐름도)을 제공했을 때 도구 호출 40% 감소, 토큰 24% 절감 효과를 확인
• pitfall 방지 효과는 코드에서 발견 가능한 수준의 함정에서는 유의미한 차이 없음
• 스킬의 핵심 가치는 "어떤 파일을 읽어야 하는지" 사전 안내에 있음
• 특히 외부 API 연동(Agora, Twilio 등) 영역은 코드만으로 파악 불가능한 제약사항이 많아 스킬 효과가 더 큼

본문

배경

connectingServer 프로젝트에 5개 도메인 스킬(agora-stt, call-evaluation, sms-auth, agora-v2v, channeltalk-workflow)을 작성해두고, 실제 작업에서 도움이 되는지 A/B 실험으로 검증했다.

실험 설계

Feature A: 동일 작업 A/B 비교

• 동일한 구현 작업("VoiceQualityEvaluation에 HUMOR 카테고리 추가")을 두 에이전트에 할당
• Agent A: 스킬 없이 소스코드만 보고 작업
• Agent B: 도메인 스킬(call-evaluation)을 프롬프트에 포함하고 작업
• 각각 독립 worktree에서 실행, 탐색 과정을 로그로 기록

Feature B: 측정 지표

• 정량: 토큰 사용량, 도구 호출 수, 파일 읽기 횟수, grep/glob 횟수
• 정성: pitfall 인지 여부, 코드 품질 차이, 불필요 탐색 여부

Feature C: 스킬 정확성 사전 검증

• 실험 전에 5개 스킬의 파일 경로, API, pitfall, 상수를 코드 대조로 spot-check
• sms-auth에서 캐시 TTL 오류 1건, agora-v2v에서 Redis lock key 오류 1건 발견
• channeltalk-workflow는 main에 코드가 없는 외부 문서 요약 성격으로 확인

실험 결과

지표	A (스킬 없음)	B (스킬 있음)	차이
토큰 사용량	95,172	72,569	-24%
도구 호출 수	43	26	-40%
파일 읽기	16	9	-44%
Grep/Glob	8	4	-50%

Pitfall 회피: 둘 다 bulk_create/save() 불일치 문제를 독자적으로 발견. 차이 없음.

코드 품질 차이: B가 하드코딩된 count == 3을 count == self.MAX_LIMIT_CATEGORY로 개선. A는 count == 4로 단순 교체. 스킬에서 "카테고리 수 동기화 필요"라는 맥락을 얻었기 때문.

불필요 탐색: A는 admin.py, chat 관련 파일 등 5개를 참고용으로 읽었으나 수정에 불필요. B는 스킬의 파일 맵을 보고 관련 파일만 정확히 탐색.

판단

• 파일 맵 + pitfall 섹션 = 유지 가치 높음 (탐색 효율의 직접적 원인)
• 상수 나열, API 엔드포인트 목록 = 제거 가능 (코드에서 즉시 파악 가능하다고 실험이 증명)
• 외부 문서 요약형 스킬 (channeltalk-workflow) = 가치 낮음, stale 위험
• 코드에서 발견 불가능한 pitfall (외부 SDK 제약 등) = 추가 실험 없이도 논리적으로 가치 자명
• 외부 API 연동 영역은 스킬 효과가 더 큼 — Agora의 "RTM 2.x는 007 토큰만 허용", Twilio의 "발송/확인 조건 동기화 필수" 같은 제약은 코드에 단서가 없고 외부 문서를 읽어야만 알 수 있음. 에이전트가 웹 검색 없이 이런 제약을 사전에 파악할 수 있는 유일한 경로가 스킬

참고