Claude Code 입문 가이드, 33페이지로 보는 개념과 사용법

Claude Code를 아직 시작하지 않았거나 더 알고 싶은 사람을 위한 비공식 입문 가이드가 공개됐다. revfactory가 만든 이 가이드는 33페이지에 걸쳐 Claude Code가 무엇이고, 어떻게 쓰며, 다른 AI 코딩 도구와 어떻게 다른지를 나레이션과 모션그래픽으로 설명한다. 영상으로는 12분 남짓이고, 같은 내용을 웹사이트에서 한 페이지씩 넘겨 볼 수 있다.

Claude Code 입문 가이드의 표지 화면. (출처: revfactory.github.io/claude-code-basic)

가이드를 보는 방법

사이트에서 시작 단추를 누르면 나레이션과 함께 33페이지가 차례로 넘어간다. 내용은 2026년 10월 21일 공식 문서를 기준으로 하고, 화면 속 Claude Code UI는 설명을 위해 다시 그린 것이다. 터미널, 코드 편집기, 데스크톱 앱 등 여러 실행 환경 가운데 기능이 가장 많은 터미널을 기준으로 설명한다.

키	동작
← →	페이지 이동
Space	재생, 일시정지
T	목차
C	자막 켜기, 끄기
M	배경음 켜기, 끄기
A	자동 넘김
F	전체 화면

구성은 여섯 묶음이다.

묶음	페이지	다루는 내용
시작	1~2	표지, 한 문장 정의
1부 개념	3~7	세 가지 방식, 에이전트 루프, 모델과 하네스, 내장 도구, 실행하는 곳
2부 시작하기	8~19	설치와 로그인, 첫 실행, 요청 쓰는 법, 되감기, 권한 모드, 계획 모드, 컨텍스트 창, CLAUDE.md, 자주 쓰는 명령
3부 확장	20~26	스킬, 서브에이전트, 훅, MCP, 플러그인, 대화 없이 실행하기
4부 비교	27~30	다른 AI 코딩 도구와 견준 장점과 한계
5부 실전·마무리	31~33	탐색·계획·구현·커밋, 좋은 요청의 조건, 정리

한 문장 정의와 기본 개념

가이드는 공식 문서의 정의에서 출발한다. Claude Code는 코드베이스를 읽고, 파일을 고치고, 명령을 실행하는 에이전트형 코딩 도구다. 코드베이스는 프로젝트를 이루는 소스 코드 전체를 말한다.

AI 코딩 도구는 일하는 방식에 따라 셋으로 나뉜다. 다음 줄을 제안하는 자동완성, 질문에 코드로 답하는 채팅, 목표를 받아 여러 단계를 스스로 진행하는 에이전트다. Claude Code는 세 번째에 속한다.

일을 맡기면 Claude Code는 세 단계를 되풀이한다. 관련 파일을 읽어 필요한 정보를 모으고, 파일을 고치거나 명령을 실행하고, 테스트로 결과를 확인한다. 결과가 기대와 다르면 다시 읽고 고치고 확인한다. 사용자는 언제든 작업을 멈추고 요청을 바꿀 수 있다.

이때 무엇을 할지 정하는 쪽은 Claude 모델이다. Claude Code는 모델이 쓸 도구와 모델에 전달할 정보를 관리하는 프로그램이고, 공식 문서는 이 프로그램을 에이전트 하네스라고 부른다.

내장 도구는 다섯 종류다.

• 파일 도구: 파일을 읽고 고친다
• 검색 도구: 코드를 찾는다
• 실행 도구: 터미널 명령을 실행한다
• 웹 도구: 웹 페이지를 가져온다
• 코드 인텔리전스: 코드 구조를 분석한다. 플러그인을 설치해야 쓸 수 있다

실행할 수 있는 곳은 터미널, VS Code와 JetBrains 같은 코드 편집기, 데스크톱 앱, 웹 브라우저, 모바일 앱, Slack, GitHub Actions다.

설치부터 첫 대화까지

