서론

Claude Code는 절대 지치지 않고, 모든 제안을 설명하며, 프로젝트 전체를 한 번에 읽어내는 페어 프로그래머 (pair programmer)입니다. 하지만 이는 단순한 코딩 플러그인이 포함된 채팅 인터페이스가 아닙니다. 터미널에서 실행되며, 파일을 읽고 쓰고, Git을 관리하며, 전체 코드베이스 (codebase) 전체에 걸쳐 추론하는 에이전트형 CLI (agentic CLI)입니다.

이 가이드는 Claude Code를 차별화하는 요소, 설치 방법, 그리고 첫 번째 프롬프트 (prompt)를 실행하는 방법을 다룹니다. 이 가이드를 마칠 때쯤이면 여러분은 Claude Code를 자동 완성 (autocomplete) 도구가 아닌 협업자로 다루는 방법을 알게 될 것입니다.

핵심 개념

Claude Code의 실체

Claude Code는 AI 지원 개발을 위한 Anthropic의 공식 명령줄 인터페이스 (command-line interface)입니다. 터미널에서 실행되며 다음과 같은 작업을 수행할 수 있습니다:

• 프로젝트 내 파일 직접 읽기 및 쓰기
• 명령 실행
• Git 워크플로우 관리 — 브랜치 (branches), 커밋 (commits), 풀 리퀘스트 (pull requests)
• 최대 100만 토큰 (tokens) 규모의 코드베이스 컨텍스트 (context)에 걸친 추론
• MCP (Model Context Protocol)를 통한 외부 서비스 연결
• 행동하기 전 일반적인 영어로 자신의 추론 과정을 제시

Pro 사용자의 경우 기본적으로 Sonnet 4.6에서 실행되며, Max 플랜의 경우 Opus 4.6에서 실행됩니다. 파일을 변경하는 어떠한 작업을 수행하기 전에, 반드시 확인을 요청하고 계획을 보여줍니다. 이것이 바로 헌법적 AI (Constitutional AI) 프레임워크가 실제로 적용된 모습입니다.

Claude Code 비교

Claude Code는 대규모 리팩터링 (refactoring), 파일 간 버그 수정, 인프라 작업을 엔드 투 엔드 (end to end)로 처리합니다. 이는 자동 완성 도구와는 다른 카테고리입니다.

설치 및 첫 번째 프롬프트

1단계 — 액세스 방법 선택

Claude Code를 사용하는 세 가지 방법:

1. Claude Web (claude.ai) — 설치가 필요 없습니다. 프롬프트 (Prompts) 실험에 적합합니다.
2. Claude Code CLI — 핵심 도구입니다. 모든 터미널에서 실행 가능하며, SSH를 통해 작동하고, CI/CD 파이프라인에서 스크립트로 활용할 수 있습니다.
3. IDE Extension — VS Code 확장 프로그램 (Cursor, Windsurf, Kiro에서도 작동)으로, 에디터를 떠나지 않고도 인라인 차이점 (Inline diffs)을 확인하고 승인/거절 (Accept/Reject) 제어를 할 수 있습니다.

CLI 설치하기

Claude Code를 설치하려면 다음 방법 중 하나를 사용하세요:

macOS, Linux, WSL:

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

또는 Node.js 18 이상을 먼저 설치한 후 다음을 실행하세요:

npm install -g @anthropic-ai/claude-code

터미널에서 claude를 실행하고 OAuth 흐름을 완료하여 인증을 진행하세요. 다음 명령어로 확인합니다:

claude doctor

Linux 패키지 관리자로 설치하기

Debian 및 Ubuntu용입니다. 롤링 채널 (Rolling channel)을 사용하려면 deb 라인의 stable이 나타나는 두 곳(URL 경로 및 suite 이름)을 모두 변경하세요.

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
...

GPG 키를 신뢰하기 전에 지문 (Fingerprint)을 확인하세요: gpg --show-keys /etc/apt/keyrings/claude-code.asc 명령의 결과가 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE로 나와야 합니다.

나중에 업그레이드하려면 sudo apt update && sudo apt upgrade claude-code를 실행하세요.

VS Code에서 설정하기

확장 프로그램 뷰(Windows/Linux: Ctrl+Shift+X, Mac: Cmd+Shift+X)를 열고 Claude Code를 검색한 뒤 설치를 클릭하세요. 처음 실행할 때 Anthropic 계정으로 로그인합니다.

이 확장 프로그램은 VS Code의 통합 터미널에서 claude를 처음 실행할 때도 설치됩니다. Cursor, Windsurf 및 기타 VS Code 포크 (Forks)에서도 동일하게 작동합니다.

설치가 완료되면 사이드바의 Spark 아이콘을 클릭하세요. 실시간 인라인 차이점 (Inline diffs), Claude가 파일에 접근하기 전의 계획 검토 (Plan review), 특정 파일 및 라인 범위를 지정하는 @ 멘션 (Mention) 지원, 그리고 탭 간 대화 기록 (Conversation history) 기능을 사용할 수 있습니다.

Cursor에서 설정하기

무거운 에이전트적 작업 (Agentic tasks)을 위해 Cursor의 통합 터미널에서 Claude Code를 실행하세요. 대화형 편집 (Interactive editing)에는 Cursor의 Composer를 사용하세요. 두 도구는 서로 다른 속도와 작업 규모로 작동하며, 서로를 보완합니다.

Zed에서 설정하기

