Claude Code Guide

가이드

완전 초보부터 무인 자동화까지 — 클로드 코드를 제대로 부리는 법을 네 단계로 정리했습니다. 어려운 말은 뺐고, 바로 따라 할 수 있는 것만 담았습니다.

완전 초보용 · 어려운 말 없이

🧭 기초편 — 이것부터

에이전트·스킬을 쓰기 전에, 클로드를 똑똑하게 만드는 파일 3개와 필수 명령어부터. 이 3개 파일이 “클로드가 나를 기억하고, 내 규칙대로 일하게” 만듭니다.

핵심 파일 3종매번 자동 적용

📗 CLAUDE.md — 규칙서

클로드가 매번 자동으로 읽는 프로젝트 규칙서. 여기 적은 대로 항상 따릅니다. “이 프로젝트에선 이렇게 해줘”를 적는 곳.

예) “테스트 먼저 써줘 · 커밋 메시지는 한국어 · 이 폴더는 건드리지 마 · 배포 전 꼭 물어봐”

💡 짧고 명령형으로. 너무 길면 힘이 빠집니다. 프로젝트 폴더 맨 위에 둡니다.

📘 PROGRESS.md — 진행 상태

지금 무슨 작업 중인지 저장하는 곳. 대화가 끊기거나 /compact로 압축돼도 여기 있으면 그대로 이어갑니다.

4블록: 현재 상태 · 내린 결정 · 다음 할 일 3개 · 주의점

💡 세션 시작 때 맨 먼저 읽고, 작업 단계가 끝날 때마다 갱신. “상태는 대화가 아니라 파일에 둔다.”

📙 MEMORY.md — 영구 기억

세션이 바뀌어도 기억할 사실의 목록. 한 줄 = 한 사실.

예) “내 이메일은 ~ · 이 파일은 두 곳이라 저장 후 동기화 · main에 push하면 자동 배포”

💡 코드에 이미 있는 건 넣지 말 것(중복). “왜 그런지”가 중요한 것만 적습니다.

⌨️ 필수 명령어6개만 알면 충분

채팅창에 /를 치면 명령. 이 6개만 알면 대화를 안 끊기게 오래 끌고 갈 수 있습니다.

/context: 지금 대화가 얼마나 찼는지 %로 봅니다. 꽉 찰수록 느려지고 비싸집니다 — 80% 넘으면 압축 신호.
/compact: 긴 대화를 요약해 압축. 맥락은 유지하며 공간 확보. 작업 하나 끝난 자연스러운 구간에서. “요약하고 PROGRESS.md 갱신 후 이어가”처럼 지시할 수 있습니다.
/clear: 대화를 완전히 비우고 새로 시작(압축과 달리 맥락 안 남김). 전혀 다른 작업 시작할 때.
/model: 쓸 모델 바꾸기. 어려운 설계·분석 = Opus, 표준 작업 = Sonnet, 단순 잡무 = Haiku.
Esc: 실행 중인 걸 즉시 중단. 엉뚱하게 가고 있으면 누르고 다시 지시합니다.
/help: 전체 명령 목록 보기. 기억 안 나면 여기서.

⭐ 처음엔 이 스킬만목적별

카탈로그가 방대하니, 처음엔 목적별로 이것만 기억하세요. (자세한 건 카탈로그에서 검색)

복잡한 일 자동으로: autopilot — 계획·실행·검증까지 알아서. 큰 작업 통째로 맡길 때.
코드 점검: code-reviewer(작성 직후) · security-reviewer(커밋 전 보안). “이 코드 리뷰해줘”로 호출.
리서치·조사: deep-research · insane-search(막힌 사이트도 뚫어 읽음).
토큰 절약: caveman · token-diet — 출력 짧게, 비용 절감.
단순하게 정리: ponytail(과잉설계 제거) · deslop(AI 군더더기 청소).

📄 일관성 있는 보고서방법 + 스킬

