01. Claude Code란?

내 컴퓨터 파일을 직접 읽고, 정리하고, 결과물로 만들어주는 AI 에이전트. 코딩을 몰라도 됩니다.

한 줄 정의

Claude Code는 내 컴퓨터 폴더에 직접 접근해서 일하는 AI입니다. 수십 개의 파일을 한 번에 읽고, 내용을 정리하고, 원하는 결과물을 만들어냅니다.

웹 브라우저에서 대화하는 Claude.ai와 달리, Claude Code는 내 컴퓨터 안에서 직접 작업합니다.

Claude.ai 웹과 뭐가 다른가요?

핵심 차이: Claude.ai는 대화창에서 답을 보여줍니다. Claude Code는 내 폴더에 직접 들어와서 결과물을 만들어 놓습니다.

어떻게 작동하나요? 실제 예시

예시 1: 문서 일괄 정리 (마케터 / 기획자)

"Downloads 폴더에 있는 회의록 30개를 읽고,
 날짜순으로 정리해서 이번 달 결정사항만 뽑아줘.
 월간_결정사항.md 파일로 저장해줘"

→ Claude Code가 하는 일:
1. 폴더의 파일 30개 전부 읽기
2. 날짜 파악 및 정렬
3. 결정사항 항목만 추출
4. 새 파일로 자동 저장

예시 2: 데이터 분석 (연구자 / 분석가)

"data 폴더에 있는 설문 결과 CSV 파일 분석해서
 주요 지표 요약 보고서 만들어줘"

파이썬 몰라도 됩니다. 말로 설명하면 알아서 처리합니다.

예시 3: 코드 개발 (개발자)

"테스트가 실패하는데 원인 찾아서 고쳐줘"
→ 테스트 실행 → 오류 파악 → 코드 수정 → 재실행

어떤 사람에게 맞는가?

이런 분에게 딱 맞습니다

이런 분에게도 추천

• "파이썬이나 엑셀 함수 없이도 데이터 정리하고 싶다"
• "문서 수십 개를 일일이 열지 않고 한 번에 처리하고 싶다"
• 터미널이 낯설어도 괜찮습니다 — 데스크탑 앱으로도 사용 가능

이런 분에게는 Claude.ai 웹이 더 적합

• 단순 글쓰기, 번역, 질문-답변만 필요한 분
• 특정 IDE 안에서만 작업하고 싶은 개발자 → Cursor나 VS Code 확장 고려

어디서 실행하나요?

한 줄 요약

Claude Code = "내 컴퓨터 폴더에 직접 들어와서, 파일을 읽고, 정리하고, 원하는 결과물을 만들어주는 AI"

코딩을 배우지 않아도 됩니다. 파이썬 몰라도 됩니다. 하고 싶은 작업을 말로 설명하면 됩니다.

플랜 선택부터 설치까지, 다음 섹션에서 이어집니다.

02. Claude Code로 할 수 있는 것들

코드 한 줄 안 짜고 이 사이트(CC101)를 만들었습니다. Claude Code는 코딩 전용 도구가 아닙니다.

먼저: 웹 UI(Claude.ai)와 뭐가 다른가요?

한마디로: Claude.ai가 대화 상대라면, Claude Code는 내 컴퓨터에서 일하는 AI 동료입니다.

할 수 있는 것들

개발 작업

코드 작성, 버그 수정, 리팩토링, 테스트, 코드 리뷰 → 이 가이드의 많은 섹션에서 다룹니다

리서치 & 분석

• 여러 웹페이지를 동시에 읽고 마크다운으로 정리
• 경쟁사 분석, 시장 조사, 기술 동향 파악
• PDF·문서 수십 개 일괄 요약

💡 deep-research 플러그인을 사용하면 멀티에이전트가 여러 소스를 병렬로 조사해 종합 보고서를 자동 생성합니다.

문서 & 콘텐츠 제작

• 블로그 포스트, 뉴스레터, SNS 콘텐츠 초안
• 제안서, 보고서, 발표 자료
• 한국어 ↔ 영어 번역 후 파일로 자동 저장

💡 docs-guide 플러그인으로 공식 문서 기반의 정확한 콘텐츠를 만들 수 있습니다.

데이터 처리

• CSV, Excel 분석 및 변환 — 파이썬 몰라도 됩니다
• 파일 수백 개 일괄 처리 (이름 변경, 형식 변환, 폴더 정리)
• JSON, XML 데이터 파싱 및 가공

학습 보조

• 강의 자료, 책 내용 구조화 정리
• 퀴즈, 플래시카드 자동 생성
• 개념 설명 + 예시 + 연습 문제

비즈니스 워크플로우

• 미팅 녹취 텍스트 → 요약 + 결정사항 + 담당자별 액션 아이템
• 주간·월간 보고서 자동화
• 이메일 초안, 고객 응대 템플릿

개인 AI 워크스페이스

CLAUDE.md로 역할과 규칙을 정의하면, 단순 AI 채팅이 아닌 나만의 AI 에이전트 시스템이 됩니다. → Advanced 17섹션에서 자세히 다룹니다

바이브코딩

코딩을 몰라도 AI에게 지시만으로 소프트웨어를 만드는 바이브코딩의 핵심 도구입니다.

• 기획서 자동 생성 (show-me-the-prd 플러그인)
• Git 버전 관리 자동화 (바르다 깃선생 플러그인)
• AI 사용 패턴 분석 & 코칭 (바선생 플러그인) → 바이브코딩이란? 섹션에서 자세히 다룹니다

실제 사례: CC101은 어떻게 만들어졌나

코드를 한 줄도 직접 짜지 않았습니다

기획 "Codex 101 같은 한국어 Claude Code 가이드를 만들고 싶다" → 아이디에이션 워크스페이스에서 3개 AI(Claude·Codex·Gemini)가 섹션 구성, UX, 기술 스택을 토론 → 20개 섹션 구조 결정

콘텐츠 제작 공식 문서 57개 수집 → Claude가 핵심 내용 추출 → 한국어·영어 마크다운으로 구조화

개발 Next.js 사이트 전체 코드 → Claude Code가 작성 다크/라이트 모드, 한영 토글, 모바일 대응 → 모두 대화로 처리

배포 Vercel 배포, Cloudflare DNS 설정, 도메인 연결 → Claude Code가 직접 처리

운영 & 보완 초안 이후 사용자가 내용을 검토하고 "이 부분 추가해줘", "이건 다르게 써줘"로 대화를 통해 지속적으로 개선 중 — 지금 이 대화도 CC101 업데이트 세션입니다

비개발자 실사용 예시

상황: 매주 팀 미팅 후 회의록을 정리해야 한다

기존 방식:
  미팅 끝 → 메모 정리 30분 → 이메일 작성 10분 → 공유

Claude Code 방식:
  미팅 녹취 텍스트 붙여넣기
  → "요약, 결정사항, 담당자별 액션 아이템 정리해줘"
  → 마크다운 파일로 저장 + 이메일 초안 자동 생성
  총 소요: 3분

오늘 바로 체험

설치가 끝났다면 지금 바로 시작할 수 있습니다:

1. 문서 요약
   폴더에 PDF나 텍스트 파일을 넣고:
   "이 문서 핵심 내용 3줄로 요약해줘"

2. 이메일 초안
   "다음 상황으로 이메일 초안 작성해줘: [상황 설명]"

3. 데이터 처리
   CSV 파일을 폴더에 넣고:
   "이 데이터에서 [컬럼명] 기준으로 정렬하고 요약해줘"

코딩 경험이 전혀 없어도 됩니다.

이 가이드의 나머지 섹션은 "어떻게 더 잘 쓰는가"에 대한 내용입니다. 일단 설치하고 시작해보세요.

03. 바이브코딩이란?

코드를 모르는 사람이 AI에게 자연어로 지시해 소프트웨어를 만드는 새로운 방법론

바이브코딩(Vibe Coding)이란?

"분위기(vibe)로 코딩한다"는 뜻. Andrej Karpathy(전 Tesla AI 총괄)가 2025년에 이름 붙인 개념으로, 코드를 직접 작성하지 않고 AI에게 자연어로 지시해서 소프트웨어를 만드는 방식입니다.

기존 코딩: 문법을 외우고, 에러를 직접 고치고, 라이브러리를 학습해야 함 바이브코딩: "로그인 기능 만들어줘" → AI가 코드를 생성 → 결과를 보고 피드백

Claude Code는 바이브코딩에 가장 적합한 도구 중 하나입니다. 터미널에서 파일을 직접 읽고, 수정하고, 실행하고, 테스트하는 것까지 모두 AI가 처리합니다.

바이브코더 vs 개발자

바이브코딩에서 가장 중요한 건 코딩 실력이 아니라 **"뭘 만들고 싶은지 명확하게 설명하는 능력"**입니다.

바이브코딩의 현실: 장점과 한계

진짜 할 수 있는 것

• 프로토타입, MVP 빠르게 만들기
• 개인용 도구, 자동화 스크립트
• 웹사이트, 간단한 앱
• 데이터 처리, 문서 자동화
• 이 사이트(CC101)도 바이브코딩으로 만들었습니다

솔직한 한계

• 대규모 상용 서비스는 전문 개발자 검수 필요
• 보안, 결제 등 민감한 로직은 반드시 전문가 리뷰
• AI가 생성한 코드를 이해하지 못하면 디버깅이 어려움
• "만들었다"와 "유지보수한다"는 다른 문제

팁: 바이브코딩으로 시작하되, 서비스가 커지면 개발자와 협업하는 게 현명합니다.

바이브코딩 잘하는 법

1. 기획이 반이다

"앱 만들어줘"보다 "사진을 날짜별로 정리하는 웹앱 만들어줘. 드래그 앤 드롭으로 올리면 EXIF 정보로 자동 분류"가 훨씬 좋은 결과를 냅니다.

→ show-me-the-prd 플러그인: 인터뷰 5~6번으로 기획서를 자동 생성해줍니다.

2. 작게 시작해서 키워라

한 번에 완성품을 요구하지 마세요. "로그인 화면 먼저" → "다음은 목록 화면" → "검색 기능 추가" 순서로 점진적으로 만들면 훨씬 안정적입니다.

3. 결과를 직접 확인하라

AI가 만든 결과물을 반드시 실행하고 확인하세요. "잘 됐어", "이 부분은 다르게 해줘" 같은 피드백이 품질을 높입니다.

4. 실수를 두려워하지 마라

Git으로 저장해두면 언제든 되돌릴 수 있습니다. 실패해도 손해 볼 게 없습니다.

→ 바르다 깃선생 플러그인: Git을 모르는 분도 "저장해줘"만으로 버전 관리 가능

바이브코더를 위한 GPTaku 플러그인

Claude Code에 설치하면 바이브코딩이 훨씬 쉬워지는 플러그인들입니다:

설치 방법은 플러그인 설치 섹션에서 다룹니다.

바이브코딩 워크플로우 예시

"할 일 관리 앱을 만들고 싶다"

Step 1: 기획
/show-me-the-prd 할 일 관리 앱 만들고 싶어
→ 5번의 인터뷰 → PRD + 데이터 모델 + Phase 분리 + 프로젝트 스펙

Step 2: 구현
"Phase 1부터 만들어줘"
→ Claude Code가 코드 생성, 파일 저장, 실행까지

Step 3: 확인 & 피드백
"화면 보여줘" → 브라우저에서 확인
"버튼 색 바꿔줘", "날짜 정렬 추가해줘" → 대화로 수정

Step 4: 저장
/git-teacher 저장해줘
→ Git 커밋 자동 생성

한 줄 요약

바이브코딩 = 코드를 모르는 사람이 AI에게 지시해 소프트웨어를 만드는 방법. 핵심은 "뭘 만들 건지 명확하게 설명하는 것". Claude Code + GPTaku 플러그인이 그 과정을 도와줍니다.

04. 제품군 & 가격

Claude Code를 사용하는 방법은 3가지입니다. 입문자라면 Max $100 플랜부터 시작하세요.

Claude Code를 쓰는 방법 3가지

방법 1. Claude.ai 구독 (Pro / Max) — 개인 입문자 추천

가장 간단한 방법입니다. Claude.ai에서 구독하면 Claude Code를 바로 사용할 수 있습니다. 토큰(사용량)을 일일이 신경 쓸 필요 없이 정해진 월정액만 냅니다.

방법 2. Anthropic API 직접 사용 — 개발자 / 자동화 목적

Anthropic Console에서 API 키를 발급받아 연결하는 방식입니다. 사용한 만큼 토큰(글자 수 단위)으로 과금됩니다. 자동화 파이프라인, CI/CD 연동 등에 적합합니다.

방법 3. 엔터프라이즈 클라우드 — 기업 보안 요건이 있는 팀

Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등 기업용 클라우드를 통해 Claude Code를 사용합니다. 데이터가 회사 클라우드 안에 머뭅니다.

Pro vs Max 플랜 비교

아래 가격은 2025년 공식 기준입니다. 최신 가격은 claude.com/pricing에서 확인하세요.

입문자 추천: Max $100

Claude Code를 본격적으로 사용하려면 Max $100 플랜을 권장합니다. 그 이유:

• Pro($20)는 사용량 한도가 빠르게 차서 Claude Code를 집중적으로 쓰기 어렵습니다.
• API 직접 사용은 토큰 과금 방식이라 예상치 못한 비용이 발생할 수 있습니다.
• Max $100는 하루 평균 사용량 기준으로 대부분의 개인 개발자에게 충분합니다.

공식 문서에 따르면, API 사용자의 평균 비용은 개발자 1인당 하루 약 $6, 월 $100~$200 수준입니다 (사용 강도에 따라 차이 있음).

비용 구조 설명

구독 플랜 (Pro / Max)

월정액 결제 → 정해진 사용량 한도 내에서 자유롭게 사용
한도 초과 시 → 추가 응답 제한 (추가 과금 없음)

• 토큰 수를 신경 쓸 필요 없음
• 한도 도달 시 일정 시간 후 리셋

API 직접 사용

사용한 토큰만큼 과금 (입력 토큰 + 출력 토큰)
모델에 따라 단가 다름 (Sonnet < Opus)

• /cost 명령어로 현재 세션 비용 확인 가능
• 자동화/팀 사용 시 Console에서 지출 한도 설정 가능

⚠️ 비용 주의사항

API 사용 시 주의할 점

⚠️ API 사용은 사용한 만큼 청구됩니다.

• 대형 프로젝트에서 장시간 작업하면 토큰이 빠르게 소모됩니다.
• Agent Team(여러 AI를 동시에 실행) 기능은 토큰 소모가 약 7배 많습니다.
• 백그라운드 작업(대화 요약 등)에도 소량의 토큰이 사용됩니다.

비용 절감 팁

어떤 플랜으로 시작할까?

처음 써보고 싶다       → Pro ($20) 로 체험
본격적으로 쓰고 싶다   → Max $100 (강력 추천)
팀/자동화 목적         → API 또는 엔터프라이즈
보안 요건이 있는 기업  → Bedrock / Vertex / Foundry

요금 페이지

최신 가격 및 플랜 비교: https://claude.com/pricing

05. 설치 & 인증

터미널에서 명령어 하나로 설치, 브라우저에서 로그인하면 끝입니다.

💡 터미널이 처음이신가요? 아래 명령어를 그대로 복사해서 붙여넣기(Cmd+V 또는 Ctrl+V) 한 후 Enter만 누르면 됩니다. 명령어의 의미를 이해할 필요가 없습니다.

• macOS: Cmd+Space → "terminal" 검색 → Enter
• Windows: Win+R → "powershell" 입력 → Enter

설치 전 확인사항

지원 운영체제

하드웨어 요구사항

• RAM: 4GB 이상
• 인터넷 연결 필수

Node.js가 필요한가요?

아닙니다. Claude Code는 네이티브(Native) 설치 방식을 사용합니다. Node.js를 따로 설치할 필요가 없습니다.

⚠️ npm 설치는 deprecated(구식)입니다. 예전에는 npm install -g @anthropic-ai/claude-code로 설치했지만, 지금은 공식적으로 아래 방법을 권장합니다. npm 방식은 사용하지 마세요.

설치 방법

macOS / Linux / WSL (Windows Subsystem for Linux)

터미널을 열고 아래 명령어를 붙여넣으세요:

curl -fsSL https://claude.ai/install.sh | bash

또는 Homebrew를 사용한다면:

brew install --cask claude-code

Windows

방법 1 — PowerShell 사용 (권장):

irm https://claude.ai/install.ps1 | iex

방법 2 — WinGet 사용:

winget install Anthropic.ClaudeCode

방법 3 — CMD 사용:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows에서 로컬 세션을 사용하려면 Git for Windows가 설치되어 있어야 합니다.

Alpine Linux 추가 패키지

apk add libgcc libstdc++ ripgrep

설치 후 인증 (로그인)

설치가 완료되면 터미널에서 아래 명령어를 실행하세요:

claude

처음 실행하면 브라우저가 자동으로 열리면서 OAuth 로그인 화면이 나타납니다. Claude.ai 계정(Pro 또는 Max 구독)으로 로그인하면 자동으로 인증이 완료됩니다.

인증 흐름 요약

터미널에서 claude 실행
       ↓
브라우저 자동 오픈 (OAuth 페이지)
       ↓
Claude.ai 계정으로 로그인
       ↓
터미널로 자동 복귀 → 인증 완료

자격 증명 보안

• macOS: API 키와 OAuth 토큰은 **macOS Keychain(암호화 저장소)**에 안전하게 저장됩니다.
• 재로그인이 필요한 경우: claude 실행 후 /login 입력

첫 실행 확인

설치와 인증이 완료되었는지 확인하려면:

claude --version

버전 번호가 출력되면 정상 설치된 것입니다. 또는 설치 진단을 위해:

claude doctor

이 명령어로 설치 타입, 버전, 환경 상태를 한 번에 확인할 수 있습니다.

자동 업데이트

Claude Code는 자동으로 최신 버전으로 업데이트됩니다. 시작 시 업데이트를 확인하고 백그라운드에서 다운로드합니다. 다음 실행 시 새 버전이 적용됩니다.

수동으로 업데이트하려면:

claude update

흔한 설치 문제 & 해결법

문제 1: curl: command not found (curl이 없다는 오류)

원인: curl이 설치되어 있지 않은 경우 (드물지만 일부 Linux 환경).

해결법:

# Ubuntu/Debian
sudo apt-get install curl

# Alpine
apk add curl

