00. Claude Code 지도 한 장 — 폴더 구조부터 서브에이전트까지

Claude Code를 처음 켜면 보통 두 부류로 갈린다. 자연어로 "이거 만들어 줘"를 외치는 자판기 사용자, 그리고 이 도구가 내부에서 어떻게 일을 나눠 처리하는지 먼저 들여다보는 사람. 같은 도구를 써도 6개월 뒤 실력 차이는 여기서 갈린다.

이 글은 그 두 번째 부류가 되기 위한 지도다. 앞으로 이어질 연재(문서 Q&A 서비스를 Claude Code로 한 겹씩 쌓아 올리는 11편)에서 계속 등장할 부품들 (슬래시 명령, 스킬, 서브에이전트, 에이전틱 팀, 플러그인, 훅, 그리고 이 모두를 연결하는 메모리)을 한자리에 모아 정리한다. 코드를 한 줄도 짜기 전에, 작업장을 먼저 파악하는 셈이다.

먼저 한 장으로 보는 작동 구조

Claude Code의 부품들은 따로 노는 게 아니라 서로 맞물린다. 사용자가 던진 지시 하나가 어떤 경로로 흘러 명령이 되고, 스킬을 부르고, 서브에이전트에게 일을 나눠 주는지를 그림으로 먼저 보자. 세부 설명은 그 뒤에 하나씩 풀어 간다.

사용자의 지시는 Claude Code 본체를 거쳐 명령/스킬/서브에이전트로 갈라지고, 훅이 위험을 걸러내며, 외부 도구는 표준 규격으로 연결된다. CLAUDE.md는 이 전 과정을 관통하는 규칙이다.

1. 메타 폴더: 설정은 전부 .claude 안에 있다

Claude Code의 모든 맞춤 설정은 프로젝트 루트의 CLAUDE.md 파일과 .claude/ 폴더에 담긴다. 이 구조만 머리에 넣어 두면 "이 설정은 어디서 바꾸지?"를 헤매지 않는다.

your-project/
├── CLAUDE.md                 # 프로젝트 메모리(팀 규칙). Claude가 매번 먼저 읽는다
├── .mcp.json                 # 이 프로젝트에서 쓸 외부 도구(MCP) 정의 (선택)
└── .claude/
    ├── settings.json         # 권한/훅/환경변수 (팀 공유, git 커밋 대상)
    ├── settings.local.json   # 개인 설정 (git 무시)
    ├── commands/             # 커스텀 슬래시 명령 (.md 한 개 = 명령 하나)
    │   └── deploy.md         #   → /deploy 로 호출
    ├── agents/               # 커스텀 서브에이전트 (.md)
    │   └── reviewer.md       #   → 코드 리뷰 전담 에이전트
    └── skills/               # 스킬 (폴더 + SKILL.md)
        └── write-post/SKILL.md

~/.claude/                    # 전역: 모든 프로젝트에 공통 적용되는 내 설정

핵심은 두 층이라는 점이다. 프로젝트 폴더 안의 .claude/는 그 저장소에서만, 홈 디렉터리의 ~/.claude/는 내 모든 프로젝트에서 적용된다. 팀과 공유할 규칙은 프로젝트 쪽에 두고 git에 커밋하면, 팀원 모두의 Claude Code가 같은 규칙을 따른다.

폴더 구조와 메모리 파일(CLAUDE.md)의 자세한 규칙은 공식 문서에 정리돼 있다 (메모리 문서, 설정 문서).

2. 기본 슬래시 명령: 자주 쓰는 것부터

Claude Code에는 60개가 넘는 내장 슬래시 명령이 있다. 전부 외울 필요는 없다. 개발하면서 손에 붙는 건 십여 개 남짓이라, 아래 표에서 개발 단골(★) 표시한 것부터 익히면 된다. 나머지는 필요할 때 /help로 찾으면 충분하다.

전체 명령 목록과 각 동작은 공식 문서에서 확인할 수 있다 (슬래시 명령 문서). 표의 ★는 이 연재 11편에서 실제 서비스를 만들며 반복해서 쓰게 될 것들이다.

3. 명령 vs 스킬 vs 서브에이전트: 무엇을 언제 쓰나

여기서부터가 진짜다. 이름이 비슷비슷해 헷갈리지만, 각자 맡는 일이 다르다. 작업장 비유로 풀면 이렇다.

슬래시 명령(command) — 단축키

매번 똑같이 입력하는 지시를 한 단어로 줄인 것이다. .claude/commands/deploy.md에 배포 절차를 적어 두면 /deploy 한 번으로 끝난다. 작고 반복적인 동작을 묶는 데 쓴다.

스킬(skill) — 전문 매뉴얼을 든 작업자

명령보다 한 단계 크다. 여러 단계의 작업 흐름과 그 분야의 전문 지식을 폴더 하나에 묶은 것이다(SKILL.md + 참고 자료). 결정적 차이는, 사용자가 명시적으로 부르지 않아도 상황이 맞으면 Claude가 알아서 꺼내 쓴다는 점이다. 예를 들어 이 블로그의 write-post 스킬은 글쓰기 요청이 들어오면 제목 추천부터 이미지 생성, 발행까지 정해진 절차로 처리한다 (스킬 문서).

서브에이전트(subagent) — 별도 방에서 일하는 보조 일꾼

