클로드 코드 치트시트: 개발자 완전 초보 가이드

Anthropic의 강력한 AI 기반 코딩 지원 도구인 Claude Code에 뛰어든다면, 명확한 참고 자료를 갖는 것이 필수적입니다. 이 Claude Code 치트 시트는 설정, 워크플로, 구성 및 고급 팁을 다루는 실용적이고 초보자 친화적인 가이드를 원하는 개발자를 위한 것입니다. 이 치트 시트가 끝날 때쯤에는 로컬 환경이나 CI/CD 프로세스의 일부로 Claude Code를 사용하는 데 더 자신감을 느낄 것입니다.

Claude Code란 무엇인가요?

Claude Code는 Anthropic의 CLI 기반 AI 코딩 도구입니다. 개발자는 Claude의 고급 모델을 사용하여 코드를 생성, 리팩토링, 테스트 및 문서화할 수 있습니다. 단순한 채팅 인터페이스보다는 AI IDE처럼 작동합니다. 즉, 저장소 구조를 이해하고, 구성 파일에 정의된 가이드라인을 적용하며, bash 명령을 실행하고, Git 워크플로와 통합됩니다.

Claude Code 설치:

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

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

# NPM:
npm install -g @anthropic-ai/claude-code

# Homebrew:
brew install --cask claude-code

Claude Code 사용 시작:

cd your-project
claude

Claude Code의 주요 구성 요소 — 치트 시트

Claude Code를 시작할 때 알아야 할 필수 구성 요소 및 기능은 다음과 같습니다.

1. CLAUDE.md — 에이전트 매니페스트

• `CLAUDE.md` 파일은 에이전트의 "헌법"입니다. 이 파일은 Claude가 저장소에서 어떻게 작동하는지 정의합니다.
• 승인된 도구, 일반적인 워크플로 및 제약 조건을 문서화하는 데 사용하세요.
• 모범 사례: 짧게 유지하고, 주요 가이드라인에 집중하며, 매우 큰 문서를 포함하지 마세요.

# MyProject CLAUDE.md

## Project Overview  
This is a Node.js + Express REST API for a task management application.  

## Technology Stack  
- Backend: Node.js (ES6), Express  
- Database: PostgreSQL  
- Testing: Jest  
- Linting & Style: ESLint, Prettier

## Development Commands  
- `npm install` — Install dependencies  
- `npm run dev` — Start development server  
- `npm run test` — Run all tests  
- `npm run lint` — Run linter  

## Coding Standards  
- Use 2-space indentation.  
- Always use `async / await` instead of `.then()` chains.  
- Functions must have JSDoc comments.  
- Prefer composition over inheritance.

## Git Workflow  
- Feature branches must follow this pattern: `feature/FOO`  
- Use `git rebase` instead of `merge` for updating branches.  
- When committing: write descriptive commit messages that follow the Conventional Commits format.

## File Structure Guidance  
- `src/` — Your main application code  
- `tests/` — Test files  
- `scripts/` — Utility or setup scripts  
- `migrations/` — Database migrations  

## Known Issues / Workarounds  
- `db.connect()` sometimes times out; in that case, retry twice.  
- For large JSON payloads, use streaming to avoid memory issues.

## Memory / Style Preferences  
- Always ask for clarification if the request is ambiguous.  
- Do not generate new `.md` files unless explicitly instructed.  
- Include a `co-authored-by Claude` line in generated commits.

2. 컨텍스트 관리

a. 현재 Claude 세션의 토큰 사용량을 확인하려면 **`/context`**를 사용하세요.

b. 컨텍스트를 다시 시작하거나 축소하는 명령:

• `/clear` + `/catchup`: 모든 대화를 지우고 커밋 또는 브랜치에서 파일을 다시 로드합니다.
• “문서화 및 지우기” 흐름: Claude가 계획을 Markdown 파일에 덤프하고, 메모리를 지운 다음, 해당 파일에서 다시 로드하도록 합니다.

3. 슬래시 명령어

• 슬래시 명령어는 미리 정의된 프롬프트에 대한 단축키입니다.
• 예시:

• 슬래시 명령어를 최소한으로 유지하고, 특정 작업에 집중하세요. 모든 작업에 의존하지 마세요.

4. 계획 모드

• 복잡한 작업을 시작할 때 계획 모드를 사용하세요. Claude는 코드를 작성하기 전에 계획을 개괄적으로 설명합니다.
• 그런 다음 Claude에게 실행을 요청하기 전에 해당 계획을 검토, 편집 또는 승인할 수 있습니다.
• 대규모 기능 작업, 리팩토링 또는 아키텍처 변경에 이상적입니다.