이후 설치 명령어 다시 실행.

문제 2: claude: command not found (설치 후에도 명령어를 못 찾는 경우)

원인: 설치 경로가 셸의 PATH에 등록되지 않은 경우.

해결법:

# 현재 셸 세션에 PATH 즉시 반영
source ~/.bashrc
# 또는 zsh 사용자라면
source ~/.zshrc

그래도 안 되면 터미널을 완전히 닫고 다시 열기.

문제 3: Windows에서 Git이 없다는 오류

원인: 로컬 세션 실행에 Git이 필요합니다.

해결법: git-scm.com에서 Git for Windows 설치 후 재시도.

다음 단계

설치와 인증이 완료되었다면, 작업할 폴더로 이동해서 바로 시작해 보세요:

# 작업할 폴더로 이동 후 실행
claude

어떤 폴더든 괜찮습니다. 코드 프로젝트뿐 아니라 문서 폴더, 리서치 폴더, 업무 자료 폴더 어디서나 Claude Code를 시작할 수 있습니다.

Claude Code가 폴더를 분석하고 무엇을 도와드릴지 기다립니다.

06. 플러그인 추천 설치

Claude Code의 기능을 확장하는 플러그인을 설치해봅시다.

플러그인이란?

Claude Code는 기본 기능만으로도 충분히 강력하지만, **플러그인(Plugin)**을 설치하면 더 많은 것을 할 수 있습니다.

플러그인은 쉽게 말하면 Claude Code에 추가 기능 꾸러미를 설치하는 것입니다. 스마트폰에 앱을 설치하듯, Claude Code에 필요한 기능을 플러그인으로 추가할 수 있습니다.

플러그인 하나에는 다음 요소들이 들어있을 수 있습니다:

공식 플러그인 마켓플레이스

Anthropic이 운영하는 공식 마켓플레이스(claude-plugins-official)는 Claude Code를 시작하면 자동으로 사용 가능한 상태입니다.

Claude Code 안에서 /plugin 을 입력하면 Discover 탭에서 바로 공식 플러그인들을 둘러볼 수 있습니다.

공식 마켓에서 플러그인 설치하기

/plugin install 플러그인이름@claude-plugins-official

공식 마켓에서 제공하는 주요 플러그인 카테고리

/plugin install typescript-lsp@claude-plugins-official
/plugin install pyright-lsp@claude-plugins-official

gptaku_plugins — 한국 입문자 전용 플러그인 모음

GitHub: https://github.com/fivetaku/gptaku_plugins

gptaku_plugins는 한국의 Claude Code 입문자, 비개발자, 바이브코더를 위해 특별히 만들어진 플러그인 모음입니다. 어렵고 낯선 개발 개념들을 Claude가 더 친절하게 안내해주도록 설계되어 있습니다.

포함된 플러그인

설치 방법

1단계: 마켓플레이스 등록 (최초 1회)

Claude Code 안에서 다음 명령어를 입력하세요:

/plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git

2단계: 플러그인 설치

마켓플레이스를 등록했으면 원하는 플러그인을 설치합니다:

/plugin install

목록에서 원하는 플러그인을 선택하거나, 이름을 직접 지정할 수도 있습니다:

/plugin install show-me-the-prd

참고: 플러그인은 한 번에 하나씩 설치됩니다. 여러 개를 설치하려면 반복하세요.

3단계: 설치 확인

/plugin list

또는 /plugin 을 입력 후 Installed 탭으로 이동하면 설치된 플러그인 목록을 볼 수 있습니다.

4단계: 업데이트

새 버전이 나오면 다음 명령어로 업데이트할 수 있습니다:

/plugin update

중요: 플러그인 설치 또는 업데이트 후에는 Claude Code를 재시작하세요.

5단계: 플러그인 사용해보기

설치가 완료되면 바로 사용할 수 있습니다:

# 기획서 자동 생성
/show-me-the-prd 할 일 관리 앱 만들고 싶어

# AI 에이전트 팀 자동 구성
/kkirikkiri 리서치 팀 만들어줘

# 스킬 자동 생성
/skillers-suda 번역 스킬 만들어줘

# Git 온보딩
/git-teacher:what-is-commit

# 공식 문서 기반 답변
/docs-guide:explain React hooks

# AI 사용 패턴 분석
/vibe-sunsang 시작

플러그인 관리

커뮤니티 플러그인 더 보기

공식 마켓플레이스 외에도 커뮤니티에서 만든 플러그인을 직접 GitHub에서 설치할 수 있습니다. 기능이 다양한 만큼, 설치 전 코드를 확인하고 신뢰할 수 있는 저장소인지 먼저 살펴보세요.

oh-my-claudecode

Claude Code 커뮤니티에서 가장 많이 쓰이는 서드파티 플러그인입니다. 단순한 확장이 아니라 Claude Code 자체를 오케스트레이터로 탈바꿈시켜 줍니다.

주요 기능:

• Autopilot: "만들어줘"라고 하면 계획 → 구현 → 검증까지 자동 수행
• 33개 전문 에이전트: 코드 리뷰, 보안 분석, 테스트, 문서화 등 역할별 AI 에이전트
• 외부 AI 연동: Codex(OpenAI), Gemini(Google)와 협업해 다각도 분석
• Skills 시스템: 자주 쓰는 워크플로를 재사용 가능한 명령어로 저장

설치: GitHub 저장소(github.com/wshf/oh-my-claudecode)의 README 참조

/plugin install typescript-lsp@claude-plugins-official
/plugin install pyright-lsp@claude-plugins-official

supermemory

Claude의 장기 기억을 강화하는 MCP 서버입니다. 대화가 새로 시작되어도 이전 작업 맥락, 프로젝트 결정 사항, 자주 쓰는 패턴을 자동으로 불러옵니다. 같은 프로젝트를 오래 작업할수록 효과가 커집니다.

설치 전 확인 사항: 커뮤니티 플러그인은 Anthropic의 검증을 거치지 않습니다. GitHub 저장소의 코드와 README를 먼저 확인하고, 유지보수가 활발한지, 이슈 대응이 되는지 살펴보세요.

⭐ CC101이 도움이 됐다면 Star 부탁드려요!

이 가이드가 도움이 됐다면, GitHub에서 Star를 눌러주세요.

Star 하나가 이 가이드를 계속 발전시키는 큰 힘이 됩니다.

→ CC101 GitHub에서 Star 누르기

어렵지 않아요. 링크 클릭 후 오른쪽 상단의 ⭐ Star 버튼만 누르면 됩니다!

다음 단계

플러그인까지 설치했다면 준비는 끝났습니다. 이제 Claude Code가 어떻게 작동하는지 들여다볼 차례입니다.

07. 핵심 개념 이해하기

Claude Code가 어떻게 작동하는지 알면, 더 잘 사용할 수 있습니다.

Claude Code는 어떻게 작동하나요?

Claude Code는 단순한 챗봇이 아닙니다. 여러분이 일을 시키면, 스스로 계획을 세우고, 파일을 읽고, 코드를 수정하고, 결과를 확인하는 에이전트(Agent) 입니다.

이 과정을 에이전트 루프(Agentic Loop) 라고 합니다.

여러분의 지시
     ↓
1. 상황 파악 (Context 수집)
   - 파일 읽기, 코드 검색, 현재 상태 파악
     ↓
2. 행동 (Action)
   - 파일 수정, 명령어 실행, 웹 검색
     ↓
3. 결과 확인 (Verify)
   - 테스트 실행, 오류 확인, 다시 수정
     ↓
작업 완료 (또는 1로 돌아가서 반복)

예를 들어 "reports/ 폴더 문서를 요약해줘"라고 하면 Claude Code는:

1. 폴더 안의 파일 목록을 확인
2. 각 문서를 읽어 내용 파악
3. 요약 및 정리 작성
4. 결과를 확인하고 빠진 내용이 있으면 다시 보완

이 모든 과정을 자동으로 수행합니다.

핵심 개념 5가지

1. Context (컨텍스트) — Claude의 작업 기억

컨텍스트는 Claude Code가 현재 기억하고 있는 모든 내용입니다. 대화 내용, 읽은 파일, 실행한 명령어 결과, CLAUDE.md 지시사항 등이 모두 컨텍스트에 담깁니다.

컨텍스트에는 토큰 한계가 있습니다. 대화가 길어지거나 큰 파일을 많이 읽으면 컨텍스트가 가득 찰 수 있습니다. 이 경우 Claude Code가 자동으로 오래된 내용을 정리합니다.

# 컨텍스트 현황 확인
/context

# 대화 압축 (오래된 내용 요약)
/compact

# 특정 주제에 집중해서 압축
/compact API 변경 사항에 집중해서 압축해줘

팁: 자주 참조해야 할 중요한 규칙이나 정보는 CLAUDE.md에 써두면, 매번 컨텍스트를 차지하지 않고도 Claude가 기억합니다.

2. Tools (도구) — Claude가 실제로 할 수 있는 일

Claude Code는 대화만 하는 게 아닙니다. 실제로 여러 **도구(Tools)**를 사용해서 작업을 수행합니다.

3. Permissions (권한) — 무엇을 허용할지 설정

Claude Code는 강력한 도구인 만큼, 무엇을 허용할지 직접 제어할 수 있습니다.

파일 읽기는 기본적으로 허용되지만, 파일 수정이나 셸 명령어 실행은 여러분의 확인을 요청합니다.

권한 규칙은 크게 세 가지입니다:

# 권한 설정 보기 및 관리
/permissions

우선순위: Deny > Ask > Allow 순으로 적용됩니다. 거부 규칙이 항상 최우선입니다.

4. Memory (메모리) — CLAUDE.md로 프로젝트 기억시키기

Claude Code는 세션이 끝나면 대화 내용을 기억하지 못합니다. 하지만 CLAUDE.md 파일을 만들어두면, 매 세션마다 자동으로 읽어서 프로젝트 맥락을 유지합니다.

CLAUDE.md는 Claude에게 주는 지시서라고 생각하면 됩니다.

CLAUDE.md에 대한 자세한 내용은 06. CLAUDE.md 완전 정복 에서 다룹니다.

5. Session (세션) — 대화의 시작과 끝

세션은 Claude Code를 시작해서 종료하기까지의 하나의 작업 단위입니다.

• 새 세션을 시작하면 이전 대화 내용은 없어집니다 (CLAUDE.md는 유지)
• 세션 중에 한 작업들은 저장됩니다

# 가장 최근 세션 이어서 시작
claude --continue

# 이전 세션 목록에서 선택해서 재개
claude --resume

# 다른 방향을 시도해보기 위해 세션 복사 (포크)
claude --continue --fork-session

"왜 가끔 멈추거나 확인을 요청하나요?"

Claude Code가 작업 중에 멈추고 확인을 요청하는 건 의도된 안전 장치입니다.

파일을 수정하거나 명령어를 실행하기 전에, 여러분이 의도한 것인지 확인하는 것입니다. 특히 되돌리기 어려운 작업(파일 삭제, 배포 등)일수록 중요합니다.

초보자가 알아야 할 권한 모드 3가지

Shift+Tab 을 누르면 권한 모드를 전환할 수 있습니다.

모드 전환 방법

# 터미널에서 Shift+Tab을 누르면 모드가 순환됩니다
# Default → Auto-Accept → Plan Mode → Default → ...

# 또는 Plan Mode로 바로 진입
/plan

모드 비교 예시

"폴더 내 문서에서 '구버전 문구'를 '신규 문구'로 일괄 교체해줘"라고 했을 때:

Default 모드:
  → 각 파일 수정 전마다 "이 파일을 수정해도 될까요?" 확인

Auto-Accept 모드:
  → 파일은 자동으로 수정, 명령어 실행은 확인 요청

Plan Mode:
  → "어떤 파일의 어느 부분을 바꿀 예정입니다"만 보여주고 실제 수정은 안 함

"모든 JavaScript 파일에서 console.log를 삭제해줘"라고 했을 때:

Default 모드:
  → 각 파일 수정 전마다 "이 파일을 수정해도 될까요?" 확인

Auto-Accept 모드:
  → 파일은 자동으로 수정, 명령어(예: git commit)는 확인 요청

Plan Mode:
  → "어떤 파일의 몇 번째 줄을 수정할 예정입니다"만 보여주고 실제 수정은 안 함

추천: 처음에는 Default 모드로 시작해서 Claude Code가 무엇을 하는지 파악하고, 익숙해지면 Auto-Accept 모드로 전환하세요.

체크포인트: 실수해도 되돌릴 수 있어요

Claude Code는 파일을 수정하기 전에 자동으로 스냅샷을 저장합니다.

실수로 잘못 수정됐다면:

• Esc 키를 두 번 연속으로 눌러서 이전 상태로 되돌리기
• 또는 Claude에게 "방금 한 것 취소해줘"라고 요청

이 개념들을 알고 나면 Claude Code 동작이 예측 가능해집니다. 다음은 이 중 가장 중요한 Memory, CLAUDE.md를 제대로 쓰는 방법입니다.

08. CLAUDE.md 완전 정복

Claude Code의 장기 기억을 설정하는 가장 중요한 파일, CLAUDE.md를 마스터해봅시다.

CLAUDE.md가 뭔가요?

Claude Code는 세션이 끝나면 대화 내용을 잊어버립니다. 다음에 다시 시작하면 처음 만난 사이처럼 아무것도 모릅니다.

CLAUDE.md는 이 문제를 해결합니다.

Claude Code를 시작할 때마다 CLAUDE.md 파일을 자동으로 읽어서, 프로젝트에 대한 맥락과 규칙을 기억한 채로 작업을 시작합니다.

CLAUDE.md는 Claude에게 주는 지시서이자 프로젝트 설명서입니다.

사람: "이 프로젝트는 Next.js로 만들었고, TypeScript를 써야 해.
       탭 대신 스페이스 2칸을 사용하고, 한국어로 커밋 메시지를 써줘."

→ 이걸 매번 말하는 대신, CLAUDE.md에 한 번 써두면 영원히 기억합니다.

어디에 만드나요?

CLAUDE.md 파일의 위치에 따라 적용 범위가 달라집니다.

가장 일반적인 위치: 프로젝트 루트 디렉토리의 CLAUDE.md

# 프로젝트 폴더에서 CLAUDE.md 생성
touch CLAUDE.md

# 또는 Claude Code가 자동으로 만들어주게 하기
/init

/init 명령어를 실행하면 Claude Code가 현재 프로젝트를 분석해서 CLAUDE.md 초안을 자동으로 생성해줍니다.

무엇을 써야 하나요?

CLAUDE.md에 정해진 형식은 없습니다. 마크다운으로 자유롭게 작성하면 됩니다. 다음 항목들을 포함하면 특히 효과적입니다.

💡 여기서 '프로젝트'는 개발 프로젝트만 뜻하지 않습니다. 리서치 폴더, 콘텐츠 작업 폴더, 업무 자동화 폴더 등 어떤 작업 폴더에도 그대로 적용됩니다. Claude Code는 코드가 없는 폴더에서도 동일하게 작동합니다.

필수 항목

1. 작업 개요

Claude가 이 폴더에서 무엇을 하는지 파악할 수 있도록 짧게 설명합니다.

## 작업 개요
이 폴더는 경쟁사 시장 조사 리서치 프로젝트입니다.
조사 결과는 reports/ 폴더에 마크다운으로 저장합니다.

2. 도구 / 환경

어떤 도구, 자료, 저장 방식을 쓰는지 명시합니다.

## 작업 환경
- **주요 도구**: Notion(기획), Google Docs(초안), Canva(디자인)
- **자료 저장 위치**: docs/ 폴더 (마크다운 형식)
- **참고 언어**: 한국어 우선, 영어 자료는 요약 번역

3. 작업 규칙

글쓰기 스타일, 파일 명명 방식, 출처 기준 등을 지정합니다.

## 작업 규칙
- 글 어조: 친근하고 명확하게 (과장 표현 금지)
- 파일명: YYYY-MM-DD_주제.md 형식
- 출처가 없는 통계/수치 사용 금지
- 항상 한국어로 작성

4. 하지 말아야 할 것들 (금지 사항)

실수를 방지하기 위해 명시적으로 금지 사항을 적어두면 효과적입니다.

## 절대 하지 말 것
- 출처 없는 통계 인용
- 검증 안 된 정보를 사실처럼 기술
- 고객/파트너 실명을 문서에 노출
- 이전 버전 파일 덮어쓰기 (항상 날짜 포함 파일명 사용)

5. 자주 쓰는 작업 절차

Claude에게 자주 시키는 작업이나, 반복 워크플로우를 정의합니다.

## 자주 쓰는 작업
- 리서치 보고서 작성: "요약 → 핵심 인사이트 5개 → 출처 목록" 형식으로
- 회의록 정리: "결정사항 → 액션아이템(담당/기한) → 미결 이슈" 형식으로
- 문서 검토: 먼저 요약 제시, 수정 필요 부분은 이유와 함께 표시

실제 예시: 목적별 CLAUDE.md 템플릿

내 작업 유형에 맞는 템플릿을 골라 복사해서 바로 사용하세요.

템플릿 A — 리서치 워크스페이스

# 리서치 프로젝트 규칙 (CLAUDE.md)

## 프로젝트 목적
- 목표: [조사 주제와 목적을 한 줄로]
- 산출물: report.md(요약), sources.md(출처), slides-outline.md(발표용 목차)

## 자료 / 폴더 규칙
- 원문 자료는 sources/ 폴더에 저장, 파일명: YYYY-MM-DD_출처_제목.md
- 내 메모/가설은 notes/ 폴더에 저장 (원문과 섞지 않기)

## 출처 규칙
- 모든 주장에 출처 붙이기 (링크 + 한 줄 근거)
- 출처 신뢰도: A(공신력/1차) / B(업계/2차) / C(개인블로그/의견)
- 불확실하면 "추정/가정" 명시

## 글쓰기 / 형식
- 항상 한국어, 문장은 짧게
- 결과물 기본 구조: 1)5줄 요약 2)핵심 인사이트 5개(근거 포함) 3)반대 근거/리스크 3개 4)다음 액션 3개

템플릿 B — 콘텐츠 제작 워크스페이스

# 콘텐츠 제작 규칙 (CLAUDE.md)

## 브랜드 톤
- 친근하지만 과장 금지 ("완벽/혁명/무조건" 금지)
- 독자: [타겟 독자 설명], 전문 용어는 괄호로 짧게 풀이

