클로드코드로 나만의 AI 부하직원 만들기 · 1편

클로드코드로 나만의 AI 부하직원 만들기 · 1편

5분이면 첫 담당자가 생겨. 진짜로.

폴더 하나 만들고, 파일 하나 쓰고, 확인. 오늘 끝나면 동작하는 코드 리뷰어가 손에 남아.

0편에서 "파일 하나면 된다"고 했지? 오늘 그걸 진짜 손으로 해볼 거야. 개발 잘 몰라도 괜찮아. 타이핑만 할 수 있으면 돼.

준비물 → 클로드코드가 이미 설치돼서 터미널에서 claude 명령이 돌아가는 상태면 돼. 아직 설치 전이면 이 편은 북마크해두고 설치부터 하고 오자.

1단계. 담당자들이 살 방(폴더) 만들기

서브에이전트는 정해진 폴더 안에 있어야 클로드코드가 알아봐. 프로젝트 폴더로 이동한 다음, 그 안에 .claude/agents 폴더를 만들어주자. (윈도우 PowerShell 기준이야)

PowerShell

# 내 프로젝트 폴더로 이동 (경로는 네 것으로 바꿔)
cd C:\projects\my-spring-app

# 담당자들이 살 폴더 생성
mkdir .claude\agents

폴더 이름 앞에 점(.)이 붙는 게 포인트야. 오타 아니고 원래 이렇게 생겼어. 탐색기에서 안 보이면 '숨김 항목 표시'를 켜면 보여.

참고 → 폴더 위치가 두 군데야. 지금처럼 프로젝트 안(.claude/agents)에 두면 그 프로젝트에서만 쓰이고, 홈 폴더(~/.claude/agents)에 두면 어느 프로젝트에서든 따라다녀. 처음엔 프로젝트 안으로 시작하는 게 헷갈리지 않아.

2단계. 첫 담당자 파일 쓰기

이제 방금 만든 폴더 안에 code-reviewer.md 파일을 만들 거야. 메모장이든 VSCode든 아무 편집기로 열어서 아래 내용을 그대로 붙여넣자.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드 변경사항을 검토해서 버그, 보안 문제, 스타일 이슈를 찾는다.
  코드를 새로 쓰거나 수정한 뒤에 사용.
tools: Read, Grep, Glob
---

너는 Spring Boot / MyBatis 프로젝트 전문 코드 리뷰어야.

리뷰할 때 반드시 확인할 것:
1. SQL 인젝션 가능성 (MyBatis 에서 ${} 직접 사용 여부)
2. 널 체크 누락
3. 트랜잭션 처리 누락 (@Transactional)
4. 네이밍 컨벤션 위반

결과는 이 형식으로 정리해줘:
- 심각(반드시 고쳐야 함)
- 경고(고치는 게 좋음)
- 제안(있으면 좋음)

각 항목마다 파일명과 문제 코드, 개선안을 같이 보여줘.
너는 리뷰만 해. 파일을 직접 수정하지는 마.

지금은 내용을 완벽히 이해할 필요 없어. 이게 왜 이렇게 생겼는지는 2편에서 낱낱이 뜯어볼 거야. 오늘은 "아 이렇게 생긴 파일을 넣는구나"만 느끼면 돼.

따라 칠 때 주의 → 위 예시에서 description이 보기 좋으라고 두 줄로 나뉘어 있는데, 그냥 한 줄로 쭉 이어서 써도 돼. 두 줄로 쓸 거면 두 번째 줄 앞의 띄어쓰기(들여쓰기)를 꼭 살려야 하고 — 안 그러면 파일을 못 읽어서 담당자가 안 나타나. 헷갈리면 그냥 한 줄로 쓰는 게 속 편해.

더 편한 방법도 있어 → 사실 이 파일을 직접 안 쓰고, 클로드코드한테 "코드 리뷰 서브에이전트 하나 만들어줘"라고 부탁하면 알아서 써주기도 해. 공식적으로도 이 방법을 추천하는데, 그래도 처음엔 한 번 직접 써봐야 구조가 눈에 익어. 그래서 1편은 손으로 가는 거야.

3단계. 잘 들어왔는지 확인하기

터미널에서 클로드코드를 실행한 다음, 이 명령을 쳐봐.

Claude Code 안에서

/agents

등록된 담당자 목록이 뜨는데, 여기에 code-reviewer가 보이면 채용 성공이야. 방금 만든 애가 출근했다는 뜻이지.

이렇게 나오면 성공 ✓
목록에 code-reviewer가 보이고, 옆에 "코드 변경사항을 검토해서..." 하는 설명이 같이 뜨면 완벽해. 안 보이면 파일이 .claude/agents/ 안에 있는지, 확장자가 .md가 맞는지(.md.txt로 저장되는 실수가 흔해) 확인해봐.

4단계. 진짜로 일 시켜보기

이제 평소처럼 리뷰를 부탁하면 돼. 아무 파일이나 골라서 이렇게 말해봐.

Claude Code 안에서

방금 수정한 UserService.java 리뷰해줘

그러면 팀장(클로드코드 본체)이 "어, 이건 리뷰 담당한테 맡기면 되겠네" 하고 방금 만든 code-reviewer를 알아서 호출해. 담당자가 자기 방에서 파일을 읽고, 심각/경고/제안으로 정리해서 결과를 가져다줄 거야.

어때, 별거 없지? 폴더 하나 + 파일 하나 = 나만의 코드 리뷰어 완성. 이게 서브에이전트의 전부야.

다음 편 예고 → 2편에선 방금 붙여넣은 그 파일을 줄 단위로 뜯어볼 거야. 특히 "왜 내 에이전트는 안 불려나오지?" 하는 흔한 문제의 범인, description을 제대로 파헤쳐볼게. 이거 하나 이해하면 담당자를 내 프로젝트에 딱 맞게 길들일 수 있어. 1편에서 만든 파일은 지우지 말고 그대로 둬. 다음 편에서 계속 쓸 거야!