5. 서브 에이전트 및 작업 위임

• Claude Code는 서브 에이전트를 지원하여, 주 에이전트의 "클론"에 작업의 일부를 위임할 수 있게 합니다.
• Shrivu는 "마스터-클론" 아키텍처를 선호합니다. 즉, 주 에이전트가 엄격한 전문 서브 에이전트를 사용하는 대신 `Task(...)`를 통해 클론을 생성합니다.
• 이는 컨텍스트의 분열을 피하면서 유연성을 유지합니다.
• 슬래시 명령어 `/agents`를 사용하여 Claude Code의 서브 에이전트에 액세스합니다.

6. Claude 스킬 vs. MCP — 차이점은 무엇인가요?

a. Claude 스킬은 Claude에게 특정 작업을 *수행하는 방법*을 가르치는 미리 구축된 "모듈"입니다. 이들은 Markdown 또는 코드로 작성되며, 필요할 때만 로드됩니다. 스킬을 사용하여 보고서 서식 지정, 데이터 요약 또는 팀 스타일 적용과 같은 워크플로를 정의할 수 있습니다.

b. 반면에 모델 컨텍스트 프로토콜 (MCP)은 프로토콜로서 Claude를 외부 데이터 및 도구(예: 데이터베이스, 코드베이스 또는 비즈니스 시스템)에 연결하기 위한 것입니다. 이는 Claude가 맞춤형 도구별 통합 없이 외부 리소스에 액세스하고 작업을 수행할 수 있도록 하는 "범용 어댑터"와 같습니다.

c. 주요 차이점:

1. 목적:

• 스킬은 절차적 지식을 인코딩합니다.
• MCP는 도구 및 데이터 연결을 처리합니다.

2. 토큰 효율성:

• 스킬은 필요할 때만 로드되며, 상대적으로 적은 토큰을 사용합니다.
• 많은 MCP 도구가 활성화된 경우 MCP 도구 정의가 상당한 토큰 공간을 차지할 수 있습니다.

d. 사용 사례:

• **스킬**을 사용하여 Claude에게 도메인별 워크플로를 가르칩니다 (예: "상태 보고서를 작성할 때는 항상 X, Y, Z를 포함하십시오").
• Claude가 데이터를 읽거나 쓰거나, API를 호출하거나, Git 또는 데이터베이스와 같은 외부 시스템에 액세스해야 할 때 **MCP**를 사용합니다.

실제로 이 둘은 함께 사용할 때 가장 효과적입니다. MCP는 Claude에게 데이터에 대한 액세스 권한을 부여하고, 스킬은 Claude에게 해당 데이터를 구조화되고 반복 가능한 방식으로 사용하는 방법을 가르칩니다.

6. 훅 (Hooks)

a. 훅은 규칙을 자동으로 적용하는 방법입니다.

b. 두 가지 일반적인 유형:

• 제출 시 차단: 예를 들어, `PreToolUse` 훅은 테스트가 통과되지 않으면 `git commit`을 차단할 수 있습니다.
• 힌트 훅: 비차단형입니다. 실행을 중단하지 않고 가이드라인 또는 제안을 제공합니다.

c. "작성 시 차단" 훅은 피하세요. Claude가 계획을 완료한 다음 유효성을 검사하는 것이 더 안정적입니다.

# Example Hook in .claude/settings.toml

[[hooks]]
# The event that triggers the hook.
event = "PostToolUse" 

# (Optional) Conditions for the hook to run.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# The shell command to execute.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Whether to run the command in the background.
run_in_background = false 

7. CLI SDK

• Claude Code SDK를 사용하면 Claude와의 상호 작용을 스크립팅할 수 있습니다. 이는 배치 처리, 내부 도구 구축 또는 에이전트 프로토타이핑에 유용합니다.
• 이를 사용하여 병렬 리팩토링을 실행하고, 템플릿에서 코드를 생성하거나, CI/CD 워크플로 내에서 경량 에이전트로 사용할 수 있습니다.

설치:

# Typescript:
npm install @anthropic-ai/claude-agent-sdk

# Python:
pip install claude-agent-sdk

8. Claude Code GitHub Actions (GHA)

• Claude Code를 GitHub Actions에 직접 통합할 수 있습니다.
• 이를 사용하여 풀 리퀘스트를 자동 생성하고, 코드 표준을 적용하거나, CI 파이프라인의 일부로 CLAUDE.md 기반 검사를 실행할 수 있습니다.
• 로그가 저장되므로 에이전트 동작을 감사하고 시간이 지남에 따라 CLAUDE.md 파일을 개선할 수 있습니다.

