커밋 직전 1분, 쿼리 지뢰를 미리 찾아주는 Claude Code 스킬 'query-inspector'
한눈에 보는 요약
query-inspector는 프로젝트 소스 코드에 숨어 있는 SQL과 ORM 쿼리를 추출해 성능 문제를 진단해 주는 Claude Code 플러그인입니다. 인덱스 누락, N+1 문제, 각종 안티패턴을 찾아내고 튜닝 가이드까지 리포트로 정리해 줍니다.
가장 큰 특징은 코드를 실행하지 않는다는 점입니다. p6spy 같은 런타임 로깅이나 APM이 "실행된 쿼리"를 보여주는 도구라면, query-inspector는 정적 분석으로 "ORM이 생성할 쿼리"를 미리 추론합니다. 즉 문제가 운영에 올라가기 전에 잡을 수 있습니다.
어떤 쿼리를 읽어낼 수 있나
지원 범위가 꽤 넓습니다.
- 생(raw) SQL
- JPA 파생 메서드(Derived Query Method)
@Query애노테이션- QueryDSL
- Kotlin JDSL
- MyBatis
현재 버전(v1.0.0)은 Kotlin/Java 중심으로 충분히 검증되었습니다. Python 생태계(Django, SQLAlchemy)도 지원 목록에 있지만, 아직 검증이 충분하지 않다고 제작자가 명시해 두었으니 참고하는 게 좋습니다.
실행 모드: 전체 vs 변경분
사용 방식은 크게 세 가지로 나뉩니다.
- 전체 스캔 — 프로젝트 전반의 쿼리를 모두 대상으로 진단
- 증분(incremental) 스캔 — git 변경분에서만 쿼리를 추출해 점검
- 추출만 — 튜닝 없이 쿼리 전문과 부가 정보만 리포트로 출력
제작자가 권하는 실전 활용법은 커밋 직전에 변경분만 돌리는 것입니다. 전체 스캔은 처음 도입할 때나 주기적인 점검용으로 한 번, 이후에는 증분 모드로 가볍게 쓰는 흐름이 자연스럽습니다. 커밋 단위로 검사하면 "이 변경이 쿼리를 망가뜨렸는지"를 바로 알 수 있어, 리뷰 부담도 줄어듭니다.
DB 접속은 선택 사항
대부분의 문제는 DB에 붙지 않아도 검출됩니다. 다만 더 정확한 판단이 필요하다면 개발용 DB에 연결해 실제 EXPLAIN 결과까지 확인할 수 있습니다.
여기서 눈여겨볼 부분은 안전 장치입니다. DB 접속 기능에는 다음과 같은 제약이 걸려 있습니다.
- 운영(production) 환경 접속 차단
- 읽기 전용 쿼리만 사용
- 접속 정보 미노출
AI 도구에 DB를 연결한다는 것이 부담스러울 수 있는 지점인데, 그 부분을 설계 단계에서 고려했다는 점이 인상적입니다.
두 가지 스킬
플러그인 안에는 목적이 다른 두 개의 스킬이 들어 있습니다.
| 스킬 | 역할 |
| --- | --- |
| tuning-report | 쿼리를 진단하고 튜닝 가이드가 포함된 리포트 생성 |
| inventory-report | 프로젝트 전체 쿼리의 목록 리포트 생성 |
inventory-report는 성능 개선 외에도 쓸모가 많습니다. 레거시 프로젝트에 새로 합류했을 때 "이 코드베이스가 DB를 어떻게 쓰고 있는지" 파악하는 지도로 활용하기 좋습니다.
정리하며
쿼리 성능 문제는 보통 배포 후 트래픽이 몰릴 때 발견됩니다. 그때는 이미 늦습니다. query-inspector가 겨냥하는 지점은 바로 이 타이밍의 격차입니다. 실행 전 정적 분석이라 런타임 도구만큼 정확하지는 않을 수 있지만, 커밋 직전에 돌리는 1분짜리 안전망으로는 충분히 매력적인 접근입니다.
Kotlin/Java 기반 백엔드 프로젝트를 Claude Code로 개발하고 있다면, 커밋 전 체크리스트에 한 줄 추가해 볼 만합니다.