Claude Code 사용법: 단계별 튜토리얼

Claude Code 사용법을 단계별로 마스터하세요. 안전한 설치부터 샌드박스 편집, 워크플로 자동화까지—코드베이스 통제권을 유지하며 AI를 실무에 도입하는 법을 알아보세요.

Author

DeepStation Team

Published

2026년 3월 1일

Explore this topic with AI

Open ChatGPT

소개: Claude Code란 무엇인가?

AI 코딩 어시스턴트를 일상적인 터미널 워크플로에 도입하려고 해본 적이 있다면, 아마 같은 벽에 부딪혔을 것입니다. 무엇을 해야 하는지는 알지만, 안전하게 설정하고, 끊임없는 중단을 피하면서, 변경되는 내용을 신뢰하는 방법을 모르겠다는 문제 말입니다.

이 가이드에서는 실제 개발 작업을 위한 커맨드 라인 도구로서 Claude Code를 실용적이고 반복 가능한 방식으로 사용하는 방법을 배우게 됩니다. 안전한 설치부터 시작하여 읽기 전용 계획 수립으로 넘어간 다음, 샌드박스 편집과 테스트 실행으로 단계를 높여갑니다. 이후에는 재사용 가능한 Skills를 구축하고, MCP로 외부 도구를 연결하며, Hooks로 가드레일을 자동화하는 방법까지 다룹니다—코드베이스에 대한 통제권을 잃지 않으면서 말입니다.

이 워크스루는 터미널 사용에 익숙하고, 실제 코드베이스에서 안전하게 사용할 수 있는 AI 코딩 워크플로를 원하는 개발자(개인 또는 팀)를 위한 것입니다. 조직에서 이를 설정하는 경우, 자격 증명이 어디에 저장되는지 아는 것도 도움이 됩니다. 예를 들어 macOS에서는 암호화된 macOS Keychain이 해당됩니다.

첫 번째 세션이 원활하게 진행되도록 접근 설정부터 시작하겠습니다.

접근 권한 확보, Claude Code 설치 및 로그인

Claude Code에 실제 개발 작업을 위임하기 전에, 깔끔한 설치와 사용 계획에 맞는 인증 방법이 필요합니다.

다음 단계를 따라 Claude Code를 설치하고 인증이 가능한지 확인하세요:

node -v를 실행하여 v18 이상이 표시되는지 확인함으로써 Node.js 18+가 설치되어 있는지 확인합니다.
Claude Code를 전역으로 설치합니다: npm install -g @anthropic-ai/claude-code.
claude를 실행하여 인터랙티브 세션을 시작한 다음, /login을 입력하고 Claude.ai(권장) 또는 Console 계정의 브라우저 기반 인증 과정을 완료하여 로그인합니다.
스크립트나 비대화형 사용을 위해 키 기반 인증을 선호하는 경우, 셸 환경에 ANTHROPIC_API_KEY를 설정합니다. 조직에서 클라우드 제공업체를 사용하는 경우, 잘못된 자격 증명 유형을 설정하지 않도록 Bedrock/Vertex를 통해 인증해야 하는지 확인하세요.

주의할 점:

WSL을 사용 중이고 OS 감지 문제나 Windows npm/Node 불일치로 설치가 실패하는 경우, WSL 수정 방법(문서화된 --force --no-os-check 설치 옵션 포함)을 사용하고, 문서에서 명시적으로 경고하는 sudo 사용은 피하세요.
Free/Pro/Max 계정으로 로그인하는 경우, 데이터 제어 설정을 검토하세요: 2025년 8월 28일 이후로 일반 사용자는 코딩 세션이 향후 Claude 모델 개선에 사용될 수 있는지 여부를 선택할 수 있습니다.

이 단계가 끝나면, claude가 오류 없이 시작되어야 하며, /login 후 짧은 프롬프트를 보내고 응답을 받을 수 있어야 합니다.

핵심 요약:

