Claude Code 완전 정복 — MCP, 스킬, 서브에이전트까지 실전 셋업 가이드

Claude Code를 열면 가장 먼저 확인해야 할 것들이 있다.

/model — 모델 전환이 핵심이다. Sonnet이 기본이고 대부분의 작업에 충분하다. Opus는 복잡한 아키텍처 설계나 대규모 리팩토링에만 쓴다. Haiku는 대량 데이터 처리나 반복 작업에 적합하다. 특히 월 20달러 플랜이라면 Opus를 기본으로 두면 크레딧이 순식간에 사라진다.

/compact — 대화가 길어지면 컨텍스트 윈도우가 차오른다. 70%를 넘기면 반드시 실행해야 한다. 이전 대화를 요약해서 압축하고, 핵심 맥락만 유지한다.

Shift+Tab — Plan 모드. 코드를 바로 쓰기 전에 "어떻게 할 건지" 계획부터 세우게 한다. 복잡한 작업일수록 이게 결과 품질을 좌우한다.

/cost — 현재 세션의 사용량 확인. 예산 관리에 필수.

이 네 가지만 습관 들여도 Claude Code 경험이 확 달라진다.

MCP(Model Context Protocol)는 Claude Code의 가장 강력한 확장 기능이다. 외부 서비스에 직접 접근할 수 있게 해준다.

가장 실용적인 예가 GitHub MCP 서버다. 연결하면 Claude가 직접 PR을 만들고, 이슈를 확인하고, 코드 리뷰를 수행한다. 터미널에서 git 명령어를 치는 것보다 훨씬 자연스럽다.

설정 방법:

• •settings.json에 mcpServers 섹션 추가
• •GitHub Personal Access Token 발급
• •서버 설정에 토큰과 리포지토리 정보 입력

럿지 개발에서 실제로 사용하는 MCP 서버들:

• •GitHub — PR 생성, 이슈 관리
• •Firebase — Firestore 직접 조회/수정
• •Playwright — 브라우저 자동 테스트
• •Context7 — 최신 라이브러리 문서 자동 참조

Context7은 특히 유용하다. Next.js나 Firebase SDK 버전이 바뀌어도 자동으로 최신 문서를 참조한다. 구버전 API로 코드를 작성하는 실수가 사라진다.

스킬은 Claude Code에게 "이런 상황에서는 이렇게 해"라고 가르치는 방법이다. SKILL.md 파일 하나에 워크플로를 정의하면 된다.

스킬이 저장되는 위치:

• •~/.claude/skills/ — 전역 스킬 (모든 프로젝트에서 사용)
• •.agents/skills/ — 프로젝트별 스킬 (이 프로젝트에서만)

럿지에서 실제로 사용하는 커스텀 스킬 예시:

blog-content-gen — 외부 링크를 주면 럿지 블로그 콘텐츠로 변환. 이미지 생성, Firestore 등록까지 원스톱.

nano-banana-pro — Gemini 이미지 생성 API를 래핑한 스킬. "이런 이미지 만들어줘"라고 하면 해상도, 프롬프트, 저장까지 자동.

ludgi-seed-data — 프로젝트 데이터 관련 유틸리티.

스킬의 핵심은 재현성이다. 한 번 정의해두면, 어떤 세션에서든, 누가 쓰든 동일한 결과가 나온다. 팀에서 공유하면 온보딩 시간도 줄어든다.

SKILL.md 작성 포맷:

• •name, description (frontmatter)
• •사용법 (Usage)
• •실행 예시 (Examples)
• •주의사항 (Important Notes)

서브에이전트는 메인 에이전트가 작업의 일부를 독립된 에이전트에게 위임하는 기능이다. 각 서브에이전트는 자체 컨텍스트에서 실행되고, 결과만 메인에게 돌려준다.

왜 중요한가? 병렬화 때문이다. 벤치마크에서 서브에이전트 병렬 실행이 순차 실행 대비 3.2배 빠른 것으로 나타났다.

