10. md 한 장으로 동료를 만드는 법 : 서브에이전트

⏰

5교시 · 15:00~15:50 개념 15분 · 실습 견적서 작성 담당 만들기 · 견적서 1장 20분 · 스몰 프로젝트 내 일에 담당 한 명 15분 쉬는 시간 15:50~16:00

즉석 동료에서 전담 동료로

🧭

클로드 코드는 큰 작업을 받으면 여러 동료를 즉석에서 소환해 나눠 맡기기도 합니다(병렬 작업, 부록 '다이내믹 워크플로우'에서 다룹니다). 이번 장에서는 그 동료 한 명(서브에이전트)의 정체를 들여다보고, 반복 업무용 나만의 전문 동료를 직접 만듭니다. '4가지 문서' 중 행동(action) 그룹의 두 번째입니다.

이번에는 전문 동료 한 명을 만들어, 직접 불러서 일을 시키는 데까지 진행해보겠습니다.

1. 회사엔 부서마다 담당자가 있다

우리 회사엔 부서마다 담당자가 있습니다.

영업본부 : 거래처 견적, 수주 응대

운항팀 : 선박 스케줄, 항만 관리

해사기술팀 : 선박 정비, 안전

안전관리팀 : 현장 점검, 사고 예방

📌

한 사람이 모든 일을 다 잘하기 어렵다. 그래서 여러 부서로 나뉘어져 있음

그 부서를 부르면 그 일은 그 자리에서 처리된다

해야할 일을 다른 사람에게 똑같이 설명할 일 없다

2. 담당자 = 그 영역의 전문가

부서마다 담당자를 두는 이유는, 그 담당자가 그 영역의 전문가이기 때문입니다.

📌

담당자는 그 영역의 룰을 알고 있다

영업본부 담당자는 거래처 응대의 격식과 견적 룰을 안다

운항팀 담당자는 항로, 항만의 패턴을 안다

매번 처음부터 설명하지 않아도, 자기 기준으로 처리한다

결과 품질이 한결같이 유지된다

3. AI에게도 그런 동료가 필요하다 = 서브에이전트

AI에게도 같은 구조가 가능합니다.

🎯

서브에이전트 = 한 장의 md 파일로 만든 전문 동료 1명

한 번 만들어 두면 그 일은 그에게 맡기면 끝

📌

사람의 회사와 같은 구조

영업 담당이 견적 본문을 직접 쓰지 않는다. 견적서 작성 담당에게 맡긴다

영업 담당 = 오케스트레이터 견적서 작성 담당 = 서브에이전트

AI도 같은 방식

3-1. 클로드 코드의 변모 : 작업자에서 오케스트레이터로

3-2. 오케스트레이터 = 지금 나와 대화하는 클로드

💡

오케스트레이터는 따로 설치하는 프로그램이 아닙니다

지금 채팅창에서 나와 대화하고 있는 클로드 코드(메인 에이전트)를 부르는 이름입니다

나는 오케스트레이터하고만 이야기합니다. 서브에이전트와 직접 말하지 않습니다

📌

오케스트레이터가 하는 일은 셋

나눈다 : 「견적서 만들어줘」를 받으면 견적 작성, 검토, 사람 승인처럼 단계로 나눈다

맡긴다 : 서브에이전트 파일의 description을 보고, 직접 할지 누구에게 맡길지 정해 부른다

모은다 : 돌려받은 결과를 합쳐 다음 단계로 넘기고, 보내기 전에는 나에게 묻는다

	오케스트레이터	서브에이전트
정체	지금 대화 중인 클로드	오케스트레이터가 부른 클로드
나와의 대화	봅니다	못 봅니다 (넘겨받은 것만 압니다)
다른 서브에이전트 부르기	부릅니다	못 부릅니다
읽는 파일	CLAUDE.md	`.claude/agents/이름.md` 한 장

🎯

오케스트레이터 = 나와 대화하며 일을 나눠 맡기고, 결과를 모아 오는 메인 클로드

둘 다 같은 클로드입니다. 다른 점은 누가 나와 대화하고 있느냐뿐입니다

💡

컨텍스트 = AI가 한 대화에서 가지고 있는 '작업 기억'

앞서 다룬 그 컨텍스트 : 대화가 길어질수록 이 기억 공간이 차고, 핵심이 묻힌다

서브에이전트는 자기만의 컨텍스트에서 일한다

조사, 시행착오 같은 지저분한 과정은 거기서 끝나고, 메인엔 깔끔한 결과만 돌아온다
컨텍스트를 아낄 수 있어 토큰 사용량을 경제적으로 관리하는 장점도 있음

4. 언제 서브에이전트가 필요한가?