설치는 터미널에 명령 한 줄을 입력하면 끝난다. 이렇게 설치하면 자동으로 업데이트된다.

# macOS, 리눅스
curl -fsSL https://claude.ai/install.sh | bash

# 윈도우 PowerShell
irm https://claude.ai/install.ps1 | iex

처음 실행하면 로그인을 요청한다. Pro, Max, Team, Enterprise 구독이나 Console 계정이 필요하고 무료 플랜으로는 쓸 수 없다.

프로젝트 폴더로 이동해 claude를 입력하면 대화가 시작된다. 가이드는 할 일 목록 웹 앱을 예로 들어, 먼저 이 프로젝트가 하는 일을 묻는다. Claude가 파일을 직접 열어 보고 구조를 설명하므로 코드를 복사해 붙여 넣을 필요가 없다.

요청은 평소 말하듯 한국어로 써도 된다. 입력창에서 쓰는 기호가 몇 가지 있다.

• @ 뒤에 파일 경로를 쓰면 그 파일을 먼저 읽는다
• 입력을 !로 시작하면 터미널 명령을 바로 실행한다
• 화면 캡처 같은 이미지는 붙여 넣어 전달한다

멈추기, 되감기, 권한

Claude가 원하지 않는 파일을 고치기 시작했다면 Esc를 눌러 바로 멈춘다. 입력창이 비어 있을 때 Esc를 두 번 누르면 되감기 메뉴가 열리고, 원하는 시점을 고르면 코드와 대화가 그때 상태로 돌아간다.

되감기에는 한계가 있다. Claude의 파일 편집 도구가 고친 내용만 기록하기 때문에 rm이나 mv처럼 터미널 명령으로 지우거나 옮긴 파일은 되돌릴 수 없다. 되감기는 git을 대신하지 못하므로 중요한 변경은 커밋으로 남겨 둔다.

파일을 고치거나 명령을 실행하기 전에 Claude가 언제 허락을 구할지는 권한 모드가 정한다. Shift와 Tab을 함께 누르면 모드가 차례로 바뀐다.

권한 모드	동작
Manual	모든 행동을 묻는다
Accept edits	파일 편집은 묻지 않는다
Plan	계획만 세운다
Auto	위험한 행동만 자동으로 막는다

허락이 필요할 때는 질문이 나타난다. 한 번만 허용하거나, 이번 대화에서 계속 허용하거나, 거절하고 다른 방법을 알려 줄 수 있다. 자주 쓰는 허용과 거부는 설정 파일에 규칙으로 남기고, 규칙이 겹치면 거부가 항상 먼저 적용된다.

여러 파일을 고치는 큰 작업은 계획 모드로 시작하는 편이 안전하다. 계획 모드에서 Claude는 파일을 읽고 조사하지만 소스 코드는 고치지 않는다. 사용자가 계획을 읽고 승인하면 그때부터 실제로 고친다.

컨텍스트 창과 CLAUDE.md

Claude가 한 번에 볼 수 있는 정보의 양을 컨텍스트 창이라고 한다. 대화, 읽은 파일, 명령 출력이 모두 컨텍스트에 들어가고 양이 늘수록 성능이 떨어진다. /context로 사용량을 보고, /compact로 대화를 요약하고, 다른 작업을 시작할 때는 /clear로 비운다.

매번 같은 설명을 반복하지 않으려면 CLAUDE.md 파일을 쓴다. /init을 실행하면 Claude가 프로젝트를 분석해 초안을 만든다. 빌드 명령, 코드 스타일, 주의할 점을 적어 두면 새 대화를 시작할 때마다 자동으로 읽는다. 두는 위치에 따라 적용 범위가 달라지고, 여러 파일이 있으면 모두 읽어 함께 적용한다.

파일 위치	적용 범위
홈 폴더의 CLAUDE.md	내 모든 프로젝트
프로젝트 폴더의 CLAUDE.md	팀 전체
CLAUDE.local.md	나에게만

