Claude Code 공식 문서 한국어 가이드, 핵심만 정리했습니다

작성자:

Claude Code 공식 문서는 영어로만 제공됩니다. docs.anthropic.com에 접속하면 설치부터 에이전트 기능까지 꽤 방대한 내용이 있는데, 영어 문서를 처음부터 끝까지 읽기가 부담스럽다는 분들이 많아요.

이 글은 공식 문서의 핵심 내용을 섹션별로 한국어로 정리한 허브 역할을 합니다. “어디서 무엇을 찾으면 되는지”를 먼저 파악하고, 필요한 항목은 각 세부 가이드로 이동하는 방식으로 읽으시면 됩니다.

왜 이 글이 필요한가요

Claude Code 공식 문서(docs.anthropic.com/ko/docs/claude-code)는 기본적으로 영어로 작성돼 있습니다. 한국어 UI가 일부 지원되지만, 문서 자체는 대부분 영어예요. 게다가 문서 구조가 기능별로 잘게 나뉘어 있어서, 처음 접하는 분들은 “뭐부터 읽어야 하지?”라는 느낌을 받기 쉽습니다.

한국어로 된 Claude Code 정리 글은 극소수입니다. 설치 방법을 다룬 글은 몇 개 있어도, 명령어·설정 파일·에이전트 기능을 하나의 흐름으로 이어주는 글은 찾기 어렵죠. 이 글은 그 역할을 합니다.

Claude Code를 이미 쓰고 있지만 “내가 모르는 기능이 더 있을 것 같다”는 분들께도 도움이 될 거예요.

설치와 첫 실행

Claude Code는 npm으로 설치합니다. 사전 조건은 Node.js 18 이상이에요. Node.js가 설치돼 있지 않으면 nodejs.org에서 LTS 버전을 받으면 됩니다.

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

설치 후 터미널에서 claude를 입력하면 실행됩니다. 처음 실행하면 Anthropic 계정 연결을 요청해요. Claude.ai 구독이 있으면 그 계정으로 로그인하면 되고, API 키를 직접 쓰는 방식도 지원합니다.

설치가 잘 됐는지 확인하고 싶으면 /doctor 명령어를 입력하세요. 환경 설정 상태와 문제점을 자동으로 점검해줍니다.

설치 과정에서 막히는 부분이 있으면 아래 전체 가이드를 참고하세요.

→ Claude Code 설치부터 첫 사용까지, 비개발자도 30분이면 됩니다

꼭 알아야 할 명령어

Claude Code 안에서 슬래시(/)로 시작하는 명령어를 입력하면 특정 기능을 바로 실행할 수 있습니다. 자주 쓰는 것만 추려보면 이렇습니다.

명령어 기능 언제 쓰나요
/help 명령어 목록 보기 뭐가 있는지 확인할 때
/compact 대화 내용 압축 대화가 길어져 느려질 때
/clear 대화 초기화 새 작업을 깔끔하게 시작할 때
/cost 토큰·비용 확인 API 비용 모니터링
/doctor 환경 점검 뭔가 이상하다 싶을 때
/mcp MCP 서버 상태 확인 연결된 외부 도구 확인
/review 변경 사항 검토 요청 코드·파일 변경 후 점검
/permissions 권한 대화형 관리 허용/차단 도구 설정

이 중에서 /compact는 실용적으로 자주 쓰게 되는 명령어입니다. 작업이 길어지면 Claude Code가 이전 대화를 처리하느라 응답이 느려지는데, /compact를 치면 맥락을 유지하면서 대화를 압축해줍니다. 긴 작업 세션에서 체감 차이가 크게 납니다.

설정 파일 3종

Claude Code에는 핵심 설정 파일이 3가지 있습니다. 각각 역할이 다르기 때문에 무엇이 어디에 들어가는지 한 번 정리해두면 나중에 헷갈리지 않아요.

① CLAUDE.md — 작업 지시서

프로젝트 폴더에 있는 CLAUDE.md는 Claude Code에게 “이 프로젝트에서는 이렇게 해줘”라고 알려주는 지시서입니다. 보고서 형식, 파일 저장 위치, 톤 규칙, 사용할 도구 등 프로젝트 맥락을 적어두면 Claude Code가 세션마다 자동으로 읽어서 적용해요.