“매번 같은 형식”의 핵심은 스킬 하나가 아니라 틀을 규칙으로 박아두는 것입니다.

1. 형식 고정: 좋은 보고서를 한 번 만들고 → 그 형식(제목·항목 순서·말투)을 CLAUDE.md에 규칙으로 적거나 나만의 스킬로 만듭니다(skillify / skill-create). 그러면 매번 같은 틀.
2. 문서 생성: document-generate · make-pdf · 오피스 docx · pptx · xlsx — Word/PPT/엑셀/PDF로 바로 뽑기.
3. 정기 보고: standup(일일) · weekly-digests(주간) · retro(회고) — 반복 보고를 같은 틀로.
핵심: 상태를 파일에 두면 사람이 바뀌어도 일관됩니다. PROGRESS.md(진행)·logs/날짜.md(회고)처럼 보고서도 틀을 파일에 두는 것이 원리.

자동화 · 확장 · 오케스트레이션

🎓 중급편 — 한 단계 위

기초가 익었으면 이제 반복을 자동화하고, 도구를 붙이고, 여러 작업을 동시에 돌리는 단계. 여기부터가 진짜 생산성입니다.

핵심 도구 3가지자동화·확장

⚙️ 훅(Hooks) — 자동화

특정 순간에 명령을 자동 실행. “저장하면 자동 포맷·린트”, “끝날 때 자동 빌드 검증”처럼 사람이 안 해도 돌아갑니다.

PreToolUse(실행 전 검사·차단) · PostToolUse(수정 후 포맷/타입체크) · Stop(세션 끝 최종 확인)

💡 settings.json에 설정. “매번 X 해줘”는 기억이 아니라 훅으로 박아야 진짜 자동입니다.

🔌 MCP — 외부 도구 붙이기

클로드에 새 능력을 꽂는 표준. GitHub·Playwright·DB·내 서버를 대화 안에서 직접 쓰게 됩니다.

로컬 claude mcp add 이름 -- node 서버.mjs · 원격 claude mcp add --transport http 이름 URL

💡 CLI는 사람이 치는 것, MCP는 에이전트가 스스로 호출하는 것. 한 번 붙이면 알아서 씁니다.

🧩 나만의 스킬 만들기

반복하는 작업을 슬래시 명령 하나로. “매번 이렇게 해줘”를 스킬로 박으면 다음부턴 /내스킬.

skillify / skill-create — 지금까지의 작업 패턴을 스킬 파일로 뽑아줍니다.

💡 보고서 형식·배포 절차·리뷰 체크리스트처럼 반복 + 일관성이 필요한 것에 최적.

🚀 워크플로 — 큰 작업 통째로OMC Tier-0

여러 단계를 알아서 계획·실행·검증. 키워드만 쓰면 발동합니다.

autopilot: 기능 하나를 계획→구현→리뷰→검증까지 자동. “큰 거 하나 맡기고 싶을 때” 기본값.
ultrawork: (ulw) 멈추지 않고 끝까지 밀어붙이는 고강도 모드. 목표가 명확할 때.
ralph: “바위는 멈추지 않는다” — 완료·검증까지 반복 루프. 지루한 대량 작업에.
team: 여러 전문 에이전트를 팀으로 병렬 실행. 큰 프로젝트 분업.
ralplan: 계획을 먼저 세우고 루프 실행. 불확실한 작업은 계획부터.

🧵 병렬 · 백그라운드 · 플랜속도·품질

독립 작업은 동시에, 오래 걸리는 건 뒤에서, 복잡한 건 계획 먼저.

병렬 위임: 서로 무관한 일은 여러 에이전트에 동시에. “보안 리뷰·성능 리뷰·타입체크 동시에 돌려”.
백그라운드: 빌드·테스트처럼 오래 걸리는 건 뒤에서 돌리고 다른 일 계속. 끝나면 알림.
플랜 모드: 코드 건드리기 전에 계획부터 세우고 승인받기(Shift+Tab로 전환). 큰 변경 전 필수.
ultrathink: “깊게 생각해” 신호 — 어려운 설계·근본원인은 이 키워드로 추론량을 늘립니다.

