클로드 코드 완전 정복, 프롬프트만 치던 당신이 몰랐던 진짜 사용법

혹시 이렇게 쓰고 계신가요?

터미널 열고, 프롬프트 몇 줄 치고, 결과 받고, 끝.

사실 저도 처음엔 그랬어요. 클로드 코드를 쓴다고 하면서, 실제로는 그냥 "ChatGPT 터미널 버전" 정도로만 쓰고 있었거든요. 그러다 어느 날 깨달았습니다. 내가 이 도구의 20%도 못 쓰고 있었다는 걸요.

클로드 코드는 단순한 코드 자동완성 도구가 아닙니다. 제대로 설정하면 파일을 스스로 탐색하고, 병렬로 여러 작업을 처리하고, 자신의 실수를 기록해서 반복하지 않는 자율 실행 에이전트가 됩니다.

2026년 기준 클로드 코드 관련 GitHub 오픈소스 모음인 everything-claude-code는 5만 개 이상의 스타를 기록했고, 대부분의 사용자가 이 도구 능력의 30% 정도만 활용하고 있다는 분석도 나와 있어요. 클로드 코드를 1년 넘게 써온 개발자들이 공통적으로 하는 말이 있습니다. "설정을 제대로 안 하면, 그냥 비싼 자동완성 도구예요."

이 글에서는 클로드 코드 핵심 개발자 Boris Cherny와 팀의 실제 워크플로우를 기반으로, 진짜 실력자들이 어떻게 쓰는지 정리했습니다.

클로드 코드, 사람들이 가장 많이 하는 오해

"프롬프트만 잘 짜면 된다."

이게 가장 흔한 오해예요. 물론 프롬프트 품질은 중요합니다. 하지만 클로드 코드의 진짜 강점은 프롬프트 실력이 아니라, 얼마나 잘 설정하고 운영하느냐에 달려 있어요.

사람들이 놓치는 세 가지가 있습니다.

첫째, 클로드 코드는 매 세션을 처음부터 시작하는 도구가 아니에요. 잘 설정하면 실수를 기록하고, 규칙을 축적하고, 팀 전체가 같은 기준으로 코드를 작성하는 시스템이 됩니다.

둘째, 반복 작업은 이미 스킬로 만들어야 합니다. 같은 지시를 두 번 이상 했다면, 그건 자동화해야 할 신호예요.

셋째, 서브에이전트를 모르는 분들이 정말 많아요. 복잡한 작업을 메인 세션에 몰아넣으면 컨텍스트가 오염되고, 결과 품질이 떨어집니다.

핵심은 .claude 폴더 구조입니다

대부분의 사람들이 .claude 폴더 안에 CLAUDE.md 파일 하나만 만들고 끝냅니다. 하지만 이 폴더는 훨씬 정교한 설정 시스템을 품고 있어요.

적용 범위는 두 가지입니다. 프로젝트 범위는 .claude/ 폴더 안에 팀 전체가 공유하는 설정을 담고, 전역 범위는 ~/.claude/ 폴더 안에 내 컴퓨터 어디서든 적용되는 설정을 담습니다.

핵심 구조를 정리하면 이렇습니다. CLAUDE.md는 매 세션마다 자동으로 불러오는 핵심 지침입니다. CLAUDE.local.md는 나만 보는 개인 노트로 절대 Git에 올라가지 않아요. skills/ 폴더는 반복 작업을 슬래시 명령어로 저장하는 공간이고, agents/ 폴더는 독립적으로 작동하는 서브에이전트 정의 파일을 담습니다.

특히 중요한 포인트가 있어요. 스킬 폴더 안에는 추가 파일, 템플릿, 예제까지 함께 넣을 수 있어서 단순 명령어보다 훨씬 강력합니다.

CLAUDE.md, Anthropic 팀은 이렇게 씁니다

CLAUDE.md는 클로드가 매 세션을 시작할 때 가장 먼저 읽는 파일입니다. Boris Cherny가 강조하는 핵심 원칙은 딱 두 가지예요.