서브에이전트를 만들 이유는 크게 세 가지입니다.

🎯

1) 새로운 관점이 필요할 때

선입견 없는 독립된 시각 : 메인 대화 흐름을 보지 않고 자기 컨텍스트에서 판단한다

예 : 견적 초안을 비판적 사고로 검토하는 검수 담당, 다른 부서 시각으로 짚어보는 담당

🧩

2) 여러 스킬을 적재적소에 묶어 줄 전문가가 필요할 때

일정한 기준으로 반복해서, 상황에 맞는 스킬을 골라 쓰도록(한 번 쓰고 말 일이면 굳이 만들 필요 없다)

예 : 견적서 작성 담당이 격식체, 표 정리, 비용 계산 스킬을 골라 적용

🧩

3) 토큰을 더더욱 경제적으로 사용할 필요가 있을 때

어떤 유료 계정이든 토큰 사용량에 제한이 있어, 경제적으로 사용할 필요가 있음

서브에이전트는 에이전트마다 모델을 지정할 수 있어, 설계는 비싼 모델이, 작업은 값싼 모델이 하도록 세팅 가능

5. 4가지 문서에서 서브에이전트의 위치

📌

앞서 메모리에서 본 4가지 문서 지도를 다시 떠올립니다

위 2개(CLAUDE.md, 메모리) = 지식. AI에게 무엇을 알게 할지

아래 2개(Skill, 서브에이전트) = 행동. AI에게 어떻게 행동시킬지

이번 장은 행동의 두 번째 : 서브에이전트

6. Skill과 서브에이전트, 무엇이 다른가

🎯

이 일을 누구에게 시킬까?

💡

한 가지 질문으로 갈린다

매뉴얼 1장이면 해결되는가?

YES → Skill (자주 하는 작업의 매뉴얼)

NO → 서브에이전트 한 명 (비슷한 작업들의 매뉴얼 묶음 + 전문가 페르소나)

한 명으로도 안 끝나면? → 여러 동료를 동시에 부르는 병렬 작업(다이내믹 워크플로우, 부록)

결과	언제	우리 회사 예시
Skill	매번 같은 절차	주간 회의록 정리, 월간 항차 실적 보고서
서브에이전트 1명	특정 관점, 전문성 필요	견적서 작성 담당, 시황 분석가 → 전문가 페르소나 or 여러 개 스킬의 묶음

📌

서브에이전트는 여러 매뉴얼을 골라 쓰는 전문가

Skill = 매뉴얼 한 장. 한 가지 작업의 설명서

서브에이전트 = 여러 매뉴얼을 체화한 전문가 한 명(상황을 보고 어느 매뉴얼을 사용할지 스스로 판단)

예 : 견적서 작성 담당은 격식체 작성, 표 정리, 비용 계산 같은 여러 매뉴얼로 요청에 맞게 골라 적용

6-1. 폴더 구조로 보기

스킬은 .claude/skills, 서브에이전트는 .claude/agents 에 들어갑니다. 견적 업무 폴더 예시입니다.

6-2. 일하는 방식의 차이

스킬은 메인 대화 안에서 직접 하고, 서브에이전트는 자기 컨텍스트에서 끝낸 뒤 결과만 돌려줍니다.

7. 서브에이전트를 어떻게 만드나

💡

위치와 구조

위치 : .claude/agents/<이름>.md

한 폴더 안에 여러 명을 둠 (한 명당 md 한 장)

frontmatter(md 문서 상단의 기본 정보 칸) 4줄 + 본문 = 한 명의 동료

🔧

md 파일을 손으로 처음부터 쓸 필요 없음

오케스트레이터에 한 줄로 부탁 :

"견적서 작성 담당이라는 서브에이전트를 만들어줘. 격식체로 견적서 본문 작성 전담이고, 외부 검색은 사용하지 않게."

오케스트레이터가 알아서 .claude/agents/견적서작성담당.md 한 장을 만들어 준다

학습자는 만들어진 파일을 한 번 훑어보고 미세 조정만 하면 충분

8. 어떻게 호출하나

💡

두 가지 방법

명시 호출 : 사용자가 누구에게 시킬지 직접 지정

자동 라우팅 : description 매칭으로 오케스트레이터가 알아서 부름

9. ⚠️ 주의사항

⚠️

서브에이전트 한 명을 쓸 때 챙길 두 가지

처음에는 자동 라우팅에 맡기지 말고 누구에게 시킬지 직접 지정해 부른다(엉뚱한 동료가 잡히는 것을 막는다)

결과 분량에 상한을 둔다(너무 길게 답하면 메인 대화의 맥락이 그만큼 차서 마무리 품질이 떨어진다)