Claude Code를 설치하고 환경에 맞는 로그인 방법을 설정했습니다.
실제 워크플로를 시도하기 전에 자격 증명 경로(대화형 /login vs API 키 vs 관리형 제공업체)를 올바르게 설정해야 합니다.
WSL/Node 경로 문제에 주의하고, 나중에 당황하지 않도록 계정의 데이터 공유 설정을 확인해야 합니다.

프로젝트 열기 및 안전하게 계획하기: 읽기 전용 모드의 AI 코딩 어시스턴트

Claude Code가 파일을 변경하거나 명령을 실행하기 전에, 먼저 코드베이스를 이해하고 실행을 방지하는 모드에서 구체적인 접근 방식을 제안하도록 해야 합니다.

다음 단계를 따라 리포지토리를 열고 안전한 계획 루프를 실행하세요:

cd /path/to/your-repo를 실행하여 프로젝트 루트로 이동합니다(package.json, pyproject.toml 또는 go.mod가 포함된 폴더를 선택하세요).
해당 디렉터리에서 claude를 실행하여 Claude Code를 시작한 다음, 이 리포지토리에 연결된 인터랙티브 프롬프트에 진입했는지 확인합니다.
/plan을 입력하여 Plan Mode로 전환합니다(또는 Shift+Tab / Alt+M으로 모드를 토글할 수 있습니다).
(선택 사항) 모든 세션에서 기본적으로 Plan Mode를 사용하려면, 공식 설정 옵션을 사용하여 .claude/settings.json 파일을 생성합니다:
- "defaultMode": "plan"을 추가하면 새 세션이 기본적으로 계획 모드로 열립니다.
- Claude Code가 절대 읽지 않았으면 하는 파일(.env, secrets/, 자격 증명 파일)에 대한 permissions.deny 목록을 추가합니다.
설정 가이드에서 권장하는 대로 claude config list를 실행하여 활성 설정을 확인한 다음, 설정이 적용되었는지 확인합니다.
승인할 수 있을 만큼 구체적인 계획을 요청합니다: "Plan Mode에서 X를 수정하기 위한 최소한의 변경 사항을 정리하고, 수정할 정확한 파일을 나열하며, 검증에 사용할 명령어를 포함해 주세요." Claude가 단계만 제안하는지 확인합니다(Plan Mode는 실행 없음이기 때문입니다).

주의할 점:

첫 번째 프롬프트는 좁은 범위로 유지하세요: 파일, 함수, 명령어를 명시하는 계획이 전체적인 리팩토링보다 승인하기 훨씬 쉽습니다.
계획이 마음에 들어서 속도를 높이고 싶더라도, acceptEdits는 탐색 중에 켜는 것이 아니라 의도적인 "구현 단계" 설정으로 취급하세요.
claude config list에 변경 사항이 반영되지 않으면, Claude Code를 시작한 리포지토리에 .claude/settings.json을 올바르게 생성했는지 다시 확인하세요.

Claude가 구조화된 계획(변경할 파일 + 검증 명령어)으로 응답하고, Plan Mode에 있는 동안 도구를 실행하거나 파일을 수정하려는 시도를 하지 않으면 이 단계가 성공한 것입니다.

핵심 요약:

올바른 프로젝트 컨텍스트에서 Claude Code를 열고, 실행 전에 계획 우선 워크플로를 강제했습니다.
다단계 작업을 요청하기 전에 Plan Mode와 .claude/settings.json 범위 제어를 설정해야 합니다.
설정 불일치(잘못된 리포지토리, 잘못된 파일 경로)에 주의하고, 구체적인 계획을 승인한 후에만 더 빠른 권한 모드로 전환해야 합니다.

변경 사항 적용, 테스트 실행 및 AI 코드 생성을 위한 샌드박싱 활성화