첫째, 짧게 유지하세요. 긴 파일은 정작 중요한 규칙을 묻어버립니다. 모든 줄에 이 필터를 적용해 보세요. "이 줄을 없애면 클로드가 실수를 하나?" 대답이 "아니오"라면 과감히 삭제합니다. 이 파일은 지식 저장소가 아니라 실수 방지 장치입니다.

둘째, 클로드가 스스로 규칙을 쓰게 하세요. 클로드가 실수를 할 때마다 "CLAUDE.md를 업데이트해서 이 실수를 반복하지 마"라고 지시합니다. 몇 주만 지나면 이 파일이 실제로 발생한 모든 문제의 해결책을 담은 살아있는 문서가 됩니다.

Anthropic 팀의 실제 CLAUDE.md는 화려한 설명 없이 이런 내용만 담겨 있어요. "항상 npm 대신 bun을 써라", "PR 전에 lint와 test를 실행해라." 모두 클로드가 모를 수 없는 실전 주의사항들입니다.

Boris는 PR 리뷰 댓글에서 @claude를 태그해 클로드가 직접 규칙을 CLAUDE.md에 커밋하게 합니다. 리뷰어가 실수를 한 번 잡으면, 그 실수는 다시는 반복되지 않아요. 이걸 "복리 엔지니어링"이라고 부릅니다.

스킬과 서브에이전트, 이 두 가지가 진짜 실력 차이를 만듭니다

스킬은 클로드 코드를 "무엇이든 할 수 있는 에이전트"에서 "우리 팀이 필요한 세 가지를 완벽하게 하는 에이전트"로 바꿔주는 핵심 기능입니다.

작동 원리는 단순해요. ~/.claude/skills/ 폴더 안에 하위 폴더를 만들고, 그 안에 SKILL.md 파일을 넣으면 폴더 이름이 자동으로 슬래시 명령어가 됩니다. summarize-changes라는 폴더를 만들면 /summarize-changes 하나로 해당 스킬이 실행되는 거예요.

스킬의 강력한 점은 세 가지입니다. 세션 시작 시에는 설명 텍스트만 읽어 토큰을 아끼고, 실제로 스킬이 호출될 때만 전체 내용을 불러옵니다. 각 스킬 폴더에 템플릿 파일, 예제, 참고 문서를 함께 넣을 수 있고, !로 시작하는 줄은 실행 시점에 셸 명령어로 실행되어 결과가 프롬프트에 삽입됩니다.

커뮤니티에서 가장 인기 있는 mattpocock/skills에는 /grill-me(코드 작성 전 계획 검토)와 /tdd(테스트 주도 개발 강제 적용) 같은 스킬이 포함되어 있어요. Anthropic 공식 스킬에는 /code-review(4개 에이전트 병렬 코드 리뷰)도 있습니다.

서브에이전트는 메인 세션의 컨텍스트를 오염시키지 않고 독립된 공간에서 특정 작업을 처리하는 전문 에이전트입니다. .claude/agents/ 폴더 안에 마크다운 파일을 하나 만들면 돼요. 파일 앞부분에 이름, 설명, 사용 가능한 도구, 모델을 선언하면 됩니다.

PR 리뷰 에이전트를 만들 때 중요한 포인트가 있어요. "지적하지 말아야 할 항목"을 반드시 명시해야 합니다. 이 부분이 없으면 결과물이 변수명 스타일 같은 사소한 지적으로 가득 차거든요.

잘 쓰는 사람만 아는 명령어들

대부분의 사용자는 /clear와 /compact 정도만 알고 사용합니다. 하지만 진짜 생산성은 잘 알려지지 않은 명령어들에 숨어 있어요.

/goal은 완료 조건을 설정하면 그 조건이 충족될 때까지 클로드가 계속 작업하는 기능입니다. "테스트가 3회 연속 실패 없이 통과할 것" 같은 검증 가능한 조건을 설정하면 자리를 비워도 됩니다.