9. 설정 및 구성

a. `settings.json`에서 다음을 구성할 수 있습니다.

• 프록시 (`HTTPS_PROXY`) — CLI 트래픽 디버깅에 유용합니다.
• 타임아웃 (`MCP_TOOL_TIMEOUT`, `BASH_MAX_TIMEOUT_MS`) — 긴 작업을 실행하는 경우 이 값을 늘리세요.
• API 키 (`ANTHROPIC_API_KEY`) — Anthropic에서 받은 키 또는 도우미 스크립트를 사용하세요.
• 권한 — Claude Code가 실행할 수 있는 시스템 도구를 제어합니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

고급 기능 및 생산성 팁

1. 모델 전환: 작업에 따라 Claude 4 Sonnet 또는 Opus를 선택하세요. Sonnet은 빠르고 비용 효율적이며, Opus는 복잡한 다중 파일 변경에 더 능숙합니다.
2. 사고 모드 (치트): 일부 사용자는 Claude의 추론 모드를 `think`, `think hard`, `think harder`, `ultrathink`로 설정하여 추론 깊이를 조절합니다.
3. 사용자 지정 명령어: `.claude/commands`에 동적 플레이스홀더 (`$argument`)를 사용하여 재사용 가능한 슬래시 명령어를 정의하세요. 테스트, 빌드 또는 검토에 유용합니다.
4. 세션 기록: `claude --resume` 또는 `claude --continue`를 사용하여 이전 세션을 다시 시작하세요. Claude는 모든 세션 기록을 로컬에 저장합니다.
5. 피드백 루프: GitHub Action 로그 또는 과거 세션 데이터를 통해 에이전트 동작을 검토하고 `CLAUDE.md`를 업데이트하여 오해를 수정하거나 더 나은 가이드라인을 적용하세요.

자주 묻는 질문 (FAQ)

Q1. `CLAUDE.md`의 목적은 무엇인가요?
답변: `CLAUDE.md`는 에이전트의 선언문 역할을 합니다. 이는 Claude Code가 따라야 할 규칙, 도구 및 규칙을 정의합니다. 저장소 전체에서 동작을 표준화하는 데 도움이 됩니다.

Q2. 서브 에이전트를 사용해야 하나요 아니면 간단한 작업만 사용해야 하나요?
답변: 엄격한 모듈식 워크플로를 원한다면 서브 에이전트를 사용하세요. 하지만 많은 사람들은 마스터-클론 패턴 (`Task(...)` 사용)이 더 유연하다고 생각합니다. 서브 작업을 위임하면서도 컨텍스트를 유지할 수 있습니다.

Q3. 모든 것을 잃지 않고 Claude 세션을 다시 시작하려면 어떻게 해야 하나요?
답변: `/clear`를 사용하여 채팅을 초기화한 다음, `/catchup`을 사용하여 Git 브랜치에서 파일을 로드하면 Claude가 다시 전체 컨텍스트를 갖게 됩니다.

Q4. 훅(Hooks)은 무엇이며, 왜 필요한가요?
답변: 훅은 Claude가 작업을 커밋할 때 규칙이나 검사를 적용합니다. 예를 들어, 제출 시 차단 훅은 Git 커밋이 허용되기 전에 테스트가 통과되었는지 확인할 수 있습니다.

Q5. Claude Code를 CI/CD에 통합하려면 어떻게 해야 하나요?
답변: Claude Code GitHub Action을 사용하여 자동화된 파이프라인에서 작업을 실행하고, 코드를 검증하고, 풀 리퀘스트를 생성하거나, `CLAUDE.md` 가이드라인을 적용하세요.

결론

이 Claude Code 치트 시트는 Claude Code를 효과적으로 사용하는 방법에 대한 실용적이고 구조화된 개요를 제공합니다. 잘 만들어진 `CLAUDE.md` 파일을 작성하는 것부터 슬래시 명령어, 서브 에이전트, 훅, CI 통합을 활용하는 것까지, 이러한 패턴은 Claude Code를 신뢰할 수 있는 AI 기반 개발 파트너로 사용하는 견고한 기반을 형성합니다.

이러한 기능을 숙달함으로써 신입 개발자는 빠르게 온보딩할 수 있으며, 숙련된 엔지니어는 워크플로를 간소화하고, 가이드라인을 적용하며, Claude가 지원하는 생산성을 확장할 수 있습니다. Claude Code는 단순한 코드 생성 도구 그 이상입니다. 이는 팀의 요구에 맞춰 조정되는 프로그래밍 가능하고 에이전트 기반 시스템입니다.