슬래시(/)를 입력하면 쓸 수 있는 명령 목록이 열린다. 가이드는 모델을 바꾸는 /model, 사용량을 보는 /usage, 이전 대화를 다시 여는 /resume부터 익히라고 권한다. 터미널에서 claude -c로 시작하면 가장 최근 대화를 바로 이어 간다.

확장 기능 여섯 가지

확장 기능	하는 일
CLAUDE.md	대화마다 항상 읽는 지침
스킬	필요할 때 불러오는 작업 지침
서브에이전트	독립된 컨텍스트에서 일하는 보조 에이전트
훅	정해 둔 시점마다 자동으로 실행되는 동작
MCP	외부 서비스 연결
플러그인	위 기능들을 묶어 배포하는 단위

스킬은 SKILL.md 파일 하나로 만드는 작업 지침이다. 대화를 시작할 때는 이름과 설명만 읽고, 관련 작업을 할 때 본문을 읽는다. 그래서 긴 절차를 여러 개 넣어 두어도 컨텍스트를 적게 쓴다. / 뒤에 스킬 이름을 입력해 직접 실행할 수도 있다.

서브에이전트는 별도의 컨텍스트 창에서 일한다. 파일을 많이 읽는 조사를 맡기면 읽은 내용 대신 요약만 현재 대화에 전하고, 여러 서브에이전트를 동시에 실행할 수도 있다.

훅을 설명하는 대목에서 가이드는 CLAUDE.md에 적은 규칙은 요청이지 보장이 아니라고 짚는다. 반드시 지켜야 하는 일은 훅으로 만든다. 파일을 고친 직후 코드 형식을 자동으로 맞추거나 위험한 명령을 실행 전에 막는 식이다. 훅은 Claude의 판단과 관계없이 정해 둔 일이 생길 때마다 실행된다.

MCP는 AI와 외부 도구, 데이터를 연결하는 공개 표준이다. claude mcp add 명령으로 작업 관리 도구, 데이터베이스, 디자인 도구의 MCP 서버를 연결하면 Claude가 그 서비스의 기능을 도구로 직접 쓴다.

플러그인을 설치하면 스킬, 서브에이전트, 훅, MCP 설정이 한 번에 들어온다. /plugin으로 마켓플레이스를 열어 설치하고, 팀원 모두가 같은 구성을 쓸 수 있다. 플러그인은 내 권한으로 코드를 실행하므로 설치하기 전에 내용을 확인해야 한다.

Claude Code는 대화 없이도 실행된다. claude -p로 요청하면 결과만 출력하고 끝나므로 스크립트나 자동 빌드·테스트 과정에 넣을 수 있다. GitHub 이슈나 PR 댓글에 @claude라고 쓰면 GitHub Actions에서 작업이 실행된다. Agent SDK를 쓰면 파이썬과 타입스크립트 프로그램에서도 같은 에이전트를 쓸 수 있다.

다른 AI 코딩 도구와의 비교

비교 기준 시점은 2026년 10월이다. GitHub Copilot과 Cursor는 코드 편집기 안에서 출발했고, Claude Code, OpenAI Codex, Gemini CLI는 터미널에서 출발했다. 지금은 Gemini CLI를 뺀 네 도구를 터미널, 편집기, 클라우드에서 모두 쓸 수 있어서 실행하는 곳만으로는 도구를 구분하기 어렵다.

기능 목록도 비슷해졌다. 여러 파일을 고치는 에이전트 모드, 계획 모드, MCP, 스킬, 서브에이전트, 훅, 대화 없이 실행하는 기능이 다섯 도구에 모두 있다. 가이드는 기능이 있느냐보다 그 기능이 어떻게 동작하느냐를 비교하는 편이 정확하다고 본다.

그 기준에서 Claude Code의 장점으로 꼽은 것은 세 가지다.

• 훅을 걸 수 있는 시점이 33가지다. 개수를 공개한 다른 도구는 8~12개다
• CLAUDE.md와 스킬 같은 설정 파일을 Cursor와 Copilot도 읽는다. 여기서 익힌 방식을 다른 도구에서도 쓸 수 있다
• Amazon Bedrock, Google Cloud, Microsoft Foundry처럼 회사가 이미 쓰는 클라우드 계약으로도 연결할 수 있다

