클로드코드 서브에이전트 · 실전편

클로드코드 서브에이전트 · 실전편

개발자라면 이런 에이전트부터 만들어봐

코드 리뷰어 하나 만들고 나면 드는 생각 — "그래서 또 뭘 만들지?" 그 답을 정리했어.

서브에이전트를 처음 만들어보면 신기하긴 한데, 딱 하나 만들고 나서 막히는 순간이 와. "이제 뭘 더 만들어야 잘 쓰는 거지?" 오늘은 그 이야기야.

정답은 사실 간단해. 네가 매번 반복하는 귀찮은 일이 곧 담당자 후보야. 아래는 개발자들이 실제로 반복하는 일들을 계열별로 묶은 거야. 다 만들 필요는 없고, 네 상황에 걸리는 것부터 하나씩 뽑으면 돼.

표시 읽는 법 — 각 담당자 옆에 붙은 딱지는 권한 수준이야.
읽기 전용 아무것도 못 망가뜨려. 첫 타자로 안전해.
수정 가능 파일을 고쳐. 작은 것부터 검증하고 쓰자.
실행 가능 명령을 돌려. 제일 신중하게.

① 코드 품질 계열 — 첫 타자로 딱

코드 리뷰어의 사촌들이야. 읽고 지적만 하니까 사고 날 일이 없어. 처음 시작하기에 제일 좋은 계열이야.

보안 스캐너 읽기 전용

리뷰어 중에서도 보안만 집요하게 파는 애야. SQL 인젝션, XSS, 인증·인가 빠진 구간만 골라서 봐. 범위가 좁은 만큼 놓치는 게 적어.

tools: Read, Grep, Glob

리팩터링 도우미 읽기 전용

"이 메서드 200줄인데 이렇게 쪼개면 어때?" 하고 제안만 하는 애. 직접 고치진 않으니까 마음 놓고 의견을 들어볼 수 있어.

tools: Read, Grep, Glob

보안 스캐너는 이렇게 생겼어. 레거시 프로젝트에서 특히 값을 해.

.claude/agents/security-scanner.md

---
name: security-scanner
description: 코드에서 보안 취약점만 집중해서 찾는다. 배포 전이나 코드 수정 후에 사용.
tools: Read, Grep, Glob
---

너는 보안 점검 담당이야. 기능이나 스타일은 신경 쓰지 말고
보안 문제만 파고들어.

집중해서 볼 것:
1. SQL 인젝션 - 쿼리에 문자열을 직접 이어붙이는 곳
2. XSS - 사용자 입력이 화면에 그대로 출력되는 곳
3. 인증/인가 누락 - 권한 체크 없이 열려있는 엔드포인트
4. 민감정보 노출 - 하드코딩된 비밀번호, 키, 로그에 찍히는 개인정보

보고 형식:
- 위험도(높음/중간/낮음)
- 파일명과 위치
- 왜 위험한지 한 줄
- 어떻게 고치면 되는지

너는 찾아내고 알려주기만 해. 직접 고치지는 마.

② 생성 계열 — 백지에서 시작하는 수고 덜기

맨땅에서 시작하는 게 제일 힘들잖아. 초안을 대신 깔아주는 애들이야. 실제로 파일을 쓰니까 권한이 한 단계 올라가.

테스트 작성기 수정 가능

서비스 클래스를 보고 단위 테스트 초안을 짜줘. 그대로 쓰긴 어렵고 손은 봐야 하지만, 빈 파일 노려보는 것보단 백배 나아.

tools: Read, Grep, Write

문서 작성기 수정 가능

주석 없는 코드에 JavaDoc을 달거나, README·API 명세 초안을 만들어줘. 다들 미루다 안 하는 그 일.

tools: Read, Grep, Edit, Write

커밋 메시지 도우미 읽기 전용

변경된 코드를 보고 깔끔한 커밋 메시지를 제안해줘. "수정", "ㅇㅇ" 같은 커밋 로그에서 벗어날 수 있어. 제안만 하니 읽기 전용으로 충분해.

tools: Read, Grep

③ 실행·검증 계열 — 제일 신중하게

실제로 명령을 돌리는 애들이야. 강력한 만큼 권한도 조심해서 줘야 해.

테스트 러너 실행 가능

테스트를 돌리고 실패한 것만 골라서 정리해줘. 로그 수백 줄에서 빨간 줄 찾는 시간이 사라져.

