9. 내 일에 필요한 서브에이전트 만들기

claude code subagents create
claude code subagents create

원하는 역할부터 이야기합니다

앞 글에서는 별도 역할에게 일을 맡길 때 방법과 원칙, 이번 프로젝트의 맥락이 함께 필요하다고 이야기했습니다.

그러면 그 역할은 어떻게 만들까요? 저는 원하는 일을 설명하고 AI에게 초안을 만들게 합니다. 만든 내용을 보고, 실제로 써보면서 고칩니다.

수업에서도 현재 공식 가이드와 만들려는 역할의 의도를 함께 주는 방법을 보여드립니다. 이미 써보고 좋았던 역할이 있다면 어떤 점이 좋았는지도 이야기할 수 있습니다. 그 파일 전체를 독자가 가지고 있어야 시작할 수 있다는 뜻은 아닙니다.

중요한 것은 ‘전문가처럼 해줘’에서 조금 더 나아가는 겁니다. 무슨 자료를 보고, 무엇을 판단하고, 어떤 결과를 가져와야 하는지 설명하면 됩니다.

Step 1. 지금 문제와 원하는 결과를 말합니다

이번에는 컴퓨터 안의 요청서와 제안서 초안을 대조하는 역할을 생각해보겠습니다. 설명을 위해 새로 잡은 가상 업무입니다.

받은 요청서와 내가 만든 제안서 초안을 따로 대조할 역할을 만들고 싶어.
요청한 항목이 빠졌는지, 자료에 없는 내용을 확정해서 쓰지는 않았는지 봐줬으면 해.
문제마다 어느 파일의 어떤 내용이 근거인지 알려줘.
파일을 직접 고치지는 말고, 내가 확인할 부분을 돌려줘.

제가 파일을 하나씩 검사하는 방법이나 도구 이름부터 설계한 것은 아닙니다. 필요한 결과를 설명한 겁니다.

AI가 어느 자료를 대상으로 할지, 어떤 항목이 중요한지 물으면 답합니다. 단순히 문장이 매끄러운지 보는 역할인지, 요청 충족과 근거를 대조하는 역할인지도 다릅니다. 이번에는 후자를 맡기겠습니다.

Step 2. 현재 형식으로 구성하게 합니다

현재 Claude Code 공식 서브에이전트 가이드를 확인해서 역할 파일을 만들어줘.
로컬 자료를 읽고 찾는 데 필요한 도구만 쓰게 하고,
역할과 반환 형식이 내 요청에 맞는지 설명해줘.
어느 범위에 저장하면 좋을지와 기존 역할 중복도 먼저 확인해줘.

현재는 자연어로 Claude에게 파일 작성을 맡길 수 있습니다. /agents를 입력해도 예전의 단계별 생성 마법사가 아니라 파일을 작성하는 방법을 안내합니다. 옛 메뉴 화면을 따라 찾을 필요는 없습니다. 현재 생성 안내

저장 위치는 역할을 어디에서 쓸지에 따라 정합니다.

범위 위치 선택 이유
프로젝트 .claude/agents/ 이 업무나 팀의 자료와 기준에 맞는 역할
사용자 ~/.claude/agents/ 같은 컴퓨터의 여러 프로젝트에서 개인적으로 쓸 역할

경로를 외워서 직접 파일을 만들라는 뜻은 아닙니다. 이번 역할에 어떤 범위가 맞는지 AI와 정하면 됩니다. 같은 이름이 두 범위에 있으면 프로젝트 역할이 사용자 역할보다 우선합니다. 이름이 겹치지 않는지도 보는 이유입니다.

역할 파일을 읽어봅니다

아래는 방금 가상 업무를 위한 새 공개 최소 예시입니다. 개인 리서치워커를 복사한 것이 아니며, 이 글을 읽은 것만으로 설치되는 역할도 아닙니다.

---
name: proposal-notes-reader
description: 로컬 요청서와 제안서 초안을 읽고 요구 누락과 근거 없는 확정을 대조할 때 사용한다.
tools: Read, Glob, Grep
---

# 제안 자료 대조 역할

