에이전트로 자동화하기

workflow.md를 만들고 나면 자동화할 만한 일이 여러 개 보입니다. 한꺼번에 손대면 어느 것도 끝나지 않으므로 먼저 하나로 좁힙니다.

후보마다 세 줄을 적습니다.

• 입력 — 일이 시작될 때 들어오는 자료
• 판단 — 사람이 결정해야 하는 기준
• 출력 — 마지막에 나와야 하는 결과

세 줄이 잘 써지지 않는 후보는 아직 흐름이 정리되지 않은 것이므로 뒤로 미룹니다.

고르는 기준은 두 가지입니다.

• 판단이 적을수록 — 먼저 자동화할 값이 큽니다
• 반복이 잦을수록 — 먼저 자동화할 값이 큽니다

판단이 많이 들어가는 업무는 자동화해도 매번 사람이 다시 봐야 해서 줄어드는 일이 적습니다.

결제, 발송, 삭제, 공개처럼 되돌리기 어려운 단계가 후보에 들어 있으면 그 단계를 자동 실행 대상에서 빼고 승인 지점으로 표시합니다.

순서 아래 실행 요청을 그대로 붙여넣어 후보를 좁혀 보세요.

넷은 같은 자리를 두고 경쟁하지 않고, 무엇을 대신 해주느냐가 각각 다릅니다.

한 문장씩

• 스킬 — 절차를 적어 둔 문서입니다. “이런 일은 이 순서로 한다”를 Claude에게 가르칩니다.
• 커맨드 — 내가 직접 불러 쓰는 단축 명령입니다. 부르는 주체가 나입니다.
• 서브에이전트 — 따로 떨어진 맥락에서 일하고 결과만 돌려주는 워커입니다. 부르는 주체는 Claude입니다.
• 에이전트 팀 — 각자 독립된 세션으로 돌면서 서로 메시지를 주고받는 구성입니다.

커맨드와 서브에이전트를 가르는 기준은 누가 부르느냐입니다. 커맨드는 내가 칩니다. 서브에이전트는 내가 이름을 대지 않아도 Claude가 상황을 보고 알아서 넘깁니다.

서브에이전트와 에이전트 팀

결과만 필요하면 서브에이전트, 서로 의견을 부딪쳐야 하면 에이전트 팀입니다. 다만 팀은 토큰을 훨씬 많이 씁니다.

에이전트 팀은 지금 꺼져 있습니다

에이전트 팀은 실험적 기능이라 기본으로 비활성입니다. 설정에서 켜지 않으면 팀이 구성되지 않고 팀원도 만들어지지 않습니다.

그래서 이 유닛의 실습은 전부 서브에이전트로 합니다. 에이전트 팀은 개념만 알아 두면 됩니다. 다른 자료에서 “팀원”이라는 말이 나올 때 서브에이전트와 헷갈리지 않는 정도면 충분합니다.

팀원과 서브에이전트가 물려받는 것

둘 다 프로젝트의 규칙 파일과 연결해 둔 도구를 물려받습니다. 다른 점은 하나입니다. 팀원은 새 세션을 켜는 것과 같아서 스킬까지 그대로 로딩되지만, 리드와 나눈 대화 기록은 넘어가지 않습니다. 팀원이 받는 건 만들 때 넣어 준 지시문뿐입니다.

그래서 팀원에게 일을 맡길 때는 앞선 대화에서 정한 것을 지시문에 다시 적어 줘야 합니다.

같은 종류의 일에 매번 같은 설명을 붙이고 있다면, 그 설명을 파일로 한 번 적어 두는 편이 낫습니다. 그러면 다음부터는 Claude가 상황을 보고 알아서 그 워커에게 넘깁니다.

어디에 만드나

정의는 마크다운 파일 하나이고, 두 자리 중 하나에 둡니다.

• .claude/agents/ — 지금 프로젝트에서만 씁니다
• ~/.claude/agents/ — 내 모든 프로젝트에서 씁니다

만드는 방법도 두 가지입니다. Claude에게 만들어 달라고 요청하거나, 파일을 직접 쓰거나.