승인된 계획이 있으므로, 이제 목표는 제어된 쓰기 접근 권한으로 이를 구현하고, 더 안전한 실행 환경에서 실제 테스트 명령어로 변경 사항을 검증하는 것입니다.

다음 단계를 따라 계획을 적용하고, 검증을 실행하며, 위험을 줄이세요:

계획이 준비되면, Claude Code가 "어떻게 진행하시겠습니까?"라고 묻고 "예, 편집을 자동 수락합니다" 또는 "예, 편집을 수동으로 승인합니다"와 같은 옵션을 제공합니다—하나를 선택하여 구현을 시작합니다.
파일 편집을 한 번에 한 배치씩 승인한 다음, 별도의 터미널 창에서 git diff를 실행하여 변경 사항을 즉시 확인합니다.
/sandbox 명령을 실행하고 워크플로에 맞는 샌드박스 옵션을 선택하여 샌드박스 명령 실행을 활성화합니다.
일상적인 작업에는 자동 허용 모드를 선택하여 샌드박스 자동 실행을 선호합니다. 이렇게 하면 Claude가 반복적으로 승인을 요청하지 않고도 일반적인 테스트 및 린트 명령을 실행할 수 있습니다.
리포지토리 루트에서 프로젝트의 테스트 명령을 실행합니다. 예를 들어 npm run test 또는 bash tool 예제에 표시된 대로 pytest && coverage report를 실행합니다.
샌드박스와 호환되지 않는 명령은 의도적으로 처리합니다: Claude Code가 샌드박스 외부에서 무언가를 실행하기 위한 이탈 경로를 제공하는 경우, 허용하기 전에 중단하고 명령이 안전한지 확인하세요.

주의할 점:

"편집 단계"와 "검증 단계"를 분리하세요: 먼저 diff를 검토한 다음, 두 번째로 테스트를 실행합니다.
명령 실행은 직접적인 시스템 접근이 될 수 있으므로 더 높은 위험으로 취급하세요; 확실하지 않으면 직접 명령을 실행하거나 샌드박스 내에서 유지하세요.
테스트가 실패하면 범위를 넓히지 마세요; Claude에게 실패한 테스트나 실패와 관련된 최소한의 코드 경로만 수정하도록 요청한 다음 다시 실행하세요.

이 시점에서 리포지토리는 git diff에 의도한 편집만 표시해야 하며, 테스트 명령이 성공적으로 완료되어야 합니다.

핵심 요약:

승인된 계획을 구현하고, 다른 작업을 하기 전에 "편집 → diff 검토 → 테스트 실행"의 촘촘한 루프로 이동했습니다.
샌드박싱을 일찍 활성화하고 가능한 한 그 안에서 테스트를 실행하면 안전성과 속도를 모두 극대화할 수 있습니다.
샌드박스 이탈 경로 사용 요청에 주의하고, 이를 속도를 늦추고 검증해야 한다는 신호로 취급해야 합니다.

첫 번째 Skill 만들기: Claude Code 튜토리얼

"계획 → 구현 → 테스트" 과정에 익숙해졌다면, 실력을 빠르게 끌어올리는 방법은 최고의 프롬프트를 재사용 가능하게 만드는 것입니다. Skills는 Claude Code에서 이를 수행하는 최신 방법으로, 요청이 스킬의 설명과 일치할 때 Claude가 자동으로 검색하고 로드하는 독립적인 기능 패키지입니다.

스킬은 필수 SKILL.md 파일과 선택적 지원 디렉터리를 포함하는 폴더입니다. Claude는 점진적 공개 모델을 사용합니다: 먼저 메타데이터를 읽고(검색용), 트리거되면 메인 지침을 로드하며, 필요할 때만 지원 파일을 가져옵니다—컨텍스트를 가볍게 유지합니다.

다음은 권장 폴더 구조입니다:

pr-summarizer/
├── SKILL.md          # 필수: frontmatter + 핵심 지침
├── references/       # 선택: 상세 문서, 엣지 케이스, API 사양
├── examples/         # 선택: 샘플 입력/출력
└── scripts/          # 선택: 실행 가능한 헬퍼(Python/Bash/Node)