전달받은 요청서와 초안을 직접 읽고, 요청 항목과 실제 내용을 대조한다.
파일을 수정하지 않는다.

## 판단 기준
- 요청 항목마다 초안의 대응 내용을 찾는다.
- 일정과 비용을 확정한 문장은 근거 자료와 맞춰본다.
- 읽지 못한 자료나 없는 근거를 추측으로 채우지 않는다.

## 반환할 결과
- 요청 항목별 충족·누락·확인 불가
- 판단의 근거가 되는 파일과 위치
- 총괄이 수정하거나 추가 확인할 사항

위쪽 --- 사이가 설정이고, 아래쪽이 역할 지침입니다. 설정과 본문이 같은 문서에 들어 있지만 역할은 다릅니다.

name과 description

서브에이전트에는 name과 description이 필요합니다. name은 역할 이름이고, description은 언제 무엇을 맡길지 판단하는 설명입니다.

‘제안서를 잘 봐준다’보다 ‘요청서와 초안을 읽고 요구 누락과 근거 없는 확정을 대조한다’가 범위를 더 잘 보여줍니다. 어떤 단어를 넣으면 무조건 실행되는 마법 문장은 아닙니다.

tools

이 역할에는 세 가지 도구만 넣었습니다.

  • Read: 파일 내용을 읽습니다.
  • Glob: 파일 이름과 경로 패턴으로 찾습니다.
  • Grep: 파일 안의 내용을 검색합니다.

서브에이전트의 tools는 사용할 도구의 허용 목록입니다. 이 예시는 로컬 자료를 읽고 찾는 역할입니다. 새 인터넷 조사를 하거나 파일을 수정하는 역할로 설명하면 안 됩니다.

필요한 도구가 달라지면 구성도 달라져야 합니다. 새 웹 조사가 필요한 역할이라면 실제 사용할 수 있는 인터넷 도구와 접근 조건을 확인해야 합니다. tools를 생략하면 상속받는 도구 범위가 넓어질 수 있지만, 모든 접근과 행동이 무제한으로 허용된다는 뜻은 아닙니다.

스킬에서 봤던 allowed-tools와도 다릅니다. 스킬의 그 필드는 호출한 턴의 사전 승인이었고, 여기의 tools는 역할이 사용할 도구를 정합니다. 역할의 도구 설정

본문은 어떤 판단을 할지 알려줍니다

이 예시에서는 문장을 대신 고치는 것이 아니라 요청과 초안의 어긋남을 찾도록 했습니다. 읽지 못한 자료가 있으면 ‘문제없음’이나 ‘실패’로 단정하지 않고 확인 불가로 돌려주게 했고요.

‘비용을 확정한 문장은 근거와 대조한다’를 빼면 검토에서 놓치는 범위가 달라질 수 있습니다. ‘맞춤법만 본다’로 바꾸면 전혀 다른 역할이 되겠죠. 파일 이름보다 이런 원칙과 반환 기준을 봐야 합니다.

모델을 따로 지정할 수도 있지만, 이 최소 예시에서는 생략했습니다. 특정 모델이 언제나 기본이라거나 복잡한 일은 무조건 특정 모델이어야 한다는 표보다, 역할의 자료와 판단 범위를 먼저 맞추겠습니다.

Step 3. 이번 업무의 자료를 전달합니다

역할 파일에는 반복해서 쓸 방법이 들어갑니다. 실제로 맡길 때는 이번 요청과 자료를 줍니다.

proposal-notes-reader에게 이번 요청서와 제안서 초안을 대조하게 해줘.
어떤 파일을 봐야 하는지 정리해서 전달하고,
필수 요청의 누락과 근거 없는 일정·비용 확정을 확인해줘.
초안은 수정하지 말고, 근거 위치와 확인할 사항을 받아와.

총괄 Claude Code가 자료를 찾고, 어느 파일을 어떤 목적으로 읽을지 묶어 넘기게 합니다. 대상이 여러 개라 애매하면 확인하면 됩니다.

