클로드 코드 활용법: CLAUDE.md·MCP·서브에이전트

클로드 코드(Claude Code)는 단순한 채팅 도구가 아니라
파일을 읽고, 셸을 실행하고, 외부 시스템을 호출하는 에이전트형 CLI입니다. 그 결과 잘 쓰는 사람과 못 쓰는 사람의 격차가 IDE 자동완성보다 훨씬 큽니다. 이 글은 Anthropic 공식 CLI를 실전에서 효율 100배로 끌어올리기 위한 핵심 패턴 8개와 흔한 함정을 정리합니다.

이 가이드는 Claude Code(Anthropic 공식 CLI) 2026년 5월 기준입니다. 슬래시 커맨드·스킬·MCP 사양은 빠르게 업데이트되므로 공식 문서를 함께 참고하세요. AI 코딩 워크플로우 전반은 AI 시대 개발자 생존법 7단계, 용어가 낯설면 AI-native 개발자 용어집 35선을 먼저 보시면 도움이 됩니다.

클로드 코드는 무엇이 다른가#

클로드 코드를 "ChatGPT 같은 챗봇 한 종류"로 받아들이는 순간 활용도가 절반으로 떨어집니다. 핵심 차이는 에이전트 루프입니다. 사용자가 한 번 요청을 하면 모델이 스스로 파일을 읽고, 코드를 수정하고, 셸 명령을 실행하고,
결과를 보고 다음 행동을 결정합니다. 이 루프가 한 번에 수십 단계까지 이어집니다.

기억해 둘 두 가지 숫자가 있습니다.

• 컨텍스트 윈도우 200K 토큰: 대형 코드베이스도 핵심 파일은 한 세션에 다 올릴 수 있습니다. 단, MCP 서버를 너무 많이 붙이면
  도구 정의가 컨텍스트를 잠식해 실효 윈도우가 70K까지 떨어진다는 실측 사례가 있습니다. MCP 10개 미만, 활성 도구 80개 미만을 권장 상한으로 잡습니다.
• 퍼미션 모델: 읽기는 자동, 쓰기·셸 실행은 사용자 승인이 기본값입니다. --dangerously-skip-permissions로 우회할 수 있지만 후술할 함정이 있습니다.

매일 쓰는 8가지 활용 패턴#

1. CLAUDE.md: 프로젝트 메모리의 핵심#

클로드 코드는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md와 사용자 홈의 ~/.claude/CLAUDE.md를
자동으로 읽어 컨텍스트에 주입합니다. 이 파일이 잘 쓰여 있으면 매번 같은 설명을 반복할 필요가 없고,
잘못 쓰여 있으면 오히려 환각을 부추깁니다.

좋은 CLAUDE.md에 적는 것

## 절대 규칙
- next.config는 .mjs 확장자 — .ts 불가 (Next.js 14 미지원)
- npm install은 항상 --legacy-peer-deps 플래그 사용
- UI 텍스트는 KO 단일, useToolT 훅 경유

## 의사결정 근거
- Material Design 3 토큰 금지 (디자인 통일성 깨짐)
- 이모지 아이콘 금지 — lucide-react SVG만 사용

## 명령어
- npm run dev — 포트 3000 고정
- npm test — Jest 단위 테스트 일괄 실행

적지 말아야 하는 것

• 코드에서 grep으로 즉시 알 수 있는 사실(파일 경로 트리, 함수 시그니처)
• 자주 변경되는 수치(도구 개수, 포스트 수). 드리프트되면 환각 유발
• 한 번만 쓰는 임시 작업 메모

원칙은 단순합니다. "읽으면 알 수 있는 것은 적지 말고, 읽어도 모르는 것만 적는다." 즉 절대 규칙·금지 사항, 그리고 과거 결정이 왜 그렇게 내려졌는지를 적습니다.

2. 서브에이전트: 메인 컨텍스트 보호#

서브에이전트는 부모 클로드가 자식 클로드를 띄워
별도의 컨텍스트 윈도우에서 작업을 수행하게 하는 기능입니다. 자식은 자신만의 200K 윈도우를 가지며, 부모에게는 최종 요약만 돌려줍니다. 효과는 두 가지입니다.