## 채널별 포맷
- 블로그: 제목 3안 → 본문(소제목 4~6개) → 체크리스트 → CTA 1개
- 인스타: 7~9장 카드뉴스(장당 1문장), 마지막 장에 요약+링크
- 뉴스레터: 3줄 요약 → 본문 600~900자 → 다음 주제 예고

## 금지 / 주의
- 경쟁사 실명 언급 금지 (필요 시 "A사/B사"로 익명화)
- 통계/수치는 출처 없으면 "예시"로 표시

## 파일 출력 규칙
- 초안: drafts/YYYY-MM-DD_주제_채널.md
- 최종본: final/ 폴더에 저장, 상단에 버전/검수자/발행일 메타데이터 표기

템플릿 C — 비즈니스 운영 워크스페이스

# 운영 문서 규칙 (CLAUDE.md)

## 회사 / 제품 맥락
- 제품: [제품명] / 고객: [타겟] / 핵심 가치: [한 줄]
- 자주 쓰는 용어 정의: [용어: 정의] 형태로 아래에 누적

## 커뮤니케이션 스타일
- 이메일/메시지: 존댓말, 3문단(요약 → 상세 → 다음 단계)
- 고객 불만 응대: "공감 1문장 → 사실 확인 질문 2개 → 해결 옵션 2개"

## 문서 템플릿
- 회의록: 회의 목적 / 결정사항 / 액션아이템(담당/기한) / 이슈
- 제안서: 문제정의 → 해결안 → 일정/범위 → 비용 → 리스크

## 보안 / 민감 정보
- 개인정보/결제정보는 마스킹 (예: 010-****-1234)
- 외부 공유 전 "대외비 문구/고객명" 자동 점검 목록 먼저 출력

# 프로젝트 지침

## 프로젝트 개요
[여기에 프로젝트 설명을 1-2줄로 작성하세요]

예시: 소상공인을 위한 재고 관리 SaaS 서비스.
Next.js 14 App Router + TypeScript + Supabase 기반.

---

## 기술 스택
- **프레임워크**: Next.js 14 (App Router)
- **언어**: TypeScript (strict 모드)
- **스타일**: Tailwind CSS
- **DB/백엔드**: Supabase
- **패키지 매니저**: pnpm
- **배포**: Vercel

---

## 코딩 규칙

### 네이밍
- 컴포넌트: PascalCase (UserCard.tsx)
- 함수/변수: camelCase (getUserData)
- 상수: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)

### TypeScript
- `any` 타입 사용 금지
- 모든 함수 반환 타입 명시

---

## 자주 쓰는 명령어
pnpm dev, pnpm build, pnpm test, pnpm lint

---

## 절대 하지 말 것
- `npm` 또는 `yarn` 사용 (반드시 `pnpm` 사용)
- `any` 타입 사용
- 환경 변수를 코드에 하드코딩

---

## Git 커밋 규칙
- 한국어로 커밋 메시지 작성
- 형식: `타입: 변경 내용`
- 예시: `feat: 사용자 로그인 페이지 추가`

전역 메모리: 모든 프로젝트에 적용하기

~/.claude/CLAUDE.md 파일을 만들면, 내 모든 프로젝트에서 공통으로 적용되는 규칙을 설정할 수 있습니다.

# 전역 CLAUDE.md 편집
nano ~/.claude/CLAUDE.md

전역 CLAUDE.md에 넣기 좋은 내용:

# 전역 설정 (모든 프로젝트 공통)

## 내 개인 선호
- 설명은 항상 한국어로 해줘
- 코드 변경 전에 무엇을 할지 먼저 설명해줘
- 중요한 변경사항은 실행 전에 한 번 더 확인해줘

## 코딩 스타일 (공통)
- 함수는 가능하면 짧게 (20줄 이하)
- 변수명은 의미가 명확하게
- 주석보다는 코드 자체가 읽기 쉽도록

메모리 우선순위

여러 CLAUDE.md 파일이 있을 때, 더 구체적인 파일이 우선합니다.

우선순위 (높음 → 낮음):
1. CLAUDE.local.md (나만의 프로젝트 설정)
2. ./CLAUDE.md (프로젝트 설정)
3. ~/.claude/CLAUDE.md (전역 설정)
4. 조직 관리 CLAUDE.md (회사 설정)

예를 들어, 전역 설정에서 "스페이스 2칸"으로 설정했더라도, 프로젝트의 CLAUDE.md에서 "탭 사용"으로 설정하면 프로젝트 설정이 우선 적용됩니다.

유용한 팁

/memory 명령어 활용

세션 중에 CLAUDE.md를 직접 편집하고 싶다면:

/memory

파일 선택기가 열려서 CLAUDE.md를 바로 편집할 수 있습니다.

파일 가져오기 (Import)

CLAUDE.md에서 다른 파일을 참조할 수 있습니다:

# 프로젝트 지침

프로젝트 개요는 @README.md 를 참고하세요.
사용 가능한 npm 스크립트는 @package.json 을 참고하세요.

## 추가 규칙
- Git 워크플로우: @docs/git-guide.md

처음 시작할 때는 CLAUDE.md부터!

새 프로젝트를 시작한다면, 첫 번째 작업으로 CLAUDE.md를 만드세요.

# 프로젝트 시작 시 Claude에게 CLAUDE.md 자동 생성 요청
/init

또는 직접 Claude에게 부탁할 수도 있습니다:

"이 폴더는 경쟁사 시장 조사 리서치 프로젝트야.
 결과물은 reports/ 폴더에 마크다운으로 저장하고,
 모든 주장에 출처를 달아줘. 한국어로 작성해줘.
 이 내용을 바탕으로 CLAUDE.md 파일을 만들어줘."

개발자라면: "이 프로젝트는 Next.js 14 + TypeScript + Tailwind로 만들 거야. pnpm을 패키지 매니저로 써. CLAUDE.md 파일을 만들어줘."

정리: CLAUDE.md 핵심 요약

CLAUDE.md 하나로 매번 설명하는 수고를 없애고, Claude Code를 진짜 팀원처럼 만들어보세요.

CLAUDE.md 하나 잘 써두는 것만으로도 매 세션마다 설명하는 수고가 없어집니다. 진짜 팀원처럼 쓰게 됩니다.

09. 명령어 모음

Claude Code를 쓸 때 알아야 할 명령어들을 한눈에 정리했습니다.

명령어 세 가지 종류

Claude Code의 명령어는 크게 세 가지로 나뉩니다.

CLI 명령어 (터미널에서 입력)

Claude Code를 시작하거나 제어하는 명령어입니다. 터미널에서 입력합니다.

기본 실행 명령어

모델 지정 실행

# 특정 모델로 시작
claude --model claude-opus-4-5

# 또는 짧게
claude --model opus
claude --model sonnet
claude --model haiku

유용한 시작 옵션

# Plan Mode로 시작 (파일 수정 없이 계획만)
claude --permission-mode plan

# 세션 이름으로 이어서 시작
claude --resume 세션이름

# 이전 대화 목록에서 선택해서 이어서 시작
claude --resume

팁: 처음엔 그냥 claude만 입력해서 시작하면 됩니다. 나머지는 필요할 때 배워도 늦지 않습니다.

슬래시 명령어 (대화 중 입력)

Claude Code와 대화하는 도중에 /로 시작하는 명령어를 입력하면 특별한 기능을 사용할 수 있습니다.

자주 쓰는 슬래시 명령어

슬래시 명령어 사용법

> /compact
→ 대화 내용을 요약해서 컨텍스트를 줄여줍니다

> /compact 코드 변경 사항 위주로 정리해줘
→ 압축 방향을 직접 지정할 수 있습니다

> /model
→ 모델 선택 화면이 나타납니다

팁: 대화창에서 /만 입력하면 사용 가능한 명령어 목록이 자동완성으로 나타납니다.

대화 분기 & 실험 전략

대화 중간에 방향을 바꾸거나 위험한 실험을 안전하게 시도할 때 활용할 수 있는 기능들입니다.

/clone — 원본 유지하며 실험하기

현재 대화 전체를 복제해서 독립된 분기를 만듭니다. 복잡한 리팩토링이나 구조적인 변경을 시도하기 전에 현재 상태를 복사해두면, 실패해도 원본으로 돌아올 수 있습니다.

> /clone
→ 현재 대화 상태 그대로 새 분기 시작
→ 원본 대화는 영향 없음

이럴 때 써보세요

• 여러 구현 방법 중 하나를 먼저 시험해보고 싶을 때
• "이렇게 고치면 어떨까" 싶은데 실패가 걱정될 때
• 같은 문제를 서로 다른 접근으로 비교해보고 싶을 때

/half-clone — 더 가볍게 새 출발

현재 대화를 AI가 압축 요약한 뒤 새 대화를 시작합니다. /compact는 기존 대화 안에서 압축하는 반면, /half-clone은 압축본을 토대로 완전히 새 대화를 엽니다.

> /half-clone
→ 핵심 정보만 담은 요약으로 새 대화 시작
→ 토큰 사용량 대폭 감소

대화가 너무 길어져서 /compact로도 부족할 때 유용합니다.

/context — 컨텍스트 사용량 확인

> /context
→ [■■■■■■■□□□] 70% (143,000 / 200,000 tokens)

현재 대화가 컨텍스트 창의 몇 %를 차지하는지 시각적으로 보여줍니다. 80% 이상 차면 /compact나 /half-clone을 고려하세요.

/rename — 세션 이름 붙이기

중요한 작업 세션에 이름을 붙여두면 나중에 쉽게 재개할 수 있습니다.

> /rename 경쟁사-리서치-2월

# 나중에 터미널에서 이어서 시작
$ claude --resume 경쟁사-리서치-2월

키보드 단축키

대화 도중 손가락 몇 개로 빠르게 제어할 수 있습니다.

핵심 단축키

입력 관련 단축키

모드 전환 단축키

초보자가 자주 쓰는 명령어 TOP 5

막 시작했다면 이 다섯 개만 외워도 충분합니다.

1. /compact — 가장 중요한 명령어

> /compact

대화가 길어지면 Claude가 느려지거나 오래된 내용을 잊어버립니다. 이럴 때 /compact를 입력하면 대화를 압축해서 속도를 회복합니다. 긴 작업 중간중간에 습관적으로 사용하세요.

2. Ctrl+C — 멈추고 싶을 때

Claude가 엉뚱한 방향으로 가고 있을 때, 또는 실수로 위험한 명령을 허가했을 때 즉시 멈춥니다.

3. /clear — 새로 시작할 때

> /clear

완전히 다른 주제로 넘어갈 때 사용합니다. 이전 대화 내용이 모두 지워집니다.

4. Shift+Enter — 긴 지시사항 입력

한 줄로 다 쓰기 어려운 긴 요청은 Shift+Enter로 줄바꿈하면서 입력하세요.

(Shift+Enter로 여러 줄 입력 예시)
로그인 페이지를 만들어줘.
- 이메일과 비밀번호 필드
- 비밀번호 보기/숨기기 버튼
- 로그인 버튼 (로딩 상태 포함)

5. /cost — 비용 확인

> /cost

현재 세션에서 얼마나 썼는지 확인합니다. (API 키 사용자용, 구독 사용자는 /stats 사용)

alias cc='claude'
alias ccd='claude --dangerously-skip-permissions'
alias ccr='claude --resume --dangerously-skip-permissions'

source ~/.zshrc

function cc { claude @args }
function ccd { claude --dangerously-skip-permissions @args }
function ccr { claude --resume --dangerously-skip-permissions @args }

빠른 참고표

터미널 입력:
  claude                    → 시작
  claude -v                 → 버전 확인
  claude --help             → 도움말
  claude -c                 → 마지막 세션 이어서
  claude --resume [이름]    → 이름 붙인 세션 재개
  claude --add-dir [경로]   → 추가 디렉토리 포함

Alias (설정 후):
  cc                        → claude (기본)
  ccd                       → 권한 자동 승인
  ccr                       → 이전 세션 재개 + 권한 자동 승인

대화 중 입력:
  /help               → 전체 명령어 목록
  /compact            → 대화 압축 (자주 쓰기!)
  /clear              → 대화 초기화
  /clone              → 대화 분기 생성
  /half-clone         → 압축 요약으로 새 분기
  /context            → 컨텍스트 사용량 확인
  /cost               → 비용 확인
  /model              → 모델 변경
  /rename [이름]       → 세션 이름 붙이기
  /bug                → 버그 리포트 전송
  /quit               → 종료

키보드 단축키:
  Ctrl+C              → 작업 취소
  Ctrl+D              → 종료
  Ctrl+B              → 백그라운드 전환, 새 창 열기
  Shift+Enter         → 줄바꿈
  ↑↓ 화살표           → 이전 명령어 탐색
  Esc Esc             → 이전 상태로 되감기

10. 초보자 워크플로우

처음 Claude Code를 쓸 때 어떻게 시작하고, 어떻게 작업하면 좋은지 단계별로 안내합니다.

첫 세션 플로우 (Step-by-Step)

처음이라면 이 순서대로 따라해보세요.

Step 1. 프로젝트 폴더로 이동

cd 내프로젝트

Claude Code는 현재 폴더를 기준으로 파일을 읽고 수정합니다. 반드시 작업할 프로젝트 폴더로 먼저 이동하세요.

폴더가 없다면 mkdir 내프로젝트 && cd 내프로젝트로 만들어도 됩니다.

Step 2. Claude Code 시작

claude

터미널에 claude를 입력하고 Enter를 누르면 대화형 모드가 시작됩니다.

Step 3. 프로젝트 파악시키기 (강력 추천)

처음 시작할 때 Claude에게 프로젝트를 파악하게 하거나, CLAUDE.md 파일을 만들어 달라고 요청하세요.

> 이 프로젝트 전체를 파악하고 CLAUDE.md 파일을 만들어줘

또는 기존 프로젝트라면:

> 이 코드베이스 구조를 설명해줘

CLAUDE.md가 중요한 이유: 이 파일에 프로젝트 규칙, 기술 스택, 주의사항을 적어두면 Claude가 매번 물어보지 않아도 됩니다. 팀이 있다면 git에 커밋해서 공유하세요.

Step 4. 작업 지시

원하는 작업을 자연어로 지시합니다.

> 로그인 기능을 만들어줘
> 이 코드에서 버그를 찾아줘
> README.md를 한글로 번역해줘

Step 5. 결과 확인 & 피드백

Claude가 파일을 수정하면 변경 내용을 보여줍니다. 마음에 들지 않으면 바로 피드백하세요.

> 좋아, 근데 에러 메시지는 한글로 바꿔줘
> 이 부분은 다르게 해줘 — [설명]

Step 6. 세션 종료

> /quit

또는 Ctrl+D를 누르면 종료됩니다.

효과적인 프롬프트 쓰는 법

구체적으로 말할수록 좋은 결과가 나옵니다

한 번에 하나씩 요청하기

여러 가지를 한꺼번에 요청하면 Claude가 중간에 방향을 잃을 수 있습니다.

# 비추천
> 로그인 만들고, 회원가입도 추가하고, 비밀번호 찾기도 만들고,
  이메일 인증도 넣고, 소셜 로그인도 추가해줘

# 추천
> 먼저 이메일/비밀번호 로그인 기능만 만들어줘
(완료 후)
> 이제 회원가입 기능 추가해줘

결과물 형태를 명시하기

> 이 코드를 설명해줘           → 설명문으로 답변
> 이 코드를 파일로 저장해줘     → 파일로 저장
> 이 코드를 개선해서 덮어써줘   → 파일 직접 수정
> 버그 목록을 표로 정리해줘     → 표 형식으로 답변

@ 기호로 파일 지정하기

@ 뒤에 파일 경로를 붙이면 Claude가 그 파일을 직접 읽고 작업합니다. "이 파일 읽고..." 라고 설명할 필요 없이 파일을 대화에 바로 넘길 수 있습니다.

> @회의록.txt 에서 액션아이템만 뽑아줘
> @계약서.pdf 핵심 조항만 정리해줘
> @데이터.csv 분석해서 인사이트 3개 뽑아줘
> @src/auth/login.js 이 파일에서 버그 찾아줘
> @README.md 보고 프로젝트 구조 파악해줘

폴더 전체를 넘길 수도 있습니다:

> @docs/ 이 폴더 문서 모두 읽고 목차 만들어줘
> @reports/2025/ 월별 보고서 비교해서 트렌드 분석해줘

팁: 대화창에서 @를 입력하면 파일 목록이 자동완성으로 나타납니다. 한글 파일명도 문제없습니다.

실제 사용 사례

문서 · 업무

> @회의록-250225.txt
  오늘 회의 내용 요약하고 액션아이템을 담당자별로 정리해줘

> @보고서초안.docx
  전체적으로 검토해줘. 논리적으로 빠진 부분이나
  데이터가 필요한 주장이 있으면 표시해줘

> ~/Downloads/meeting-250225.mp3 파일이 있어.
  회의 내용을 텍스트로 변환하고 요약해줘

Claude Code가 STT 변환에 필요한 도구를 직접 설치하고 실행합니다. 파이썬이나 라이브러리를 몰라도 됩니다.

데이터 · 분석

> @sales-q1.csv
  1분기 매출 데이터 분석해서 인사이트 3가지 뽑아줘.
  차트도 이미지로 저장해줘

> @경쟁사A.html @경쟁사B.html @경쟁사C.html
  세 경쟁사 랜딩페이지 비교 분석해줘. 강점/약점 표로 정리해줘

개발

> 사용자 프로필 페이지를 만들어줘.
  - 닉네임, 이메일, 가입일 표시
  - 프로필 사진 업로드 가능
  - 닉네임 수정 기능

> npm test 실행하면 아래 에러가 나는데 고쳐줘:
  TypeError: Cannot read property 'id' of undefined
  at UserService.getUser (src/services/user.js:45)

> @src/payment/ 폴더의 코드를 리뷰해줘.
  보안 취약점과 개선할 점을 알려줘

Plan Mode 활용 팁

Plan Mode란? Claude가 파일을 수정하지 않고, 계획만 세우는 모드입니다. 위험한 작업을 하기 전에 먼저 계획을 검토할 수 있습니다.

Plan Mode 켜는 방법

Shift+Tab 두 번 누르기
또는
> /plan

언제 Plan Mode를 쓰나?

• 여러 파일을 동시에 수정해야 할 때
• 데이터베이스 마이그레이션처럼 되돌리기 어려운 작업
• 처음 보는 코드베이스를 수정하기 전
• 아키텍처 변경처럼 큰 작업