실전 패턴:

탐색 전용 서브에이전트 — "이 코드베이스에서 인증 관련 파일 전부 찾아줘." 메인은 기다리지 않고 다음 작업을 기획한다.

병렬 구현 — 3개 서브에이전트가 각각 다른 API 엔드포인트를 동시에 수정한다. worktree 격리로 파일 충돌 없음.

리뷰 전용 — 코드를 쓰는 에이전트와 리뷰하는 에이전트를 분리한다. 셀프 리뷰보다 품질이 높다.

주의할 점이 있다. 서브에이전트에게 너무 큰 작업을 던지면 안 된다. "이 프로젝트 전체 리팩토링해줘"가 아니라 "이 파일의 이 함수를 이 방식으로 바꿔줘"처럼 구체적으로 지시해야 한다. 분해 능력이 핵심이다.

Claude Code의 메모리는 세 계층으로 나뉜다.

Layer 1: 세션 메모리 (임시)

현재 대화 안에서만 유지된다. 세션을 닫으면 사라진다. /compact로 압축하면 핵심만 남긴다.

Layer 2: 프로젝트 메모리 (CLAUDE.md)

프로젝트 루트에 CLAUDE.md 파일을 두면 매 세션 시작 시 자동으로 읽는다. 여기에 기술 스택, 코딩 규칙, 아키텍처 결정, 보안 정책을 적어둔다.

럿지 CLAUDE.md에 포함된 내용:

• •Next.js 16 + Firebase + Tailwind 기술 스택
• •API 작성 시 verifySession/verifyAdmin 필수
• •Rate limiter 프리셋 (emailLimiter, aiLimiter)
• •Firestore rules 수정 시 owner/admin 체크 필수
• •블로그 콘텐츠 생성 파이프라인

Layer 3: 영구 메모리 (~/.claude/memory/)

프로젝트를 넘어 유지되는 기억. 사용자 선호, 피드백, 프로젝트 간 공통 패턴을 저장한다. "지난번에 이 방식 좋았다"고 하면 메모리에 저장해서 다음에도 동일하게 적용한다.

이 세 레이어를 잘 설계하면, 새 세션을 열어도 "이 프로젝트가 뭔지, 어떤 규칙이 있는지, 사용자가 뭘 선호하는지" 에이전트가 즉시 이해한다.

이론은 충분하다. 오늘 당장 이 순서대로 해보자.

1단계: 모델 전환 습관 (1분)

간단한 작업은 Haiku, 일반 코딩은 Sonnet, 복잡한 설계는 Opus. /model로 전환하는 습관을 들인다.

2단계: CLAUDE.md 작성 (10분)

프로젝트 루트에 CLAUDE.md를 만든다. 기술 스택, 코딩 규칙, 프로젝트 구조만 적으면 충분하다.

3단계: MCP 서버 하나 연결 (15분)

GitHub MCP부터 시작한다. settings.json에 설정 추가하고 토큰 발급받으면 끝. Claude가 PR 만들고 이슈 확인하는 걸 보면 감동이 온다.

4단계: 스킬 하나 만들기 (20분)

자주 하는 작업을 SKILL.md로 정의한다. "테스트 돌리고 결과 정리해줘" 같은 간단한 것부터.

5단계: 서브에이전트 써보기 (10분)

"이 파일 분석해줘"를 서브에이전트에 위임해본다. 메인이 기다리지 않고 다음 작업을 할 수 있다는 걸 체감하면 돌아갈 수 없다.

럿지에서 프로젝트를 의뢰하는 클라이언트들도 이 도구를 활용한다. 기획 단계에서 AI 프로젝트 가이드가 요구사항을 정리해주고, 프리랜서와의 소통에서도 에이전트가 초안을 잡아준다. 도구를 아는 클라이언트가 더 좋은 결과물을 받는다.