🍊 기초(LV35)#바이브코딩#ClaudeCode#클로드 코드 스킬#클로드 코드 에이전트#자동화
14분·2026. 4. 24.·조회 8
오늘도 AI 한입 하세요 🍊
새 아티클이 발행되면 이메일로 알려드릴게요.
댓글을 남기려면 로그인이 필요합니다.
아직 댓글이 없습니다. 첫 댓글을 남겨보세요!
클로드 코드(Claude Code)가 파일 수정할 때마다 Yes를 물어봐서 답답하다면, 권한 자동 허용(bypassPermissions)을 켜면 됩니다. 설정법부터 Shift+Tab 전환, 위험성, plan mode 활용, settings.json 영속화까지 한 글로 끝냅니다.
똑같은 지시를 또 복붙하고 있었습니다. 이번 주만 세 번째입니다.
"커밋 메시지에 AI 흔적 남기지 말고, 본문은 '왜'를 설명하고, 브랜치는 dev에서 따고, 머지 전에 꼭 rebase하고..."
복붙하다가 문득 이런 생각이 듭니다. "이거, 클로드한테 한 번만 알려주면 다음부터는 알아서 하게 만들 수 없나?" 그리고 검색을 시작하면 네 가지 단어가 한꺼번에 쏟아져 나옵니다. 스킬(Skill), 커맨드(Slash Command), 서브에이전트(Subagent), 에이전트팀(Agent Team). 공식 문서와 커뮤니티 글을 넘나들며 읽다 보면 네 가지가 서로 비슷해 보이기도 하고, 전혀 달라 보이기도 합니다.
반대 방향의 경험도 있습니다. 어디서 본 "에이전트팀 쓰면 병렬로 작업 분배해서 훨씬 빨라집니다"라는 말에 혹해 QA 작업에 팀을 투입했는데, 결과가 영 이상했던 경험입니다. 시간은 평소보다 오래 걸렸고, 토큰은 네다섯 배가 나갔고, 보고서는 서로 맥락이 안 맞는 이상한 상태로 돌아왔습니다. "혼자 할 걸 그랬나..." 후회가 들었죠.
결론부터 말씀드리면, 이 두 혼란은 같은 뿌리에서 나옵니다. 각 도구가 무엇을 해결하려고 만들어졌는지가 머릿속에 정리되지 않은 상태에서 이름만 보고 고르다 보니, 매번 엉뚱한 곳에 엉뚱한 도구를 쓰게 되는 것입니다.
이 글은 클로드 코드(Claude Code)를 몇 주~몇 달 써본 분이 클로드 코드 스킬, 커맨드, 클로드 코드 서브에이전트, 클로드 코드 에이전트팀 — 이 네 가지를 언제 뭘 써야 하는지 스스로 결정할 수 있도록, 네 도구의 역할을 두 개의 축으로 정리합니다. 각 도구의 세부 설정 방법은 공식 문서와 후속 글에서 더 자세히 다루기로 하고, 여기서는 오직 선택 기준 한 가지에 집중하겠습니다. "클로드 코드 사용법"이라는 검색어로 들어오신 분들을 위한 비교·선택 가이드라고 보시면 됩니다.
클로드 코드를 아직 설치하지 않으셨다면 이 글은 클로드 코드가 이미 내 PC에 돌아가고 있다는 전제로 시작합니다. 설치·첫 실행 단계가 아직이라면 아래 입문 글을 먼저 훑고 오시면 이 글의 모든 예시가 훨씬 잘 읽힙니다. 👉 Claude Code, 처음 시작할 때 이것만 따라하세요
같은 지시를 복붙하거나, 팀을 써봤다가 망하거나 — 혼란의 두 방향
매트릭스로 들어가기 전에, 네 가지가 각각 어떤 문제를 풀려고 만들어진 도구인지만 짧게 훑고 갑시다. 이름만 들어서는 구분이 어려운 이유가, 해결하려는 문제는 서로 다른데 생김새가 비슷하기 때문입니다.
.claude/skills/{이름}/SKILL.md에 규칙을 박아두면, 클로드가 관련된 표현을 들었을 때 그 파일을 자동으로 불러와서 따릅니다. "커밋해줘"라고 말하면 commit 스킬의 트리거 키워드에 매칭되므로 클로드가 스스로 규칙을 읽고 적용합니다. 핵심은 내가 부르지 않아도 발동한다는 점입니다..claude/commands/{이름}.md에 절차를 박아두면 /이름 슬래시로 호출할 수 있습니다. 스킬과 형태는 비슷하지만 결정적 차이가 있습니다. 커맨드는 내가 부를 때만 실행되고, 자동 발동은 없습니다. "지금부터 이 루틴을 돈다"는 신호를 내가 직접 켜는 스위치입니다.Agent 도구로 서브에이전트를 띄우면, 그 에이전트는 자기만의 컨텍스트에서 작업을 끝내고 메인에는 요약된 결과 한 덩어리만 돌려줍니다. 탐색 과정에서 읽은 수십 개 파일은 서브에이전트 컨텍스트에만 남았다가 사라집니다.이름만 보면 네 도구가 한 줄 위에 나란히 서 있는 동급 선택지처럼 보입니다. 실제로는 그렇지 않습니다. 이제 공간을 두 축으로 나눠서, 이 네 도구가 각각 어느 칸에 사는지 보겠습니다.
도구 하나하나를 비교표에 나열하면 결국 특징의 홍수에 빠집니다. 대신 공간을 두 개의 축으로 나누고 네 도구를 배치하면, 이름의 혼란이 사라지고 해결하려는 문제만 남습니다.
첫 번째 축은 이 도구가 무엇을 해주는가입니다.
이 구분이 가장 중요합니다. 사람들은 보통 "스킬과 서브에이전트 중 뭘 쓸까"를 고민하는데, 두 도구는 애초에 다른 문제를 푸는 도구이기 때문에 같은 축에서 비교할 수가 없습니다. 마치 "포크와 냉장고 중에 뭘 쓸까"를 고민하는 격입니다.
두 번째 축은 각 계열 안에서 어떻게 굴리느냐입니다.
/이름을 내가 직접 입력해야 발동합니다.
세로축은 "무엇을 해주는가", 가로축은 "어떻게 굴리는가"
| 자동 · 단일 | 명시 · 다중 | |
|---|---|---|
| 기억 (박아두기) | 스킬 | 커맨드 |
| 실행 (위임) | 서브에이전트 | 에이전트팀 |
이 매트릭스를 머릿속에 박아두면 "뭘 써야 하지?"라는 고민이 훨씬 짧아집니다. 먼저 "지금 내가 뭘 해결하려는 거지?"에 답하면 세로축이 정해지고, "이걸 어떻게 굴리고 싶지?"에 답하면 가로축이 정해집니다. 두 답을 교차하면 네 칸 중 하나가 남습니다.
이제 각 칸이 실제로 어떤 상황에서 선택되는지, 케이스별로 봅시다.
클로드 코드 스킬과 커맨드는 겉보기엔 비슷하지만, 발동 방식이 완전히 다릅니다. 가장 자주 마주치는 상황입니다. 같은 지시를 세 번째로 치고 있다는 걸 깨닫는 순간, "이건 박아둘 타이밍이다"라는 신호입니다. 그럼 스킬인가, 커맨드인가.
이게 전부입니다. 같은 규칙이라도 어느 타이밍에 클로드가 그 규칙을 기억하길 원하는지에 따라 답이 달라집니다.
"커밋할 때는 항상 AI 흔적을 제거해야 한다"는 규칙을 생각해봅시다. 이건 내가 /commit이라는 명령어를 치든, "커밋해줘"라고 말로 풀든, "이거 커밋하자"라고 하든 항상 적용되기를 원하는 규칙입니다. 즉, 클로드가 "아, 지금 커밋하려는 상황이구나"를 스스로 알아차려야 합니다.
이런 상황이 스킬입니다. .claude/skills/commit/SKILL.md의 프론트매터에 트리거 키워드로 커밋해줘, 커밋하자, /commit, 변경사항 저장 같은 것들을 나열해두면, 클로드는 사용자 메시지에서 이 패턴을 발견하는 순간 SKILL.md를 불러와 규칙을 따릅니다.
스킬은 내가 부르지 않아도 클로드가 스스로 발동시킨다
반면 "지금부터 이 여섯 단계 루틴을 돌려라"처럼 절차성이 강한 작업은 커맨드가 맞습니다. 예를 들어 /submit은 "변경사항 확인 → 커밋 → PR 생성 → 머지 → 브랜치 동기화 → 배포 확인"을 한 방에 돌리는 루틴입니다. 이걸 자동 발동으로 만들면 위험합니다. "제출해줘"라는 말 한마디에 PR이 머지되고 배포까지 나가버리면 사고입니다.
이런 작업은 커맨드로 만들어두고, 내가 의식적으로 /submit을 쳤을 때만 루틴이 돌도록 합니다. 스위치의 방향이 내 손에 있어야 하는 작업이 커맨드입니다.
/submit 한 번에 커밋부터 배포까지 원스톱, 내가 켜야만 돈다
저장소에 실제 박아둘 법한 반복 지시와, 각각이 어느 쪽인지 정리하면 다음과 같습니다.
| 반복 상황 | 선택 | 이유 |
|---|---|---|
| 커밋 메시지 규칙 | 스킬 | 커밋이라는 의도는 말투가 다양, 자동 인식 필요 |
| 커밋 + PR + 머지 + 배포 확인 원스톱 | 커맨드 | 실수 방지를 위해 명시적 호출이 안전 |
| 코드 리뷰 체크리스트 | 스킬 | "리뷰해줘"라는 의도가 나올 때 항상 적용돼야 함 |
| 배포 상태 모니터링 | 커맨드 | 내가 원할 때만 시작, 길게 돌아가는 작업 |
| 문서 작성 톤앤매너 | 스킬 | 문서를 쓰는 모든 순간에 적용돼야 함 |
| 이슈 자동 분류 루틴 | 커맨드 | 의식적으로 "지금 분류 돌린다"가 명확 |
같은 재료(박아둔 지시)를 두 가지 스위치로 쓰는 것이라고 생각하면 됩니다. 하나는 자동문, 하나는 눌러야 열리는 버튼입니다.
스킬은 편해서 금세 모든 걸 스킬로 만들고 싶어집니다. 하지만 트리거 키워드가 너무 포괄적이면 엉뚱한 맥락에서 스킬이 발동됩니다. 예를 들어 deploy-status 스킬 트리거에 단순히 "배포"를 넣어두면, "이번 배포 일정이 언제죠?"라는 질문에도 스킬이 로드되어 컨텍스트가 불필요하게 커집니다. 트리거는 행동 의도가 분명한 문구(예: "배포 확인", "배포 모니터링")로 좁혀야 합니다.
또 하나의 함정은 스킬 간 충돌입니다. 여러 스킬의 트리거 키워드가 겹치면 클로드가 둘 다 불러오고, 서로 상충하는 규칙을 적용하려다 이상한 응답을 뱉습니다. 스킬 하나를 새로 만들 때는 기존 스킬들의 트리거 목록을 한 번 훑어보는 습관을 들이는 편이 좋습니다.
스킬을 실제로 만드는 방법이 궁금하다면 이 섹션은 "스킬이냐 커맨드냐"의 선택 기준을 다뤘습니다. SKILL.md의 프론트매터, 트리거 키워드 설계, RULES.md 분리 같은 실제 제작 절차는 별도 글에서 예제와 함께 자세히 다룹니다. 👉 클로드 코드 스킬 만드는 법 — 반복 업무를 한 단어로 끝내기
클로드 코드 서브에이전트(Claude Code Subagent)는 이 문제를 정면으로 푸는 도구입니다. 같은 세션에서 오래 작업하다 보면, 대화가 점점 느려지고 응답이 이상해지기 시작합니다. 이유는 단순합니다. 컨텍스트 윈도우가 다 찼거나, 프롬프트 캐시가 반복해서 깨지고 있기 때문입니다.
이런 작업들이 메인 대화를 빠르게 무겁게 만듭니다.
browser_snapshot 같이 한 번에 5만~10만자를 뱉는 MCP 도구 호출한 번은 반드시 필요한 작업들입니다. 문제는 이 탐색 과정의 잔해가 모두 메인 대화에 남는다는 점입니다. 잔해가 쌓이면 이후 대화에서 매 턴마다 LLM이 그 모든 토큰을 다시 읽어야 하고, 응답 시간과 비용이 함께 커집니다. 가장 나쁜 건 체감하기 힘들다는 것입니다. 어느 순간 "대화가 좀 느려졌네?" 정도로 느껴지는데, 그때는 이미 돌이키기 어렵습니다.
서브에이전트는 이 문제를 구조적으로 해결합니다. Agent 도구로 서브에이전트를 띄우면, 그 에이전트는 자기만의 컨텍스트 윈도우를 씁니다. 탐색·검색·분석을 그 안에서 끝내고, 메인에는 요약된 결과 메시지 하나만 돌려줍니다.
[메인 대화]
├─ 사용자: "로그인 관련 훅이 어디에 다 쓰이는지 찾아줘"
│
├─ Agent 도구 호출 (Explore 타입)
│ └─ [서브에이전트 컨텍스트 — 메인과 분리]
│ ├─ Grep "useLogin" 호출 (수십 개 매치)
│ ├─ Read 수십 파일
│ ├─ 결과 정리
│ └─ 요약 반환 (300토큰)
│
└─ 메인은 300토큰만 받음. 탐색 과정의 수만 토큰은 메인에 남지 않음.
탐색의 잔해를 서브에이전트에 격리하면 메인은 요약만 받는다
자주 쓰는 타입은 세 가지입니다.
프로젝트마다 .claude/agents/에 커스텀 서브에이전트 타입을 정의해 추가할 수도 있습니다. qa-tester, bug-fixing, code-reviewer 같은 역할 특화 에이전트들이 좋은 예입니다. 역할이 분명하면 매번 맥락을 브리핑할 필요 없이 에이전트 타입만 지정해도 작업의 방향이 잡힙니다.
쓰면 좋은 경우
쓰면 안 되는 경우
마지막 항목이 초보자가 자주 실수하는 지점입니다. "검토하고 수정해줘"를 서브에이전트에 맡기면, 서브에이전트가 자기 판단으로 수정해버리고 결과만 돌려줍니다. 내가 중간에 "그건 이쪽 방향으로"라고 개입할 여지가 없습니다. 결정이 필요한 작업은 메인에 두고, 결정에 필요한 자료 수집만 서브에이전트에 맡기는 것이 안전합니다.
서브에이전트를 쓰기 시작하면 자연스럽게 "여러 개를 병렬로 돌리면 더 빠르겠네?"라는 생각이 듭니다. 맞는 경우도 있지만, 치명적인 예외가 있습니다. 브라우저 자동화(Playwright MCP)를 쓰는 작업은 절대 병렬로 돌리면 안 됩니다. Playwright는 단일 브라우저 인스턴스만 지원하기 때문에, 두 서브에이전트가 동시에 브라우저를 조작하면 페이지가 서로를 덮어씁니다. 첫 에이전트가 스크린샷을 찍으려니 엉뚱한 페이지가 찍히거나 그냥 에러가 납니다.
원칙은 이렇습니다.
Explore) — 병렬 OK클로드 코드 에이전트팀(Claude Code Agent Team)은 가장 강력해 보이지만 가장 까다로운 선택지입니다. 여기부터가 초보자가 가장 자주 실패하는 영역입니다.
팀이 혼자 하는 것보다 확실히 좋은 결과를 내는 상황은 생각보다 드뭅니다. 실전 경험상 이 세 가지가 전부입니다.
팀원은 대화 히스토리를 상속받지 않아 TaskCreate 설명이 전부다
이건 공식 문서에도 잘 부각되지 않는 함정인데, 실전에서 팀이 느리고 엉뚱한 결과를 내는 이유의 대부분이 여기에 있습니다.
팀원 에이전트는 리더의 대화 히스토리를 상속받지 않습니다. TaskCreate로 일을 넘길 때 description 필드에 적어 전달한 텍스트만이 팀원이 보는 전부입니다. 그래서 이런 흐름이 자주 벌어집니다.
이런 루프가 한 번 돌기 시작하면 토큰 비용은 혼자 할 때의 5배를 넘기고, 시간은 두세 배 걸립니다. 팀에 위임할 때 리더가 모든 필요한 맥락을 TaskCreate 설명에 명시적으로 담지 않으면 팀은 쓸모가 없습니다. 더 정확히 말하면, 팀이 혼자 하는 것보다 나쁩니다.
이 문제는 "팀원은 똑똑한 동료가 아니라, 방금 회사에 입사한 신입이다"라고 생각하면 쉽게 기억됩니다. 신입에게는 "지난주 회의에서 결정한 대로"라고 말할 수 없습니다. 회의에 없었기 때문입니다. 팀원에게 작업을 넘길 때도 마찬가지입니다.
팀을 쓰기로 결정했다면 반드시 지켜야 하는 세 가지입니다.
1. TaskCreate 설명은 자기 완결적으로 작성한다. 팀원이 그 설명만 읽고도 작업을 시작할 수 있도록 관련 파일 경로, 제약 조건, 참고 규칙, 합격 기준을 모두 적습니다. 대화에서 공유한 맥락을 "알고 있을 것"이라고 가정하지 않습니다. 설명이 길어져도 괜찮습니다. 설명 길이의 오버헤드보다 재작업 비용이 훨씬 큽니다.
2. 브라우저 작업은 절대 병렬로 돌리지 않는다. 서브에이전트 케이스에서 이야기한 것과 같은 이유입니다. Playwright MCP는 단일 브라우저 인스턴스 기반이기 때문에, 팀원 둘 이상이 동시에 브라우저를 잡으면 세션이 충돌합니다. 팀이라도 브라우저 작업은 한 팀원에게 몰아서 순차 처리하게 합니다.
3. 팀원끼리 강한 의존성이 있는 작업은 쪼개지 않는다. "A 팀원의 결과를 받아서 B 팀원이 이어서 처리"하는 구조는 팀으로 풀면 동기화 오버헤드가 작업 자체보다 커집니다. 이럴 때는 차라리 한 서브에이전트가 순차로 처리하거나, 메인이 직접 처리하는 편이 빠릅니다.
팀과 병렬 실행은 직관적으로는 "여럿이 하면 빠르겠지"라는 기대를 줍니다. 실전에서는 반대인 경우가 훨씬 많습니다. 자주 보이는 안티패턴 세 가지입니다.
"간단한 버그 하나 고쳐줘"에 팀을 붙이면 이런 일이 벌어집니다.
메인 혼자였다면 이미 로드된 컨텍스트에서 수정과 테스트를 이어서 했을 작업이, 팀을 거치면서 같은 파일을 세 번 읽고, 같은 맥락을 세 번 재구성하는 구조가 됩니다. 비용은 3~5배, 결과는 오히려 더 나쁠 가능성이 높습니다.
단순 작업에 팀을 붙이면 같은 파일을 3번 읽고 맥락을 3번 재구성하게 된다
앞에서 두 번이나 언급했지만, 실전에서 가장 자주 발생하는 사고라 다시 한번 정리합니다. 서브에이전트든 팀이든, 브라우저 조작(Playwright MCP)을 포함하는 병렬 실행은 거의 항상 실패합니다. 첫 에이전트가 사이트 A로 이동하는 사이 두 번째 에이전트가 같은 브라우저에서 사이트 B로 이동해 A 페이지를 덮어씁니다. 그 결과 첫 에이전트가 스크린샷을 찍으려니 엉뚱한 페이지가 찍힙니다.
해결책은 두 가지입니다.
설계·아키텍처·대규모 리팩토링처럼 "전체 문맥을 이해하고 있어야" 판단이 가능한 작업을 팀에 쪼개면, 각 팀원이 쪼가리만 보고 쪼가리에 맞는 답을 내놓습니다. 통합하면 방향이 서로 어긋나 있고, 리더가 다시 맞추는 데 드는 비용이 혼자 한 것보다 큽니다.
경험칙 하나를 드리면 이렇습니다.
"이 작업을 내가 신입한테 설명하려면 30분은 걸리겠는데"라는 느낌이 들면, 팀 쓰지 말고 메인에서 하세요. 30분짜리 맥락을 TaskCreate 설명으로 압축할 수 없다면, 팀원도 그걸 못 따라옵니다.
지금까지 한 이야기를 한 장으로 압축하면 다음 세 질문입니다. 글 머리에 박아두고, 도구를 꺼내기 전에 한 번씩 돌려보는 것을 권합니다.
Q0만 던져도 결정의 90%가 끝난다 — 기본은 언제나 메인
Q0. 이거, 그냥 메인에서 직접 하면 안 되는 이유가 있는가?
대부분의 경우 답은 "없다"입니다. 네 도구는 모두 메인에서 직접 하는 기본값에 비해 추가 비용을 치르는 선택이고, 그 비용을 상쇄할 명확한 이득이 있어야 꺼냅니다. "도구를 써야 멋있을 것 같아서"가 아니라, "메인에서 하면 이런 구체적인 문제가 생기기 때문에"라는 답이 있어야 Q1로 넘어갑니다.
Q1. 이건 기억시키는 일인가, 실행을 맡기는 일인가?
Q2 (기억일 때). 자동으로 발동되길 원하는가, 내가 부를 때만 발동되길 원하는가?
.claude/skills/{이름}/SKILL.md에 트리거 키워드와 함께 작성..claude/commands/{이름}.md로 작성하고 /이름으로 호출.Q3 (실행일 때). 관점이나 역할이 여럿 필요한가?
Agent 도구, 단일 컨텍스트)이 네 개의 질문을 순서대로 돌리면, "뭘 써야 하지?"라는 고민이 1~2분짜리 결정으로 압축됩니다. 실제로 한 달만 이 순서로 굴려보면, 나중에는 Q0만 던져도 90%의 결정이 끝납니다.
네 도구를 써본 시간이 쌓일수록 한 가지가 분명해집니다. 기본은 메인입니다.
팀을 쓰면 뭔가 더 똑똑해 보이고, 더 정교해 보이는 환상이 있습니다. 제 경험상 팀은 가장 비싸고, 가장 자주 실패하는 선택지입니다. 메인에서 먼저 시작하고, 박아둘 신호가 오면 스킬·커맨드를 꺼내고, 컨텍스트가 무거워지면 서브에이전트로 격리하고, 진짜 여러 관점이 꼭 필요할 때만 팀에 손을 대는 순서가 대체로 가장 빠르고 가장 정확했습니다.
도구가 많은 건 좋은 일입니다. 단, 많은 도구를 모두 쓰는 것보다, 적절한 도구 하나를 적시에 꺼내는 것이 훨씬 강력합니다. 클로드 코드 사용법의 진짜 승부는 "네 도구를 모두 쓸 줄 아는가"가 아니라 "네 도구 중 지금 상황에 맞는 하나를 고를 수 있는가"에서 갈립니다. 이 글이 그 "적시"를 판단하는 매트릭스 하나를 머릿속에 남기는 데 도움이 되었기를 바랍니다.
기본은 메인, 신호가 오면 스킬·커맨드·서브에이전트·팀 순으로 꺼낸다