다음 단계를 따라 첫 번째 스킬을 만들고 테스트하세요:

mkdir -p .claude/skills/pr-summarizer를 실행하여 프로젝트에 스킬 폴더를 생성합니다(git에 커밋할 프로젝트 공유 스킬에는 .claude/skills/를 사용하고, 개인 스킬에는 ~/.claude/skills/를 사용합니다).
name과 description을 포함하는 YAML frontmatter가 있는 필수 SKILL.md 파일을 생성합니다—Claude가 스킬을 언제 로드할지 결정하는 데 description이 매우 중요합니다:

---
name: pr-summarizer
description: Summarize a pull request diff and produce a changelog entry. Use when asked to summarize, review, or create release notes from a PR or diff.
allowed-tools: Read, Grep, Glob, Bash(git diff)
---

When triggered, follow these steps:

1. Read the PR title, body, and diff
2. Extract high-level changes, breaking changes, and impacted modules
3. Return a 3-sentence summary and a one-paragraph changelog entry

Example output format:
**Summary:** Added user authentication flow with OAuth2 support...
**Changelog:** This release introduces OAuth2-based authentication...

SKILL.md를 간결하게 유지하되(1,500–2,000단어 목표; 3,000단어 이하), 지원 콘텐츠는 하위 폴더로 정리합니다:
- references/ — 상세 문서, 스키마, 문제 해결 가이드
- examples/ — 샘플 입력/출력, 실행 가능한 데모
- scripts/ — 컨텍스트에 로드하지 않고 실행되는 실행 가능한 헬퍼
(선택 사항) 엣지 케이스를 위한 참조 파일을 추가합니다. references/EDGE-CASES.md를 생성합니다:

# Edge Cases for PR Summarizer

## Merge commits
When summarizing merge commits, focus on the merged branch's changes, not the merge commit itself.

## Empty diffs
If the diff is empty, return: "No code changes detected. This may be a metadata-only update."

그런 다음 SKILL.md에서 이를 참조합니다: "엣지 케이스에 대해서는 references/EDGE-CASES.md를 참조하세요."

리포지토리에서 Claude Code를 재시작한 다음, 스킬이 트리거되어야 하는 요청(예: "마지막 커밋의 변경 사항을 변경 로그 항목으로 요약해 주세요")을 보내 검색 기능을 테스트하고, Claude가 스킬의 지침을 로드하고 따르는지 확인합니다.
예상대로 스킬이 트리거되지 않으면, 더 명확한 트리거 키워드와 사용자 표현 예시를 추가하여 description 필드를 개선한 다음 다시 테스트합니다.

주의할 점:

name 필드는 소문자, 숫자, 하이픈만 허용됩니다(최대 64자); 폴더 이름이 일치해야 합니다. description은 최대 약 1,024자입니다.
SKILL.md나 지원 파일에 비밀 키나 API 키를 하드코딩하지 마세요—외부 서비스 접근에는 MCP 연결이나 환경 변수를 사용하세요.
격리된 실행이 필요한 스킬(메인 대화를 깔끔하게 유지)의 경우, frontmatter에 context: fork를 추가합니다; 이렇게 하면 스킬이 별도의 하위 에이전트 컨텍스트에서 실행됩니다.
frontmatter에서 allowed-tools를 사용하여 스킬이 접근할 수 있는 도구를 제한합니다—필요한 것만 부여하세요.

Claude가 일치하는 요청을 기반으로 스킬을 자동으로 로드하고 SKILL.md에서 지정한 형식으로 출력을 생성하면 이 단계가 성공한 것입니다.

핵심 요약:

Skills는 Claude Code에서 재사용 가능한 기능을 패키징하는 최신 권장 방법으로, 대부분의 워크플로에서 하위 에이전트를 대체했습니다.
명확한 트리거 키워드가 포함된 description을 작성하고 SKILL.md를 핵심 지침에 집중시킴으로써 최고의 검색 결과를 얻을 수 있습니다.
폴더 구조(references/, examples/, scripts/)를 활용하여 메인 스킬을 간결하게 유지하면서도 필요할 때 Claude에게 깊은 컨텍스트를 제공해야 합니다.

MCP로 외부 AI 코딩 도구 연결하기

MCP (Model Context Protocol)는 도구, 리소스, 데이터를 제공하는 외부 서버와 Claude Code가 통신할 수 있게 해주는 개방형 표준입니다. 범용 어댑터라고 생각하면 됩니다: 이슈 설명이나 데이터베이스 결과를 프롬프트에 붙여넣는 대신, MCP 서버를 연결하면 Claude가 직접 쿼리합니다.

다음 단계를 따라 첫 번째 MCP 서버를 추가하세요:

원격 HTTP 서버(Notion, Linear 또는 호스팅 API와 같은 클라우드 서비스용)가 필요한지 로컬 stdio 서버(직접 파일 시스템 접근이 필요한 도구용)가 필요한지 결정합니다; 대부분의 통합에는 HTTP가 권장됩니다.
CLI를 사용하여 원격 MCP 서버를 추가합니다: claude mcp add --transport http notion https://mcp.notion.com/mcp (실제 서비스 엔드포인트로 대체하세요).
인증이 필요한 서버의 경우, 헤더 플래그를 포함합니다: claude mcp add --transport http linear https://api.linear.app/mcp --header "Authorization: Bearer your-token".
claude mcp list를 실행하여 서버가 추가되었는지 확인한 다음, claude mcp get <name>으로 설정을 검사합니다.
Claude에게 통합을 사용하도록 요청하여 연결을 테스트합니다(예: "Linear에서 내 열린 이슈를 나열해 줘" 또는 "온보딩에 대한 Notion 페이지를 찾아줘").

로컬 서버나 팀 공유 설정의 경우, 프로젝트 루트에 .mcp.json 파일을 생성합니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

주의할 점:

토큰 범위를 최소화하고 파일 시스템 서버에 대해 ALLOWED_PATHS를 제한하세요—최소 권한 원칙이 여기에 적용됩니다.
MCP 서버에는 과거에 패치된 보안 취약점이 있었습니다; 서버를 최신 상태로 유지하고 신뢰할 수 있는 소스의 서버만 사용하세요.
도구 출력은 10,000 토큰에서 경고를 트리거하고 기본적으로 25,000 토큰에서 제한됩니다; 대용량 응답에 대해서는 페이지네이션을 고려하거나 쿼리 범위를 더 좁히세요.

Claude가 콘텐츠를 수동으로 붙여넣지 않고도 외부 시스템에 성공적으로 쿼리하거나 작업(이슈 나열 또는 문서 읽기 등)을 수행할 수 있으면 이 단계가 성공한 것입니다.

핵심 요약:

MCP는 Claude Code를 외부 도구 및 데이터 소스에 연결하는 방법으로, 여러 AI 플랫폼에서 지원되는 개방형 프로토콜입니다.
매일 사용할 하나의 통합(예: 이슈 트래커)으로 시작하고, 안정적으로 작동한 후에만 확장하면 가장 큰 가치를 얻을 수 있습니다.
과도하게 넓은 권한에 주의하세요; 파일 경로와 API 토큰의 범위를 좁게 설정하고, MCP 서버를 최신 상태로 유지해야 합니다.

Hooks로 가드레일 자동화하기

Hooks를 사용하면 Claude Code의 라이프사이클에서 특정 시점—프롬프트를 제출할 때, 도구 실행 전후, 세션이 시작될 때—에 셸 명령을 자동으로 실행할 수 있습니다. 코드 스타일 적용, 명령 로깅 또는 위험한 작업 차단과 같은 가벼운 자동화에 사용하세요.