tools: Read, Grep, Bash

로그 분석기 실행 가능

에러 로그 뭉치를 던지면 "이 스택트레이스의 진짜 원인은 여기, 이 파일 몇 번째 줄 봐라" 하고 짚어줘. 실무에서 체감이 제일 큰 애 중 하나야.

tools: Read, Grep, Bash

순서를 지키자 → 실행 계열은 처음부터 만들지 마. 읽기 전용 담당자로 먼저 감을 잡고, 결과가 믿을 만해지면 그때 Bash를 쥐여주는 게 안전해. 급할수록 돌아가는 게 맞더라고.

④ 데이터·SQL 계열 — 느린 쿼리 잡을 때

쿼리 점검기 읽기 전용

SQL이나 매퍼 파일을 보고 "이 조건이면 인덱스 안 타겠는데?", "이 조인 순서 바꾸는 게 나아" 하고 성능 관점에서 짚어줘. 읽고 분석만 하니 읽기 전용으로 충분해.

tools: Read, Grep, Glob

실제 파일로 보면 이래.

.claude/agents/query-inspector.md

---
name: query-inspector
description: SQL과 매퍼 파일을 성능 관점에서 점검한다. 쿼리를 새로 짜거나 느린 쿼리를 찾을 때 사용.
tools: Read, Grep, Glob
---

너는 SQL 성능 점검 담당이야.

점검할 것:
1. 인덱스를 못 타는 조건 (컬럼에 함수 적용, 앞자리 와일드카드 LIKE 등)
2. 불필요한 전체 조회 (필요 없는 SELECT *, 조건 없는 조회)
3. 비효율적인 조인 순서나 중복 조인
4. 페이징 처리가 필요한데 전체를 다 가져오는 곳
5. N+1 문제를 유발할 수 있는 반복 조회

보고 형식:
- 문제 쿼리 위치 (파일명, 쿼리 ID)
- 무엇이 문제인지
- 개선안 (바꾼 쿼리 예시 포함)
- 예상 효과 한 줄

실행 계획을 직접 볼 수 없으니, 확신이 없으면
"이건 실제 EXPLAIN으로 확인 필요"라고 표시해줘.

⑤ 레거시 이해 계열 — 인수인계 문서가 없을 때

레거시 해설사 읽기 전용

오래된 코드를 던지면 "이 화면이 무슨 일을 하고, 이 함수는 어디서 호출되는지" 풀어서 설명해줘. 문서 하나 없는 옛날 코드 파악할 때 시간을 확 줄여줘.

tools: Read, Grep, Glob

이 계열은 의외로 활용도가 높아. 새 프로젝트에 투입됐을 때, 남이 짠 코드를 넘겨받았을 때, 몇 년 전 내가 짠 코드를 다시 볼 때(...) 전부 해당되거든.

그래서 뭐부터 만들까

딱 하나만 고르라면 읽기 전용 계열에서 지금 제일 아쉬운 것을 골라. 보안이 걱정되면 보안 스캐너, 쿼리가 느리면 쿼리 점검기, 남의 코드 파악이 힘들면 레거시 해설사.

이유는 두 가지야. 읽기 전용이라 실수해도 아무 피해가 없고, 결과를 보면서 "아 description을 이렇게 써야 잘 불려오는구나", "본문을 이렇게 적으니 원하는 형식으로 나오는구나" 하는 감을 안전하게 익힐 수 있거든. 그 감이 쌓이면 수정·실행 권한 주는 것도 무섭지 않아져.

욕심내지 말자 → 처음부터 담당자 열 명 뽑아놓으면 오히려 안 쓰게 돼. 어떤 애를 언제 부르는지 헷갈리거든. 하나 만들어서 2주 써보고, 진짜 쓸모 있으면 다음 애를 뽑는 리듬이 제일 오래가.

정리하면

담당자를 뽑는 기준은 딱 하나야 — 내가 매번 반복하는 귀찮은 일인가? 그렇다면 담당자 후보고, 아니라면 굳이 안 만들어도 돼.

그리고 순서는 항상 읽기 전용 → 검증 → 권한 확대. 이것만 지키면 서브에이전트 때문에 사고 날 일은 거의 없어.

오늘 소개한 것 중에 하나 골라서 .claude/agents/에 넣어봐. 위 예제 두 개는 그대로 복사해서 써도 돼. 그럼 잘 만들어보자! 👋