• 메인 컨텍스트 오염 방지: 큰 디렉터리 탐색 결과가 부모 세션에 그대로 들어오면 이후 작업이 모두 좁은 윈도우에서 이루어집니다. 서브에이전트로 분리하면 검색 결과 100KB가 요약 1KB로 압축되어 돌아옵니다.
• 권한·모델 격리: 자식 에이전트에 도구 화이트리스트를 걸거나,
  비싼 Opus 대신 빠른 Haiku로 라우팅해 비용을 줄일 수 있습니다.

언제 서브에이전트를 쓰면 좋은지 정리하면 다음과 같습니다.

3. 슬래시 커맨드와 스킬: 반복 작업 자동화#

슬래시 커맨드는 자주 쓰는 프롬프트를 마크다운 한 장으로 코드화하는 기능입니다. 2026년 시점 권장 형식은 스킬(.claude/skills/<name>/SKILL.md)이며,
동일한 /name 호출이 가능하면서도 모델이 자율적으로 호출할 수 있다는 점이 다릅니다.

---
name: review
description: 현재 브랜치의 변경 사항을 코드 품질·보안·테스트 관점에서 리뷰합니다.
---

## 절차
1. `git diff main...HEAD`로 변경 범위를 확인합니다.
2. 신규·수정 함수에 단위 테스트가 누락됐는지 점검합니다.
3. 보안 체크리스트(입력 검증·인증 흐름·SQL 인젝션·시크릿 노출)를 실행합니다.
4. 마이그레이션·설정 변경이 포함됐다면 롤백 가능 여부를 확인하고 결과를 마크다운 표로 보고합니다.

이 패턴의 진짜 가치는 팀의 SOP를 코드화한다는 점입니다. 사람이 매번 기억해야 하는 절차를 파일로 옮기면 신규 입사자(혹은 다른 AI 세션)에게 그대로 넘길 수 있고,
절차가 바뀌면 마크다운 한 장만 고치면 됩니다.

4. MCP 서버: 외부 시스템 통합#

MCP(Model Context Protocol)는 Claude Code와 외부 시스템을 잇는 표준 프로토콜입니다. 자주 쓰는 연결 예는 다음과 같습니다.

• Playwright MCP: 로컬 개발 서버를 브라우저로 열어 시각 검증 자동화
• Firecrawl MCP: 웹 페이지 스크래핑·검색 결과 수집
• GitHub MCP: PR 생성·리뷰·이슈 검색
• 데이터베이스 MCP(PostgreSQL·Supabase 등): 스키마 조회·마이그레이션 검증

설정은 보통 .mcp.json 또는 ~/.claude.json에 한 블록 추가하면 됩니다.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

다만 1번에서 언급한 컨텍스트 잠식 때문에 꼭 필요할 때만 켜고, 평소에는 비활성하는 운영이 안전합니다.

5. 컨텍스트 관리: /clear와 /compact#

장시간 세션은 200K 윈도우라도 포화됩니다. 모델은 가까운 메시지일수록 가중치를 두고 참조하기 때문에,
오래된 작업 잔재가 누적되면 환각률이 올라갑니다. 두 가지 명령으로 관리합니다.

• /clear: 컨텍스트를 완전히 비우고 새 세션 시작. 작업 주제가 바뀔 때 사용.
• /compact: 누적된 메시지를 모델이 요약해 압축. 같은 주제를 이어가지만 토큰을 줄이고 싶을 때.

경험적으로는 하나의 PR = 하나의 세션이 가장 안정적입니다. 작업이 끝났다고 판단되면 미련 없이 /clear합니다.

6. Plan 모드: 위험 작업의 안전장치#

Plan 모드는 모델이 먼저 계획만 작성하고
사용자 승인 후에 실행하도록 강제하는 모드입니다. 다음과 같은 작업에서 효과가 큽니다.

• 마이그레이션·인프라 변경
• 다수 파일에 걸친 리팩터
• 외부 API 호출이 포함된 자동화

팀에서 Plan 모드 사용을 의무화해 두면
한 사람의 부주의가 전체 코드베이스를 흔들 가능성이 크게 줄어듭니다. "한 번 잘못하면 되돌리기 비싼 작업"
앞에서는 무조건 Plan 모드를 켜는 것이 비용 대비 안전 마진이 큽니다.

