클로드 코드 확장 지도: CLAUDE.md, 스킬, 서브에이전트, 훅은 각각 뭘 대신하나

Claude Code(클로드 코드)는 설치한 그대로도 쓸 수 있지만, 반복되는 작업을 맡기려면 CLAUDE.md, 스킬, 서브에이전트, 훅, 플러그인 같은 확장 장치를 붙이게 됩니다. 이 장치들은 이름은 비슷해 보여도 각각 대신하는 일이 다릅니다.

실제로 이 장치 이름들이 먼저 헷갈리기 시작하는 시점이 있습니다. 특히 스킬, 서브에이전트, 훅, 플러그인 네 가지는 다 "뭔가를 자동으로 해준다"는 말로 들리는데 정작 언제 어느 것을 써야 하는지는 아무도 정리해주지 않습니다. 터미널을 처음 열고 Claude Code를 설치해 첫 질문을 던지고 MCP까지 연결해 봤다면 다음으로 마주치는 게 바로 이 혼동입니다. 실제로 영어권 자동완성에는 "claude code subagents vs skills"라는 쿼리가 그대로 잡힙니다. 나만 헷갈리는 게 아니라는 뜻입니다.

다섯 자리를 한 번 구분해두면 그다음부터는 이름표만 보고도 어디로 가야 할지 알게 됩니다. 스킬, 서브에이전트, 훅은 Claude Code 자체 기능이라 릴리스마다 세부가 바뀔 수 있으니 오래된 시점에 읽으신다면 공식 문서를 함께 확인해 주세요.

확장 (Extend)

확장은 Claude Code의 기본 동작 위에 무언가를 더하는 다섯 가지 장치를 통틀어 부르는 말이다. CLAUDE.md는 매 세션 항상 켜져 있는 맥락이고, 스킬은 필요할 때 불러오는 지식과 절차이고, 서브에이전트는 격리된 실행 창구이고, 훅은 정해진 시점에 사람 손 없이 실행되는 스크립트이고, 플러그인은 이것들을 묶어 배포하는 단위다.

다섯 확장 장치 비교표

Claude Code 공식 문서 "확장하기(Extend Claude Code)"는 정확히 이 장치들을 한 표로 비교합니다. 그 표를 우리 트랙의 순서에 맞춰 다시 짰습니다.

표 오른쪽 끝, 플러그인 자리를 조금 풀어드리겠습니다. 플러그인은 나머지 넷과 나란히 놓인 하나의 장치라기보다 포장지에 가깝습니다. 공식 문서는 플러그인이 스킬, 훅, 서브에이전트, MCP 서버를 하나의 설치 단위로 묶어 배포한다고 설명합니다. 그래서 표의 "무엇을 대신하나" 칸도 다른 넷과 결이 다릅니다. 나머지 넷은 내가 직접 만드는 것을 대신하고, 플러그인은 남이 만든 것을 설치하는 일을 대신합니다.

"언제 손이 가나" 칸이 막연하게 느껴진다면 공식 문서가 제시하는 더 구체적인 신호를 참고하셔도 됩니다. Claude가 같은 관례나 명령을 두 번 틀리면 CLAUDE.md에 적을 때가 된 신호이고, 같은 지시를 세 번째 채팅창에 붙여넣고 있다면 스킬로 만들 때가 된 신호이고, 곁가지 작업이 다시 참조하지도 않을 검색 결과와 로그로 대화창을 채우고 있다면 서브에이전트로 돌릴 때가 된 신호입니다. 신호가 오기 전에 미리 다섯 장치를 전부 갖춰둘 필요는 없습니다. 공식 문서도 처음부터 모든 걸 설정하지 않아도 된다고 못박습니다.

배우는 순서는 부담이 커지는 순서다