다른 자료에서 /agents를 쳐서 생성 화면을 띄우고 이름·색깔을 고르는 장면을 봤을 수 있습니다. 그 대화형 화면은 지금 없어졌습니다. 파일 위치와 적는 항목은 그대로입니다.

무엇을 적나

파일 맨 위 --- 사이에 설정을 적고, 그 아래 본문에 역할 설명을 적습니다. 본문이 그 에이전트의 시스템 프롬프트가 됩니다.

꼭 있어야 하는 건 둘뿐입니다.

• name — 소문자와 붙임표로 짓는 고유한 이름입니다
• description — 언제 이 에이전트에게 넘겨야 하는지를 적습니다

나머지는 필요할 때만 적는데, 자주 쓰는 것만 보면 이렇습니다.

• tools — 쓸 수 있는 도구를 좁힙니다. 안 적으면 쓸 수 있는 도구를 다 물려받습니다
• model — 어떤 모델로 돌릴지 정합니다. 안 적으면 본 대화와 같은 모델을 씁니다
• skills — 시작할 때 스킬 내용을 미리 들고 시작하게 합니다

만들자마자는 안 보입니다

파일을 만든 직후 같은 대화에서 불러 보면 “그런 에이전트가 없다”고 나오지만, 정의를 잘못 쓴 게 아닙니다.

쓸 수 있는 에이전트 목록은 대화를 시작할 때 정해집니다. 그래서 도중에 만든 정의는 그 대화에서는 안 보이고, 다음 대화부터 보입니다.

만들었으면 대화를 새로 시작하고 나서 확인합니다. 이걸 모르면 정의를 계속 고치면서 왜 안 되는지 찾게 됩니다.

설명이 호출을 결정합니다

Claude는 각 에이전트의 설명을 읽고 지금 요청을 넘길지 판단합니다. 그래서 설명을 어떻게 쓰느냐가 그 에이전트가 실제로 일을 하느냐 마느냐를 가릅니다.

역할만 적으면 잘 안 불려 나옵니다.

• 잘 안 되는 쪽: description: 코드 리뷰 담당
• 잘 되는 쪽: description: 파일을 고친 뒤 읽기 쉬움과 성능 관점에서 개선점을 찾을 때 사용

뒤쪽에는 언제가 들어 있고, 앞쪽에는 없습니다.

skills는 권한이 아니라 미리 들고 시작하기입니다

skills에 스킬을 적으면 그 스킬의 내용 전체가 시작할 때 주입됩니다. 설명만이 아니라 본문까지 들어갑니다.

여기에 적지 않았다고 그 스킬을 못 쓰는 건 아닙니다. 서브에이전트는 적어 두지 않은 스킬도 필요하면 불러 쓸 수 있습니다.

모든 스킬을 다 나열하지 말고, 처음부터 들고 시작해야 하는 것만 적습니다.

에이전트를 만들 줄 알게 되면 다음 질문은 “그래서 뭘 맡기지”입니다. 여기서 판단이 흔들리면 위임을 남발하게 됩니다.

기준 두 가지

규모. 도구를 몇 번 쓰면 끝나는 일은 직접 합니다. 위임에는 무엇을 해야 하는지 설명하고, 결과를 기다리고, 돌아온 것을 검수하는 시간이 듭니다.

일이 짧으면 이 왕복 시간이 실제 작업보다 길어집니다.

독립성. 지금까지의 대화를 몰라도 끝낼 수 있는 일만 넘깁니다. 서브에이전트는 자기 맥락에서 따로 일해서, 앞에서 정한 규칙이나 주고받은 결정을 모르는 채로 시작합니다. 그걸 다 설명해 줘야 한다면 위임할 만한 일이 아닙니다.

둘 다 해당할 때만 위임이 이득이고, 하나만 해당하면 대개 직접 하는 편이 빠릅니다.

위임이 이득인 쪽

• 파일을 여러 개 뒤져야 하는 조사
• 같은 작업을 대상만 바꿔 반복하는 일
• 결과 요약만 있으면 되고 중간 과정은 안 볼 일