7. 외부 문서 인라인 참조#

URL을 직접 프롬프트에 넣으면
클로드 코드는 WebFetch 도구로 본문을 가져와 컨텍스트에 주입합니다. 활용도가 가장 높은 두 시나리오는 다음과 같습니다.

• 공식 문서를 즉석에 가져와 학습: "이 라이브러리 v2.3의 변경점을 요약해 우리 코드에 어떻게 적용할지 알려줘"
• 사양서 기반 구현 검증: RFC·MDN·표준 문서 URL을 함께 던져 모델이 임의 해석으로 빠지지 않게 함

훈련 데이터의 컷오프 이후에 나온 라이브러리·API는 모델이 자신 있게 환각하기 쉬운 영역입니다. 이때 URL 한 줄이 가장 비용 대비 효과가 큰 방어책입니다.

8. 프롬프트 엔지니어링: 모호함을 제거한다#

CLI 에이전트라고 해서 "이 함수 고쳐줘" 같은 한 줄 프롬프트로 100% 결과가 나오지 않습니다. 모호함을 제거할수록 결과가 좋아집니다.

❌ 이 함수 좀 고쳐줘
✅ src/api/users.ts:42의 getActiveUsers에서
   - 최근 30일 이내 로그인한 사용자만 반환하도록 필터를 추가하고
   - 기존 단위 테스트(src/api/users.test.ts)는 모두 통과시켜라
   - 새 테스트 1건을 같은 파일에 추가하라

좋은 프롬프트는 파일 경로 + 라인 번호 + 기대 결과 + 제약의 4요소를 갖춥니다. 함수 docstring을 미리 쓰는 행위와 거의 동일합니다.

흔한 함정과 실패 사례#

환각 함수 호출#

모델이 존재하지 않는 라이브러리·함수를 자신 있게 호출하는 사고는 여전히 흔합니다. 특히 인기 패키지의 이름은 비슷한데 시그니처가 다른 경우가 가장 위험합니다.

방어책은 두 단계입니다. 첫째, 새 라이브러리를 도입하는 작업 앞에는 공식 문서 URL을 함께 던져
모델이 임의 해석할 여지를 줄입니다. 둘째, CLAUDE.md에 "확인하지 않은 API는 호출 금지, 의심되면 grep 또는 공식 문서 fetch 후 결정"을
절대 규칙으로 적어둡니다.

컨텍스트 포화로 인한 품질 저하#

200K 윈도우는 단일 PR에는 충분하지만, 멀티 PR·다중 작업 세션에서는 부족합니다. 윈도우가 차오르면 모델은 일부 메시지를 우선순위가 낮은 것으로 취급하고,
결과적으로 초반 지시를 잊은 듯한 동작을 합니다.

대책은 두 갈래입니다. 작업을 작은 단위로 쪼개 PR마다 새 세션을 시작하거나(권장),
그게 어려우면 /compact로 중간 압축을 끼워 넣습니다.

자동 승인의 함정#

--dangerously-skip-permissions(또는 일부 환경의 yolo 모드)는 매력적이지만,
모델이 의도와 다른 파일을 삭제하거나 git push --force를 자체 판단으로 실행하는 사고가 보고됩니다. 권장하는 운영은 다음과 같습니다.

• 위험 작업(파일 삭제, git 푸시, 마이그레이션)은 항상 사용자 승인 유지
• 반복적·읽기 위주 작업은 도구별 화이트리스트(permissions.allow)로만 자동 허용
• 중요 작업은 Plan 모드로 진입해 사전 승인

테스트 없이 머지#

AI가 만든 코드는 컴파일·타입 검사를 통과해도 의미적 오류가 자주 남습니다. 가장 흔한 패턴은 의도와 결과가 미묘하게 다른 함수 입니다. 검증 없이 머지하면 운영 단계에서 발견됩니다.

따라서 운영 안정성을 중시하는 팀은
머지 전에 빌드·타입 검사·시각 회귀 검증을 모두 통과시키는 파이프라인을 둡니다. AI 워크플로우의 사람 검증 단계는 줄이는 게 아니라 위치만 옮기는 것으로 봐야 합니다.