10. 실습 : 서브에이전트 한 명 만들어 써보기

🎯

거래처가 보낸 메일, 브로커 시세, 사내 운항 메모처럼 흩어진 자료를, 견적서 작성 담당 한 명에게 맡겨 깔끔한 격식 견적서 한 장으로(명령 한 줄에)

📎

실습 자료 받기

입력 3개 : 거래처 견적 문의 메일(docx), 브로커 시세 메모(md), 사내 운항 메모(xlsx · 운항 정보, 부대비용, 결제조건) · 형식과 정리 상태가 제각각

양식 1개 : 견적서_양식_샘플.xlsx (빈 양식 · 상하이와 닝보를 나란히 적는 칸)

아래 zip 파일을 받아 압축을 풀면 견적실습 폴더가 나옵니다

vs code에서 견적실습 폴더를 엽니다

서브에이전트_실습자료.zip46.58 KiB

1️⃣

Step 1. 견적서 작성 서브에이전트 만들기

채팅창에 그대로 입력 : "견적서 작성 서브에이전트를 만들어줘. 이름은 quote-writer. 이 폴더의 거래처 메일, 브로커 시세 메모, 사내 운항 메모를 읽고 견적서_양식_샘플.xlsx 양식 그대로 격식 있는 견적서를 만든다. 자료에 없는 값은 지어내지 말고 '확인 필요'로 표시한다. 외부 검색은 쓰지 않는다."

.claude 폴더에 파일을 만들어도 되는지 묻는 창이 뜨면 허용을 누릅니다

만들어진 .claude/agents/quote-writer.md 를 열어 맨 위 줄(name · description · tools)을 확인합니다. tools 에 WebSearch · WebFetch 가 없으면 외부 검색을 하지 않습니다

고칠 곳이 있으면 채팅창에 "quote-writer 파일에서 ○○를 고쳐줘" 라고 부탁합니다

2️⃣

Step 2. 다시 실행하고 견적 맡기기

방금 만든 서브에이전트는 클로드 코드를 다시 실행해야 부를 수 있습니다. 만든 대화나 /clear 로는 「찾을 수 없다(not found)」가 나옵니다 (스킬은 /clear 로도 됩니다)

터미널에서 /exit 로 끝내고, 같은 폴더에서 claude 를 다시 실행합니다

채팅창에 그대로 입력 : "quote-writer 에게 맡겨서, 이 폴더의 견적 문의 메일에 대한 견적서를 견적서_양식_샘플.xlsx 와 같은 양식의 엑셀 파일로 만들어줘."

화면에 quote-writer 가 불렸다는 표시가 나오는지 봅니다

3️⃣

Step 3. 결과 확인

폴더에 새로 생긴 견적서 엑셀을 열어 아래 값과 맞춰 봅니다 (USD, 40HC 1개 기준)

해상운임 상하이 580 · 닝보 330 (시세 메모 9월 4주차)

THC 140 · 서류발급비 30 (사내 운항 메모 부대비용)

유류할증 15 (브렌트유 $91 → 1단계 × USD 15)

합계 상하이 765 · 닝보 515

결제조건 T/T 선불 (신규 거래처 · 최초 3회 선적까지, 사내 운항 메모 결제조건 표)

자료에 없는 견적번호 · 견적일 · 유효기간은 '확인 필요'로 남았는지

같은 요청을 한 번 더 해서 같은 양식으로 나오는지

11. 🌱 스몰 프로젝트 : 내 일에 전문 동료 한 명 붙이기

🌱

내가 매번 같은 기준으로 반복하는 일 하나를 골라, 그 일 전담 동료 한 명을 만들어봅니다

오늘 실습과 같은 순서입니다 : 고르기 → 만들기 → 다시 실행해서 부르기 → 다듬기 (15분)

재료는 1회차에 받은 내 직무 엑셀 하나면 됩니다. 파일이 없으면 1회차 직무 자료에서 다시 받습니다

1️⃣

Step 1. 고르기 (3분)

새 폴더(예 : 내서브에이전트)에 내 직무 엑셀을 넣고, VS Code에서 그 폴더를 엽니다

아래 표에서 내 직무 줄을 고릅니다. 마땅한 게 없으면 채팅창에 그대로 입력 : "이 폴더의 내 직무 엑셀을 보고, 매번 같은 기준으로 반복하는 일 중 서브에이전트로 만들 만한 것 3개를 추천해줘. 각각 영문 이름, 하는 일 한 줄, 기준 한 줄로."