이런 일은 중간 결과가 본 대화에 쌓이면 맥락만 무거워집니다. 따로 시키고 요약만 받는 편이 낫습니다.

위임이 손해인 쪽

• 한두 줄이면 끝나는 확인
• 앞 대화의 결정을 계속 참조해야 하는 일
• 워커 하나로 충분한데 여럿을 띄우는 경우

특히 마지막이 자주 생깁니다. 여러 관점이 필요한 일이 아니라면 하나면 됩니다.

비용도 판단에 들어갑니다

에이전트 팀은 팀원 하나하나가 별도 세션이라 토큰이 훨씬 많이 듭니다. 공식 문서도 조사·리뷰·새 기능처럼 병렬로 파고들 값이 있는 일에는 쓸 만하지만, 일상적인 작업에는 단일 세션이 낫다고 합니다.

서브에이전트는 결과가 요약돼 돌아오니 팀보다 가볍지만, 그래도 공짜는 아닙니다. “일단 위임” 대신 “이 일이 위임할 만한가”를 매번 한 번 묻는 습관이 결국 비용을 가릅니다.

다른 도구에 넘기는 방식도 있습니다

같은 원리로, 실행이 무거운 작업을 다른 회사의 코딩 도구에 넘기는 운영 방식도 있습니다. 판단은 한쪽에서 하고 실행만 다른 쪽에 맡기는 식입니다.

다만 그 도구의 계정과 구독이 따로 필요하고, 설정도 별개입니다. 이 유닛의 실습은 Claude Code 안에서만 합니다. 이런 방식이 있다는 것만 알아 두면 됩니다.

이번 수업에서 만들 것

내 업무를 다섯 가지 작업 방식에 배치한 Claude 작업 방식 선택표를 만듭니다. 표를 만든 뒤 새 세션으로 떼어낼 일 하나를 실제로 실행합니다.

다섯 가지 작업 방식

세션은 Claude Code의 대화 한 갈래입니다. Claude Desktop의 새 세션이나 작업 칩으로 일을 떼어내면 각 세션이 자기 대화 기록과 변경 내용을 따로 관리합니다. Git 저장소에서는 새 세션이 별도 작업 폴더에서 실행되므로 같은 파일을 동시에 고칠 위험도 줄어듭니다.

서브에이전트는 현재 대화가 옆일을 맡기는 전용 작업자입니다. 별도 맥락에서 조사하고 요약을 현재 대화로 돌려주므로, 긴 조사 과정이 본 대화에 쌓이지 않게 할 때 적합합니다.

세션 메시지는 이미 실행 중인 다른 세션에 상태나 발견 내용을 묻고 답하는 기능입니다. 텍스트만 전달되며 대화 기록과 파일은 함께 넘어가지 않습니다. 메시지에 결정 내용과 파일 위치를 적어야 상대 세션이 이어서 확인할 수 있습니다.

에이전트 팀은 팀장 역할의 Claude가 여러 작업자를 배정하고 공동 작업 목록을 관리하는 방식입니다. 팀원은 서로 직접 메시지를 보낼 수 있습니다. 현재 실험 기능이며 기본으로 꺼져 있고, 여러 세션을 함께 사용하므로 토큰 사용량도 늘어납니다.

새 세션과 에이전트 팀의 차이

수강생이 처음 병렬 작업을 연습할 때는 새 세션 두 개로 시작하는 편이 관리하기 쉽습니다. 각 세션에 결과물, 참고할 파일, 완료 기준을 적고 사용자가 결과를 하나씩 확인합니다. 진행 중에 두 세션이 같은 판단을 공유해야 하면 세션 메시지를 추가합니다.

에이전트 팀은 조사 결과를 서로 반박하고 보완해야 하는 일, 서로 다른 부분을 만들면서 공동 작업 목록을 계속 갱신해야 하는 일에 사용합니다. 같은 파일을 순서대로 고치거나 앞 단계가 끝나야 다음 단계가 시작되는 작업은 단일 세션에서 진행합니다.

확인할 것

선택표에 다음 네 항목이 적혀 있으면 됩니다.