💡 프로젝트를 처음 기획할 때는 show-me-the-prd 플러그인으로 인터뷰 기반 기획서를 자동 생성할 수 있습니다.

Plan Mode 사용 예시

# Plan Mode로 시작
claude --permission-mode plan

# 또는 대화 중에 전환
> Shift+Tab (두 번)

# 계획 수립 요청
> 인증 시스템을 JWT에서 OAuth2로 마이그레이션하는 계획을 세워줘

# Claude가 계획을 보여주면 검토
# 괜찮으면 일반 모드로 전환 후 실행

작업 전 git commit 습관

Claude Code가 파일을 수정하기 전에 현재 상태를 git에 저장해두면, 실수해도 쉽게 되돌릴 수 있습니다.

git add .
git commit -m "Claude Code 작업 전 백업"

💡 Git 명령어가 낯설다면? 바르다 깃선생 플러그인을 설치하면 "저장해줘", "올려줘"만으로 Git 관리가 가능합니다.

이후 Claude가 수정한 내용이 마음에 들지 않으면:

git diff          # 변경된 내용 확인
git checkout .    # 모든 변경 취소 (주의!)

또는 Claude Code 안에서 Esc + Esc를 눌러 이전 상태로 되감기할 수도 있습니다.

⚠️ 절대 하지 말아야 할 것들

민감 정보 입력 금지

# 절대 금지
> 내 AWS 액세스 키는 AKIAXXXXXXXX 이고...
> DB 비밀번호는 mypassword123 인데...
> 내 개인 SSH 키는 -----BEGIN RSA...

API 키, 비밀번호, 개인 인증서 등은 절대 대화창에 직접 입력하지 마세요. 환경변수나 .env 파일을 사용하세요.

권한 요청 무분별 허용 금지

Claude가 sudo 명령이나 시스템 파일 수정 권한을 요청할 때, 이유를 먼저 파악하세요.

# Claude가 이런 권한을 요청하면 이유를 먼저 물어보기
> 왜 sudo가 필요해? 다른 방법은 없어?

--dangerously-skip-permissions 사용 주의

이 옵션은 모든 권한 확인을 건너뜁니다. 격리된 테스트 환경(컨테이너 등)이 아니면 사용하지 마세요.

중요한 작업 전 백업 없이 진행 금지

대규모 리팩토링이나 데이터베이스 마이그레이션 전에는 반드시 git commit이나 백업을 먼저 하세요.

세션 관리 팁

긴 작업은 이름을 붙여 저장

> /rename auth-refactor

나중에 이어서 할 때:

claude --resume auth-refactor

컨텍스트가 길어지면 압축

작업이 길어지면 Claude의 응답이 느려집니다. 주기적으로:

> /compact

관련 없는 새 작업은 초기화 후 시작

> /clear

한 줄 요약

구체적으로 지시하고 → 한 번에 하나씩 요청하고 → 결과를 확인하고 → 피드백을 반복하세요.

막히는 상황이 생기면 다음 섹션 트러블슈팅에서 찾아보세요.

11. 세션 & 컨텍스트 관리

Claude Code를 오래, 효율적으로 사용하는 법. 길어진 세션 압축, 이전 작업 재개, 복잡한 작업 전 안전장치까지.

컨텍스트 윈도우란?

배경지식이 없는 분께:

Claude는 대화할 때 지금까지 오간 내용을 전부 기억하면서 작업합니다. 그런데 이 기억에는 한계가 있어서, 대화가 계속 쌓이다 보면 오래된 내용부터 밀려나기 시작합니다.

"분명히 아까 말했는데 왜 모르지?" 하는 상황이 바로 이것 때문입니다. Claude가 일부러 잊은 게 아니라, 메모지가 꽉 차서 오래된 내용이 잘려나간 겁니다.

배경지식이 있는 분께: 컨텍스트 윈도우는 AI 모델이 한 번에 처리할 수 있는 토큰의 최대 수입니다. Claude Code는 슬라이딩 윈도우 방식으로 작동해, 한도를 넘으면 오래된 토큰부터 잘려나갑니다.

공통으로 일어나는 일:

대화가 길어질수록:
  초반 내용이 밀려나기 시작함
  → Claude가 앞에서 한 작업을 기억 못할 수 있음
  → 답변 품질이 떨어지기 시작함
  → 같은 실수를 반복하기 시작함

그냥 두면 점점 대화가 엉켜갑니다. 가끔 정리해줘야 합니다.

/compact — 대화 압축

/compact

현재까지의 대화를 요약해서 컨텍스트를 줄여줍니다.

• 중요한 내용은 요약에 포함됩니다
• 세션을 끊지 않고 계속 이어갈 수 있습니다
• 언제 쓰나: 대화가 오래됐다 싶을 때, 답변이 이상해지기 시작할 때

압축 방향을 직접 지정할 수도 있습니다:

/compact 리서치 결과와 주요 발견사항 중심으로 요약해줘
/compact 작성 중인 보고서의 구조와 진행 상황 중심으로
/compact 결론/근거/미해결 질문만 남겨줘

세션 재개 방법

--continue — 직전 세션 이어받기

claude --continue

마지막으로 종료한 세션을 그대로 이어받습니다.

• 터미널을 닫았다가 다시 열었을 때
• 하던 작업을 다음 날 계속할 때

--resume — 세션 선택해서 재개

claude --resume

이전 세션 목록을 보여주고 선택해서 이어받습니다.

• 여러 프로젝트를 번갈아 작업할 때
• 며칠 전 특정 세션으로 돌아가고 싶을 때

언제 새 세션을 시작해야 하나

복잡한 작업 전엔 Plan Mode

여러 파일을 동시에 수정하거나 큰 변경이 예상될 때, 일단 실행하기 전에 계획을 먼저 확인받을 수 있습니다.

Shift + Tab  →  Plan Mode 전환

Plan Mode에서 Claude는:

1. 실행 계획만 보여줍니다 (파일을 바꾸지 않음)
2. "이렇게 하려고 하는데 맞나요?" 확인을 먼저 받습니다
3. 승인하면 그때 실행합니다

언제 쓰나: 여러 파일 동시 수정, 폴더 구조 개편, 대량 내용 교체, 되돌리기 어려운 작업 전

병렬 세션

터미널을 여러 개 열어서 동시에 다른 작업을 맡길 수 있습니다.

터미널 1: claude (경쟁사 A 리서치)
터미널 2: claude (보고서 초안 작성)
터미널 3: claude (발표 자료 정리)

각 세션은 독립적으로 작동합니다.

주의: 같은 파일을 두 세션에서 동시에 수정하면 충돌이 생깁니다. 담당 파일/역할을 나눠서 쓰세요.

자주 있는 상황별 대처법

Claude 답변이 갑자기 이상해졌을 때

1. /compact로 압축 시도
2. 그래도 이상하면 → 새 세션 시작
3. 새 세션에서 핵심 컨텍스트만 다시 제공: "현재 [프로젝트명] 작업 중이고, 지금까지 [요약] 했다. 다음으로 [작업]을 해야 한다."

긴 작업을 중간에 멈춰야 할 때

작업 중 → Ctrl+C로 중단
→ 터미널 닫기
→ 다음에: claude --continue

Claude가 중단된 지점부터 상태를 기억하고 있습니다.

비용과도 연결됩니다: 컨텍스트가 길수록 더 많은 토큰을 씁니다. /compact를 주기적으로 쓰면 속도도 빠르고 비용도 줄어듭니다. → 자세한 내용은 18섹션 비용 관리에서.

12. GitHub 시작하기

🖥️ 이 섹션은 주로 코드를 작성하는 개발자를 위한 내용입니다. 코딩 작업이 없다면 아래 비개발자 파일 버전 관리 팁만 읽고 다음 섹션으로 넘어가도 됩니다. 명령어를 몰라도 괜찮습니다 — 자연어로 시작하면 됩니다.

비개발자라면? 파일 버전 관리 3가지

코딩이 없어도 파일이 실수로 바뀌거나 사라지는 상황은 누구에게나 생깁니다. 간단한 대안들:

Git이 궁금해졌다면? Git은 코드 외에도 어떤 파일이든 버전 관리가 가능합니다. 리서치 파일, 보고서, 기획안도 Git으로 안전하게 관리할 수 있습니다. 관심이 생겼다면 이 섹션을 계속 읽어보세요.

왜 Git & GitHub가 필요한가요?

Claude Code로 코드를 수정하다 보면 파일이 계속 바뀝니다. Git이 없으면:

• 어제 잘 됐던 코드가 오늘 왜 안 되는지 모름
• Claude가 실수로 중요한 코드를 지워도 되돌릴 수 없음
• 팀원과 같은 파일을 수정하다 서로의 작업을 덮어씀

Git: 모든 변경 기록을 저장하고 언제든 이전 상태로 되돌리는 도구 GitHub: 그 기록을 클라우드에 백업하고 팀과 공유하는 플랫폼

Claude Code 사용자에게 Git + GitHub는 선택이 아닙니다.

Google Drive와 Git의 딱 한 가지 차이

Git을 처음 쓰는 분들이 가장 헷갈려하는 부분입니다.

이 차이 하나만 기억하면 됩니다.

Git에는 항상 두 단계가 있습니다:

1. 저장 (Commit) — 변경 내용을 내 컴퓨터에 기록
2. 올리기 (Push) — 기록한 내용을 GitHub에 업로드

왜 두 단계인가요? 인터넷이 없어도 로컬에서 저장할 수 있고, 나중에 준비된 것만 골라서 올릴 수 있습니다.

첫 시작: 바르다 깃선생으로 5분 셋업

Git 명령어를 외우지 않아도 됩니다. 바르다 깃선생(git-teacher) 플러그인이 자연어로 모든 걸 처리해 줍니다.

gptaku_plugins를 04섹션에서 설치했다면 이미 준비되어 있습니다. 아니라면:

/plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git
/plugin install git-teacher

설치 후 Claude Code를 완전히 종료하고 다시 시작하세요.

최초 1회: 셋업

"깃 시작해줘"

자동으로 처리되는 것들:

1. Git 설치 확인 (없으면 설치 안내)
2. GitHub CLI(gh) 설치 확인
3. GitHub 계정 로그인 (브라우저 자동 열림)
4. 프로젝트 폴더 설정
   • 새 프로젝트 → 새 폴더 + GitHub 저장소 생성
   • 기존 프로젝트 → GitHub에서 가져오기
   • 현재 폴더 → 현재 위치를 저장소로 설정

이미 완료된 단계는 자동으로 건너뜁니다.

매일 하는 세 가지

1. 저장하기 (Commit)

"저장해줘"

바뀐 파일 목록을 보여주고, 설명(커밋 메시지)을 입력하라고 묻습니다.

예시: "로그인 페이지 디자인 수정"
      "버그 수정: 비밀번호 검증 오류"

저장 완료 후 이 안내가 나옵니다:

✅ 저장 완료!
아직 내 컴퓨터에만 있어요.
GitHub에 올리려면 "올려줘"라고 하세요.

2. GitHub에 올리기 (Push)

"올려줘"

저장된 내용을 GitHub에 업로드합니다. 완료되면 저장소 링크를 보내줍니다.

자동 오류 처리:

• 팀원이 먼저 올린 내용과 겹치면 자동으로 합쳐서 올림 (--rebase)
• SSH 인증 오류는 HTTPS로 자동 전환

3. 검토 요청하기 (Pull Request)

팀원에게 내 변경 사항을 검토받고 싶을 때:

"검토 요청해줘"

자동으로 처리: Branch 생성 → 저장 & 업로드 → PR 생성 → 링크 제공 → 원래 상태로 복귀

자연어 명령어 전체 표

하고 싶은 것                    이렇게 말하세요
─────────────────────────────────────────────────
처음 설정                       "깃 시작해줘"
현재 변경 파일 확인               "지금 어떤 상태?"
                               "뭐가 바뀌었어?"
저장하기 (Commit)               "저장해줘"
                               "세이브해줘"
GitHub에 올리기 (Push)          "올려줘"
                               "업로드해줘"
검토 요청하기 (PR)               "검토 요청해줘"
                               "팀원한테 보여주고 싶어"
용어 설명 요청                   "commit이 뭐야?"
                               "push랑 commit 차이 알려줘"

슬래시 명령어로도 사용 가능합니다:

Git 용어 빠른 해설

처음 보는 단어가 나왔을 때 참고하세요.

모르는 용어가 생기면 언제든 물어보세요:

"push랑 commit 차이가 뭐야?"

Claude Code와 함께하는 하루 루틴

작업 시작:
  claude 실행 → "깃 시작해줘" (첫 날 한 번만)

작업 중간중간:
  코드 수정 → "저장해줘" → "올려줘"
  (큰 작업 전: "지금 어떤 상태?"로 확인)

작업 마무리:
  "저장해줘" → "올려줘" (반드시 두 단계 모두)

팀 협업:
  기능 완성 → "검토 요청해줘" → PR 링크 공유

이 루틴을 지키면 Claude Code로 작업한 내용이 항상 안전하게 보관됩니다. 실수로 코드가 망가져도 언제든 이전 상태로 돌아올 수 있습니다.

.gitignore — API 키가 GitHub에 올라가지 않게

Git을 처음 쓸 때 가장 많이 하는 실수가 .env 파일에 있는 API 키를 GitHub에 올리는 것입니다.

바르다 깃선생은 "저장해줘" 시 프로젝트 타입을 자동 감지해서 .gitignore를 생성해 줍니다. 이미 있다면 건너뜁니다.

직접 만들고 싶다면:

# .gitignore 예시
.env
.env.local
node_modules/
.DS_Store

직접 Git 명령어를 쓰고 싶다면: Claude Code에 그냥 말해도 됩니다 — git commit, git push를 직접 실행해 줍니다. 바르다 깃선생은 비개발자를 위한 안내, 자동 오류 처리, 한국어 상태 설명이 추가된 레이어입니다. Git이 낯선 분이라면 바르다 깃선생부터 시작하세요.

13. 자주 하는 실수 & 해결법

초보자가 Claude Code를 쓰면서 자주 겪는 문제들을 Q&A 형식으로 정리했습니다.

Q1. claude 명령어를 못 찾는다고 한다 (command not found)

증상

$ claude
zsh: command not found: claude

원인 & 해결법

설치는 됐지만 터미널이 claude 명령어 위치를 모르는 상황입니다.

방법 1: 네이티브 설치 사용 (가장 확실)

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

설치 후 터미널을 완전히 닫고 새로 열어보세요.

방법 2: PATH 확인

# claude가 어디 설치됐는지 확인
which claude

# PATH 확인
echo $PATH

~/.local/bin이 PATH에 없으면 shell 설정 파일(.zshrc 또는 .bashrc)에 추가:

export PATH="$HOME/.local/bin:$PATH"

추가 후 source ~/.zshrc 실행.

방법 3: 설치 상태 점검

claude doctor

Q2. 로그인이 안 된다

증상

• 브라우저가 열리지 않음
• 인증 화면에서 멈춤
• 로그인 후에도 인증 오류

해결법

브라우저 팝업이 안 열릴 때

claude 실행 후 c를 눌러 인증 URL을 복사한 뒤, 브라우저에 직접 붙여넣기 하세요.

로그아웃 후 재인증

# Claude Code 안에서
> /logout

# 또는 인증 파일 직접 삭제
rm -rf ~/.config/claude-code/auth.json
claude

여전히 안 된다면

# 모든 설정 초기화 후 재시작
rm ~/.claude.json
rm -rf ~/.claude/
claude

주의: 이렇게 하면 모든 설정과 세션 기록이 삭제됩니다.

Q3. 너무 느리다 / 응답이 늦다

원인

대화가 길어질수록 Claude가 처리해야 할 내용(컨텍스트)이 쌓여서 느려집니다. 이는 정상적인 동작입니다.

해결법

방법 1: /compact로 컨텍스트 정리 (가장 효과적)

> /compact

대화 내용을 압축해서 속도를 회복합니다.

방법 2: /clear로 초기화

완전히 새로 시작해도 되는 경우:

> /clear

방법 3: 더 빠른 모델로 변경

복잡한 작업이 아니라면 Haiku나 Sonnet이 Opus보다 훨씬 빠릅니다.

> /model

모델 선택 화면에서 변경하세요.

방법 4: MCP 서버 줄이기

불필요한 MCP 서버가 많으면 느려질 수 있습니다.

> /mcp

사용하지 않는 서버를 비활성화하세요.

Q4. 내가 원하는 대로 안 고쳐준다

원인

지시가 모호하거나, Claude가 프로젝트 맥락을 모르거나, 같은 말을 계속 반복해서 Claude가 혼란스러운 경우입니다.

해결법

방법 1: 더 구체적으로 지시하기

# 모호한 지시
> 코드 개선해줘

# 구체적인 지시
> auth.js의 login 함수에서 이메일 유효성 검사가 빠져있어.
  정규식으로 이메일 형식 확인하는 코드를 42번 줄 다음에 추가해줘

방법 2: CLAUDE.md에 규칙 추가

자주 반복되는 요구사항은 프로젝트 규칙으로 저장하세요.

> /memory

또는 CLAUDE.md 파일에 직접 추가:

# 코드 스타일
- 에러 메시지는 항상 한글로 작성
- 함수마다 JSDoc 주석 필수
- var 사용 금지, const/let만 사용

방법 3: 같은 실수가 두 번 반복되면 초기화

> /clear

새로 시작해서 더 명확한 지시로 다시 요청하세요.

Q5. 파일을 수정했는데 실수인 것 같다

해결법

방법 1: Claude Code 안에서 되감기 (가장 빠름)

Esc 키를 두 번 연속으로 누르기
또는
> /rewind

이전 상태로 대화와 코드를 함께 되돌립니다.

방법 2: git으로 복구

# 변경된 내용 확인
git diff

# 특정 파일만 되돌리기
git checkout -- src/auth/login.js

# 모든 변경 취소
git checkout .

방법 3: 작업 전 git commit 습관 들이기

Claude Code로 큰 작업을 시작하기 전에 항상:

git add .
git commit -m "작업 전 백업 $(date +%Y%m%d-%H%M)"

Q6. 갑자기 비용이 많이 나왔다

원인

• 대화가 너무 길어짐 (컨텍스트가 클수록 토큰 소모 증가)
• 파일이 많은 프로젝트를 전체 분석 요청
• Opus 모델을 계속 사용
• 에이전트 팀 기능 사용