순서를 정한 기준은 하나입니다. 설치해서 쓰기보다 파일 하나 쓰기가 부담이 크고, 파일 하나 쓰기보다 절차를 정리해서 스킬로 만드는 일이 부담이 크고, 그보다 일을 나눠 맡기는 서브에이전트가 부담이 크고, 가장 큰 부담은 사람이 지켜보지 않아도 돌아가게 만드는 자동화입니다. 아래에서 위로 갈수록 내가 직접 판단하고 관리할 것이 많아집니다.

다만 이 트랙의 실제 레슨 순서가 부담 순서와 정확히 겹치지는 않습니다. 사다리로 보면 플러그인 설치가 CLAUDE.md보다 아래(레슨으로 치면 앞)에 있어야 자연스럽지만, 이 트랙은 CLAUDE.md를 레슨 2에 놓고 플러그인을 레슨 3으로 미뤘습니다. 이유는 순서가 아니라 재료 때문입니다. 이 뒤에 나오는 스킬, 서브에이전트, 자동화 레슨이 전부 CLAUDE.md에 적어둔 규칙을 그대로 가져다 씁니다. 무엇을 배우기 전에 무엇을 먼저 준비해둬야 하는지가, 순수한 부담 크기보다 앞선 셈입니다.

.claude 디렉토리를 한 번 열어본다

다섯 장치는 전부 파일이나 폴더의 형태로 존재합니다. 어디에 있는지 눈으로 한 번 확인하면 이후 레슨이 훨씬 수월해집니다. Claude Code는 두 자리를 봅니다. 지금 작업 중인 프로젝트 폴더의 .claude/와 내 컴퓨터 홈 폴더의 ~/.claude/입니다. 공식 문서 ".claude 디렉토리 살펴보기"에 따르면 프로젝트의 .claude/에는 settings.json(권한과 훅 설정), settings.local.json(내 컴퓨터에만 있는 개인 설정), skills/, agents/, rules/, commands/ 같은 폴더가 들어갑니다. 훅은 따로 폴더가 없고 settings.json 안의 hooks 항목으로 존재합니다. 홈의 ~/.claude/에는 여기에 더해 개인 CLAUDE.md와 자동 메모리가 쌓이는 projects/ 폴더가 함께 있습니다.

저는 이 확인을 한참 뒤에야 했습니다. 처음 열어본 .claude/에는 뭐가 이미 들어 있었고, 그게 신기해서 자동으로 관리되는 줄 알았습니다. 프로젝트마다 만들어 쓰면서도 안을 들여다보지는 않았죠. 그러다 어느 날, 한참 쓰던 프로젝트의 폴더가 비어 있고 만들어둔 줄 알았던 스킬도 제대로 만들어져 있지 않다는 걸 발견했습니다. 저만 잘 되고 있는 줄 알았던 겁니다. 폴더 구조부터 배워야겠다고 처음 느낀 게 그때였고, 위의 명령어 두 줄이 그때 아쉬웠던 확인을 대신해 줍니다.

MCP가 빠진 이유: 방향이 다르다

MCP는 다섯 장치 옆에 자주 붙어 다니는 이름이지만 이 레슨에는 넣지 않았습니다. 공식 문서도 확장 기능을 나열할 때 MCP를 같은 표 안에 넣어두긴 하지만, 하는 일 자체는 다릅니다. CLAUDE.md, 스킬, 서브에이전트, 훅, 플러그인은 전부 Claude Code가 스스로 무엇을 할지에 관한 장치입니다. MCP는 방향이 다릅니다. Claude Code를 데이터베이스나 Slack(슬랙) 같은 바깥 서비스에 연결하는 통로입니다. 이미 이 여정의 앞에서 두 번 다뤘습니다. 트랙 ②(연결하기)가 MCP라는 공통 규격 자체를 설명했고, 트랙 ③(CLI 트랙)에서 claude mcp add로 실제 연결까지 해봤습니다. 여기서 다시 설명하면 중복이라 이 트랙은 MCP를 다루지 않습니다.