기본 서브에이전트는 부모 대화 전체를 자동으로 이어받지 않습니다. 제가 조금 전에 다른 자료를 읽었다고 그 역할도 이미 아는 것은 아닙니다. 필요한 요청과 자료, 받은 결과를 어떻게 쓸지 전달하는 이유입니다.

Step 4. 등록과 실제 호출을 확인합니다

파일이 생긴 것과 역할이 실제로 실행된 것은 다릅니다. AI에게 저장한 정의가 발견되는지와 실제 별도 위임이 일어났는지 나눠 확인하게 합니다.

이미 감시 중인 agents 폴더 안에서 추가하거나 바꾼 파일은 다음 위임에 반영됩니다. 다만 세션을 시작할 때 없던 agents 폴더를 처음 만들었다면 재시작이 필요합니다. 추가 디렉터리에서 가져온 역할이나 감시가 꺼진 환경에도 재시작 조건이 있습니다. 모든 경우에 저장 즉시 된다고 볼 수는 없습니다. 역할 변경 반영 조건

이름을 말했는데 일반 답변만 나왔다면 역할이 실행됐다고 단정하지 않습니다. 별도 위임 표시와 대상 역할을 봅니다. 현재 위임 도구 이름은 Agent입니다. 글에 호출처럼 생긴 문자열을 적는 것과 실제 도구 실행이 일어난 것도 다르고요.

안 되면 ‘description을 더 세게 써줘’부터 반복하기보다 파일 위치와 필수 필드, 등록 상태, 사용 가능한 도구를 확인해야 합니다.

결과가 역할에 맞는지도 봅니다

다음은 이 역할을 확인하는 설명용 가상 자료입니다. 실제 고객 요청이나 실행 결과가 아닙니다.

자료 내용
요청서 일정은 미정이며 협의 후 확정한다
초안 행사는 11월 10일 개최로 확정한다

이 두 파일을 읽었다면 확정의 근거가 없다는 차이를 짚어야 합니다. 날짜가 적혀 있다는 이유로 요청을 충족했다고 하면 안 됩니다.

반대로 요청서를 읽지 못했다면 같은 결론을 확정할 수 없습니다. 무엇을 못 읽었고 왜 판단할 수 없는지 돌려줘야 합니다. ‘근거가 없다’와 ‘근거를 확인하지 못했다’도 구별할 수 있어야 합니다.

테스트에서는 이런 차이를 봅니다. 요청의 누락을 찾는지, 실제 파일의 근거 위치를 주는지, 읽지 못한 경우를 구별하는지, 수정하지 말라는 범위를 지키는지요.

만든 파일을 한 번 읽어본 것으로 끝내지 않고, 결과가 목표와 맞는지를 봅니다. 도구가 제한된 역할이라면 총괄이 받은 내용을 적용하고 수정하는 단계도 별도로 남아 있습니다.

쓰면서 역할을 고칩니다

처음 초안이 완벽할 필요는 없습니다. 결과를 보고 필요한 기준을 더하면 됩니다.

‘요청 항목을 몇 개 빠뜨렸어. 항목별로 대응한 곳을 먼저 나눠서 봐줘.’

‘근거 파일 이름만 있어서 찾기 어려워. 어느 부분인지 함께 돌려줘.’

AI가 역할 파일을 수정하면, 이전에 문제가 났던 자료와 다른 자료에 다시 써봅니다. 지침이 바뀐 것과 결과가 고쳐진 것을 함께 확인하는 겁니다.

제가 서브에이전트를 만드는 방식도 이 흐름입니다. 원하는 역할을 설명하고, 현재 가이드로 구성하고, 내용을 읽고, 실제로 맡겨본 뒤 고칩니다.

다음으로는 별도 역할을 활용해 요청과 실제 결과를 대조하는 이야기를 보겠습니다. 기존 번호로는 11편입니다. 사이트의 발행 순서상 다음은 10편 OSMU지만, 기본 학습은 역할 제작 다음에 확인과 대조로 이어가는 순서를 권합니다.

Subscribe to 비개발자를 위한 Claude Code | 일을 잘하기 위한 AI Workspace

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
[email protected]
Subscribe