CLAUDE.md 드리프트#

CLAUDE.md에 적힌 수치·구조가 실제 코드와 어긋나기 시작하면,
모델은 문서 쪽 정보를 더 신뢰하는 경향 때문에 오히려 더 큰 환각을 만듭니다. 자주 변경되는 수치는 CLAUDE.md에 적지 않거나,
적었다면 빌드 시점에 문서값과 실제 코드가 일치하는지 확인하는 단위 테스트로 동기화를 강제합니다.

MCP 권한 과다#

MCP는 강력한 만큼 위험도 큽니다. 데이터베이스 MCP가 자동 승인 상태로 켜져 있으면,
모델이 디버깅 중에 DELETE 쿼리를 실행할 가능성이 0이 아닙니다. 운영 DB MCP는 항상 읽기 전용으로 분리하고, 쓰기 권한은 별도 채널로 분리합니다.

자주 묻는 질문#

Q. Cursor와 Claude Code 중 무엇을 써야 하나요?

A. 둘은 경쟁이 아니라 보완 관계입니다. IDE 안에서 인라인 편집·자동완성이 핵심이면 Cursor,
멀티 파일 리팩터·셸 통합·CI 자동화가 핵심이면 Claude Code가 강합니다. 실무에서는 Cursor로 작은 단위를 빠르게 쓰고 Claude Code로 큰 단위 변경·검증을 한다는 식의 병행이 일반적입니다.

Q. CLAUDE.md는 어디에 두나요?

A. 두 위치가 자동 로드됩니다. 프로젝트 루트의 CLAUDE.md(팀 공유용, 저장소 커밋),
사용자 홈의 ~/.claude/CLAUDE.md(개인 전역 설정). 같은 키가 충돌하면 프로젝트 쪽이 우선합니다. 팀 규칙은 프로젝트, 개인 선호(말투·스타일)는 홈에 둡니다.

Q. 컨텍스트가 부족할 때 어떻게 하나요?

A. 우선순위는 다음과 같습니다. ① 작업을 더 작게 쪼개 새 세션으로 분리, ② 무거운 검색은 서브에이전트에 위임,
③ MCP를 일시 비활성화해 도구 정의 토큰을 회수, ④ /compact로 압축. ④는 마지막 카드로 남깁니다. 압축 자체가 모델 한 번을 더 태우므로 비용이 들고 정보가 손실됩니다.

Q. 슬래시 커맨드와 스킬은 어떤 차이가 있나요?

A. 둘 다 마크다운 한 장으로 정의되며 /name으로 호출됩니다. 다만 스킬(.claude/skills/<name>/SKILL.md)은 모델이 자율적으로 필요할 때 호출할 수 있도록 설계된 신규 형식이며,
슬래시 커맨드는 사용자 명시 호출 전용입니다. 신규 작성은 스킬 형식을 권장합니다.

Q. 100배 효율이라는 표현은 과장 아닌가요?

A. 평균치는 아닙니다. 다만 반복적이고 정형화된 작업(보일러플레이트 생성, 다중 파일 리네임, 테스트 보강, 마이그레이션 스크립트 작성)에서는
실제로 두 자릿수 배 차이가 흔합니다. 반대로 문제 정의 자체가 어려운 일(아키텍처 의사결정, 도메인 설계)은
같은 도구라도 가속이 잘 붙지 않습니다. 잘 쓰는 사람은 가속이 붙는 작업과 안 붙는 작업을 구분합니다.

함께 보면 좋은 글#

• AI 시대 개발자 생존법: 페어 코딩·코드 리뷰·테스트 워크플로우 7단계: Claude Code뿐 아니라 모든 AI 코딩 도구에 공통되는 워크플로우 원리
• AI-native 개발자 용어집: LLM·에이전트·DX·운영까지 35선: MCP·RAG·에이전트 등 이 글에 나온 용어의 정의 사전

---

Sources

• Claude Code 공식 문서 (Anthropic): 1차 출처 (2026년 5월 기준)
• Claude Code 슬래시 커맨드·스킬 가이드: 1차 출처
• Model Context Protocol 공식 사양: 1차 출처
• Claude Code 서브에이전트 문서: 1차 출처