하네스 엔지니어링 입문에서 "에이전트에게 일을 맡기는 구조"라는 개념을 다뤘는데, 이번 글은 그 구조를 실제로 조립하는 도구편입니다. 도구는 Anthropic의 CLI 에이전트인 Claude Code 기준입니다. 쓰다 보면 skill, sub-agent, hook, MCP, plugin이라는 다섯 확장 포인트가 계속 나오는데, 각각 언제 꺼내 드는 물건인지가 헷갈려서 아무거나 잡으면 유지보수 지옥이 열립니다. 다섯 개를 한 장의 지도로 정리하고, 운영하면서 정한 기준들을 공유합니다.
지도 먼저, 확장 포인트 5가지
| 확장 포인트 | 한 줄 정의 | 이럴 때 |
|---|---|---|
| skill / command | 절차를 적은 마크다운 지시서 | 반복 업무의 순서·규칙을 박제할 때 |
| sub-agent | 별도 컨텍스트로 위임되는 보조 에이전트 | 본 작업과 분리된 탐색·검토를 시킬 때 |
| hook | 도구 실행 전후에 시스템이 강제 실행하는 스크립트 | 모델의 재량을 못 믿는 규칙을 강제할 때 |
| MCP | 외부 서비스(Jira·Slack·DB)와의 표준 연결 | 에이전트가 사내 도구를 직접 만져야 할 때 |
| plugin | 남이 만든 skill·hook 묶음의 설치 단위 | 검증된 하네스를 통째로 가져올 때 |
위 표에서 아래로 갈수록 도입 비용이 커집니다. 그래서 운영 원칙 1번은 단순합니다. 마크다운으로 해결되면 마크다운으로 끝낸다. skill로 충분한 일에 MCP 서버를 세우는 건 과잉 설계입니다.
skill과 slash command, 절차의 파일화
skill은 특정 작업의 절차서를 담은 마크다운 파일입니다. 프로젝트의 .claude/skills/ 아래에 두면 에이전트가 해당 작업에서 그 절차를 따릅니다. slash command는 그 절차를 /이름 한 번으로 호출하는 진입점이고요. 이 블로그의 글쓰기도 /write라는 커맨드 하나로 시작해서, 주제 선정부터 검수·발행까지의 절차가 전부 파일에 박혀 있습니다.
설계 요령은 소프트웨어의 함수 설계와 비슷합니다. 하나의 skill은 하나의 작업만. "데이터 분석 + 보고서 작성 + 슬랙 공유"를 한 skill에 다 넣으면 어느 단계가 틀렸는지 디버깅이 안 됩니다. 그리고 금지 조항을 아끼지 마세요. 에이전트 사고의 대부분은 시키지 않은 일을 친절하게 해버리는 데서 납니다.
skill을 언제 쪼개고 언제 합칠지 고민된다면, 사람 신입에게 업무 문서를 어떻게 나눠 줄지 생각하면 거의 같은 답이 나옵니다.
sub-agent, 컨텍스트를 나누는 칼
sub-agent는 본 세션과 분리된 컨텍스트에서 일하고 결과만 돌려주는 보조 에이전트입니다. 핵심 가치는 병렬성보다 컨텍스트 분리입니다. 대화가 길어질수록 에이전트의 작업 기억이 비싸지는데, "이 레포 전체에서 X 패턴을 찾아와" 같은 탐색을 본 세션에서 하면 검색 과정의 파일 내용이 전부 컨텍스트에 쌓입니다. sub-agent에게 시키면 결론만 받아옵니다.
언제 쓰나의 기준을 셋으로 줄였습니다. 탐색 범위가 넓어서 중간 산출물이 클 때, 본 작업과 독립적인 검토(코드 리뷰, 사실 확인)가 필요할 때, 그리고 진짜로 병렬이 이득인 큰 독립 작업일 때. 반대로 "그냥 빨라 보여서" 띄우는 병렬 sub-agent는 토큰 비용을 곱으로 태우면서 디버깅 난이도만 올립니다. 하네스 입문 글에서 말한 멀티 에이전트 신중론이 여기에도 그대로 적용됩니다.
📌 sub-agent vs skill, 헷갈린다면
skill은 "어떻게 일할지"의 절차서고, sub-agent는 "누가 일할지"의 분업입니다. 절차가 문제면 skill을 고치고, 컨텍스트 오염이나 작업 독립성이 문제면 sub-agent로 분리합니다. 실제로는 sub-agent에게 skill을 들려 보내는 조합이 많습니다.
hook, 모델이 아니라 시스템이 강제한다
지시서의 약점은 결국 모델이 따라줘야 작동한다는 점입니다. 99번 잘 따르다 1번 빼먹는 게 확률적 시스템의 본성이고요. hook은 그 재량을 없앱니다. 도구 실행 전후 같은 시점에 시스템이 무조건 실행하는 스크립트라서, 모델이 잊어도 동작합니다.
대표 시점은 도구 실행 직전(위험한 명령을 패턴으로 차단), 도구 실행 직후(파일 수정마다 포매터·린터 자동 실행), 세션 시작(팀 규칙 자동 로드) 정도입니다. 설정은 settings.json에 거는데, 모양은 이렇습니다.
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{ "type": "command",
"command": "bash scripts/lint-content.sh $FILE" }]
}]
}
}
운영 기준은 이겁니다. 어겨도 되는 규칙은 skill에, 어기면 안 되는 규칙은 hook에. 글의 어조 가이드는 skill에 있어도 되지만, "main 브랜치에 직접 push 금지"는 hook이어야 합니다. 이 블로그의 콘텐츠 린터도 처음엔 지시서 속 권고였다가, 한 번 빼먹는 걸 본 뒤 hook 후보로 승격을 검토 중입니다.
{/* TODO_HUNY: 실제로 운영 중인 hook이 있다면 (예: rtk 토큰 절약 hook 같은) 어떤 사고를 막으려고 달았는지 한 단락. 본인 settings.json에서 하나 골라 소개하면 글의 실물감이 확 삽니다. */}
MCP, 외부 세계와의 연결
MCP(Model Context Protocol)는 에이전트가 외부 서비스를 도구로 쓰게 해주는 표준 프로토콜입니다. Jira 티켓 조회, Slack 메시지 발송, Google Drive 문서 읽기, DB 쿼리까지. 서버 하나를 연결하면 그 서비스의 기능들이 에이전트의 도구 목록에 추가됩니다.
강력한 만큼 운영 주의점이 셋 있습니다. 첫째, 도구 폭발. 서버 몇 개만 연결해도 도구가 수십 개로 늘어 모델의 선택이 둔해지고 컨텍스트가 무거워집니다. 지금 프로젝트에 필요한 서버만 연결하는 게 기본입니다. 둘째, 권한. MCP 도구는 실제 사내 시스템을 건드립니다. 읽기 전용으로 시작해서 쓰기 권한은 필요가 증명된 뒤에 여세요. 셋째, 외부 데이터의 신뢰. MCP로 들어온 외부 콘텐츠(티켓 본문, 메일)는 지시가 아니라 데이터로 다루도록 지시서에 명시해두는 게 prompt injection에 대한 최소 방어입니다.
마케팅 데이터 쪽이라면 그림이 바로 그려질 겁니다. 매체 리포트가 쌓이는 BigQuery에 읽기 전용 MCP를 연결하고, skill에 지표 정의를 박아두면 "지난주 캠페인 요약해줘"가 실제로 돌아가는 구조가 됩니다.
plugin, 남의 하네스를 가져다 쓰기
plugin은 skill·command·hook 묶음을 설치 단위로 배포하는 체계입니다. 직접 만들기 전에 marketplace를 먼저 뒤져보는 습관이 시간을 아껴줍니다.
실제 사례 하나. 이 블로그에는 오늘 humanizer라는 오픈소스 skill을 설치했습니다. AI 글쓰기 특유의 패턴 33가지를 찾아 고치는 지시서인데, 그대로 쓰지 않고 한국어 블로그용 체크리스트를 덧붙여 글쓰기 절차에 끼워 넣었습니다. 이게 plugin 생태계의 현실적인 사용법이라고 생각합니다. 남의 하네스를 골격으로 가져오되, 자기 도메인의 살은 직접 붙이는 것. 설치만 하고 끝나는 plugin은 대개 한 달 뒤 잊힙니다.
도입 전 체크는 소프트웨어 의존성 추가와 같습니다. 소스가 공개돼 있는지, 어떤 권한을 요구하는지, 안 맞으면 깔끔하게 제거되는지.
권한·모델 라우팅, 안전과 비용의 두 다이얼
마지막으로 운영자가 쥐고 있어야 할 다이얼 두 개입니다.
권한. Claude Code는 도구 실행마다 허용 범위를 설정으로 통제합니다(settings.json의 allow/deny 목록). 자주 쓰는 안전한 명령은 미리 허용해 흐름을 부드럽게 하고, 파괴적인 패턴은 명시적으로 막아둡니다. 모든 확인을 끄는 옵션은 격리된 환경이 아니면 쓰지 않는 게 원칙입니다. 편하자고 끈 안전장치는 꼭 가장 바쁜 날 사고를 냅니다.
모델 라우팅. 모델 티어마다 능력과 비용이 다르니, 작업 난이도에 맞춰 고르는 것도 운영의 일부입니다. 기준은 단순하게 가져갑니다. 설계·디버깅·글쓰기처럼 판단이 필요한 일은 상위 모델, 형식 변환·단순 추출처럼 기계적인 일은 하위 모델. sub-agent를 띄울 때 보조 작업에 가벼운 모델을 지정하는 것만으로도 비용 곡선이 달라집니다.
{/* TODO_HUNY: 사용량 한도나 비용 관련 본인 경험 (예: 병렬 세션이 사용량을 얼마나 먹는지 /usage에서 본 것) 한두 문장. 실측 얘기가 들어가면 이 섹션이 일반론에서 벗어납니다. */}
우리 팀에 이식한다면, 운영 표준 제안
다섯 확장 포인트를 도구 상자에 넣었다면, 마지막은 운영 규칙입니다. 제안하는 최소 표준은 이렇습니다.
- 레포마다 CLAUDE.md 한 장. 프로젝트의 컨벤션, 금지 사항, 자주 쓰는 명령을 적습니다. 모든 세션이 이걸 읽고 시작합니다.
- 반복 업무가 세 번째 등장하면 skill로 만듭니다. 두 번까지는 우연, 세 번이면 패턴입니다.
- 사고가 나면 회고 대신 hook이나 린트 룰을 추가합니다. 같은 사고는 두 번 나지 않게.
- MCP와 plugin은 분기마다 인벤토리를 점검합니다. 안 쓰는 연결은 도구 목록만 오염시킵니다.
- 권한 설정은 팀 공통 기본값을 버전 관리에 넣고, 개인 취향은 로컬 설정으로 분리합니다.
skill은 절차, sub-agent는 분업, hook은 강제, MCP는 연결, plugin은 재사용. 다섯 개의 위치가 잡히면 나머지는 반복이다.
마치며
Claude Code의 기능 목록은 계속 늘지만, 운영의 뼈대는 변하지 않습니다. 절차는 파일로, 어기면 안 되는 규칙은 hook으로, 외부 연결은 최소로, 남의 것은 골격만 가져와 내 살을 붙이는 것. 이 글 자체도 그 표준의 산출물입니다. /write 커맨드가 주제 풀을 읽고, 린터가 형식을 검사하고, humanizer가 문장을 다듬은 뒤에 사람이 경험을 채워 발행됐으니까요.
신기능이 나올 때마다 이 글 끝에 changelog 섹션을 덧붙여 운영 표준 문서로 키워갈 예정입니다.
Top comments (0)