Claude Code 이해하기: 파일을 읽고 수정하는 AI 도구
Claude Code(클로드 코드)는 앤트로픽이 만든 에이전트형 코딩 도구로, 작업 폴더의 파일을 읽고 고치며 명령을 실행합니다. 터미널, IDE, 데스크톱 앱, 브라우저에서 쓰고 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다.
같은 말:Claude Code클로드 코드Claude Code CLI클로드 코드 사용법클로드 코드 설치
AI 채팅에서 코드나 정리 방법을 받아도, 그 내용을 어느 파일에 붙여 넣고 어떻게 실행할지에서 멈추는 경우가 많습니다. Claude Code(클로드 코드)는 그 다음 단계를 직접 맡는 도구입니다. 내가 정한 작업 폴더의 파일을 읽고, 고치고, 필요한 명령을 실행해 결과를 파일로 남깁니다.
Claude Code는 앤트로픽(Anthropic)이 만든 에이전트형 코딩 도구로, 작업 폴더의 파일을 읽고 수정하며 명령을 실행합니다. 앤트로픽은 AI 모델 클로드를 만든 회사입니다. Claude Code는 터미널, VS Code 같은 편집기, 데스크톱 앱, 브라우저에서 쓸 수 있고, Pro, Max, Team, Enterprise 구독이나 Console(API) 계정이 필요합니다. 무료 claude.ai 플랜에는 포함되지 않습니다.
클로드 코드 입문
Claude Code의 결과는
폴더에 파일로 남습니다
민수 씨는 1월과 2월 매출 CSV를 합치려 합니다.
같은 요청을 채팅에 보낼 때와 Claude Code에 맡길 때, 바탕화면의 폴더가 어떻게 달라지는지 비교해 봅니다.
민수 씨의 요청
january.csv와 february.csv를 합쳐서 merged.csv로 저장해 줘. 원본 두 파일은 바꾸지 마.
- january.csv1월 매출, 자료 2행
- february.csv2월 매출, 자료 2행
위에서 보낼 곳을 고르면 이 폴더에 무엇이 남는지 보입니다.
가상 예시입니다. 두 답의 문장은 설명을 위해 만든 것입니다.
Claude Code는 작업 폴더의 파일을 읽고, 고치고, 명령을 실행해 결과를 파일로 남깁니다.
그래서 확인할 곳도 대화 화면이 아니라 폴더입니다.
네 가지 환경은
어디서 실행되는지가 다릅니다
환경을 고르면 내 컴퓨터와 클라우드 가운데 어디서 실행되는지 켜집니다.
네 곳 모두 같은 엔진이라 CLAUDE.md, 설정, MCP 서버가 똑같이 동작합니다.
- 설치
- 설치 명령 한 줄로 설치합니다.
- 화면에서 할 수 있는 일
- 공식 문서 기준으로 Claude Code의 전체 기능을 쓸 수 있습니다.
- 조건
- macOS 13.0 이상이나 Windows 10 1809 이상, 메모리 4GB 이상이 필요합니다.
- 어울리는 사람
- 글자 명령 창에 익숙해지고 싶은 사람입니다.
2026년 10월 Claude Code 공식 문서 기준입니다. diff는 바뀌기 전과 후를 나란히 보여 주는 화면입니다.
Shift+Tab을 누르면
확인을 묻는 범위가 바뀝니다
v2.1.283 이상의 대화형 터미널과 VS Code 세션은 auto 모드로 시작합니다.
키를 눌러 모드가 바뀌는 순서와 묻는 범위를 확인해 봅니다.
누른 횟수 0번
auto시작할 때의 기본값
- 파일 읽기안전 검사 뒤 진행
- 파일 편집안전 검사 뒤 진행
- mkdir, cp, mv 같은 파일 명령안전 검사 뒤 진행
- 그 밖의 명령 실행안전 검사 뒤 진행
백그라운드 안전 검사를 거쳐 작업을 실행하므로, 파일을 만들 때 승인 창이 뜨지 않을 수 있습니다.
2026년 10월 Claude Code 권한 모드 문서 기준입니다. dontAsk와 bypassPermissions는 Shift+Tab 순서에 없습니다. 어떤 모드에서도 직접 만든 ask 규칙과 중요한 경로를 지우는 명령은 자동 승인되지 않습니다.
첫 작업을 맡기기 전에 이것을 봅니다
- 1
Pro, Max, Team, Enterprise 또는 Console 계정이 있는지 확인합니다. 무료 플랜에는 포함되지 않습니다.
- 2
터미널, IDE, 데스크톱 앱, 웹 가운데 하나만 골라 시작합니다.
- 3
배우는 동안은 Shift+Tab으로 Manual 모드로 바꿔 확인을 받습니다.
- 4
답의 문장이 아니라 폴더에 생긴 파일을 직접 열어 원본과 대조합니다.
Claude Code는 파일을 읽고 고치는 에이전트형 코딩 도구입니다
공식 문서는 Claude Code를 "Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools."라고 설명합니다. 코드베이스를 읽고, 파일을 고치고, 명령을 실행하며 개발 도구와 연결되는 에이전트형 코딩 도구라는 뜻입니다.
에이전트형(agentic)은 목표를 받으면 필요한 도구를 스스로 골라 쓰며 여러 단계를 이어서 진행한다는 뜻입니다. 코드베이스(codebase)는 한 프로젝트의 코드와 관련 파일 전체를 말합니다. 질문에 답만 하는 데서 끝나지 않고, 파일을 열어 보고, 고치고, 검사 명령을 돌려 결과를 확인하는 과정까지 한 번의 요청 안에서 이어집니다.
클로드 채팅과 비교하면 자료가 들어오는 길과 결과가 남는 곳이 다릅니다.
| 항목 | 클로드 채팅 | Claude Code |
|---|---|---|
| 자료를 주는 방법 | 대화에 파일 첨부 | 작업 폴더의 파일을 직접 읽음 |
| 결과가 남는 곳 | 대화 화면 | 작업 폴더의 파일 |
| 확인할 것 | 답의 내용 | 바뀐 파일과 명령 실행 결과 |
| 무료 claude.ai 플랜 | 쓸 수 있음 | 쓸 수 없음 |
위 표는 파일 작업을 맡길 때를 기준으로 비교한 것입니다. 글을 다듬거나 아이디어를 묻는 일은 채팅으로도 충분합니다.
Claude Code에 맡길 수 있는 일은 공식 문서 기준으로 다음과 같습니다. 처음부터 모두 익힐 필요는 없고, 지금 하는 일에 필요한 것부터 씁니다.
- 검사와 정리: 테스트를 작성해 실행하고, 형식 오류를 고치고, 병합 충돌을 해결하고, 의존성을 업데이트합니다
- 기능 구현과 버그 수정: 요청한 기능을 만들고 오류를 찾아 고칩니다
- 변경 기록: Git으로 변경을 기록하고 커밋 메시지, 브랜치, 검토 요청(PR)을 준비합니다. Git은 파일의 변경 이력을 남기는 도구입니다
- 외부 도구 연결: MCP로 다른 서비스의 자료와 기능을 씁니다. MCP는 AI 도구와 외부 서비스를 잇는 연결 규격입니다
- 반복 작업 저장: 지침 파일 CLAUDE.md(기존 AGENTS.md도 읽음), 자동 메모리, 스킬, 훅으로 반복하는 규칙과 절차를 남깁니다
- 자동화와 예약:
claude -p로 다른 프로그램과 잇거나, 예약 작업과/loop로 정해진 때에 실행합니다
Claude Code는 터미널, IDE, 데스크톱 앱, 웹에서 씁니다
Claude Code를 쓰는 곳은 네 가지이고 처음에는 하나만 고르면 됩니다. 네 곳 모두 같은 Claude Code 엔진에 연결되어, 저장소의 CLAUDE.md, 설정, MCP 서버가 어디서든 똑같이 동작합니다.
2026년 10월 공식 문서 기준으로 쓸 수 있는 환경은 4곳이고, 권한 모드는 6가지이며, 컴퓨터에는 4GB 이상의 메모리(RAM)와 x64 또는 ARM64 프로세서가 필요합니다.
환경마다 설치 방법과 화면에서 할 수 있는 일이 조금씩 다릅니다.
| 환경 | 설치 | 실행되는 곳 | 화면에서 할 수 있는 일 | 조건 |
|---|---|---|---|---|
| 터미널 CLI | 설치 명령 한 줄 | 내 컴퓨터 | 전체 기능 | macOS 13.0 이상, Windows 10 1809 이상 |
| VS Code, JetBrains | VS Code 확장은 CLI 포함, JetBrains는 CLI 따로 설치 | 내 컴퓨터 | 인라인 diff, @멘션, 계획 검토 | VS Code 1.94.0 이상 |
| 데스크톱 앱(Code 탭) | CLI 설치 필요 없음 | 내 컴퓨터(클라우드 세션도 시작 가능) | diff 검토, 여러 세션, 예약 작업 | 유료 구독 |
| 웹(claude.ai/code) | 설치 없음 | 클라우드 | 브라우저, iOS와 Android 앱 | Pro, Max, Team과 Enterprise 일부 좌석 |
diff는 바뀌기 전과 후를 나란히 보여 주는 화면입니다. 웹판 클라우드 세션의 Enterprise 대상은 premium 좌석 또는 Chat + Claude Code 좌석입니다. 글자 명령 창에 익숙해지고 싶다면 터미널을 고릅니다. 이미 VS Code로 일한다면 VS Code 확장을, 명령어 창이 부담스럽다면 데스크톱 앱을 씁니다. 설치 없이 바로 시작하려면 웹판을 엽니다.
터미널은 명령어를 글자로 입력해 프로그램을 쓰는 창이고, 이렇게 쓰는 방식을 CLI(명령줄 인터페이스)라고 부릅니다. IDE는 코드를 쓰고 실행하는 편집 프로그램입니다. 웹판은 내 컴퓨터가 아니라 클라우드에서 실행되므로, 내 컴퓨터에만 있는 파일이나 설정은 웹판에서 보이지 않습니다.
문구 쇼핑몰의 월별 매출 CSV 두 개를 합치는 과정
작은 문구 쇼핑몰을 운영하는 민수 씨를 예로 들어 보겠습니다. 민수 씨는 매달 쇼핑몰 관리 화면에서 그달 매출을 CSV 파일로 내려받습니다. CSV는 쉼표로 값을 나눈 표 파일이고 엑셀로 열 수 있습니다. 1월과 2월 파일을 하나로 합쳐 상품별 합계를 보고 싶은데, 매번 복사해 붙이다 보니 줄을 빠뜨리는 일이 생겼습니다.
민수 씨의 작업 폴더에는 파일 두 개가 있습니다. january.csv에는 1월 매출로 메모장 1,000원과 연필 2,000원이 들어 있고, february.csv에는 2월 매출로 메모장 3,000원과 연필 4,000원이 들어 있습니다. 시작하는 순서는 다음과 같습니다.
- 설치: 공식 설치 명령 한 줄을 입력합니다. 설치 중에는 진행 표시가 없습니다.
- 설치 확인: 새 터미널에서
claude --version을 입력합니다. - 작업 폴더에서 실행: 폴더로 이동한 뒤
claude를 입력합니다. - 로그인: 첫 실행 때 브라우저에서 로그인합니다.
- 작업 요청: 읽기만 하는 요청을 먼저 보내고, 그다음 새 파일을 만들게 합니다.
민수 씨는 먼저 파일을 읽기만 하게 한 뒤, 내용이 맞으면 새 파일을 만들게 했습니다. 원본을 바로 고치지 않고 결과를 새 파일로 받는 것이 첫 작업의 기본입니다.
민수 씨가 보낸 두 요청과 받은 답은 다음과 같습니다. 설명을 위해 만든 가상 예시입니다.
| 순서 | 민수 씨의 요청 | Claude Code의 답 |
|---|---|---|
| 1 | 이 폴더의 january.csv와 february.csv만 읽고 열 이름과 행 수를 알려 줘. 파일은 만들거나 고치지 마. | 두 파일 모두 열은 월, 상품명, 매출이고 자료 행은 각각 2개입니다. |
| 2 | 두 파일을 합쳐 merged.csv라는 새 파일로 저장해 줘. 원본 두 파일은 바꾸지 마. | merged.csv를 만들었습니다. 머리글 1줄과 자료 4행이고, 상품별 합계는 메모장 4,000원, 연필 6,000원입니다. |
마지막 답에 "만들었습니다"라고 나와도 그것만으로 끝내지 않습니다. 파일 탐색기나 Finder에서 merged.csv를 직접 열어 자료가 4행인지, 1월과 2월 숫자가 원본과 같은지, january.csv와 february.csv가 그대로인지 확인합니다. 채팅 답이 아니라 폴더에 남은 파일이 Claude Code의 결과물입니다.
권한 모드가 확인을 묻는 범위를 정합니다
민수 씨의 화면에서 파일을 만들기 전에 승인 창이 뜨지 않았다면 권한 모드 때문입니다. 권한 모드는 Claude Code가 사용자에게 묻지 않고 해도 되는 일의 범위입니다. v2.1.283 이상의 대화형 터미널과 VS Code 세션은 auto 모드로 시작합니다. auto 모드는 백그라운드 안전 검사를 거쳐 작업을 실행하므로 파일 생성 같은 단계에서 승인 창이 뜨지 않을 수 있습니다.
| 권한 모드 | 묻지 않고 하는 일 | 쓰는 경우 |
|---|---|---|
default (화면 이름 Manual) | 파일 읽기 | 편집과 명령을 하나씩 확인하며 배울 때 |
acceptEdits | 읽기, 파일 편집, mkdir, touch, mv, cp 같은 파일 명령 | 편집은 맡기고 다른 명령은 확인할 때 |
plan | 읽기 | 고치기 전에 계획부터 검토할 때 |
auto | 백그라운드 안전 검사를 거친 모든 작업 | 대화형 세션의 기본값 |
dontAsk | 작업 폴더 안 읽기와 미리 허용한 도구(나머지는 거부) | 묻지 않고 정해진 일만 시킬 때 |
bypassPermissions | 모든 작업 | 격리된 컨테이너와 가상 머신 전용 |
처음 배우는 동안 매번 확인받고 싶다면 Shift+Tab을 눌러 Manual 모드로 바꿉니다. auto에서 처음 누르면 Manual(default)로 바뀌고, 그 뒤로는 누를 때마다 acceptEdits, plan, default 순서로 돌아갑니다. 상태 표시줄에 manual mode on이 보이면 바뀐 것입니다. 처음부터 Manual로 시작하려면 claude --permission-mode default로 실행합니다. 모드별 차이는 권한 모드 실무에서 더 자세히 다룹니다.
권한 모드와 관련해 처음 쓰는 분들이 자주 하는 오해는 다음 세 가지입니다.
| 흔한 오해 | 실제 |
|---|---|
| 요청에 "원본은 고치지 마"라고 쓰면 원본이 잠긴다 | 그 문장은 작업 범위를 알리는 지시입니다. 실제로 확인을 묻게 하는 장치는 권한 모드와 권한 규칙입니다 |
| auto 모드에서는 무엇이든 확인 없이 실행된다 | 어떤 모드에서도 직접 만든 ask 규칙, 사용자 입력이 필요한 도구, 중요한 경로를 지우는 명령은 자동 승인되지 않습니다 |
| Esc를 누르면 지금까지 한 작업이 되돌아간다 | Esc는 진행 중인 응답과 도구 호출을 멈추고 지금까지의 작업은 그대로 둡니다. 되돌리려면 Esc를 두 번 눌러 되감기 메뉴를 엽니다 |
그래서 민수 씨처럼 파일을 만들거나 고치기 전에 매번 확인받고 싶다면, 요청에 "꼭 물어봐"라고 덧붙이는 대신 Shift+Tab으로 Manual 모드로 바꿉니다. 요청 문장은 지시일 뿐 확인 장치가 아니고, /exit로 나갔다가 다시 실행하면 대화형 세션은 auto 모드로 시작합니다.
작업을 멈추는 방법도 함께 알아 둡니다. Esc는 진행 중인 응답이나 도구 호출을 멈추고, Ctrl+C는 실행 중인 작업을 중단하며 아무 작업도 없을 때 두 번 누르면 종료합니다. Claude Code를 끝낼 때는 /exit를 입력합니다.
비유로 보면 옆 책상에서 일하는 신입 직원과 닮았습니다
채팅이 전화로 방법을 알려 주는 사람이라면, Claude Code는 내 옆 책상에 앉아 서류를 직접 만지는 신입 직원과 닮았습니다. 서류함을 내주고, 할 일을 지시하고, 어디까지 혼자 처리해도 되는지 정해 둡니다.
| Claude Code | 옆 책상의 신입 직원 |
|---|---|
| 작업 폴더 | 신입에게 내준 서류함 |
| 작업 요청 | 업무 지시 |
| 권한 모드 | 결재 없이 처리해도 되는 일의 범위 |
| CLAUDE.md | 책상에 붙여 둔 업무 인수인계 메모 |
| Esc | "잠깐, 거기서 멈춰 주세요" |
비유가 맞지 않는 곳도 있습니다. 신입 직원은 "지우지 마세요"라는 말을 듣고 스스로 조심하지만, Claude Code에서 그 문장은 지시일 뿐이고 실제로 멈춰 세우는 장치는 권한 모드와 규칙입니다. 또 Claude Code는 서브에이전트로 일을 나눠 여러 작업을 동시에 진행할 수 있습니다.
비유에서 가져갈 점은 하나입니다. 신입에게 일을 맡기면 결과 서류를 직접 확인하듯이, Claude Code의 결과도 폴더의 파일을 열어 확인합니다. 실제 작업에서는 다음 순서를 지킵니다.
- 연습용 폴더를 따로 만들고 그 안에서 시작합니다. 다운로드 폴더나 회사 공유 폴더에서 처음 시작하지 않습니다.
- 읽기만 하는 요청을 먼저 보내 Claude Code가 파일을 제대로 읽었는지 확인합니다.
- 결과는 새 파일로 받고 원본은 바꾸지 않게 합니다.
- 파일 탐색기나 Finder에서 결과 파일을 직접 열어 원본 숫자와 대조합니다.
민수 씨의 CSV 합치기를 직접 해 보기
설치와 첫 실행 수업에서 만든 claude-practice 폴더를 그대로 씁니다. 아직 설치하지 않았다면 그 수업을 먼저 따라갑니다. macOS, Linux, WSL에서는 curl -fsSL https://claude.ai/install.sh | bash를, Windows PowerShell에서는 irm https://claude.ai/install.ps1 | iex를 입력해 설치합니다.
- january.csv와 february.csv를 내려받아
claude-practice폴더에 저장합니다. - 터미널에서 그 폴더로 이동해
claude --permission-mode default로 시작합니다. 상태 표시줄에manual mode on이 보이는지 확인합니다. - 앞의 표와 같은 두 요청을 차례로 보냅니다. 파일을 만들기 전에 승인을 물으면 대상이
claude-practice폴더의merged.csv인지 보고 승인합니다. merged.csv를 직접 열어 머리글 1줄과 자료 4행이 있는지, 메모장 합계가 4,000원이고 연필 합계가 6,000원인지 확인합니다.
같은 방법을 혼자 한 번 더 해 봅니다. 메모장이나 텍스트 편집기로 march.csv를 만들고 다음 세 줄을 저장합니다.
월,상품명,매출
2026-03,메모장,5000
2026-03,연필,1000이번에는 세 파일을 합쳐 merged-v2.csv로 저장해 줘. 기존 merged.csv와 원본 세 파일은 바꾸지 마.라고 요청합니다. 자료가 6행이고 합계가 메모장 9,000원, 연필 7,000원으로 나오면 세 파일을 제대로 합친 것입니다. 파일을 찾지 못한다는 답이 나오면 터미널의 현재 폴더가 claude-practice인지, 파일 이름 끝에 .txt가 덧붙지 않았는지 확인합니다.
이 다음에는 슬래시 명령과 Plan Mode를 이어서 보면 좋습니다. 사용량이 어떻게 차감되는지는 플랜과 사용량 한도에서 다룹니다.
자주 묻는 질문
Claude Code는 무료로 쓸 수 있나요?
무료 claude.ai 플랜으로는 쓸 수 없습니다. 공식 문서는 Claude Code에 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하다고 안내하며, Amazon Bedrock 같은 외부 클라우드 공급자 계정으로도 쓸 수 있습니다.
Claude Code는 어떻게 설치하나요?
macOS, Linux, WSL에서는 터미널에 curl -fsSL https://claude.ai/install.sh | bash를 입력해 설치합니다. Windows PowerShell에서는 irm https://claude.ai/install.ps1 | iex를 씁니다. 설치 중에는 진행 표시가 없고, 끝나면 새 터미널에서 claude --version으로 확인합니다. 이 방식으로 설치하면 백그라운드에서 자동으로 업데이트됩니다.
Windows에서도 Claude Code를 쓸 수 있나요?
쓸 수 있습니다. Windows 10 1809 이상 또는 Windows Server 2019 이상에서 동작하고 설치에 관리자 권한이 필요하지 않습니다. Git for Windows는 선택 사항입니다. Git for Windows가 설치되어 있으면 Claude Code가 Bash 도구를 쓰고, 없으면 PowerShell을 셸 도구로 씁니다.
작업 중인 Claude Code를 멈추려면 어떻게 하나요?
Esc를 누르면 진행 중인 응답이나 도구 호출이 멈추고 지금까지의 작업은 그대로 남습니다. 이미 바뀐 파일을 되돌리려면 Esc를 두 번 눌러 되감기 메뉴를 열고, Claude Code를 끝내려면 /exit를 입력합니다.
마무리: Claude Code에 첫 작업을 맡기기 전에 볼 것
- 계정: Pro, Max, Team, Enterprise 또는 Console 계정이 있는지 먼저 확인합니다. 무료 플랜에는 포함되지 않습니다.
- 쓸 환경: 터미널, IDE, 데스크톱 앱, 웹 가운데 하나만 골라 시작합니다.
- 권한 모드: 대화형 세션은 auto로 시작하므로, 배우는 동안은 Manual로 바꿔 확인을 받습니다.
- 결과 확인: 답의 문장이 아니라 폴더에 생긴 파일을 직접 열어 원본과 대조합니다.
결제나 설정을 바꾸지 않고 지금 해 볼 수 있는 일은 세 가지입니다.
- 연습 폴더에서
claude --permission-mode default로 시작해 상태 표시줄의manual mode on을 확인합니다. - january.csv와 february.csv를 읽기만 하게 한 뒤 merged.csv를 만들게 하고, 파일을 직접 열어 4행과 합계를 대조합니다.
- march.csv를 더해 merged-v2.csv를 만들고 합계가 메모장 9,000원, 연필 7,000원인지 확인합니다.
참고 자료
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
클로드 채팅(claude.ai)과 Claude Code의 차이로 맞는 것은 무엇일까요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.
