Claude Code /agent 커맨드로 커스텀 서브에이전트 만들기 | Playbook Tip

메타 엔지니어가 공개한 워크플로 중에 꽤 실용적인 게 있어요. 유닛 테스트 작성 요청을 매번 Claude Code에 직접 하는 대신, 그 역할만 전담하는 서브에이전트를 /agent 커맨드로 만들어두는 방식이에요. 한 번 만들어두면 "테스트 써줘"라고 할 때마다 같은 지시를 반복할 필요가 없어요.

특정 역할을 반복적으로 시키는 상황이라면 이 방식이 맞아요. 코드 리뷰 전담, 문서 작성 전담, 번역 전담 등 뭐든 패턴이 반복되면 서브에이전트로 분리할 수 있어요.

준비물

Claude Code 최신 버전 (서브에이전트 기능은 비교적 최근에 추가됐어요)
Claude Code가 열려 있는 터미널 세션

스텝

1. /agent 커맨드 실행

Claude Code 채팅창에 다음을 입력해요. 이 커맨드가 서브에이전트 생성 UI를 띄워줘요.

/agent

2. 에이전트 이름과 설명 입력

이름은 나중에 호출할 때 식별자로 쓰이니까 짧고 명확하게 짓는 게 좋아요. 설명은 이 에이전트가 어떤 역할인지 적어두는 메모 같은 거예요.

Name: unit-test-writer
Description: 주어진 함수나 모듈에 대한 유닛 테스트를 작성하는 전담 에이전트

3. 시스템 프롬프트 작성

이 에이전트가 항상 따를 지시를 여기에 넣어요. 매번 타이핑하던 내용을 여기에 한 번만 써두면 돼요.

You are a unit test specialist. When given a function or module, write comprehensive unit tests using the project's existing test framework. Always check for edge cases, null inputs, and error conditions. Match the style and conventions already present in the codebase.

4. 툴 권한 선택

서브에이전트가 어떤 툴에 접근할 수 있는지 선택해요. 유닛 테스트 에이전트라면 파일 읽기와 쓰기 정도면 충분해요. 불필요한 권한은 주지 않는 게 안전해요.

허용할 툴:
✅ Read files
✅ Write files
❌ Execute commands
❌ Web search

5. 모델 선택

어떤 Claude 모델을 이 에이전트에 쓸지 고를 수 있어요. 테스트 작성처럼 정확도가 중요한 작업엔 가장 강력한 모델을 쓰는 게 낫고, 빠른 반복이 필요한 작업엔 더 빠른 모델을 쓰면 돼요.

Model: claude-opus-4-5  # 또는 프로젝트 상황에 맞게 선택

6. 색상 설정

여러 에이전트를 쓸 때 채팅창에서 시각적으로 구분하기 위한 설정이에요. 취향대로 고르면 돼요.

Color: 🟢 Green  # 유닛 테스트 에이전트엔 초록색이 어울리더라고요

설정을 저장하면 에이전트가 생성돼요.

확인 방법

생성된 에이전트를 호출해서 실제로 동작하는지 봐요.

@unit-test-writer src/utils/formatDate.ts 파일에 대한 테스트 작성해줘

에이전트가 시스템 프롬프트에 적은 지시를 따라 테스트를 작성하면 성공이에요. 채팅창에서 설정한 색상으로 응답이 표시되는 것도 확인할 수 있어요.

응용

같은 방식으로 code-reviewer, doc-writer, migration-helper 같은 에이전트를 추가로 만들 수 있어요. 에이전트마다 다른 모델을 쓰는 것도 가능해서, 빠른 리뷰는 가벼운 모델로, 복잡한 리팩터링은 강력한 모델로 분리하는 식으로 쓸 수 있어요.

트러블슈팅

/agent 커맨드가 보이지 않는 경우: Claude Code 버전이 오래됐을 가능성이 높아요. claude --version으로 확인하고 업데이트하면 돼요.

에이전트가 툴 권한 밖의 작업을 시도하는 경우: 시스템 프롬프트에 "파일 읽기와 쓰기만 사용해"처럼 명시적으로 제한을 써두는 게 안전해요.

@에이전트명으로 호출이 안 되는 경우: 이름에 공백이나 특수문자가 들어가면 인식이 안 될 수 있어요. 하이픈만 쓰는 게 안전해요.

이 설정으로 반복되는 역할을 한 번만 정의해두고 계속 재사용할 수 있게 돼요.

준비물

스텝