다음 단계를 따라 첫 번째 Hook을 추가하세요:

로그 기록(Claude가 특정 명령을 실행할 때) 또는 편집 후 코드 자동 포매팅과 같은 저위험 자동화부터 시작할 것을 결정합니다.
Hooks 가이드를 참고하여 프로젝트의 .claude/settings.json(또는 사용자 범위의 ~/.claude/settings.json)에 Hook을 추가합니다. Claude가 실행하는 모든 Bash 명령을 기록하는 시작 예제입니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $(echo $CLAUDE_TOOL_INPUT | jq -r '.command')\" >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

보다 실용적인 Hook으로, 편집할 때마다 TypeScript 파일에 Prettier를 자동 실행하려면 PostToolUse hook을 추가합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path') 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Claude Code를 재시작하고 matcher와 일치하는 명령을 실행하여 Hook을 트리거한 다음, 로그 파일이나 포매팅된 출력을 확인하여 Hook이 실행되었는지 검증합니다.
Claude Code 내에서 /hooks를 실행하여 등록된 Hook을 검사하거나, claude --debug를 사용하여 Hook 실행 로그를 확인함으로써 Hook을 디버그합니다.

주의할 점:

Hook은 사용자 권한으로 임의의 셸 명령을 실행하므로, 상태를 변경하는 작업을 추가하기 전에 읽기 전용 또는 로깅 작업부터 시작하세요.
Hook은 기본적으로 60초 제한 시간이 있습니다; Claude의 워크플로를 지연시키지 않도록 명령을 빠르게 유지하세요.
종료 코드 2를 사용하여 작업을 차단합니다(위험한 명령을 거부해야 하는 PreToolUse Hook의 경우); 다른 0이 아닌 코드는 차단하지 않는 경고입니다.

Hook이 예상 트리거 시점에서 안정적으로 실행되고 관찰 가능한 출력(로그 항목, 포매팅된 파일 또는 차단된 명령)을 생성하면 이 단계가 성공한 것입니다.

핵심 요약:

Hooks는 Claude Code의 라이프사이클에서 특정 시점에 셸 명령을 실행하는 가벼운 자동화입니다—가드레일, 포매팅, 로깅에 사용하세요.
파일을 수정하거나 작업을 차단하는 Hook으로 진행하기 전에 무해하고 관찰 가능한 Hook부터 시작하면 가장 안전합니다.
느리거나 불안정한 Hook에 주의하세요; 격리된 환경에서 테스트하고 /hooks 또는 --debug를 사용하여 문제를 해결하세요.

DeepStation으로 더 빠르게 구축하기

가이드를 읽는 것은 훌륭한 시작이지만, 진정한 속도 향상은 Claude Code 설정이 프로젝트 전반에 걸쳐 몸에 익은 습관이 될 때 나타납니다. DeepStation은 커뮤니티의 힘을 통해 AI 교육과 혁신을 가속화함으로써 바로 이를 도와줍니다—실제 워크플로를 비교하고, 다른 개발자들의 AI 코딩 팁을 탐색하며, "일회성 프롬프트"를 신뢰할 수 있는 일관되고 안전한 Claude Code 프로세스로 전환할 수 있습니다.

이번 주에 추진력을 키울 준비가 되셨다면, 지금 참여하여 Claude Code 워크플로, AI 코딩 모범 사례, 개발자 자동화 루틴을 개선하는 다른 빌더들과 함께 실력을 키워보세요. Claude Code 워크플로 트레이닝 & AI 교육에 지금 등록하세요! 활성 커뮤니티 세션의 자리는 빠르게 채워집니다—자리를 확보하고 다음 터미널 세션을 측정 가능한 성과로 바꿔보세요.

DeepStation

Global AI Community

Join our global AI community of engineers, founders, and enthusiasts to stay ahead of the AI wave.