본체와 분리된 자기만의 대화 문맥에서 일하는 일꾼이다. 기본으로 Explore(코드를 읽기만 하며 훑는 탐색 전용), Plan(계획 수립)이 제공되고, .claude/agents/에 직접 만들 수도 있다. 핵심 이점은 격리다. 수십 개 파일을 뒤지는 긴 탐색을 서브에이전트에게 맡기면, 그 잡음이 본체 대화를 어지럽히지 않고 결론만 돌아온다 (서브에이전트 문서).

에이전틱 팀(agentic team) — 여러 일꾼을 동시에

서브에이전트 하나가 아니라 여럿을 병렬로 굴리는 방식이다. 큰 작업을 잘게 쪼개 동시에 처리한다. 화면 열 개의 다국어 문구를 한꺼번에 분리하거나, 같은 코드를 세 관점(정확성/보안/성능)으로 동시에 검증하는 식이다. 손이 여러 개로 늘어나는 셈인데, 그만큼 결과를 한데 모아 검수하는 일이 사람의 몫으로 남는다.

플러그인(plugin) — 통째로 배포되는 묶음

위의 명령/스킬/서브에이전트/외부 도구 설정을 하나로 묶어 배포하는 패키지다. 마켓플레이스에서 /plugin으로 설치한다. 디자인, 보안, 기능 개발처럼 분야별로 잘 만들어진 묶음을 한 번에 들여올 수 있다. 단, 플러그인은 남이 만든 외부 코드이므로 신뢰 수준을 먼저 확인해야 한다(공식 마켓플레이스를 우선) (플러그인 문서).

훅(hook) — 자동 안전벨트

특정 행동 직전이나 직후에 자동으로 끼어드는 장치다. 대표적으로 rm -rf나 운영 DB 삭제 같은 위험 명령이 실행되기 전에 막는다. 사람이 매번 지켜보지 않아도 위험을 거르는 안전벨트라, 보안 편에서 본격적으로 다룬다 (훅 문서).

MCP — 외부 도구를 잇는 표준 콘센트

MCP(Model Context Protocol: 모델 컨텍스트 프로토콜)는 AI와 외부 도구(데이터베이스/API/웹검색)를 잇는 표준 규격이다. 콘센트 규격이 같으니 어떤 도구든 같은 방식으로 꽂힌다. /mcp로 관리하며, 예컨대 PostgreSQL 데이터베이스를 Claude가 직접 쓰는 도구로 연결한다 (MCP 문서).

CLAUDE.md(메모리) — 이 모두를 관통하는 규칙

마지막 부품이자 가장 중요한 것. 위의 모든 도구가 어떻게 동작하든, CLAUDE.md에 적힌 팀 규칙은 매 작업에서 먼저 적용된다. "스택은 무엇, API 주소는 환경변수로, 운영 DB 직접 변경 금지" 같은 규칙을 한 번 새겨 두면, 사람이 자리를 비워도 에이전트가 선을 넘지 않는다.

사용자는 감독, 서브에이전트들은 각자 방에서 동시에 일하는 팀원이다. 결과를 모아 "이게 맞나"를 판단하는 자리는 여전히 사람의 것이다.

이 연재가 만들 서비스의 기술 지도

앞의 도구 이야기를 실제로 써먹을 무대가 필요하다. 이 연재는 문서 질의응답 서비스 하나를 빈 폴더에서 끝까지 만든다. 그 서비스를 한 장의 기술 지도로 펼치면 이렇다. 왼쪽 기획에서 출발해 가운데 개발을 거쳐 오른쪽 운영과 마케팅으로 이어진다.

네 덩어리로 읽으면 쉽다. 기획은 PRD(Product Requirements Document: 제품 요구사항 문서)에서 프로토타이핑까지, 무엇을 만들지 정하는 단계다. 개발은 화면(FE)에서 캐시, 백엔드(BE), 다시 캐시, 데이터베이스(RDB)로 이어지는 본체이고, 여기서 외부 API와 AI 모델(검색, 매칭, LLM 등), 데이터 저장(VectorDB 포함), 큐(백그라운드 작업)가 가지를 친다. 운영은 서버운영과 모니터링, 보안을 묶고, 마케팅은 SEO와 AEO(Answer Engine Optimization: 답변엔진 최적화), 사용자 분석을 맡는다.

앞으로 매 편은 이 지도 위에서 오늘 만지는 부분만 진하게 켜고 나머지는 흐릿하게 둔다. 그 자리엔 안내하는 학생이 한 명씩 등장한다. 큰 그림의 어디쯤을 다루는지 늘 같은 지도에서 확인하면, 개념이 따로 놀지 않고 한 서비스로 꿰인다.

그래서, 이 지도를 왜 먼저 보나

도구의 작동 구조를 알면 지시가 정교해진다. "검색 만들어 줘" 대신 "Explore 서브에이전트로 저장 구조를 먼저 훑고, 키워드와 벡터 검색을 각각 붙여 줘"라고 콕 집어 시킬 수 있다. 같은 AI라도 무엇을 시킬 수 있는지 아는 사람이 더 나은 결과를 끌어낸다.

다음 편부터는 이 부품들을 실제 서비스에 하나씩 끼워 넣는다. 빈 폴더에서 시작해 Plan Mode로 골격을 세우고(1편), 에이전트가 데이터베이스를 망가뜨려도 되돌리는 법을 익히고(2편), 서브에이전트로 검색 세 종류를 동시에 만들어 비교한다(3편). 지도를 손에 들었으니, 이제 길을 나설 차례다.