해결법

현재 비용 확인

> /cost

API 사용자용. 구독 사용자는 /stats로 사용량 확인.

비용 줄이는 방법

1. /compact 자주 사용해서 컨텍스트 관리
2. 단순 작업은 Sonnet이나 Haiku 사용 (/model로 변경)
3. 큰 파일/폴더 전체를 맥락 없이 읽히지 않기
4. 관련 없는 작업 사이에는 /clear로 초기화

예산 한도 설정 (자동화 사용 시)

claude -p --max-budget-usd 1.00 "질문"

Q7. 권한 요청이 너무 많이 뜬다

상황

Claude가 파일을 수정하거나 명령어를 실행할 때마다 허가를 요청합니다.

해결법

방법 1: 자주 쓰는 도구는 항상 허용으로 설정

> /permissions

권한 관리 화면에서 특정 도구를 Always Allow로 설정합니다.

방법 2: 파일 수정을 자동 허용

Shift+Tab을 눌러 Auto-Accept Edit Mode 선택

현재 세션 동안 파일 수정 요청을 자동으로 허용합니다.

방법 3: 각 권한 모드 이해하기

--dangerously-skip-permissions 사용 주의

이 옵션은 모든 권한 확인을 건너뜁니다. 격리된 컨테이너 환경이 아니면 사용하지 마세요. 실수로 시스템 파일을 수정하거나 삭제할 위험이 있습니다.

Q8. 한글이 깨진다 / 이상한 문자가 나온다

원인

터미널이 UTF-8 인코딩을 사용하지 않을 때 발생합니다.

해결법

macOS / Linux

shell 설정 파일(.zshrc 또는 .bashrc)에 추가:

export LANG=ko_KR.UTF-8
export LC_ALL=ko_KR.UTF-8

추가 후 source ~/.zshrc 실행.

터미널 앱 설정 확인

• iTerm2: Preferences → Profiles → Terminal → Character Encoding → UTF-8
• macOS 기본 터미널: 환경설정 → 프로파일 → 고급 → 문자 인코딩 → Unicode(UTF-8)
• VS Code 터미널: 자동으로 UTF-8 사용 (대부분 문제없음)

Windows (WSL)

# WSL에서 실행
sudo locale-gen ko_KR.UTF-8

Q9. 맥락을 잃어버렸다 (세션이 초기화됐다)

상황

• Claude가 이전에 한 작업을 기억하지 못함
• 세션이 갑자기 끊김
• 터미널을 닫았다 다시 열었음

해결법

방법 1: 이전 세션 이어서 시작

# 가장 최근 세션 이어서
claude --continue

# 세션 목록에서 선택
claude --resume

# 이름으로 이어서 (이름을 미리 저장했을 때)
claude --resume 경쟁사-리서치-2월

방법 2: 세션에 이름 붙여두기 (예방책)

중요한 작업을 시작할 때:

> /rename 경쟁사-리서치-2월

방법 3: CLAUDE.md에 중요 정보 저장

세션이 끊겨도 유지되어야 할 정보는 CLAUDE.md에:

> /memory

# 현재 진행 중인 작업
- 목표: Q1 시장 경쟁사 분석 보고서 완성
- 완료: A사, B사 분석
- 진행 중: C사 분석, 최종 비교표 작성
- 참고 파일: research/competitors/ 폴더

Q10. 코드가 너무 많이 바뀌었다 (예상치 못한 대규모 변경)

상황

"간단히 수정해줘"라고 했는데 Claude가 관련 없는 파일까지 대거 수정하는 경우.

해결법

방법 1: 즉시 멈추기

Claude가 작업 중이면 바로:

Ctrl+C

또는 Esc를 눌러 현재 작업 중단.

방법 2: 이전 상태로 되감기

Esc 두 번 연속
또는
> /rewind

방법 3: git으로 확인 및 복구

# 변경된 파일 목록 확인
git status

# 변경 내용 상세 확인
git diff

# 특정 파일만 복구
git checkout -- 파일경로

# 전부 취소
git checkout .

방법 4: Plan Mode로 먼저 확인 (예방책)

큰 작업 전에는 Plan Mode에서 계획을 먼저 검토하세요.

Shift+Tab (두 번)

또는

claude --permission-mode plan

방법 5: 지시를 더 구체적으로

# 범위를 명확하게 지정
> auth.js 파일의 login 함수만 수정해줘. 다른 파일은 건드리지 마

# 금지 사항 명시
> 리팩토링은 하지 말고 버그만 수정해줘

Q11. Claude가 문서 일부만 고치지 않고 전체를 새로 써버렸어요

상황

"3단락만 고쳐줘"라고 했는데 Claude가 문서 전체를 처음부터 다시 작성하는 경우.

해결법

방법 1: 즉시 되감기

Esc 두 번 연속
또는
> /rewind

방법 2: 범위를 더 명확하게 지정

# 모호한 지시
> 3단락 고쳐줘

# 구체적인 지시
> "도입부 두 번째 단락에서 '하지만'으로 시작하는 문장만 더 부드럽게 바꿔줘.
  나머지는 건드리지 마"

방법 3: Plan Mode로 먼저 확인

Shift+Tab으로 Plan Mode 진입 → Claude가 "어디를 어떻게 바꿀 예정"인지 먼저 보여줍니다. 확인 후 승인.

Q12. 한국어로만 검색했더니 정보가 부족해요

상황

Claude에게 리서치를 맡겼는데 한국어 자료만 찾아서 결과가 빈약한 경우.

해결법

검색 언어를 명시적으로 지시하세요:

"영어, 한국어 자료를 모두 검색해서 정리해줘"

"주로 영어 자료를 찾고, 핵심 내용은 한국어로 요약해줘"

"글로벌 트렌드는 영어 자료 기반으로, 국내 현황은 한국어로 조사해줘"

Claude는 언어를 지정하지 않으면 한국어 대화 맥락에서 한국어 자료 위주로 검색하는 경향이 있습니다.

Q13. AI가 추천한 패키지를 설치했는데 이상한 것 같다 🖥️ 개발자 전용

슬롭스쿼팅(Slopsquatting)이란?

AI 모델이 실제로 존재하지 않는 패키지를 자신 있게 추천(hallucination)할 때, 공격자가 그 이름으로 악성 코드가 담긴 패키지를 npm/PyPI에 미리 올려두는 공격 기법입니다.

Claude가 react-auth-helper라는 패키지를 추천했는데, 실제로는 존재하지 않거나 같은 이름의 악성 패키지가 등록돼 있을 수 있습니다.

설치 전 반드시 확인하는 법

npm 패키지 정보 먼저 조회

# 설치 전 패키지 정보 확인
npm info 패키지이름

# 다운로드 수, 최근 업데이트, 의존성 확인
# → 배포된 지 며칠 안 됐거나 다운로드가 극소수면 주의

Claude에게 출처를 함께 요청

"이 패키지가 정말 존재하는지 npmjs.com 링크와
GitHub 저장소 주소도 함께 알려줘"

낯선 패키지 대신 잘 알려진 것 우선

• 비슷한 기능이라면 GitHub star가 많고 오래된 패키지 선택
• Anthropic, Microsoft, Vercel, Meta 같은 검증된 조직의 패키지 우선
• 처음 보는 패키지는 README와 소스 코드를 직접 확인

설치 후 코드 검토

# 설치된 패키지 진입점 확인
cat node_modules/패키지명/index.js | head -100

💡 docs-guide 플러그인을 사용하면 Claude가 공식 문서를 직접 참조하므로, 존재하지 않는 패키지를 추천할 가능성이 크게 줄어듭니다.

Q14. Claude 작업 후 보안이 걱정된다 / 예상치 못한 변경이 생겼다 🖥️ 개발자 전용

AI 코드 병합 전 확인할 8가지 체크포인트

Claude가 작성하거나 수정한 코드를 커밋하기 전에 확인하세요.

보안 체크리스트:
□ 1. 하드코딩된 시크릿 없는가? (API 키, 비밀번호, 토큰)
□ 2. 사용자 입력이 제대로 검증되는가? (SQL 인젝션, XSS 방지)
□ 3. 동적 코드 실행 함수 사용 없는가? (eval 계열)
□ 4. 파일 경로가 사용자 입력을 그대로 사용하지 않는가? (path traversal)
□ 5. 에러 메시지에 내부 구조가 노출되지 않는가?
□ 6. 외부 URL 요청 시 도메인 검증이 있는가? (SSRF 방지)
□ 7. 의존성(패키지)이 갑자기 추가되지 않았는가?
□ 8. 기존 인증/권한 로직이 우회되지 않는가?

git add -p로 변경 사항 줄 단위 검토

git add .는 Claude가 변경한 모든 것을 한꺼번에 스테이징합니다. 대신 git add -p를 쓰면 변경 덩어리(hunk)마다 포함 여부를 선택할 수 있습니다.

git add -p

# 각 변경 덩어리에서:
# y → 이 변경 포함
# n → 이 변경 제외
# s → 더 작게 분리해서 보기
# d → 이 파일 나머지 전부 제외
# q → 종료

의심해야 할 AI 작업 패턴

원칙: Claude가 생성한 코드도 외부에서 받은 코드처럼 검토하세요. AI가 작성했다고 안전이 보장되지 않습니다.

요약: 자주 하는 실수 방지 체크리스트

Claude Code 시작 전:
□ 프로젝트 폴더로 이동했나? (cd 내프로젝트)
□ 중요한 작업이면 git commit 했나?
□ CLAUDE.md에 프로젝트 규칙이 있나?

작업 중:
□ 지시가 충분히 구체적인가?
□ 한 번에 너무 많이 요청하지 않았나?
□ 대화가 길어지면 /compact 사용했나?
□ 뭔가 이상하면 Ctrl+C로 바로 멈췄나?

작업 후:
□ 변경 내용을 확인했나? (git diff)
□ 테스트가 통과하는가?
□ 중요한 세션이면 이름을 저장했나? (/rename)

문제가 해결되지 않으면 Claude Code 안에서 /doctor를 실행해 설치 상태를 점검하거나, /bug를 입력해 Anthropic에 직접 문제를 보고할 수 있습니다.

14. MCP & 외부 도구 연결

Notion, Slack, Google Sheets, GitHub, DB 등 외부 도구를 Claude가 직접 다룰 수 있게 해주는 표준 프로토콜

MCP란?

**MCP(Model Context Protocol)**는 Claude가 외부 도구와 데이터 소스에 연결할 수 있게 해주는 오픈 표준입니다.

쉽게 말하면: Claude Code는 기본적으로 파일과 터미널만 다룹니다. MCP를 연결하면 Claude가 Notion 문서를 직접 읽고, Slack 메시지를 요약하고, Google Sheets를 업데이트하는 등 외부 도구와 상호작용할 수 있게 됩니다.

개발자라면 GitHub PR 리뷰, 데이터베이스 직접 쿼리, Sentry 에러 분석 등도 가능합니다.

비유: MCP는 Claude에게 USB 포트를 달아주는 것과 같습니다. 어떤 도구든 꽂으면 사용할 수 있게 됩니다.

MCP로 없어지는 노가다

MCP 없이는 이런 일들을 직접 해야 합니다:

업무/리서치 사용자

MCP로 할 수 있는 것들

GitHub — PR/이슈 직접 조작

# GitHub MCP 서버 연결
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 연결 후 이런 요청이 가능해집니다
> "PR #456 검토하고 개선점 제안해줘"
> "방금 발견한 버그 이슈 새로 만들어줘"
> "나에게 할당된 오픈 PR 목록 보여줘"

Sentry — 프로덕션 에러 분석

# Sentry 연결
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# /mcp 명령으로 인증 완료 후
> "지난 24시간 주요 에러가 뭐야?"
> "에러 ID abc123 스택트레이스 보여줘"
> "이 에러들이 어느 배포에서 생겼어?"

PostgreSQL — DB 직접 쿼리

# DB 연결 (읽기 전용 추천)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 연결 후
> "이번 달 총 매출 얼마야?"
> "orders 테이블 스키마 보여줘"
> "90일째 구매 안 한 고객 찾아줘"

Slack — 메시지 읽고 보내기

Slack 연동을 통해 슬랙 채널의 맥락을 그대로 Claude에게 전달할 수 있습니다. 팀 대화에서 버그 리포트가 올라오면 Claude가 해당 스레드 맥락을 읽고 바로 코딩 작업을 시작할 수 있습니다.

Notion, Asana, Figma 등

MCP 레지스트리(api.anthropic.com/mcp-registry/docs)에서 수백 가지 MCP 서버를 찾을 수 있습니다.

MCP 서버 설치 방법

방법 1: 원격 HTTP 서버 (권장)

# 기본 문법
claude mcp add --transport http <이름> <URL>

# 예시: Notion 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 인증 헤더가 필요한 경우
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

방법 2: 로컬 stdio 서버

내 컴퓨터에서 실행되는 서버입니다. 시스템 직접 접근이나 커스텀 스크립트에 적합합니다.

# 기본 문법
claude mcp add [옵션] <이름> -- <커맨드> [인자...]

# 예시: Airtable 연결
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

MCP 서버 관리 명령어

# 설정된 서버 목록 보기
claude mcp list

# 특정 서버 상세 확인
claude mcp get github

# 서버 제거
claude mcp remove github

# Claude Code 내에서 상태 확인
/mcp

설정 파일 위치 (스코프)

MCP 서버 설정은 사용 범위에 따라 세 곳에 저장됩니다:

# 팀 공유용 프로젝트 스코프로 추가
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 모든 프로젝트에서 쓸 유저 스코프로 추가
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

팀 프로젝트에서는 .mcp.json을 Git에 커밋해서 팀원 모두가 동일한 MCP 서버를 사용할 수 있습니다.

입문자 추천 MCP 3가지

실용성 기준으로 처음 써볼 만한 MCP 서버입니다:

1. Notion MCP

claude mcp add --transport http notion https://mcp.notion.com/mcp

없어지는 노가다: 회의록/리서치 결과 수동 복사, 페이지 내용 붙여넣기, 데이터베이스 일일이 업데이트

활용 예시:

• "Notion의 '회의록' DB에서 지난 7일 항목을 가져와서 결정사항·액션아이템만 모아 weekly.md로 만들어줘"
• "이 리서치 결과를 Notion '경쟁사 분석' 페이지에 추가해줘"

2. Slack MCP

claude.ai 계정 연결 후 claude.ai/settings/connectors에서 바로 설정 가능

없어지는 노가다: 채널 스레드 수동 읽기, 요약 요청을 위한 복붙, 공지 초안 직접 작성

활용 예시:

• "#마케팅 채널의 오늘 스레드를 읽고, 쟁점 3개와 합의된 다음 액션을 정리해서 슬랙 공지 초안을 만들어줘"

3. Google Chrome (웹 리서치)

claude.ai 계정 연결 후 claude.ai/settings/connectors에서 바로 설정 가능

없어지는 노가다: 웹사이트 방문해서 정보 수동 복사, 여러 사이트 비교를 위한 반복 탭 전환

활용 예시:

• "지정한 5개 경쟁사 사이트를 훑고, 오늘의 주요 변화·새 기능·가격 변경만 표로 정리해줘"

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Claude Code 공식 커넥터

Claude.ai 계정으로 Claude Code에 로그인한 경우, claude.ai/settings/connectors에서 설정한 MCP 서버가 Claude Code에 자동으로 연결됩니다.

공식적으로 지원되는 커넥터:

• Slack: 채널 메시지 읽기/쓰기
• Google Chrome: 브라우저 자동화 (Playwright 기반)

OAuth 인증이 필요한 서버 연결 방법

Sentry, GitHub 같은 클라우드 서버는 OAuth 인증이 필요합니다:

# 1단계: 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2단계: Claude Code 내에서 인증
> /mcp

# 브라우저 열림 → 로그인 → 완료

인증 토큰은 자동으로 저장되고 갱신됩니다.

MCP 프롬프트를 커맨드로 사용하기

MCP 서버가 프롬프트를 제공하는 경우, Claude Code에서 /mcp__서버명__프롬프트명 형식으로 직접 실행할 수 있습니다:

> /mcp__github__list_prs
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "로그인 버그" high

⚠️ 주의사항

신뢰할 수 없는 MCP 서버를 함부로 설치하지 마세요.

• MCP 서버는 Claude를 통해 내 파일 시스템, DB, 외부 서비스에 접근할 수 있습니다
• 특히 외부 콘텐츠를 가져오는 MCP 서버는 프롬프트 인젝션 위험이 있습니다
• Anthropic이 직접 검증한 서버만 공식 MCP 레지스트리에 등록되어 있습니다
• 출처가 불명확한 서버는 설치 전 소스 코드를 반드시 확인하세요

# 프로젝트 스코프 서버는 팀원들에게 확인 요청이 표시됩니다
# (보안 검토를 위한 안전장치)

GPTaku 플러그인과 MCP

여러분이 이미 설치한 GPTaku 플러그인들도 내부적으로 MCP를 활용합니다:

💡 플러그인을 설치하면 MCP 설정이 자동으로 추가됩니다. 별도로 MCP를 설정할 필요 없이, 플러그인이 알아서 처리합니다.

한 줄 요약

MCP = Claude에게 외부 세계를 연결하는 플러그인. GitHub, DB, Slack을 Claude가 직접 다루게 해서 "복사-붙여넣기" 노가다를 없앤다.

MCP가 "외부 세계와 연결"이라면, 다음 Hooks는 "Claude Code 자체 동작을 자동화"하는 것입니다.

15. Hooks — 내 작업을 지키는 안전장치

AI가 rm -rf를 실행하거나 git push --force로 히스토리를 날려버리면? Hooks를 설정하면 그런 일이 절대 일어나지 않습니다.

왜 Hooks가 필요한가?

Claude Code는 강력합니다. 파일을 만들고, 수정하고, 삭제하고, Git 명령어를 실행합니다. 그런데 바이브코딩 중에 이런 일이 실제로 일어납니다:

• rm -rf 한 방에 프로젝트 폴더가 사라짐
• git reset --hard로 커밋하지 않은 작업이 통째로 날아감
• git push --force로 팀원의 코드가 덮어씌워짐
• DROP TABLE로 데이터베이스가 날아감

Hooks는 이런 위험한 명령어를 Claude가 실행하기 전에 자동으로 차단합니다. LLM의 "판단"에 의존하는 게 아니라, 코드로 100% 확실하게 막는 겁니다.

