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

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

왜 내 에이전트는 안 불려나오지?

1편에서 붙여넣은 그 파일, 이제 줄 단위로 뜯어보자. 설정 3개 + 본문 1개, 딱 이 구조만 알면 돼.

1편에서 만든 code-reviewer.md 기억나지? 오늘은 그 파일이 왜 그렇게 생겼는지 뜯어볼 거야. 구조를 알면 내 프로젝트에 맞게 마음대로 고칠 수 있거든.

파일은 크게 두 덩어리로 나뉘어. 위쪽 --- 사이에 있는 설정 부분(프론트매터)이랑, 그 아래 본문(성격서). 설정 부분엔 항목이 3개(name, description, tools) 들어가니까, 결국 설정 3개 + 본문 1개인 셈이야. 다시 한번 보자.

.claude/agents/code-reviewer.md

---                                ← 여기서부터
name: code-reviewer               ① 이름
description: 코드 변경사항을...    ② 언제 부를지
tools: Read, Grep, Glob           ③ 쓸 수 있는 도구
---                                ← 여기까지가 설정

너는 Spring Boot / MyBatis 전문 리뷰어야... ④ 본문 = 성격서

① name — 담당자 이름표

name

이 담당자를 부를 때 쓰는 고유 이름

영어 소문자에 하이픈(-)으로 짓는 게 관례야. code-reviewer, test-runner처럼. 나중에 "code-reviewer 써줘"라고 콕 집어 부를 때 이 이름을 써.

별거 없어. 그냥 이름이야. 파일 이름이랑 똑같이 맞춰두면 관리하기 편해.

② description — 가장 중요한 한 줄

description

"이 담당자를 언제 불러야 하는가"의 판단 기준

팀장(클로드코드 본체)이 이 문장만 보고 "지금 이 담당자를 부를까 말까"를 결정해. 그래서 이게 흐리멍덩하면 담당자가 있어도 안 불려나와.

바로 이게 "왜 내 에이전트는 안 불려나오지?"의 범인이야. description을 애매하게 쓰면 팀장이 언제 써야 할지 몰라서 그냥 자기가 처리해버리거든.

아쉬운 예 ✕
description: 코드 리뷰
→ 너무 짧아. 언제 써야 하는지 팀장이 감을 못 잡아.

좋은 예 ○
description: 코드를 새로 쓰거나 수정한 뒤에 사용. 버그와 보안 문제를 찾는다.
→ "~한 뒤에 사용" 같은 트리거 문구를 넣으면 팀장이 타이밍을 딱 잡아. 영어로 쓸 땐 "Use this agent when..." 또는 "use proactively"로 시작하면 더 잘 먹혀.

③ tools — 손에 쥐여줄 도구

tools

이 담당자가 쓸 수 있는 도구 목록 (화이트리스트)

Read(파일 읽기), Grep(내용 검색), Glob(파일 찾기), Edit(수정), Bash(명령 실행) 등을 골라서 줘. 여기 적은 것만 쓸 수 있어.

리뷰어한테는 Read, Grep, Glob만 줬지? 읽고 찾기만 하면 되니까. Edit이나 Bash를 일부러 뺀 거야. 그러면 이 담당자는 아무리 실수해도 파일을 못 고치고 명령도 못 돌려. 안전장치인 거지. (이 얘기는 4편에서 제대로 다룰게)

알아두면 좋은 것 → tools 줄을 아예 빼면 어떻게 될까? 그럼 팀장이 가진 모든 도구를 물려받아. 편하긴 한데 위험할 수 있어. 그래서 처음엔 필요한 것만 딱 적어주는 습관이 좋아.

④ 본문 — 담당자의 성격서

--- 아래 모든 글이 이 담당자의 성격이자 업무 지침이 돼. 여기 적은 대로 담당자가 행동해. "너는 누구고, 뭘 확인하고, 결과를 어떤 형식으로 줘야 하는지"를 적으면 돼.

팁 하나. 담당자는 이 본문 말고는 아무것도 모른다고 생각하고 써. 클로드코드 본체가 아는 걸 이 담당자는 모를 수 있거든. 그래서 결과를 어떤 형식으로 달라는 것까지 딱 적어주면 훨씬 쓸모 있어져. 우리 리뷰어가 "심각/경고/제안으로 정리해줘"라고 못박은 것처럼.

이제 내 프로젝트에 맞게 고쳐보자

구조를 알았으니 응용이야. 예를 들어 JSP랑 IBSheet를 주로 쓰는 프로젝트라면, 본문을 이렇게 바꿔볼 수 있어.

.claude/agents/code-reviewer.md (본문만 수정)

너는 우리 회사 레거시 웹 프로젝트 전문 리뷰어야.

리뷰할 때 확인할 것:
1. JSP 스크립틀릿 안에서 SQL 직접 조립 여부
2. IBSheet 데이터 바인딩 시 XSS 위험
3. jQuery 이벤트 중복 바인딩
4. 예외 처리 없이 넘어가는 구간

결과는 심각/경고/제안 순으로,
파일명과 라인 위치를 꼭 같이 표시해줘.

보이지? 뼈대(name, description, tools)는 그대로 두고 본문만 우리 상황에 맞게 갈아끼운 거야. 이게 서브에이전트를 '나만의 것'으로 만드는 방법이야.

다음 편 예고 → 3편은 짧고 실용적이야. 만든 담당자를 부르는 방법 두 가지를 배울 거야. 알아서 오게 둘 것인가, 콕 집어 부를 것인가. 그리고 요즘 버전에서 바뀐 /agents 명령 얘기도 짚어줄게. 이거 모르면 헤맬 수 있거든. 그럼 3편에서 봐!