• 만들 결과물이 무엇인지 적었습니다.
• 누가 작업을 조율할지 정했습니다.
• 작업자끼리 중간 결과를 주고받아야 하는지 확인했습니다.
• 같은 파일을 함께 고칠 가능성이 있는지 확인했습니다.

이 기준을 적용한 뒤에 OMC처럼 작업 흐름을 더하는 플러그인을 배웁니다. Claude Code의 기본 작업 방식을 먼저 구분해야 플러그인의 team 모드가 필요한 상황도 정확히 고를 수 있습니다.

OMC는 Claude Code에 실행 방식을 더하는 제3자 플러그인입니다. 작업을 맡기는 순서를 묶어 두어서, 긴 작업을 시작할 때 어떤 흐름으로 진행할지 고를 수 있습니다.

선택 기준

실행 방식은 요구사항의 상태, 작업자 사이의 소통 필요, 완료 조건으로 선택합니다. 서로 다른 결과물을 만들고 사용자가 각각 확인할 수 있으면 Claude Code의 새 세션을 먼저 사용합니다. 같은 파일을 여러 명이 차례로 고쳐야 하는 작업은 team으로 나누기 어렵습니다. 짧은 수정은 설명과 검수에 드는 시간이 더 커서 한 세션에서 처리하는 편이 적합합니다.

설치 전 확인

플러그인은 스킬뿐 아니라 자동 실행되는 훅과 외부 연결을 포함할 수 있습니다. Claude Code 공식 안내에 따라 출처와 추가 항목을 확인한 뒤 처음에는 현재 프로젝트에만 적용합니다.

공식 OMC 안내의 설치 흐름은 마켓플레이스 추가, 플러그인 설치, 프로젝트 설정 순서입니다. 수업에서는 명령을 바로 실행하지 않고 먼저 설치될 항목을 확인합니다. 설치했다면 /plugin list에서 활성 상태를 확인한 뒤 비밀 정보가 없는 연습 폴더에서 모드 하나만 시험합니다.

team 사용 조건

OMC의 team은 Claude Code 에이전트 팀 기능을 사용합니다. 이 기능은 실험 단계라 별도로 켜야 하며 팀원마다 별도 세션이 생겨 토큰 사용량이 늘어납니다. 팀원끼리 조사 결과를 공유하거나 공동 작업 목록을 갱신해야 할 때 사용합니다. 에이전트 팀은 팀원별 작업 폴더를 자동으로 분리하지 않으므로 각 팀원에게 서로 다른 파일 범위를 배정합니다.

완료 확인

바뀐 파일을 열고 약속한 검사 명령을 실행한 뒤, 결과가 완료 조건과 맞는지 확인합니다. OMC의 완료 설명과 파일 또는 검사 결과가 다르면 원인을 확인하고 작업을 계속합니다.

에이전트를 만들 줄 알아도 흐름이 안 서면 여전히 매번 손으로 이어 붙이게 되므로, 순서를 먼저 적는 것이 시작입니다.

순서를 먼저 적습니다

고른 반복 업무를 지금 손으로 하는 그대로 적되, 도구 이름 없이 무엇을 하는지만 적습니다.

카드 한 장을 만드는 일이라면 이런 식입니다.

1. 소재를 모은다
2. 초안을 쓴다
3. 사실을 확인한다
4. 형식을 맞춘다
5. 올린다

각 단계의 수행 방법을 정합니다

이제 단계마다 세 가지 수행 방법 중 하나를 정합니다.

위 예시라면 1번과 3번이 위임하기 좋습니다. 찾아볼 자료가 많고 앞 대화를 몰라도 되기 때문입니다.

2번은 판단이 들어가서 직접 하는 편이 낫고, 4번은 매번 같은 확인이라 Hook으로 옮길 수 있습니다.

수행 방법을 정하는 기준은 앞에서 본 규모와 독립성 그대로입니다.

그다음에 만듭니다

수행 방법을 정한 뒤 필요한 기능만 만듭니다. 순서를 거꾸로 하면 조사 담당과 초안 담당을 각각 만들었는데 둘 다 조사부터 하는 식으로 역할이 겹칩니다.