직무 폴더	이름 예	맡길 일 (내 엑셀의 열 기준)
01 선사영업	booking-checker	상태가 부킹대기 · 롤오버인 건과 B/L발급일이 빈 건(취소 제외)을 담당자별로 정리 (수입은 D/O발급일)
02 고객지원	reply-writer	긴급 · 재문의 건을 먼저 골라 문의유형별 답변 초안 작성
03 운항	delay-reporter	지연시간이 긴 항차를 지연사유별로 정리
04 컨테이너장비	repair-checker	수리비가 크거나 체류일수가 긴 건 표시 (수급은 재고상태 · 반납지연)
05 선사지점	cutoff-checker	반입률이 낮거나 롤오버가 생긴 항차 정리
06 경영관리	expense-reviewer	예산보다 많이 집행한 건 · 결제기한이 지난 미수금 표시
07 물류영업	lost-quote-reporter	수주하지 못한 견적을 미수주사유별로 정리
08 물류센터	stock-reporter	입고 · 출고를 화주별로 모아 매주 같은 양식으로 보고, 반출예정일이 지난 건 표시
09 운송	order-checker	작업일이 지났는데 완료가 아닌 오더 정리
10 포워딩	margin-checker	이익이 낮은 선적 건 · 처리일수가 긴 업무 표시
11 선박관리	finding-tracker	조치기한이 지났는데 조치완료일이 빈 지적 사항 정리 (탱커는 증서만료일)

💭

무엇을 만들지 고민될 때

아래 세 질문 중 하나라도 「예」이면 후보입니다

매주 · 매달 같은 파일을 열어 같은 것을 찾는 일인가?
누가 해도 같은 기준으로 나와야 하는 일인가?
내가 만든 것을 다른 눈으로 한 번 더 봐야 하는 일인가?

그래도 모르겠으면 채팅창에 그대로 입력 : "나는 ○○팀에서 ○○를 한다. 내가 매주 반복하는 일을 한 번에 질문 하나씩, 5개까지 물어봐줘. 다 듣고 나면 서브에이전트로 만들 만한 일 하나를 골라 영문 이름, 하는 일, 기준으로 정리해줘."

피할 것 : 한 번 하고 말 일, 기준이 매번 바뀌는 일, 승인 · 협상처럼 사람이 정해야 하는 일. 이런 건 그냥 대화로 충분합니다

매번 같은 순서만 필요하고 판단이 필요 없다면 서브에이전트보다 스킬이 더 맞습니다 (6절)

2️⃣

Step 2. 만들기 (5분)

아래 문장에서 【】 세 곳만 바꿔 채팅창에 입력합니다

"서브에이전트를 만들어줘. 이름은 【영문 이름】. 이 폴더의 【내 엑셀 파일】을 읽고 【맡길 일】을 표로 정리해 엑셀로 저장한다. 자료에 없는 값은 지어내지 말고 '확인 필요'로 표시한다. 돌려줄 때는 파일 경로와 5줄 요약만."

예 (수출영업 2팀) : "서브에이전트를 만들어줘. 이름은 booking-checker. 이 폴더의 수출영업2팀_부킹내역 엑셀을 읽고 상태가 부킹대기 · 롤오버인 건과 B/L발급일이 빈 건(취소 제외)을 담당자별 표로 정리해 엑셀로 저장한다. (뒤는 같음)"

파일을 만들어도 되는지 묻는 창이 뜨면 허용

3️⃣

Step 3. 다시 실행해서 부르기 (5분)

터미널에서 /exit 로 끝내고 claude 를 다시 실행합니다. 만든 대화나 /clear 로는 아직 불리지 않습니다

채팅창에 입력 : "【영문 이름】 에게 맡겨서 이 폴더의 내 엑셀을 정리해줘."

폴더에 새 엑셀이 생기고, 채팅창에는 5줄 요약만 돌아오면 성공입니다

4️⃣

Step 4. 다듬기 (2분)

결과를 보고 아쉬운 점을 그대로 말합니다 : "방금 결과에서 ○○가 빠졌어. 【영문 이름】 파일에 반영해줘."

고친 뒤에는 /exit → claude 로 다시 실행해 불러 확인합니다

✅

다 됐는지 확인

.claude/agents/ 에 내 서브에이전트 파일이 한 장 있다

다시 실행한 뒤 이름으로 불렀더니 결과 엑셀이 생겼다

채팅창에는 긴 내용 대신 5줄 요약만 돌아왔다

12. 다른 pc에서 사용 하고 싶다면?

폴더를 구글 드라이브 업로드 후 다른 pc에서 vs code에서 열어서 사용

깃허브에 업로드 후 다른 pc에서 다운 받아서 사용

다음 시간 미리보기 : 여러 명이 이어 일하면

내 PC에서 사용하고 싶다면?