Hooks란?

Hooks는 Claude Code의 특정 이벤트가 발생할 때 자동으로 실행되는 셸 커맨드입니다.

핵심: exit 0 = 허용, exit 2 = 차단 (stderr 메시지가 Claude에게 전달됨)

설정 위치

/hooks 커맨드로 인터랙티브하게 설정할 수도 있지만, 아래 예시를 복사-붙여넣기 하는 게 더 빠릅니다.

필수 Hook 1: Safety Hook — 위험한 명령어 자동 차단

이 Hook 하나만 설정해도 대부분의 사고를 막을 수 있습니다.

Step 1: 스크립트 파일 생성

~/.claude/hooks/block_dangerous.py 파일을 만드세요:

#!/usr/bin/env python3
"""위험한 명령어를 자동 차단하는 Safety Hook"""
import json, re, sys

BLOCKED_PATTERNS = [
    # 파일 삭제 차단 — rm 대신 trash 사용 (휴지통으로 이동, 복구 가능)
    (r"\brm\s+", "rm 대신 trash를 사용하세요 (brew install trash)"),
    (r"\bunlink\s+", "unlink 대신 trash를 사용하세요"),

    # Git 히스토리 파괴 차단
    (r"git\s+reset\s+--hard", "git reset --hard는 커밋하지 않은 작업을 삭제합니다"),
    (r"git\s+push\s+.*--force", "git push --force는 원격 히스토리를 덮어씁니다"),
    (r"git\s+push\s+.*-f\b", "git push -f는 원격 히스토리를 덮어씁니다"),
    (r"git\s+clean\s+-.*f", "git clean -f는 추적되지 않은 파일을 영구 삭제합니다"),
    (r"git\s+checkout\s+\.\s*$", "git checkout .은 모든 변경사항을 삭제합니다"),
    (r"git\s+stash\s+drop", "git stash drop은 스태시를 영구 삭제합니다"),
    (r"git\s+branch\s+-D", "git branch -D는 브랜치를 강제 삭제합니다"),

    # 데이터베이스 파괴 차단
    (r"DROP\s+(DATABASE|TABLE)", "DROP은 데이터를 영구 삭제합니다"),
    (r"TRUNCATE\s+TABLE", "TRUNCATE는 모든 데이터를 삭제합니다"),
]

data = json.load(sys.stdin)
if data.get("tool_name") != "Bash":
    sys.exit(0)

command = data.get("tool_input", {}).get("command", "")
for pattern, reason in BLOCKED_PATTERNS:
    if re.search(pattern, command, re.IGNORECASE):
        print(f"차단됨: {reason}", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

Step 2: 실행 권한 부여

터미널에서 실행하세요:

chmod +x ~/.claude/hooks/block_dangerous.py

Step 3: Hook 등록

~/.claude/settings.json에 추가하세요:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block_dangerous.py"
          }
        ]
      }
    ]
  }
}

동작 원리

Claude가 rm -rf node_modules를 실행하려고 하면:

1. PreToolUse 이벤트 발생 → block_dangerous.py 실행
2. 명령어가 rm 패턴에 매치됨
3. exit 2로 차단 + "rm 대신 trash를 사용하세요" 메시지 전달
4. Claude가 메시지를 받고 trash node_modules로 대안 실행

trash는 파일을 휴지통으로 보내서 실수해도 복구할 수 있습니다. brew install trash (macOS) 또는 npm install -g trash-cli로 설치하세요.

차단 패턴을 더 추가하고 싶다면

BLOCKED_PATTERNS 리스트에 원하는 패턴을 추가하면 됩니다:

# 예: chmod 777 차단
(r"chmod\s+777", "chmod 777은 보안상 위험합니다"),

# 예: 프로덕션 서버 SSH 차단
(r"ssh\s+.*prod", "프로덕션 서버 접근이 차단되었습니다"),

필수 Hook 2: 완료 알림

Claude가 작업을 끝내면 소리로 알려줍니다. 바이브코딩 중 다른 창을 보고 있어도 놓치지 않습니다.

macOS — 시스템 사운드

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Frog.aiff"
          }
        ]
      }
    ]
  }
}

Stop과 Notification에 다른 소리를 쓰면 "끝남" vs "확인 필요"를 소리만으로 구분할 수 있습니다.

사용 가능한 macOS 시스템 사운드 확인:

ls /System/Library/Sounds/

macOS — 데스크탑 알림 팝업

소리 대신 (또는 함께) 화면에 알림 팝업을 띄울 수도 있습니다:

{
  "type": "command",
  "command": "osascript -e 'display notification \"작업이 완료되었습니다\" with title \"Claude Code\"'"
}

Linux

{
  "type": "command",
  "command": "notify-send 'Claude Code' '작업이 완료되었습니다'"
}

두 Hook을 합쳐서 설정하기

Safety Hook + 완료 알림을 하나의 settings.json에 합치면 이렇습니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block_dangerous.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Frog.aiff"
          }
        ]
      }
    ]
  }
}

이미 settings.json에 다른 설정이 있다면, hooks 키만 추가하거나 병합하세요. /hooks 커맨드로 확인할 수 있습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=\"$(jq -r '.tool_input.file_path // empty')\"; if [[ \"$FILE\" == customers/* || \"$FILE\" == invoices/* ]]; then echo \"차단: 민감 폴더입니다\" >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/업무규칙.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "모든 태스크가 완료되었는지 확인하세요. 미완료 항목이 있으면 계속 작업하세요."
          }
        ]
      }
    ]
  }
}

트러블슈팅

디버그: claude --debug 또는 Ctrl+O로 Hook 실행 로그 확인

한 줄 요약

Safety Hook + 완료 알림 — 이 두 개만 설정하면 바이브코딩이 훨씬 안전하고 편해집니다. rm 한 방에 프로젝트 날리는 사고를 미리 막으세요.

다음 섹션에서는 반복 작업을 Skills로 자동화하는 방법을 배웁니다.

16. Skills & 플러그인 만들기

자주 하는 일을 레시피로 저장해두기 — /커맨드 하나로 꺼내 쓰고, 팀과도 공유할 수 있습니다

Skills란?

Skills는 Claude Code에 새로운 능력을 추가하는 재사용 가능한 워크플로우입니다. SKILL.md 파일을 만들면 Claude가 그것을 도구로 인식하고, /스킬이름 커맨드로 직접 실행하거나 상황에 맞게 자동으로 활성화합니다.

쉽게 말하면: 자주 쓰는 작업 절차를 문서화해 두면, 다음부터는 한 마디로 실행됩니다.

참고: 기존 .claude/commands/ 폴더의 커스텀 슬래시 커맨드는 Skills로 통합되었습니다. 기존 파일은 그대로 작동합니다.

Skills vs 일반 대화 차이점

Skills로 없어지는 노가다

내 Skills 만드는 방법

Step 1: 디렉터리 생성

# 내 모든 프로젝트에서 사용할 경우 (개인용)
mkdir -p ~/.claude/skills/commit

# 현재 프로젝트에서만 사용할 경우
mkdir -p .claude/skills/commit

Step 2: SKILL.md 작성

.claude/skills/commit/SKILL.md:

---
name: commit
description: 변경사항을 분석해서 좋은 커밋 메시지를 작성하고 커밋합니다. 커밋할 때 사용.
disable-model-invocation: true
---

현재 staged 변경사항을 분석해서 Conventional Commits 형식으로 커밋하세요:

1. `git diff --staged` 실행해서 변경사항 확인
2. 변경 유형 파악 (feat/fix/docs/refactor/test/chore)
3. 50자 이내 제목 작성
4. 필요시 본문에 상세 설명 추가
5. `git commit -m "..."` 실행

Step 3: 실행

# 직접 실행
/commit

# 또는 자연어로 → Claude가 자동 감지
"변경사항 커밋해줘"

Skills 파일 구조

my-skill/
├── SKILL.md           # 메인 지시사항 (필수)
├── template.md        # Claude가 채울 템플릿 (선택)
├── examples/
│   └── sample.md      # 예시 출력 (선택)
└── scripts/
    └── validate.sh    # Claude가 실행할 스크립트 (선택)

팁: SKILL.md는 500줄 이내로 유지하고, 상세 내용은 별도 파일로 분리하세요.

핵심 Frontmatter 옵션

---
name: my-skill           # 스킬 이름 (디렉터리명 기본값)
description: 설명        # Claude가 언제 이 스킬을 쓸지 판단하는 기준 (필수)
disable-model-invocation: true  # true면 사용자만 실행 가능 (Claude 자동 실행 불가)
user-invocable: false    # false면 메뉴에 안 보임 (Claude만 자동 실행 가능)
allowed-tools: Read, Grep, Glob  # 이 스킬 실행 중 허용할 도구만 지정
context: fork            # 독립된 서브에이전트 컨텍스트에서 실행
model: sonnet            # 이 스킬에서 사용할 모델 지정
---

실용 예시 4가지

예시 1: 회의록 자동 정리

.claude/skills/meeting/SKILL.md:

---
name: meeting
description: 회의 녹음 파일을 받아 텍스트로 변환하고 회의록과 액션아이템을 정리합니다. 회의 후 정리할 때 사용.
argument-hint: [녹음 파일 경로]
disable-model-invocation: true
---

$ARGUMENTS 파일을 처리해서 회의록을 만드세요:

1. 음성 변환 도구(whisper 등)가 없으면 설치
2. $ARGUMENTS 파일을 텍스트로 변환
3. 다음 형식으로 회의록 작성:
   - 날짜 / 참석자
   - 주요 논의 내용 (3~5줄 요약)
   - 결정된 사항
   - 담당자별 액션아이템 (이름: 할 일, 기한)
4. 원본 파일명과 같은 이름으로 .md 파일 저장

실행:

/meeting ~/Downloads/meeting-250225.mp3

파이썬이나 변환 도구를 몰라도 됩니다. Claude Code가 필요한 것을 알아서 준비합니다.

예시 2: SNS 콘텐츠 자동화

.claude/skills/sns-post/SKILL.md:

---
name: sns-post
description: 주어진 내용을 SNS 게시물로 변환합니다. 블로그, 인스타그램, LinkedIn 포스팅이 필요할 때 사용.
argument-hint: [주제 또는 원고 내용]
---

$ARGUMENTS를 SNS 게시물로 변환하세요:

1. 인스타그램 버전 (해시태그 10개, 이모지 포함, 친근한 어조, 300자 이내)
2. LinkedIn 버전 (전문적 어조, 인사이트 강조, 500자 이내)
3. 트위터/X 버전 (140자 이내, 핵심만 간결하게)

각 버전을 구분선으로 나눠 출력하세요.

실행:

/sns-post 우리 팀이 새 제품 출시에 성공했습니다. 6개월의 개발 끝에...

---
name: review
description: 코드를 리뷰합니다. 코드 품질, 보안, 성능 측면에서 검토가 필요할 때 사용.
---

다음 순서로 코드를 리뷰하세요:

1. `git diff HEAD~1` 또는 `$ARGUMENTS`로 지정된 파일 분석
2. 다음 항목 체크:
   - 코드 가독성 및 명명 규칙
   - 에러 처리 누락 여부
   - 보안 취약점 (SQL injection, XSS, 하드코딩된 시크릿)
   - 중복 코드
   - 테스트 커버리지
3. 우선순위별 정리:
   - 🔴 Critical (반드시 수정)
   - 🟡 Warning (수정 권장)
   - 🔵 Suggestion (고려 사항)

/review src/auth/login.ts

---
name: fix-issue
description: GitHub 이슈를 구현합니다. 이슈 번호를 전달하면 분석-구현-테스트-커밋까지 진행.
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Edit, Write
---

GitHub 이슈 $ARGUMENTS를 처리하세요:

1. `gh issue view $ARGUMENTS` 로 이슈 내용 확인
2. 요구사항 파악 후 구현 계획 수립
3. 관련 파일 찾고 코드 구현
4. 테스트 작성 및 실행
5. `gh issue close $ARGUMENTS` 후 커밋 생성

/fix-issue 123

예시 3: 번역 자동화

.claude/skills/translate/SKILL.md:

---
name: translate
description: 파일이나 텍스트를 번역합니다.
argument-hint: [파일경로 또는 텍스트] [대상언어]
---

$ARGUMENTS[0]을 $ARGUMENTS[1]로 번역하세요.

- 기술 용어는 원문 유지 (코드, 명령어, 고유명사)
- 마크다운 구조 보존
- 번역 결과를 원본과 같은 파일명에 언어 코드 추가해서 저장

실행:

/translate README.md ko

동적 컨텍스트 주입 (고급)

! + 백틱 문법으로 스킬 실행 전에 셸 커맨드를 실행하고 결과를 컨텍스트에 주입할 수 있습니다:

---
name: pr-summary
description: PR 요약을 작성합니다.
context: fork
allowed-tools: Bash(gh *)
---

## PR 컨텍스트
- 변경 내용: !`gh pr diff`
- PR 댓글: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

위 내용을 바탕으로 명확한 PR 요약을 작성하세요.

Claude가 이 스킬을 실행하면:

1. 백틱 안의 명령어가 먼저 실행됨
2. 실제 데이터가 프롬프트에 삽입됨
3. Claude가 실제 PR 내용을 보고 요약 작성

Skills가 저장되는 위치

같은 이름의 스킬이 여러 위치에 있으면 엔터프라이즈 > 개인 > 프로젝트 순으로 우선순위가 적용됩니다.

스킬 만들기가 어렵다면: 스킬러들의 수다

직접 SKILL.md를 작성하는 게 막막하다면, 스킬러들의 수다(skillers-suda) 플러그인이 대신 만들어줍니다.

/skillers-suda 번역 스킬 만들어줘

4명의 전문가(기획자/사용자/전문가/검수자)가 내부적으로 논의한 뒤:

1. 인터뷰 — 3~5개 질문으로 핵심 정보 수집
2. 워크플로우 설계 — 6가지 단계 타입(프롬프트/스크립트/API·MCP/RAG/검토/생성)을 조합
3. 파일 생성 — SKILL.md + scripts/ + references/ 전체 구조 자동 생성
4. 테스트 + 고도화 — 만든 스킬을 바로 테스트하고, 대화로 계속 개선

코드를 몰라도 "번역 스킬 만들어줘", "회의록 정리 스킬 만들어줘"처럼 말하면 전문가급 스킬이 생성됩니다.

스킬러들의 수다 설치: 플러그인 설치 섹션의 gptaku_plugins 참조

플러그인으로 패키징하기

팀 전체에 배포하거나 커뮤니티와 공유하려면 플러그인으로 패키징합니다.

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 플러그인 메타데이터
├── skills/
│   ├── review/
│   │   └── SKILL.md
│   └── commit/
│       └── SKILL.md
└── hooks/
    └── hooks.json         # 플러그인 전용 Hooks

plugin.json