만들 때는 공식 가이드를 따르라고 함께 요청하는데, 그 말이 없으면 형식이 제각각인 파일이 나옵니다.

한 단계씩 붙입니다

다 만들었다고 전 단계를 한 번에 잇지 않습니다. 한 단계 붙이고 돌려 보고, 결과가 쓸 만하면 다음을 붙입니다.

전부 이어 놓고 한 번에 돌리면 결과가 이상할 때 어느 단계에서 어긋났는지 찾기 어렵습니다. 자동화한 단계가 많을수록 더 그렇습니다.

한 바퀴는 실제 일감으로 돌립니다

시험용으로 만든 가짜 일감은 늘 잘 돌아갑니다. 이번 주에 실제로 해야 하는 일 하나로 돌려 봐야 어디가 막히는지 나옵니다.

멈춘 단계가 그다음에 고칠 곳입니다.

자동화가 잘 돌아가는 것처럼 보이는 상태가 제일 위험합니다. 손이 안 가니까 결과를 안 보게 되고, 어긋난 것이 다음 단계로 그대로 흘러갑니다.

기준을 먼저 정합니다

무엇을 통과로 볼지부터 정합니다. 이 순서를 뒤집으면 결과를 보고 “이 정도면 됐다”고 판단하게 되는데, 그건 기준이 아닙니다.

기준은 확인할 수 있는 형태로 적습니다.

• 확인 안 되는 쪽: 결과가 자연스러운가
• 확인 되는 쪽: 표에 빈 칸이 없는가, 출처 링크가 전부 열리는가

기계와 사람을 가릅니다

정한 기준을 둘로 나눕니다.

기계가 확인할 수 있는 것 — 빈 칸 여부, 형식, 링크가 열리는지, 정해 둔 문구가 들어갔는지. 이런 건 훅으로 걸어 둡니다. 동작 전에 반드시 막아야 하면 PreToolUse를, 동작 뒤에 검사 결과를 알려 주면 되면 PostToolUse를 고릅니다.

사람이 봐야 아는 것 — 어조가 맞는지, 이 표현을 써도 되는지, 지금 이걸 내보내도 되는지. 이건 자동으로 바꾸려 하지 말고 그 지점에서 나에게 묻게 남깁니다.

기계 검사로 바꾸려다 기준이 헐거워지면 안 하느니만 못합니다.

막는지 확인합니다

검사를 걸어 두는 것과 그게 막는 것은 다릅니다. PostToolUse는 이미 끝난 파일 수정을 되돌리지 못하며, 명령형·HTTP형 Hook이 제한 시간을 넘기면 기본 흐름이 계속될 수 있습니다. 다음 단계까지 멈춰야 한다면 빌드나 배포 경로에도 같은 기준을 연결합니다.

확인하는 방법은 하나입니다. 일부러 어겨 보는 것. 기준을 어기는 입력을 하나 만들어 돌려 보고, 정말 멈추는지 봅니다. 안 멈추면 아직 게이트가 아닙니다.

위임한 결과도 검수 대상입니다

서브에이전트가 돌려준 요약은 이미 정리된 형태라 그대로 믿기 쉽습니다. 그런데 정리 과정에서 빠진 것은 요약만 봐서는 안 보입니다.

받은 요약 중 하나를 골라 실제 파일과 대조해 보는 습관이 필요합니다. 매번 전부 대조할 수는 없어도, 한 번은 확인합니다. 그 요약이 다음 단계의 입력으로 들어갈 때는 특히 그렇습니다.

특히 조심할 것은 읽은 내용은 맞는데 판정이 틀린 경우입니다. 위임한 워커가 파일을 정확히 읽고도, 어느 기준을 적용할지 헷갈려서 통과할 것을 위반으로 뒤집을 수 있습니다. 이때 돌아오는 보고는 근거까지 붙어 있어서 더 그럴듯해 보입니다.

그래서 위임할 때 기준을 정의 안에 못박아 둡니다. “문체를 검사해 줘”가 아니라 “어떤 어미를 통과로 볼지”까지 적어 두는 식입니다. 기준이 비어 있으면 워커가 그 자리를 스스로 채웁니다.