[query-inspector] SQL/ORM 쿼리 추출 및 튜닝을 수행하는 Claude Code 스킬

query-inspector는 프로젝트 소스 코드에서 SQL/ORM 쿼리를 추출해 인덱스 누락 / N+1 문제 / 안티패턴을 진단하고 튜닝하는 Claude Code 스킬입니다.

데이터가 쌓이기 전까지는 멀쩡하던 쿼리, 코드 리뷰를 통과한 N+1 문제, 코드만으로는 보이지 않는 ORM의 실제 SQL. 이런 문제를 운영 환경이 아니라 커밋 직전에 검출합니다.

자주 겪는 문제

• 인덱스 없이 배포한 쿼리가 데이터 몇만 건에서 갑자기 풀스캔으로 전환된다.
• N+1 문제가 코드 리뷰를 통과해, 목록 API 한 번에 수십 개의 쿼리가 실행된다.
• JPA나 QueryDSL이 실제로 어떤 SQL을 생성하는지, 코드만으로는 알 수 없다.
• 코드 리뷰는 로직을 검토하지, "이 변경이 생성할 쿼리"를 SQL 관점으로 분석하지는 않는다.
• QA 단계에서도 발견하기 어렵다. 테스트 데이터가 적어 인덱스 누락이나 N+1 문제가 성능 저하로 드러나지 않기 때문이다.

이 문제들은 대부분 배포한 뒤에야 드러난다는 공통점이 있습니다.

query-inspector는 그 시점을 커밋 직전으로 옮깁니다.

query-inspector 개요

Claude Code 플러그인이고, 두 개의 스킬로 이루어져 있습니다.

• tuning-report - git 변경분에서 SQL/ORM 쿼리를 추출해 인덱스 누락 / N+1 / 안티패턴을 진단하고, 바로 적용할 수 있는 수정안을 리포트로 생성합니다.
• inventory-report - 프로젝트가 실행하는 쿼리를 본문 전문과 인덱스 커버까지 목록으로 정리합니다.

둘 다 코드를 직접 수정하지 않고 리포트만 생성합니다.

커밋 직전에 한 번 실행하면, 배포 후에야 드러날 성능 문제를 미리 발견할 수 있습니다.

차별점

기존에도 런타임 SQL 로깅(p6spy, Hibernate statistics)이나 APM으로 쿼리 성능을 점검하는 방법은 있었습니다. 다만 이들은 쿼리가 실행된 뒤에야 문제가 드러납니다.

query-inspector는 실행하기 전에, 커밋 직전 변경분에서 점검한다는 점이 다릅니다.

실행 없이 ORM이 생성할 SQL을 추론하는 이 방식은 최근 AI의 발전으로 비로소 현실화할 수 있게 되었습니다.

변경분만, 커밋 흐름 그대로

전체를 매번 검사하지 않고 마지막 튜닝 이후 변경된 부분만 분석합니다.
따라서 빠르고, git add -> query-inspector 실행 -> 커밋이라는 평소 흐름에 자연스럽게 통합됩니다.

물론 프로젝트 전체 스캔도 가능합니다.

코드에 직접 드러나지 않는 SQL 추론

직접 작성한 SQL은 물론이고, JPA 파생 메서드 / @Query / QueryDSL / Kotlin JDSL / MyBatis 동적 쿼리도 "실제로 생성될 SQL"을 추론하여 분석 또는 추출합니다.

각 쿼리에는 EXACT / INFERRED / AMBIGUOUS 신뢰도 라벨이 붙어, 어디까지 신뢰할지 판단할 수 있습니다.

정적 분석부터 실 DB 실행계획까지, 원하는 깊이로

DB 없이도 대부분의 문제(인덱스 누락 / N+1 / SQL 방언 불일치 / 안티패턴)를 검출합니다.

더 확신이 필요할 때만 개발 DB에 직접 접속해 실제 EXPLAIN 까지 확인합니다.

안전을 위해 운영 DB 접속은 기본으로 차단되고, 읽기 전용 쿼리만 수행합니다.

바로 사용하는 리포트

"이 부분이 느릴 수 있음" 수준에서 끝나지 않습니다.

컬럼 순서까지 갖춘 CREATE INDEX 문, 정확한 파일:라인, 복사해서 바로 사용할 수 있는 Action Items를 제공합니다.

개발자 또는 그 개발자를 돕는 AI가 이 리포트를 보고 바로 수정 작업에 착수할 수 있습니다.

이전 제안 반영 추적

이전 실행의 제안과 현재 코드를 대조해, 아직 반영되지 않은 항목을 다시 식별합니다.

이번에 수정하지 않은 파일이라도 식별의 대상이 됩니다.

JVM 중심 스택, 다국어 리포트

현재 버전은 Kotlin/Java(JPA·Hibernate·QueryDSL·MyBatis·native SQL)에 특화돼 있습니다. Python(Django/SQLAlchemy)도 지원하지만, 주력 스택만큼 검증되지는 않았습니다.

앞으로 스택을 계속 확장해 나갈 예정입니다.

SQL 방언(MySQL/MariaDB, PostgreSQL)은 자동으로 감지합니다.

리포트는 Claude와 대화 중인 언어로 출력됩니다(강제 지정도 가능합니다).

리포트 예시

tuning-report가 변경분을 분석해 생성하는 리포트의 일부입니다.

# Query Tuning Report - 증분(변경 파일 2)
- 심각도(미해결): 🔴 3 / 🟡 2 / ⚪ 1   /   이전 제안: ✅ 2건 해결 / ⚠️ 2건 여전히 미반영

## 🔴 [critical] 인덱스 누락 - FK `orders.user_id` - OrderMapper.xml
- 왜 치명적: N+1 자식 쿼리라 user N명마다 `orders` 풀스캔.
- 제안:  CREATE INDEX idx_orders_user_id ON orders (user_id);
- 검증(실 DB EXPLAIN): `type: ALL -> ref` 로 개선 확인.

같은 프로젝트를 inventory-report로 확인하면, 튜닝 대신 쿼리 목록을 나열합니다.

# Query Inventory
- 쿼리 수: 24 ( SELECT 18 / INSERT 3 / UPDATE 2 / DELETE 1 )

#### [order-03] 사용자별 주문 목록 조회
- 원천: OrderMapper.xml:42 (selectOrdersByUser) / 유형: SELECT
- 대상: orders / 접근 컬럼: WHERE user_id, ORDER BY created_at
- 인덱스 커버: ❌ 미커버 (user_id 인덱스 없음)

고쳐야 할 곳을 찾으려면 튜닝 리포트를, 무엇이 실행되는지 전부 확인하려면 인벤토리를 사용하면 됩니다.

시작하기

설치와 사용법은 GitHub README(한국어)에 정리돼 있습니다. github.com/jogakdal/query-inspector

Claude Code가 있다면 다음 명령 두 줄로 설치할 수 있습니다.

claude plugin marketplace add jogakdal/query-inspector
claude plugin install query-inspector@query-inspector-marketplace

결과물을 먼저 확인하려면, 저장소의 리포트 예시와 도커 예제 환경을 참고할 수 있습니다.

아직 v1.0.0입니다. 사용해 본 뒤 GitHub 이슈로 피드백을 남기면 개선에 반영하겠습니다. 유용하다면 star도 환영합니다.

다음 커밋 전에 한 번 실행해 보세요.