“매번 같은 설명을 반복하기 귀찮다”면 CLAUDE.md에 한번 써두는 게 가장 빠른 해결책입니다.

② settings.json — 권한 규칙서

.claude/settings.json은 어떤 도구를 자동으로 허용하거나 차단할지 정하는 파일입니다. allowedTools에 넣은 도구는 매번 승인 없이 바로 실행되고, deniedTools에 넣은 도구는 아예 막혀요.

프로젝트마다 쓰는 설정과 내 컴퓨터 전체에 적용할 설정을 분리해서 관리할 수 있습니다.

→ Claude Code 설정 완벽 가이드, settings.json부터 권한 관리까지

③ .claude/skills/ — 커스텀 명령어 폴더

.claude/skills/ 폴더 안에 마크다운 파일을 넣어두면, 그 파일명이 슬래시 명령어처럼 동작합니다. 예를 들어 report.md를 만들어두면 /report를 입력할 때 해당 파일의 지시대로 Claude Code가 동작해요. 자주 하는 작업을 명령어화할 수 있습니다.

→ Claude Code Skills 사용법, 커스텀 명령어 만들기

에이전트 기능 한눈에

Claude Code의 가장 강력한 기능은 단순 질문·응답을 넘어서는 에이전트 동작입니다. 공식 문서에서는 이 부분이 여러 페이지에 걸쳐 나뉘어 있어요. 한눈에 보면 이렇습니다.

서브에이전트 (Subagents)

Claude Code는 복잡한 작업을 처리할 때 자기 복제본을 여러 개 띄워서 병렬로 처리할 수 있어요. 이를 서브에이전트라고 합니다. 예를 들어 “3개 파일을 동시에 분석해줘” 같은 요청을 받으면, 메인 에이전트가 3개의 서브에이전트를 생성해서 각각 분석한 뒤 결과를 합쳐줍니다.

사용자가 직접 설정할 필요는 없고, Claude Code가 판단해서 자동으로 활용합니다.

Hooks — 자동 실행 트리거

Hooks는 특정 이벤트가 발생할 때 자동으로 실행될 명령어를 등록해두는 기능입니다. 예를 들어 “파일 저장 후 자동으로 FTP 업로드”, “Claude Code 실행 완료 후 알림 전송” 같은 자동화를 만들 수 있어요. settings.json에 등록합니다.

→ Claude Code Hooks 사용법, 자동화 트리거 설정하기

MCP (Model Context Protocol)

MCP는 Claude Code에 외부 도구를 연결하는 표준 방식입니다. 구글 드라이브, Gmail, 깃허브, 슬랙 등 다양한 서비스를 MCP 서버를 통해 Claude Code와 연결할 수 있어요. 연결하면 Claude Code가 해당 서비스를 직접 읽고 쓸 수 있게 됩니다.

/mcp 명령어로 현재 연결된 서버 상태를 확인할 수 있고, settings.json에서 서버를 등록합니다.

→ Claude Code MCP 연결 및 설정 가이드

VS Code · JetBrains 통합

Claude Code는 터미널 외에도 IDE에서 직접 쓸 수 있어요. VS Code와 JetBrains 계열(IntelliJ, WebStorm 등)에 공식 확장 프로그램이 있습니다. 설치하면 에디터 안에서 Claude Code와 대화하면서 코드를 바로 수정할 수 있습니다.

데스크톱 앱도 있어요. claude.ai/download에서 받을 수 있고, 터미널 없이 GUI로 Claude Code를 쓰고 싶은 분들에게 적합합니다.

더 깊이 알고 싶다면 — 내부 링크 허브

Claude Code 관련 글을 주제별로 정리했습니다. 필요한 항목으로 바로 이동하세요.

기초 — 설치와 첫 설정

설정 파일 — CLAUDE.md와 settings.json

자동화 — Hooks와 Skills

확장 — MCP 연결

공식 문서 바로가기

이 글에서 다루지 못한 세부 기능, 최신 API 레퍼런스, 팀 관리 기능 등은 공식 문서에서 확인할 수 있습니다.

공식 문서는 기능이 추가될 때마다 업데이트되므로, 이 글에서 다루지 않은 최신 기능은 직접 확인하는 것을 권장합니다.

※ 이 글은 2026년 6월 기준으로 작성됐습니다. Claude Code의 기능과 명령어는 버전에 따라 달라질 수 있습니다.