🔧 설정 · 권한 · 모델settings.json

클로드가 얼마나 알아서 하게 할지, 어떤 두뇌를 쓸지 조절합니다.

권한 모드: 매번 물어보기 ↔ 자동 수락. 믿을 만한 계획엔 자동 수락, 탐색적일 땐 물어보게. (위험한 --dangerously-skip는 쓰지 말 것)
모델 라우팅: 어려운 설계·분석 = Opus/Fable, 표준 = Sonnet, 잡무 = Haiku(싸고 빠름). 잡무까지 Opus면 낭비.
allowedTools: 자주 쓰는 안전한 명령은 미리 허용해 물어보는 횟수를 줄입니다(settings.json).
킬 스위치: 자동화가 과하면 DISABLE_OMC 등으로 끕니다. 즉시 중단 Esc는 기초편 참고.

오케스트레이션 · 자동화 파이프라인

🏔️ 고급편 — 직접 짜고, 무인으로 돌린다

중급까지가 “주어진 걸 잘 쓰기”라면, 고급은 내 워크플로를 직접 설계하고 사람 없이도 돌아가게 만드는 단계. 여기서부터 클로드가 도구가 아니라 시스템이 됩니다.

핵심 역량 3가지설계·무인화

🎛️ 워크플로 직접 설계

여러 에이전트를 결정적으로 팬아웃·검증. 코드로 흐름을 짭니다: pipeline(단계별)·parallel(동시)·agent()(위임).

패턴: 적대적 검증(N명이 반박 시도) · 심사 패널(여러 안 점수화) · 완료까지 루프(빈 결과 K번까지).

💡 ultracode = 모든 작업을 워크플로로. 토큰 아끼지 말고 가장 철저한 답이 목표일 때.

🛰️ 원격 · 예약 에이전트

에이전트를 클라우드에서 돌리거나 정해진 시각에 자동 실행. 내 PC를 안 켜도 돕니다.

/schedule — cron 반복 에이전트(routine). /loop — 주기 반복. 원격 격리 실행도 가능.

💡 “매일 아침 새 스킬 스캔해 요약”, “1시간마다 배포 확인”처럼 무인 반복에.

🧑‍🔧 커스텀 서브에이전트

나만의 전문 에이전트를 직접 정의. .claude/agents/이름.md에 역할·모델·쓸 도구를 적으면 끝.

frontmatter: model(opus/haiku…) · tools(허용 도구) · isolation: worktree(격리 작업공간).

💡 반복되는 전문 역할(예: “우리 결제 규칙 리뷰어”)을 박아두면 팀원처럼 부릅니다.

🔁 CI · 헤드리스 자동화사람 없이

대화 밖에서 — 스크립트·CI·서버에서 클로드를 프로그램처럼 호출합니다.

헤드리스: claude -p "프롬프트" — 창 없이 한 번 실행하고 결과만. 스크립트·cron에서 호출.
GitHub Actions: PR 열리면 자동 리뷰·수정, 이슈에 답변. 워크플로에 클로드를 한 단계로.
Agent SDK: 내 앱·서버 코드에서 클로드 에이전트를 직접 임베드(TS/Python). 제품에 AI 기능 넣을 때.
MCP 서버 배포: 내 데이터·도구를 MCP로 공개 → 누구나 claude mcp add로 연결.

🧠 컨텍스트 무중단 — 오래 끌기끊기지 않게

긴 프로젝트를 압축·재시작에도 무손실로. “상태는 대화가 아니라 파일에.”