다른 도구가 더 맞는 경우도 함께 적었다.

원하는 것	더 맞는 도구
코드를 입력하는 동안 다음 줄 제안받기	자동완성이 있는 Copilot, Cursor
여러 회사의 모델을 골라 쓰기	Copilot, Cursor
도구의 소스 코드를 직접 읽고 고치기	오픈소스인 Codex CLI, Gemini CLI
무료로 쓰기	Claude Code에는 무료 플랜이 없다

실전 순서와 좋은 요청

마지막 묶음은 앞서 본 할 일 앱의 버그를 고치는 과정이다. 공식 문서가 권하는 순서는 탐색, 계획, 구현, 커밋이다. Claude가 관련 코드를 먼저 읽고, 계획 모드에서 고칠 방법을 정하고, 사용자가 계획을 승인한 뒤 고치고, 테스트를 통과하면 커밋한다.

결과는 요청을 얼마나 구체적으로 쓰느냐에 따라 달라진다. 가이드가 든 조건은 다음과 같다.

• 어느 파일에서 어떤 증상이 나는지 적는다
• 어떻게 되면 고쳐진 것인지 적는다
• 테스트처럼 Claude가 직접 돌려 볼 수 있는 확인 방법을 함께 준다
• 같은 문제를 두 번 넘게 바로잡았다면 /clear로 대화를 비우고 요청을 다시 쓴다

가이드의 정리는 짧다. Claude Code는 코드를 읽고, 고치고, 실행하고, 결과를 확인하는 에이전트다. 권한 모드와 되감기로 안전하게 쓰고, CLAUDE.md와 확장 기능으로 프로젝트에 맞는 규칙과 도구를 더한다. 마지막 문장은 프로젝트 폴더에서 claude를 입력하고 첫 질문을 해 보라는 권유다.

이 가이드를 만든 도구, Showreel 스킬

제작자는 이 가이드를 자신이 만든 Showreel 스킬로 제작했다고 밝혔다. Showreel은 Claude Code에서 한국어 모션그래픽 영상을 만드는 스킬로, MIT 라이선스로 공개돼 있다. 저장소 README에 따르면 요청 하나로 콘셉트, 조사, 원고, ElevenLabs 나레이션, 음악과 효과음, 이미지 생성, 렌더, 비평과 재작업, 믹스, 자동 검수를 모두 거친다.

정해 둔 무드나 템플릿을 고르는 방식이 아니다. 요청마다 콘셉트 후보를 셋 이상 세워 점수를 매기고, 구간마다 아트 디렉션을 새로 정한다. 사용자에게는 대상, 꼭 넣을 정보, 자료 위치처럼 사용자만 아는 사실만 묻는다. 화면보다 소리를 먼저 만들고, 나레이션 단어 타이밍과 음악 박자를 이름 붙은 큐로 바꿔 장면이 그 큐를 참조하게 한다. 그래서 나레이션 한 줄을 다시 만들어도 화면을 손댈 필요가 없다. 완성본은 받아쓰기(STT)로 발음을 다시 확인하고 음량, 섬광, 멈춘 화면을 검사한다.

README가 밝힌 한계도 있다. Claude는 소리를 들을 수 없어 음량과 발음을 수치로만 확인하므로, 공개하기 전에 사람이 직접 들어 봐야 한다. 개발과 시험은 macOS에서 이루어졌고, 실제 인물의 얼굴과 신체는 생성하지 않는다. 나레이션에는 ElevenLabs API 키가 필요하며 음악 생성은 유료 플랜에서만 된다.

출처

• revfactory, Claude Code 입문(비공식 입문 가이드, 2026년 10월 21일 공식 문서 기준). https://revfactory.github.io/claude-code-basic/
• revfactory, showreel 저장소 README. https://github.com/revfactory/showreel