{
  "name": "my-plugin",
  "description": "팀 공통 워크플로우 모음",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

로컬 테스트

# 플러그인 디렉터리로 실행
claude --plugin-dir ./my-plugin

# 스킬 실행 (플러그인 네임스페이스 포함)
/my-plugin:review
/my-plugin:commit

Standalone vs 플러그인 선택 기준

Skills 자동 감지 원리

Claude는 description 필드를 보고 어떤 상황에서 스킬을 써야 할지 판단합니다:

# 잘 쓴 description 예시
description: 코드를 리뷰합니다. PR 리뷰, 코드 품질 검토, 보안 분석이 필요할 때 사용.

# 아쉬운 description 예시
description: review tool

• "어떤 상황에서 쓰는지"를 명확히 기술할수록 Claude가 더 잘 감지합니다
• disable-model-invocation: true를 설정하면 Claude가 자동으로 실행하지 않습니다

트러블슈팅

한 줄 요약

Skills = 내가 자주 하는 작업을 /커맨드 하나로 만들어두는 것. 팀에 배포하려면 플러그인으로 패키징하면 된다.

Skills를 만들어뒀다면, Sub-agents로 그 Skills를 여러 Claude가 동시에 실행하게 할 수 있습니다.

17. Sub-agents & Agent Teams

Claude가 다른 Claude에게 작업을 위임 — 복잡한 작업을 병렬로 처리하는 방법

Sub-agents란?

**Sub-agents(서브에이전트)**는 메인 Claude가 특정 작업을 전문화된 별도의 Claude 인스턴스에 위임하는 기능입니다.

쉬운 비유: 팀장이 프로젝트를 받으면 혼자 다 하지 않고 팀원에게 나눠 맡깁니다. "리서치는 A에게, 번역은 B에게, 최종 교정은 C에게" — Sub-agents는 Claude가 이렇게 작업을 분담하는 방식입니다.

각 서브에이전트는:

• 독립된 컨텍스트 창을 가집니다 (메인 대화와 분리)
• 커스텀 시스템 프롬프트로 특정 역할에 집중합니다
• 제한된 도구만 사용합니다 (필요한 것만)
• 작업 완료 후 요약 결과만 메인으로 반환합니다

개념도

메인 Claude (오케스트레이터)
    │
    ├──► 서브 Claude A: 탐색 전담 (Explore)
    │         └── 파일 읽기, 코드 검색만 가능
    │
    ├──► 서브 Claude B: 구현 전담 (general-purpose)
    │         └── 파일 읽기+수정 가능
    │
    └──► 서브 Claude C: 테스트 전담 (custom)
              └── Bash 실행만 가능

각 서브에이전트는 독립 컨텍스트에서 실행
→ 메인 컨텍스트를 깨끗하게 유지
→ 결과 요약만 메인으로 반환

언제 유용한가?

Sub-agents를 쓰면 좋은 상황

Sub-agents보다 일반 대화가 나은 상황

내장 서브에이전트

Claude Code는 기본적으로 3개의 서브에이전트를 포함합니다:

Claude가 코드를 탐색해야 할 때는 자동으로 Explore 서브에이전트를 씁니다. 탐색 결과(수천 줄의 파일 내용)가 메인 대화를 오염시키지 않고, 요약만 메인으로 돌아옵니다.

나만의 서브에이전트 만들기

방법 1: /agents 인터랙티브 메뉴 (권장)

/agents

1. Create new agent 선택
2. User-level (모든 프로젝트) 또는 Project-level (현재 프로젝트) 선택
3. Generate with Claude 선택 후 역할 설명
4. 허용 도구 선택
5. 모델 선택 (Haiku/Sonnet/Opus)
6. 저장

방법 2: 파일 직접 작성

아래 예시를 .claude/agents/ 폴더에 저장하면 즉시 사용할 수 있습니다.

리서치 요약 에이전트 (.claude/agents/researcher.md):

---
name: researcher
description: 자료 폴더를 읽고 핵심 요약/인사이트/다음 질문을 정리합니다. 리서치가 필요할 때 자동으로 사용.
tools: Read, Grep, Glob
model: sonnet
---

당신은 리서치 어시스턴트입니다.
- 결론을 먼저 5줄로 요약
- 근거가 되는 문장/출처 파일명을 함께 표기
- "추정/가정"은 명확히 라벨링
- 마지막에 다음 조사 질문 5개를 제안

번역 에이전트 (.claude/agents/translator.md):

---
name: translator
description: 파일/문장을 지정 언어로 번역하고, 마크다운 구조를 유지합니다.
tools: Read, Write
model: sonnet
---

번역 규칙:
- 고유명사/제품명/코드/명령어는 원문 유지
- 문장 톤은 "친절하지만 과장 금지"
- 표/목차/링크 구조는 유지

최종 점검(QA) 에이전트 (.claude/agents/editor-qa.md):

---
name: editor-qa
description: 최종 문서의 오탈자/표기 통일/금지어/링크 누락을 점검합니다.
tools: Read, Grep, Glob
model: haiku
---

점검 체크리스트:
- 날짜/숫자 표기 통일 (예: 2026-02-26)
- 금지어(완벽/혁명/무조건) 탐지
- 링크(https://) 누락/깨짐 의심 구간 표시
- "다음 액션"이 빠졌으면 추가 제안

---
name: code-reviewer
description: 코드를 리뷰합니다. 코드 변경 후 품질, 보안, 성능을 검토할 때 자동으로 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 시니어 코드 리뷰어입니다.

실행 시:
1. `git diff`로 최근 변경사항 확인
2. 수정된 파일에 집중

리뷰 체크리스트:
- 코드 가독성 및 명명 규칙
- 에러 처리 적절성
- 보안 취약점 (노출된 시크릿, 입력 검증)
- 테스트 커버리지

피드백 형식:
- 🔴 Critical (반드시 수정)
- 🟡 Warning (수정 권장)
- 🔵 Suggestion (고려 사항)

서브에이전트 설정 옵션

---
name: my-agent           # 소문자 + 하이픈 (필수)
description: 설명        # Claude가 언제 위임할지 판단 기준 (필수)
tools: Read, Grep, Glob  # 허용 도구 목록 (생략 시 모든 도구 상속)
disallowedTools: Write   # 제외할 도구
model: haiku             # haiku / sonnet / opus / inherit(기본값)
permissionMode: default  # default / acceptEdits / dontAsk / bypassPermissions
maxTurns: 20             # 최대 실행 턴 수
memory: user             # 영구 메모리: user / project / local
background: false        # true면 항상 백그라운드 실행
isolation: worktree      # worktree면 격리된 Git 워크트리에서 실행
---

서브에이전트 저장 위치

실용 예시

예시 1: 병렬 리서치 (경쟁사 동시 분석)

"경쟁사 A, B, C를 각각 별도 에이전트로 동시에 분석해줘.
 각 에이전트는 웹사이트, 가격, 리뷰를 조사하고
 결과를 하나의 비교표로 통합해줘"

→ 3개 리서치 에이전트가 동시에 작동 → 결과를 하나의 비교표로 통합 → 순서대로 처리했을 때 대비 3배 빠름

예시 2: 문서 일괄 처리 (PDF 20개 병렬 요약)

"Downloads 폴더의 PDF 20개를 5개씩 나누어
 4개 에이전트가 동시에 요약하고
 결과를 하나의 보고서로 합쳐줘"

→ 4개 요약 에이전트 병렬 실행, 처리 속도 4배 → 방대한 요약 로그가 메인 대화를 오염시키지 않음

예시 3: 역할 분담 — 리서치 → 편집 연쇄

"researcher 에이전트로 sources/ 폴더를 읽고 1페이지 요약해줘"
"editor-qa 에이전트로 final/ 폴더 문서 품질 점검하고, 수정이 필요한 항목만 리스트업해줘"
"translator 에이전트로 drafts/post.md를 영어로 번역해서 drafts/post.en.md로 저장해줘"

→ 각 전담 에이전트가 순서대로 작업 → 메인 Claude는 흐름만 조율

"인증, DB, API 모듈을 각각 별도 서브에이전트로 병렬 분석해줘"

"code-reviewer 에이전트로 성능 문제 찾고, optimizer 에이전트로 수정해줘"

"서브에이전트로 전체 테스트 실행하고 실패한 것만 보고해줘"

영구 메모리 기능

서브에이전트에 memory 필드를 설정하면 세션 간에도 학습 내용이 유지됩니다:

---
name: code-reviewer
description: 코드를 리뷰합니다
memory: user
---

코드를 리뷰하면서 발견한 코드베이스 패턴, 아키텍처 결정, 반복되는 이슈를
메모리에 기록하세요. 다음 리뷰 때 이전 학습 내용을 활용하세요.

포그라운드 vs 백그라운드 실행

• 포그라운드: 완료될 때까지 대기. 권한 요청이 사용자에게 전달됨
• 백그라운드: 백그라운드에서 동시 실행. 계속 다른 작업 가능

# 백그라운드 실행 요청
"이걸 백그라운드에서 실행해줘"

# 실행 중 백그라운드로 전환
Ctrl+B

주의: 백그라운드 서브에이전트는 MCP 도구를 사용할 수 없습니다.

Agent Teams란?

Agent Teams는 서브에이전트보다 한 단계 더 나아간 개념입니다. 여러 에이전트가 각자의 완전히 독립된 세션에서 실행되며 협력합니다.

서브에이전트로 컨텍스트 창이 부족하거나, 작업이 여러 세션에 걸쳐 지속되어야 할 때 Agent Teams를 고려합니다.

플러그인으로 쉽게 시작하기: 끼리끼리

Agent Teams를 직접 설정하는 게 어렵다면, 끼리끼리(kkirikkiri) 플러그인이 대신 해줍니다.

/kkirikkiri 리서치 팀 만들어줘

자연어 한마디로:

1. 의도 파악 — 리서치/개발/분석/콘텐츠 중 매칭
2. 인터뷰 — 2~3개 질문으로 세부 요구사항 수집
3. 환경 스캔 — 설치된 CLI(Codex, Gemini 등) 자동 탐지
4. 팀 구성 제안 — 역할별 에이전트 + 예상 비용/시간 안내
5. 실행 — Agent Teams 자동 생성 및 실행
6. 품질 검증 — 결과 자동 판정, 부족하면 재시도

팀장은 항상 가장 똑똑한 모델(Opus)이 맡고, 코드를 짜지 않고 계획/배분/검증만 합니다.

끼리끼리 설치: 플러그인 설치 섹션의 gptaku_plugins 참조

⚠️ 비용 주의

서브에이전트는 각각 독립된 Claude 인스턴스입니다. 에이전트마다 토큰을 소모합니다.

• 서브에이전트 3개 병렬 실행 = 토큰 사용량 대폭 증가
• 결과가 메인 컨텍스트로 돌아올 때 추가 토큰 소모
• 불필요한 서브에이전트 남용은 비용 증가로 이어짐

비용 절약 팁:

• 읽기 전용 탐색에는 Haiku 모델 서브에이전트 사용
• 서브에이전트가 반환하는 결과의 양을 명확히 지정
• 단순 작업은 메인 대화에서 처리

초보자를 위한 조언

처음엔 단일 Claude로 충분합니다.

서브에이전트는 다음 상황이 생겼을 때 도입하세요:

1. 메인 컨텍스트가 자꾸 넘쳐서 압축이 반복될 때
2. 동일한 탐색 작업을 여러 번 반복할 때
3. 특정 도구만 쓰는 안전한 리뷰어가 필요할 때

한 줄 요약

Sub-agents = Claude가 다른 Claude에게 작업 위임. 독립 컨텍스트에서 실행되므로 메인 대화를 깨끗하게 유지하면서 병렬 처리 가능. 단, 토큰 비용은 에이전트 수만큼 증가.

18. 나만의 AI 워크스페이스 설계하기

CLAUDE.md, Skills, Hooks를 배웠다면 이제 조합할 차례입니다. 단순한 AI 도구가 아닌, 나를 위한 자동화 사무실을 만드는 방법.

워크스페이스란?

일반적인 AI 사용: "질문 → 답변" (매번 처음부터)

워크스페이스: 역할이 정해진 AI가, 나만의 규칙으로, 일관된 방식으로 작동하는 시스템

구성 요소:

CLAUDE.md     → AI의 역할, 규칙, 지식 (장기 기억)
폴더 구조     → 작업물이 체계적으로 쌓이는 구조
Skills        → 반복 작업의 자동화 (/명령어)
Hooks         → 품질 보장을 위한 자동 검증

핵심 설계 철학

"모든 규칙을 CLAUDE.md에 넣지 마세요. Skills로 분산하고, Hooks로 강제하세요."

• CLAUDE.md: 변하지 않는 역할과 원칙
• Skills: 반복되는 작업 흐름
• Hooks: 놓치면 안 되는 품질 기준

용도별 워크스페이스 예시

리서치 워크스페이스

CLAUDE.md 핵심:
  - 출처 없는 주장 금지
  - 모든 정보에 출처 등급 표기 (A~E)
  - 리서치 결과는 /reports 폴더에 자동 저장

폴더 구조:
  inbox/      → 참고 자료 보관
  reports/    → 완성된 리서치
  sources/    → 출처 모음

Skills:
  /research [주제]  → 웹 검색 → 정리 → 저장
  /summary [파일]   → 문서 요약

콘텐츠 제작 워크스페이스

CLAUDE.md 핵심:
  - 브랜드 톤 정의 (예: 친근하고 실용적, 전문 용어 최소화)
  - 타겟 독자 정의
  - 콘텐츠 형식 템플릿

폴더 구조:
  drafts/     → 초안
  published/  → 발행 완료
  templates/  → 재사용 형식

Skills:
  /blog [주제]       → 블로그 포스트 초안
  /newsletter [내용] → 뉴스레터 형식 변환
  /sns [내용]        → 인스타그램·트위터 버전

💡 리서치 워크스페이스를 구성할 때 deep-research 플러그인을 활용하면 별도의 Skills 제작 없이 바로 멀티에이전트 리서치가 가능합니다. 콘텐츠 작업에는 docs-guide로 공식 문서 기반의 정확한 자료를 확보할 수 있습니다.

비즈니스 워크플로우

CLAUDE.md 핵심:
  - 회사/팀 정보, 주요 프로젝트 현황
  - 이메일 스타일 (공식적/친근함 수준)
  - 보고서 형식 템플릿

Skills:
  /meeting [녹취]    → 요약 + 결정사항 + 액션 아이템
  /report [주제]     → 주간 보고서 초안
  /email [상황]      → 이메일 초안

실제 사례 공개: 아이디에이션 워크스페이스

CC101(이 사이트)이 만들어진 워크스페이스를 공개합니다.

CLAUDE.md 핵심 내용

# 아이디에이션 워크스페이스

## 역할
아이디어 발굴, 검증, 실행을 돕는 AI 파트너

## 핵심 원칙
- 한국어 전용
- 리서치 없이 주장 금지 (할루시네이션 방지)
- 모든 출처 등급 표기 (A~E)
- 검증 없이 "될 것 같다" 발언 금지
- 아이디어는 반드시 문서화 (휘발 방지)

## 검증 방식
4개 페르소나 Council:
- Visionary: 잠재력·비전
- Pragmatist: 실현 가능성·리소스
- Critic: 리스크·약점
- User Advocate: 사용자 가치

## 폴더 구조
10-inbox/      → 참고 자료
20-sparks/     → 아이디어 포착
30-research/   → 리서치 결과
40-foundry/    → 검증 결과
50-blueprints/ → MVP 설계
60-ventures/   → 실행 중
70-playbook/   → 경험 축적
90-shelf/      → 보류 아이디어

사용 중인 Skills

/spark [아이디어]   → 아이디어 포착 + ICE 스코어 평가
/research [주제]    → 7단계 딥리서치
/validate           → 4페르소나 Council 검증
/insight [내용]     → 교훈 Playbook 저장

이 워크스페이스에서 만들어진 것

• CC101 아이디어 포착 및 검증
• 3개 AI 섹션 구성 토론 (agent-council)
• 공식 문서 57개 리서치
• Next.js 사이트 개발 및 배포
• 이후 대화를 통한 지속 보완

나만의 워크스페이스 만들기 — 4단계

1단계: 목적 정의

자문하세요:
□ 어떤 작업을 반복하고 있나?
□ AI에게 어떤 역할을 맡기고 싶나?
□ 어떤 규칙을 일관되게 지키길 원하나?
□ 결과물이 어디에 쌓이면 좋겠나?

2단계: CLAUDE.md 작성

최소 구성 템플릿 (복사해서 시작하세요):

# [워크스페이스 이름]

## 역할
[AI에게 부여할 역할과 목적 — 1-2문장]

## 핵심 규칙
- [절대 지켜야 할 것 1]
- [절대 지켜야 할 것 2]
- [절대 하지 말아야 할 것]

## 폴더 구조
- [폴더명]/  → [용도]
- [폴더명]/  → [용도]

## 주요 작업 방식
[반복되는 워크플로우 설명]

3단계: 폴더 구조 설정

번호 prefix를 사용하면 순서가 유지됩니다:

mkdir -p 01-inbox 02-work 03-output 04-archive

4단계: 반복 작업 → Skills화

같은 작업을 3번 이상 하게 된다면 Skill로 만드세요. → Skills 만들기는 15섹션에서 다룹니다

MCP와의 조합

워크스페이스에 MCP를 연결하면 훨씬 강력해집니다:

→ MCP 연결은 13섹션에서 다룹니다

워크스페이스는 한 번에 완성되지 않습니다. 쓰면서 불편한 게 생기면 CLAUDE.md를 수정하고, 반복 작업이 보이면 Skill을 추가하세요. 시간이 지날수록 나에게 맞게 진화합니다.

19. 비용 관리 & 절약 팁

Claude Code를 더 스마트하게, 더 저렴하게 쓰는 방법을 알아봅니다.

비용 구조 한눈에 보기

Claude Code의 비용 방식은 크게 두 가지입니다.

Claude.ai Pro/Max 구독자는 구독료 안에 Claude Code 사용이 포함되어 있어 API 비용이 따로 청구되지 않습니다. /cost 명령어가 표시하는 숫자는 API 사용자를 위한 것이므로 구독자는 참고용으로만 보면 됩니다.

API 사용자는 사용량에 따라 요금이 발생합니다. 공식 문서에 따르면 평균적으로 개발자 1인당 하루 약 $6, 90%의 사용자는 하루 $12 이하의 비용이 발생합니다.

토큰이란?

**토큰(token)**은 Claude가 텍스트를 처리하는 단위입니다.

• 영어 기준: 단어 약 1개 = 1~2 토큰
• 한국어 기준: 글자 약 2~3자 = 1 토큰
• 대략적으로: 4글자(영어) ≈ 1 토큰

쉽게 말하면, Claude에게 파일을 읽히거나, 질문을 하거나, 답변을 받을 때마다 토큰이 소모됩니다. 컨텍스트(대화 맥락)가 길어질수록 더 많은 토큰이 사용됩니다.

비용이 많이 드는 상황

1. 긴 파일을 반복해서 읽을 때

Claude가 같은 파일을 여러 번 읽으면 그때마다 토큰이 소모됩니다. 10,000줄짜리 로그 파일을 통째로 읽히면 한 번에 수만 개의 토큰이 사용됩니다.

2. 컨텍스트를 오래 유지할 때

대화가 길어질수록 이전 내용을 모두 컨텍스트로 포함시켜야 합니다. 관련 없는 작업을 계속 같은 세션에서 진행하면 불필요한 정보가 쌓여 비용이 늘어납니다.

3. 고성능 모델을 사용할 때

Opus 모델은 Sonnet보다 강력하지만 토큰당 비용도 높습니다. 간단한 작업에 Opus를 쓰는 것은 비효율적입니다.

4. 자동화(CI/CD)에서 무분별하게 실행할 때

GitHub Actions 등으로 자동화하면 사람의 개입 없이 대량의 토큰이 소모될 수 있습니다.

절약 팁 5가지

팁 1: /compact로 컨텍스트 정리하기

대화가 길어졌을 때 /compact 명령어를 실행하면 이전 내용을 요약해서 컨텍스트 크기를 줄여줍니다.

/compact 코드 변경 사항과 테스트 결과 중심으로 요약해줘

이렇게 하면 중요한 정보는 유지하면서 불필요한 대화 내용은 압축됩니다.

CLAUDE.md에 압축 방식을 미리 지정할 수도 있습니다:

# Compact instructions

When you are using compact, please focus on test output and code changes

팁: /clear를 쓰면 컨텍스트를 완전히 초기화할 수 있습니다. 전혀 다른 작업을 시작할 때 유용합니다.

팁 2: 불필요한 파일 참조 피하기

막연한 요청은 Claude가 불필요하게 많은 파일을 읽게 만듭니다.

구체적인 요청일수록 Claude가 필요한 파일만 읽어서 토큰 소모가 줄어듭니다.

팁 3: Haiku 모델 활용하기

모든 작업에 고성능 모델을 쓸 필요는 없습니다.

모델 전환은 세션 중에도 가능합니다:

/model haiku

또는 시작할 때 지정:

claude --model haiku

opusplan 모드: 계획 단계에서는 Opus, 실행 단계에서는 Sonnet으로 자동 전환되는 하이브리드 모드입니다.

/model opusplan

팁 4: Fast Mode 이해하고 활용하기

/fast 명령어로 Fast Mode를 켜면 Opus 4.6이 약 2.5배 빠르게 응답합니다.

/fast

단, Fast Mode는 토큰당 비용이 더 높습니다. 속도가 중요한 순간(빠른 반복 작업, 실시간 디버깅)에만 사용하고, 장시간 자율 작업에는 끄는 것이 좋습니다.

참고: Fast Mode는 구독 플랜의 기본 사용량에 포함되지 않고 추가 사용(extra usage)으로 청구됩니다.

팁 5: /cost로 주기적으로 확인하기

API 사용자라면 현재 세션의 토큰 사용량을 확인할 수 있습니다:

/cost

출력 예시:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

구독자는 /stats로 사용 패턴을 확인할 수 있습니다.

상태 표시줄(status line)을 설정하면 컨텍스트 사용량을 실시간으로 볼 수도 있습니다.

팁 6: CLAUDE.md 다이어트하기

CLAUDE.md는 Claude가 매 응답마다 읽는 파일입니다. 길면 길수록 매번 더 많은 토큰을 소모합니다.

실제 효과: 과도하게 작성된 CLAUDE.md(~19,000 tokens)를 핵심만 남긴 버전(~9,000 tokens)으로 정리하면 같은 작업에 드는 비용이 절반 가까이 줄어듭니다.

다이어트 기준

삭제해도 되는 것:
- 긴 배경 설명 ("이 프로젝트는 2023년부터...")
- 반복되는 당연한 내용 ("항상 최선을 다해주세요")
- 예시 코드 블록 여러 개 (하나만 남기거나 삭제)
- 모호한 규칙 ("좋은 코드를 작성하세요")

반드시 남길 것:
- 금지 사항 (절대 하지 말아야 할 것)
- 프로젝트 기술 스택 (1~3줄 요약)
- 자주 참조하는 파일 경로
- 언어/포맷 규칙 (구체적인 것만)

대부분의 CLAUDE.md는 정리하면 50% 이상 줄일 수 있습니다.

팁 7: .claudeignore로 불필요한 파일 제외

node_modules, .git, 빌드 결과물 등 Claude가 읽을 필요 없는 파일을 명시적으로 제외하면, Claude가 실수로 대용량 파일을 읽는 것을 방지합니다.

.gitignore와 같은 문법으로 프로젝트 루트에 .claudeignore 파일을 만드세요:

# .claudeignore
node_modules/
.next/
dist/
build/
coverage/
*.log
*.lock
.git/

언제 특히 효과적인가

• 모노레포처럼 파일 수가 많은 프로젝트
• "이 프로젝트를 전체적으로 분석해줘" 요청을 자주 할 때
• GitHub Actions 등으로 Claude를 반복 실행할 때

모델별 비용 비교 (간략)

정확한 토큰 가격은 Anthropic 가격 페이지를 참고하세요.

Claude.ai Max 플랜의 장점

Claude.ai Pro 또는 Max 구독자는 API 종량제 비용 없이 Claude Code를 사용할 수 있습니다.

• 월정액 안에 Claude Code 사용 포함
• 추가 API 키 불필요
• 비용 걱정 없이 다양한 실험 가능
• Max 플랜의 경우 더 높은 사용량 한도

단, Fast Mode와 1M 컨텍스트 초과 분은 추가 사용(extra usage)으로 청구될 수 있습니다.

팀 비용 관리

API를 팀 단위로 사용하는 경우:

• Workspace 지출 한도 설정: Anthropic Console에서 팀 전체 지출 한도를 설정할 수 있습니다.
• 사용량 대시보드: Console에서 팀원별 비용과 사용량을 확인할 수 있습니다.
• 에이전트 팀 주의: Agent Teams(여러 Claude 인스턴스 동시 실행) 기능은 표준 세션보다 약 7배 많은 토큰을 소모합니다.

💡 끼리끼리 플러그인은 작업 특성에 맞게 에이전트 팀을 자동 구성하고, 품앗이는 Codex가 설치되어 있으면 저렴한 모델로 병렬 개발하고, 없으면 Claude만으로도 동작합니다.

정리: 비용 절약 체크리스트

✅ 작업이 끝나면 /clear로 컨텍스트 초기화
✅ 관련 없는 작업은 새 세션에서 시작
✅ 구체적인 파일명과 함수명을 명시
✅ 간단한 작업은 Haiku 모델 사용
✅ Fast Mode는 필요할 때만 켜기
✅ /cost 또는 /stats로 주기적으로 확인
✅ CLAUDE.md에 compact 지침 설정
✅ CLAUDE.md는 핵심 규칙만 남기고 주기적으로 다이어트
✅ .claudeignore로 node_modules, 빌드 결과물 제외

20. Headless 모드 & GitHub Actions 자동화

Claude Code를 사람 없이 자동으로 실행하는 방법을 배웁니다.

📌 이 섹션은 두 부분으로 나뉩니다

• Headless 모드 (기본 사용법): 비개발자도 활용할 수 있는 자동화 — 뉴스 요약, 주간 보고서, 파일 일괄 처리 등
• GitHub Actions 연동 (개발자 심화): 소프트웨어 개발팀 전용 CI/CD 자동화

Headless 모드란?

보통 Claude Code는 터미널에서 대화형으로 사용합니다. 사람이 직접 질문하고, Claude가 답하고, 다시 사람이 피드백을 주는 방식이죠.

Headless 모드는 사람 없이 Claude Code를 자동으로 실행하는 방식입니다. 스크립트나 CI/CD 파이프라인에서 Claude Code를 프로그램처럼 호출할 수 있습니다.

Headless = 사람 없이 자동 실행

이전에는 "headless mode"라고 불렸지만, 공식적으로는 Agent SDK CLI라고도 합니다. -p 플래그와 모든 CLI 옵션은 동일하게 작동합니다.

언제 사용하나요?

기본 사용법

-p (또는 --print) 플래그를 붙이면 비대화형(non-interactive) 모드로 실행됩니다.

가장 간단한 형태

claude -p "이 프로젝트가 무엇을 하는지 설명해줘"

도구 권한 허용하기

Claude가 파일을 읽고 저장할 수 있도록 도구를 허용합니다:

claude -p "~/Downloads의 PDF를 모두 읽어서 요약집.md로 정리해줘" --allowedTools "Read,Write,Bash"

JSON 출력 받기

스크립트에서 결과를 파싱하기 쉽도록 JSON 형식으로 출력할 수 있습니다:

claude -p "이 프로젝트를 요약해줘" --output-format json

출력 형식 옵션:

• text (기본값): 일반 텍스트
• json: JSON 구조체로 결과 반환 (세션 ID, 메타데이터 포함)
• stream-json: 실시간 스트리밍 JSON

실용적인 예시: 비개발자 자동화 3가지

일일 뉴스·업계 동향 요약:

claude -p "inputs/links.txt를 읽고 오늘의 업계 뉴스 요약을 daily/brief_오늘날짜.md로 저장해줘" \
  --allowedTools "Read,Write"

주간 액션아이템 취합:

claude -p "meetings/ 폴더의 지난 7일 회의록을 읽고 미완료 액션아이템만 표로 정리해서 weekly/this-week.md로 저장해줘" \
  --allowedTools "Read,Write"

콘텐츠 캘린더 초안 생성:

claude -p "ideas/ 폴더를 읽고 다음 주 평일 5일치 콘텐츠 캘린더를 만들어 drafts/next-week.md로 저장해줘" \
  --allowedTools "Read,Write"

claude -p "스테이징된 변경 사항을 검토하고 적절한 커밋 메시지로 커밋해줘" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

대화 이어가기

# 첫 번째 요청
claude -p "이 폴더의 문서들을 분석해줘"

# 이전 대화 이어서
claude -p "그 중에서 핵심 결론 부분만 따로 모아줘" --continue

/install-github-app

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # @claude 멘션에 자동으로 응답

@claude 이 PR의 보안 취약점을 검토해줘
@claude 이 함수에 엣지 케이스가 있는지 확인해줘
@claude 이 이슈를 기반으로 기능을 구현해줘

name: 코드 리뷰
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

name: 일일 리포트
on:
  schedule:
    - cron: "0 9 * * *"  # 매일 오전 9시

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "어제의 커밋과 열린 이슈를 요약해줘"
          claude_args: "--model sonnet"

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}  # 필수
    prompt: "작업 지시사항"        # 선택 (없으면 @claude 멘션에 반응)
    claude_args: "--max-turns 10"  # 선택 (추가 CLI 인자)

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    - claude -p "${AI_FLOW_INPUT:-'변경 사항을 검토하고 개선사항을 제안해줘'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write"

⚠️ 비용 주의사항

자동화는 토큰 소모가 매우 큽니다.

• CI/CD 파이프라인은 사람의 감독 없이 실행되므로 비용이 예상보다 빠르게 쌓일 수 있습니다.
• --max-turns 옵션으로 최대 반복 횟수를 제한하세요.
• 워크플로우에 타임아웃을 설정하세요.
• 불필요한 트리거를 줄이세요.

claude_args: "--max-turns 5 --model sonnet"

API 비용 외에 GitHub Actions 실행 시간 비용도 발생합니다 (GitHub Actions 무료 한도를 초과할 경우).

보안 주의사항

• API 키를 코드에 직접 넣지 마세요. 항상 GitHub Secrets를 사용하세요.

# 올바른 방법
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# 절대 하지 말 것
anthropic_api_key: "sk-ant-api03-..."

• Claude의 제안을 머지하기 전에 항상 검토하세요.
• 액션 권한은 필요한 것만 허용하세요.

입문자에게

이 기능은 지금 당장 필요하지 않습니다.

Headless 모드와 GitHub Actions 연동은 Claude Code를 어느 정도 익힌 후에 도입하는 것이 좋습니다. 기본 사용법, CLAUDE.md 설정, 그리고 MCP 연동을 먼저 익히고 나서 자동화를 고려하세요.

지금은 "이런 것도 가능하구나"라고 알아두는 것으로 충분합니다.

핵심 정리

Headless 모드: claude -p "작업내용" --output-format json
GitHub Actions: anthropics/claude-code-action@v1
트리거: @claude 멘션 또는 자동 프롬프트
비용 제어: --max-turns, 타임아웃, 모델 선택
보안: API 키는 반드시 Secrets 사용

21. 다음 단계 & 리소스

CC101을 마친 당신에게. 이제 진짜 시작입니다.

여기까지 오셨군요

Claude Code의 기초부터 고급 자동화까지 전 과정을 완주하셨습니다. 쉽지 않은 여정이었지만, 이제 당신은 AI 기반 자동화 도구를 실제 업무에 활용할 수 있는 기반을 갖췄습니다.

잠깐 돌아보면, 이런 것들을 배웠습니다:

• Claude Code가 무엇이고 어떻게 작동하는지
• 설치와 인증 설정
• CLAUDE.md로 프로젝트 맞춤 설정
• 기본 명령어와 워크플로우
• MCP로 외부 도구 연결
• Hooks와 Skills로 자동화
• 플러그인 생태계 탐색
• 비용 관리와 최적화
• Headless 모드와 CI/CD 연동

이 지식은 단순히 도구 하나를 배운 것이 아닙니다. AI와 협업하는 새로운 업무 방식을 익힌 것입니다.

다음 학습 경로

입문 완료 (지금 여기)

✅ Claude Code 설치 & 인증
✅ CLAUDE.md 작성
✅ 기본 명령어 (/help, /cost, /compact, /model)
✅ 파일 읽기, 내용 수정, 문서 생성
✅ 플러그인 기본 사용

중급: 실전 응용

CC101에서 배운 기초를 조합해 실제 업무에 적용해보세요.

나만의 워크플로우 자동화

• CLAUDE.md + Hooks + Skills를 조합해 반복 업무를 원커맨드로 줄이기
• 예: 매주 보고서 자동 생성, 코드 리뷰 자동화, 회의록 정리 파이프라인

플러그인 활용 극대화

• show-me-the-prd로 기획 → 끼리끼리로 리서치 팀 구성 → Claude Code로 구현 — 아이디어에서 프로토타입까지 하루 만에
• deep-research로 시장 조사 후 docs-guide로 기술 검증 — 의사결정에 AI 활용
• 바선생의 피드백을 반영해 프롬프트 품질 점진적 개선

멀티 세션 & 병렬 작업

• 여러 터미널에서 Claude Code를 동시에 실행해 작업 분담
• 품앗이로 작업 분담 병렬 개발 체험 (Codex 없어도 Claude만으로 동작)

고급: CC101 너머의 세계

이 가이드에서 다루지 않은 심화 주제들입니다.

Agent SDK로 나만의 AI 앱 만들기

• Anthropic의 Agent SDK를 사용하면 Claude를 엔진으로 한 독립 AI 애플리케이션을 개발할 수 있습니다
• Python/TypeScript로 커스텀 에이전트 구축 — Claude Code 없이도 동작하는 자동화 시스템

Model Context Protocol (MCP) 서버 직접 만들기

• CC101에서는 MCP 서버를 "사용"하는 법을 배웠지만, 직접 MCP 서버를 "만들"수도 있습니다
• 회사 내부 API, 사내 DB, 사내 위키를 MCP 서버로 감싸면 Claude Code가 바로 접근 가능
• MCP 공식 스펙

Claude Code 플러그인 개발

• 자신만의 플러그인을 만들어 커뮤니티에 공유하기
• Skills, Hooks, Agents, MCP 서버를 하나의 패키지로 묶는 구조
• 스킬러들의 수다 플러그인으로 빠르게 프로토타이핑 가능

팀 단위 도입 & 거버넌스

• 팀 전체가 Claude Code를 사용할 때의 권한 관리, 비용 분배, 보안 정책
• Enterprise 플랜의 관리자 기능 (Admin Controls, Audit Logs)
• 사내 코딩 표준을 CLAUDE.md로 강제하는 방법

프로덕션 자동화 파이프라인

• GitHub Actions + Headless Claude Code로 PR 자동 리뷰, 자동 테스트 생성
• 야간 배치 작업: 매일 새벽에 데이터 처리, 보고서 생성, 코드 품질 검사
• 모니터링 + 알림 연동 (Slack, Discord)

공식 리소스

공식 문서

CC101 & gptaku_plugins 커뮤니티

이 가이드가 도움이 됐다면 Star 를 눌러주세요! 업데이트와 발전에 큰 힘이 됩니다.

Claude Code를 잘 쓰는 법 & 피해야 할 패턴

도구를 배웠다면 이제 언제, 어떻게 써야 하는지가 중요합니다.

잘 맞는 작업 (마음껏 활용하세요)

주의가 필요한 작업 (검토를 철저히 하세요)

항상 지키는 5가지 원칙

1. 작업 전 git commit → 언제든 롤백 가능한 상태 유지
2. 범위를 명확히 → "이 파일의 이 함수만" 처럼 구체적으로
3. 생성된 코드는 직접 읽어보기 → 이해 못 한 코드는 사용하지 않기
4. 보안/결제 코드는 반드시 별도 검토
5. 큰 작업은 Plan Mode로 계획 먼저 확인 (Shift+Tab)

첫 실전 프로젝트 추천

CC101을 마쳤다면 바로 실전에 뛰어들어 보세요. 코딩 여부와 관계없이 바로 시작할 수 있는 프로젝트들입니다.

1. 회의록 자동 정리 워크플로우

매주 반복되는 회의 정리 작업을 Claude Code에게 맡겨보세요.

"~/Downloads/meeting-250225.mp3 파일 있어.
 회의 내용 변환하고, 요약 + 담당자별 액션아이템 정리해서
 meeting-250225.md 로 저장해줘"

녹음 파일을 텍스트로 변환하는 도구 설치부터 정리까지 전부 알아서 합니다.

2. 내 업무용 Skills 만들기

매주 반복하는 작업을 /커맨드 하나로 줄여보세요.

"매주 월요일마다 지난 주 작업 내용 정리하는 Skills 만들어줘.
 GitHub 커밋 내역이랑 메모 파일 기반으로 주간 보고서 초안 생성하는 방식으로"

3. 경쟁사 분석 보고서

관심 있는 분야의 경쟁사를 분석해보세요.

"경쟁사 A, B, C 웹사이트 분석해서
 주요 기능, 가격, 타깃 고객, 차별화 포인트 비교표 만들어줘.
 competitor-analysis.md 로 저장해줘"

4. 포트폴리오 사이트 만들기 🖥️ 개발자

"HTML/CSS/JS로 포트폴리오 사이트를 만들어줘.
섹션: 소개, 기술 스택, 프로젝트, 연락처.
미니멀하고 다크 테마로 만들어줘."

5. 기존 코드 리팩토링 🖥️ 개발자

"이 파일의 코드를 리뷰하고 개선해줘.
가독성, 성능, 에러 처리에 집중해줘.
@src/utils/dataProcessor.js"

막히면 어떻게 하나요?

1단계: 공식 문서 확인

대부분의 답은 공식 문서에 있습니다.

https://docs.anthropic.com/en/docs/claude-code

Claude Code 안에서도 도움을 받을 수 있습니다:

/help

2단계: Claude Code에게 직접 물어보기

Claude Code 자체가 가장 강력한 도움말입니다.

"Claude Code에서 MCP 서버를 추가하는 방법을 알려줘"
"이 에러 메시지의 의미가 뭔지 설명해줘: [에러 내용]"

3단계: 커뮤니티

• GitHub Issues: github.com/anthropics/claude-code/issues
• CC101: github.com/fivetaku/cc101

4단계: Anthropic 지원

계정이나 결제 관련 문제는 Anthropic 콘솔에서 지원을 요청하세요.

마지막으로

Claude Code는 빠르게 발전하는 도구입니다. 오늘 배운 것이 몇 달 후에는 달라져 있을 수 있습니다. 중요한 것은 기본 원리를 이해하는 것입니다.

AI와 함께하는 업무는 단순히 작업을 빠르게 처리하는 것이 아닙니다. AI의 강점(넓은 지식, 반복 작업, 패턴 인식)과 사람의 강점(판단력, 창의성, 도메인 지식)을 결합하는 새로운 협업 방식입니다.

CC101을 마친 여러분은 그 첫걸음을 내딛었습니다. 앞으로의 여정이 기대됩니다.

빠른 참조 카드

공식 문서:      https://docs.anthropic.com/en/docs/claude-code
GitHub:         https://github.com/anthropics/claude-code
플러그인:       https://github.com/anthropics/claude-plugins-official
gptaku_plugins: https://github.com/fivetaku/gptaku_plugins
CC101:          https://github.com/fivetaku/cc101
콘솔:           https://platform.claude.com

다음 목표:
  바이브코더 → gptaku_plugins 설치, show-me-the-prd로 기획, 바선생으로 성장
  중급 → MCP 설정 (Notion/Slack/GitHub), Hooks 커스터마이징, 플러그인 탐색
  고급 → 나만의 Skills 제작 (또는 스킬러들의 수다), 끼리끼리로 Agent Teams
  (개발자) → CI/CD 완전 자동화, 품앗이로 병렬 개발