단계로 쪼개기: 각 단계 산출물 = 코드 + 갱신된 문서. 단계 사이엔 컨텍스트를 비워도 무손실.
경로만 주기: 큰 파일·긴 로그는 통째로 넣지 말고 경로만 → 필요할 때 읽게. 출력도 파일로 빼기.
서브에이전트 위임: 독립 하위작업은 에이전트에 맡기고 결과만 받습니다 → 메인 컨텍스트 경량 유지.
압축 타이밍: 70~80% 차면 자연스러운 구간에서 /compact. 프롬프트 캐시는 5분 — 이어서 할 거면 텀을 짧게.

💰 토큰 예산 · 라우팅 심화비용·품질 저울

얼마나 깊게 팔지를 돈으로 조절. 깊이와 비용은 저울입니다.

예산 지시: “+500k”처럼 이번 턴 토큰 목표를 주면 워크플로가 그만큼 깊이·병렬을 자동 확장.
모델 티어: 잡무는 Haiku(3배 저렴)·표준 Sonnet·최고 난도만 Opus/Fable. 에이전트별로 다르게 지정 가능.
캐시 활용: 같은 컨텍스트 재사용은 프롬프트 캐시로 싸집니다. 5분 TTL — 이어서 할 거면 텀을 짧게.
절약 스킬: caveman·token-diet로 출력 자체를 줄이기. 긴 세션에 누적 효과 큼.

문제 → 해결

❓ 자주 막히는 것 (Q&A)

처음에 흔히 부딪히는 문제들. 대부분 인코딩 · 맥락 · 재시작 세 가지로 풀립니다.

표시 · 설치 문제4

SKILL.md 글자가 깨져 보여요

인코딩 문제. 파일은 UTF-8인데 프로그램이 다른 인코딩으로 여는 것. VSCode·옵시디언으로 열거나 저장할 때 “UTF-8” 지정. 윈도우 기본 메모장은 피하세요.

스킬을 썼는데 아무 변화가 없어요

① 스킬명 오타·미설치 → /help로 목록 확인 · ② /로 호출했는지 · ③ 새로 넣은 스킬은 Claude Code 재시작 후 잡힘 · ④ 조언형 스킬은 “그대로 코드도 고쳐줘”까지 말해야 파일이 바뀝니다.

MCP·에이전트가 목록에 안 떠요

설치·설정(claude mcp add, .claude/agents/) 후 재시작 필요. 연결 중이면 잠시 뒤 다시.

한글·공백 경로에서 오류나요

경로에 공백·한글이 있으면 따옴표로 감싸기: "D:/프로젝트/내 폴더/파일".

응답 · 품질 문제4

물었는데 반응이 별로예요

맥락이 부족한 것. “이 파일 고쳐줘”보다 경로·목표·제약을 구체적으로: “이 함수가 X일 때 Y 에러 나는데 Z 방식으로 고쳐줘.” 큰 일은 Plan 모드로 계획부터.

엉뚱한 방향으로 가요

Esc로 즉시 중단 → 다시 구체적으로. 되돌리려면 변경 전 상태를 말하거나 git으로 복구. 큰 변경 전엔 Plan 모드로 먼저 검토.

점점 느려지고 비싸져요

대화가 꽉 찬 것. /context로 확인 → 80% 넘으면 /compact. 단순 잡무는 /model로 Haiku.

대화가 끊기면 이어가질 못해요

상태를 파일에. PROGRESS.md에 현재 상태·다음 할 일을 적어두면 압축·재시작해도 이어감(기초편 참고).

권한 · 배포 문제2

자꾸 권한을 물어봐요

신뢰하는 명령은 settings.json의 allowedTools에 허용, 또는 믿을 만한 계획엔 자동 수락. (위험한 --dangerously-skip은 금지)

커밋·푸시했는데 사이트가 이상해요

운영 중 repo는 push = 자동 재배포. 배포 전 빌드·테스트 확인, 실서비스는 변경 전 백업. 충돌은 먼저 해결하고 푸시.

이제 스킬을 둘러보세요

가이드를 읽었다면 다음은 실전입니다. 용도별로 정리한 스킬·에이전트 스킬 카탈로그에서 지금 필요한 것을 찾아 설치 명령을 복사하세요.