Claude Code는 놀라울 정도로 뛰어납니다. 하지만 기본적으로 사용자가 프롬프트(prompt) 하는 대로 작동하며, 대부분의 프롬프트는 시니어 엔지니어가 결코 건너뛰지 않을 검사 과정을 조용히 생략합니다. '느린 엔드포인트를 수정해 달라'고 요청하면, 실제로 속도가 N+1 문제인지 측정하지 않고 관계(relation)를 기꺼이 eager-load하여 끝난 것처럼 처리합니다. 능력 자체는 존재합니다. 하지만 _규율(discipline)_은 그렇지 않습니다. 왜냐하면 사용자가 그것을 요구하지 않았기 때문입니다.

해결책은 더 큰 프롬프트가 아닙니다. 워크플로우를 **스킬(skill)**로 인코딩하는 것입니다.

스킬이란 무엇인가

Claude Code 스킬은 약간의 프런트매터(frontmatter)와 지침 본문으로 구성된 Markdown 파일(SKILL.md)입니다. 프런트매터는 이 스킬을 발견 가능하게 만드는 요소입니다:

---
name: n-plus-one-hunter
description: "N+1 쿼리 문제와 뜨거운 경로(hot-path) 데이터베이스 낭비를 찾아 수정합니다. 페이지가 느리거나, DB CPU 사용량이 높거나, 트래픽 이벤트 전에 사용하세요."
...

이 description 부분이 핵심입니다. Claude가 언제 이 스킬을 사용할지 결정하는 기준이 됩니다.

1. 정적으로 의심 사례 찾기 (Locate suspects statically). ORM (Object-Relational Mapping)과 그 지연 로딩 (lazy-loading) 관용구를 식별하세요. 루프, .map, 그리고 템플릿 반복문 내부의 관계 접근(relation access)을 grep으로 찾으세요.
2. 쿼리 횟수로 확인하기 — 확인되지 않은 의심 사례는 절대 수정하지 마세요. 쿼리 카운팅을 설정하세요 (assertNumQueries, 엔진 이벤트 리스너 (engine event listener), Prisma $on('query')). 엔드포인트를 현실적인 N 값(2)이 아닌 20 이상의 N으로 실행하세요. 실제 N+1 문제는 N에 따라 쿼리 횟수가 증가하는 것을 보여줍니다. 엔드포인트, N, 횟수, 실행 문장(statement)을 기록하세요.
3. 선호 순서에 따라 수정하기: 즉시 로딩 (eager-load), 그 다음 DB 내 어노테이션/집계 (annotate/aggregate), 그 다음 구조 재조정 (restructure), 마지막으로 캐싱 (cache) 순으로 진행하세요 (캐싱은 최후의 수단이며, 문제를 숨길 수 있으므로 반드시 그렇게 명시해야 합니다).
4. 증명하기. 카운터를 다시 실행하고, 커밋에 수정 전/후를 기록하세요 ("queries: 142 → 4 at N=50"). 전체 테스트 스위트를 실행하세요 (즉시 로딩은 쿼리셋 (queryset)의 의미론을 변경할 수 있으므로, 테스트 변경 사항은 단순한 승인이 아니라 주의가 필요한 신호(red flag)입니다).

2단계를 주목하세요. "수정 전 확인"이라는 관문이 없다면, 의욕만 앞선 어시스턴트는 전혀 느리지 않았던 것들을 최적화하고, 그것이 실제로 도움이 되었는지 측정하지도 않을 것입니다. 이 관문이 핵심입니다.

직접 시도해보기

어떤 프로젝트에도 바로 적용할 수 있도록 이 중 두 가지를 무료 리포지토리 (repo)로 패키징했습니다:

• readme-refresh — README의 모든 주장을 코드와 대조하여 검증해야 할 대상으로 취급합니다.
• pr-description — 기억이 아닌 실제 차이점 (diff)을 바탕으로 PR (Pull Request) 설명을 작성합니다.

https://github.com/joanwinter333-rgb/claude-code-skills-free

설치 방법은 .claude/skills/ 폴더로 복사한 뒤, Claude Code에서 /를 입력하면 됩니다.

이 기능들이 유용하다면, 다음 링크에서 전체 10종 세트(레거시 감사, 마이그레이션 안전성, 보안 점검, 성능 기준점, 장애 사후 분석 등 포함)를 확인할 수 있습니다: https://winterjoy1.gumroad.com/l/qnrbr

솔직한 말씀: 이 스킬 문서들은 AI의 도움을 받아 작성되었으며, 실제 운영 중인 시스템을 유지 관리한 실무 경험을 바탕으로 다듬어졌습니다. 모든 워크플로우는 출시 전 Claude Code에서 테스트를 거쳤습니다.