Zed 1.0부터 Claude Code는 ACP (Agent Client Protocol)를 통해 Zed의 에이전트 패널 (Agent Panel)에 기본적으로 내장되어 있습니다. 별도의 설치가 필요 없습니다. Zed는 GPU 가속 렌더링을 지원하는 Rust 언어로 구축되었습니다.

진입점을 선택하세요: 이미 사용 중이라면 VS Code를, 에이전트 작업과 함께 심도 있는 프로젝트 전반의 IDE 기능을 원한다면 Cursor를, 순수 성능을 원한다면 Zed를 선택하세요.

2단계 — 첫 번째 프롬프트 (Prompt)

선택한 인터페이스를 열고 다음을 전송하세요:

"안녕 Claude! 'Hello, Claude!'를 출력하고, 코드의 각 줄이 무엇을 하는지 주석으로 설명하는 Python 프로그램을 작성해줘."

Claude의 응답:

# 변수 'message'에 문자열 'Hello, Claude!'를 할당합니다
message = 'Hello, Claude!'

...

Claude는 요청하지 않았음에도 각 줄을 설명했습니다. 이것이 기본 동작입니다. Claude는 사용자가 단순히 코드를 복사하는 것이 아니라 코드를 이해하기를 원한다고 가정합니다.

이제 더 나아가 보세요:

"이것을 JavaScript로 다시 작성하고 차이점을 설명해줘."

Claude는 JavaScript 버전을 생성하며, const가 Python의 암시적 할당 (Implicit assignment)을 대체하고 console.log()가 print()를 대체한다는 점을 설명합니다:

// const를 사용하여 문자열 'Hello, Claude!'를 변수 'message'에 할당합니다
const message = "Hello, Claude!";

...

3단계 — 반복 (Iterate)

"Python 버전을 업데이트해서 내 이름을 묻고, 나에게 개인적인 인사를 건네며, 현재 시간을 보여주도록 해줘."

Claude는 input()을 추가하고, datetime을 임포트(Import)하여 실행 가능한 스크립트를 반환합니다:

import datetime

# 사용자에게 이름을 묻습니다
...

각 후속 요청은 Claude의 추론 (Reasoning)과 출력을 수정합니다. 이를 단발성 질의 (One-shot query)가 아닌 대화로 취급하세요.

모범 사례 (Best Practices)

초보자를 위한 팁

• 웹 인터페이스(Web interface)로 시작하세요 — 별도의 설정 없이 즉각적인 피드백을 받을 수 있습니다.
• Claude에게 모든 결정 사항을 설명해 달라고 요청하세요. 그 추론(Reasoning) 과정은 종종 코드 자체보다 더 유용합니다.
• 작고 구체적인 요청을 하세요. 모호한 프롬프트(Prompt)는 모호한 결과물을 생성합니다.

숙련된 개발자를 위한 팁

• CLI와 IDE 확장 프로그램(Extension)을 설치하세요. 컨텍스트 스위칭(Context switching)을 크게 줄일 수 있습니다.
• 생각의 사슬(Chain-of-thought) 프롬프트를 사용하세요: 복잡한 문제에 대해 코드를 작성하기 전, Claude에게 "단계별로 생각하라(think step by step)"고 요청하세요.
• 전체 코드베이스(Codebase)를 컨텍스트(Context)에 넣으세요. Claude는 1M 토큰을 읽을 수 있으므로, 대용량 파일과 문서에 이를 활용하세요.
• Git 작업을 일상적인 언어로 설명하세요. Claude Code는 브랜치(Branch)를 생성하고, 커밋 메시지(Commit message)를 작성하며, 풀 리퀘스트(Pull request)를 생성합니다.

흔한 실수

• 모호한 버그 보고는 모호한 수정안을 만듭니다. "이 버그를 고쳐줘"라고 하는 대신, "이 함수는 X를 반환해야 하지만 Y를 반환합니다. 여기 코드와 에러 메시지가 있습니다"라고 말하세요.
• Claude의 설명을 무시하는 것은 이 도구의 가장 큰 장점을 낭비하는 것입니다. 추론 과정을 읽으세요.
• 단일 프롬프트에 대한 기대는 Claude가 가장 잘 작동하는 방식과 일치하지 않습니다. 반복(Iterate)하세요.
• Claude Code를 단순한 라인 완성(Line completion) 용도로 사용하는 것은 빵을 썰기 위해 전기톱을 사용하는 것과 같습니다. 여러 파일과 여러 단계가 필요한 작업에 사용하세요.

결론

Claude Code는 코드베이스를 읽고, 명령을 실행하며, Git 워크플로(Workflow)를 관리하고, 모든 결정 사항을 설명하는 에이전트형(Agentic) CLI입니다. 이제 여러분은 다음 내용을 알고 있습니다:

• Claude Code가 무엇인지, 그리고 자동 완성(Autocomplete) 도구와 어떻게 다른지
• CLI를 설치하고 VS Code, Cursor 또는 Zed를 설정하는 방법
• 첫 번째 프롬프트를 실행하고 반복하는 방법

다음 단계: CLI를 설치하고, 첫 번째 "Hello, Claude!" 프롬프트를 보낸 다음, 더 어려운 작업을 시도해 보세요. 실제 파일을 리팩터링(Refactor)하거나, 에러 핸들링(Error handling)을 추가하거나, 변경 사항을 커밋(Commit)하도록 요청해 보세요. Claude Code가 자율적으로 수행할 수 있는 작업의 범위가 빠르게 명확해질 것입니다.

감사의 글: Anthropic의 공식 문서 및 커뮤니티 연구를 바탕으로 작성되었습니다. 기술적 세부 사항은 2026년 5월 기준의 Claude Code 상태를 반영합니다.