/rewind는 매 프롬프트마다 체크포인트를 저장합니다. 클로드가 잘못된 방향으로 가면 "그거 안 됐어, 다시 해봐"라고 입력하지 말고, /rewind로 실수 이전으로 되돌아가야 해요. 잘못된 시도가 컨텍스트 안에 남으면 모델이 계속 그 방향으로 영향을 받기 때문입니다.

/btw는 현재 대화 기록에 남지 않는 사이드 질문을 할 때 씁니다. /branch는 위험한 시도를 하기 전에 세션을 복사해서 실험합니다. --bare 옵션은 비대화형 실행 시 시작 속도를 최대 10배 빠르게 합니다.

자동 모드와 /focus, /goal을 조합하면 "지시 작성 후 자리 비움, 완성된 PR로 복귀"가 가능해집니다.

MCP로 코딩 에이전트를 시스템 에이전트로 확장하기

MCP(Model Context Protocol)는 클로드 코드를 외부 시스템과 연결하는 표준 인터페이스입니다. MCP가 없으면 클로드는 파일을 읽고 명령어를 실행하는 수준이지만, MCP가 있으면 GitHub 이슈를 읽고, 데이터베이스를 쿼리하고, Figma 디자인을 가져오고, Sentry 에러를 실시간으로 확인합니다.

실무에서 자주 쓰이는 MCP를 정리하면 이렇습니다. GitHub은 저장소 관리와 PR, 이슈를 처리합니다. Context7은 최신 라이브러리 문서를 실시간으로 가져오는데, 프롬프트 뒤에 "use context7"만 붙이면 돼요. Sentry는 실제 에러 스택 트레이스를 가져오고, Playwright는 브라우저 자동화를 처리합니다.

중요한 주의사항이 있어요. MCP를 너무 많이 설치하지 마세요. 도구 목록이 길어질수록 클로드의 의사결정 품질이 떨어집니다. GitHub, Context7, 도메인 특화 한두 가지로 시작하는 게 좋습니다.

팀 공유 MCP 설정은 .mcp.json 파일에 담아 저장소에 커밋하면, 새 팀원이 저장소를 클론하는 순간 모든 연결이 완성됩니다. 온보딩 시간이 확 줄어드는 걸 체감할 수 있어요.

Anthropic 팀이 실제로 하는 것들

Boris와 팀이 일상적으로 쓰는 습관 몇 가지를 정리했습니다.

클로드가 결과를 검증하는 방법을 항상 제공합니다. 테스트, 스크린샷, 실제 명령어 출력이 없으면 완성으로 인정하지 않아요. 이 습관 하나가 결과물 품질을 2~3배 끌어올린다고 합니다.

3~5개의 세션을 병렬로 운영합니다. Git 워크트리를 활용해 각 세션이 독립된 공간에서 작업하게 하는 거예요. 실제로 클로드 코드 1년 사용자 중에는 모니터 3개를 이용해 6개의 워크트리를 동시에 돌리는 세팅으로 개발 속도를 극대화한 사례도 있습니다.

새 코드베이스를 이해할 때는 클로드에게 ASCII 다이어그램으로 그려달라고 합니다. 생각보다 훨씬 빠르게 구조가 파악돼요.

/voice 명령어로 말로 프롬프트를 입력하면 타이핑보다 훨씬 자연스럽게 세부 사항을 전달할 수 있습니다.

마무리

클로드 코드는 "잘 치는 프롬프트"의 도구가 아닙니다. 잘 설정하고, 잘 운영하는 도구입니다.

CLAUDE.md에 실수 규칙을 쌓고, 스킬로 반복 작업을 저장하고, 서브에이전트로 작업을 격리하고, MCP로 개발 스택 전체와 연결하면, 그게 진짜 클로드 코드입니다.

오늘 당장 하나만 시작한다면 CLAUDE.md에 "이 실수 반복하지 마"를 쓰는 습관부터 시작해 보세요. 몇 주 후면 이 파일이 살아있는 팀 가이드가 되어 있을 거예요.

프롬프트를 잘 치는 사람과 설정을 잘 하는 사람, 6개월 후 결과물의 차이는 생각보다 훨씬 큽니다.