테마
01. Claude Code 개요
AI 개발 파트너의 핵심 개념과 아키텍처를 이해한다.
1. Claude Code란?
Claude Code는 Anthropic이 만든 터미널(CLI) 기반 AI 개발 도구다. 브라우저 채팅창에서 코드 조각만 생성하는 기존 AI 도구와 근본적으로 다르다. Claude Code는 개발자의 터미널에 직접 들어와서 파일 시스템을 읽고, 코드를 수정하고, 명령어를 실행하며, 개발 워크플로우 전체를 함께 수행하는 AI 파트너다.
핵심 특징
| 특징 | 설명 |
|---|---|
| 터미널 네이티브 | 별도 GUI 없이 터미널에서 claude 명령어로 바로 실행한다 |
| 파일 시스템 접근 | 프로젝트 파일을 직접 읽고, 편집하고, 생성할 수 있다 |
| 명령어 실행 | git, npm, make 등 시스템 명령어를 직접 실행한다 |
| 컨텍스트 인식 | 프로젝트 구조, 코드 패턴, 커밋 히스토리를 파악한다 |
| 대화형 | 자연어로 대화하며 작업을 진행한다 |
단순 코드 생성 vs. AI 개발 파트너
Claude Code가 기존 AI 코드 생성 도구와 다른 점을 명확히 이해해야 한다.
기존 AI 코드 생성 도구:
사용자: "로그인 함수 만들어줘"
AI: (코드 스니펫 출력)
사용자: (수동으로 복사 → 붙여넣기 → 수정 → 테스트)
Claude Code:
사용자: "로그인 기능 구현해줘"
Claude: (프로젝트 구조 분석 → 관련 파일 탐색 → 코드 작성 → 파일 저장 → 테스트 실행 → 결과 확인)Claude Code는 분석, 계획, 구현, 테스트, 배포 전 과정을 지원한다. 개발자가 각 단계에서 승인하면서 함께 일하는 구조다.
2. Claude Code의 전체 아키텍처
Claude Code가 어떤 구조로 동작하는지 전체 그림을 먼저 파악하자.
이 다이어그램에서 핵심은 도구 라우터와 권한 시스템이다. 사용자가 자연어로 요청하면, Claude Code 엔진이 적절한 도구를 선택하고, 권한 시스템이 해당 도구의 실행을 제어한다. 읽기 도구는 자동 승인되지만, 쓰기와 실행 도구는 사용자 승인이 필요하다.
3. Claude Code가 사용하는 도구들
Claude Code는 다양한 내장 도구를 사용하여 개발 작업을 수행한다. 각 도구는 권한 등급에 따라 분류된다.
읽기 도구 (승인 불필요)
읽기 도구는 파일 시스템을 변경하지 않기 때문에 자동으로 승인된다. Claude Code가 프로젝트를 파악할 때 가장 많이 사용하는 도구들이다.
| 도구 | 기능 | 사용 예 |
|---|---|---|
| ls | 디렉토리 내 파일/폴더 목록 조회 | 프로젝트 구조 파악 |
| Glob | 패턴 기반 파일 검색 (**/*.ts) | 특정 확장자 파일 찾기 |
| Grep | 파일 내용 텍스트 검색 (정규식 지원) | 함수 정의, 변수 사용처 찾기 |
| Read | 파일 내용 읽기 (줄 번호 포함) | 코드 분석, 설정 파일 확인 |
쓰기 도구 (승인 필요)
쓰기 도구는 파일을 변경하므로 사용자의 명시적 승인이 필요하다.
| 도구 | 기능 | 사용 예 |
|---|---|---|
| Edit | 기존 파일의 특정 부분 수정 (diff 방식) | 버그 수정, 리팩토링 |
| Write | 새 파일 생성 또는 전체 덮어쓰기 | 새 컴포넌트 생성, 설정 파일 작성 |
실행 도구 (승인 필요)
시스템 명령어를 실행하는 도구다. 잘못된 명령이 시스템에 영향을 줄 수 있으므로 반드시 승인이 필요하다.
| 도구 | 기능 | 사용 예 |
|---|---|---|
| Bash | 셸 명령어 실행 | git commit, npm test, make build |
관리 도구
작업 흐름을 관리하는 내부 도구들이다.
| 도구 | 기능 | 사용 예 |
|---|---|---|
| TodoWrite | 작업 목록(체크리스트) 생성 및 관리 | 복잡한 작업을 단계별로 추적 |
| Task | 서브에이전트에게 작업 위임 | 독립적인 조사 작업을 병렬로 수행 |
| Skill | 등록된 기술(Skill) 호출 | 특화된 도구 세트 활성화 |
웹 도구
외부 웹 리소스에 접근하는 도구들이다.
| 도구 | 기능 | 사용 예 |
|---|---|---|
| WebFetch | 지정 URL의 콘텐츠 가져오기 | API 문서 참조, 라이브러리 홈페이지 확인 |
| WebSearch | 웹 검색 수행 | 에러 메시지 검색, 최신 문서 찾기 |
4. 실행 방법
기본 실행
Claude Code는 터미널에서 claude 명령어로 실행한다. 반드시 프로젝트 디렉토리 안에서 실행해야 한다. 프로젝트 디렉토리 밖에서 실행하면 Claude Code가 프로젝트 맥락을 파악할 수 없다.
bash
# 프로젝트 디렉토리로 이동 후 실행
cd ~/my-project
claude
# 특정 질문과 함께 실행
claude "이 프로젝트의 구조를 설명해줘"세션 이어가기
Claude Code는 대화 세션을 저장한다. 이전 세션을 이어서 작업할 수 있다.
bash
# 가장 최근 세션 이어가기
claude --continue
# 대화 안에서 이전 세션 복원
/resume--continue는 CLI 옵션이고, /resume은 대화 중 사용하는 슬래시 명령어다. /resume을 사용하면 이전 대화 목록에서 원하는 세션을 골라 복원할 수 있다.
IDE 통합
Claude Code는 다양한 IDE와 함께 사용할 수 있다.
Cursor IDE:
Cursor의 내장 터미널에서 claude를 실행하면 된다. Cursor의 AI 기능과 Claude Code를 동시에 활용할 수 있다. Cursor의 AI는 코드 자동완성에, Claude Code는 복잡한 작업 수행에 각각 강점이 있다.
VS Code:
VS Code 확장 프로그램이 존재하지만, 보조 도구로만 사용하는 것을 권장한다. 핵심 작업은 터미널에서 Claude Code를 직접 실행하는 것이 가장 안정적이다.
권장 사용 방식: IDE의 터미널 패널에서 Claude Code를 실행한다. 코드 편집기와 AI를 한 화면에서 볼 수 있어 효율적이다.
비대화형 모드
스크립트나 CI/CD에서 Claude Code를 자동화할 수도 있다.
bash
# 프롬프트를 직접 전달하고 결과만 받기
claude -p "package.json에서 의존성 목록을 추출해줘"
# 파이프로 입력 전달
cat error.log | claude -p "이 에러 로그를 분석해줘"5. 개발 워크플로우 사이클
Claude Code의 핵심 가치는 개발 워크플로우 전체 단계를 지원한다는 점이다. 아래 사이클은 AI 도구 없이도 개발자가 항상 거치는 흐름이다. Claude Code는 각 단계를 가속한다.
각 단계에서 Claude Code 활용법
1단계 - 요구사항 분석:
"이 프로젝트의 현재 구조를 분석하고, 사용자 인증 기능을 추가하려면
어떤 부분을 수정해야 하는지 알려줘"Claude Code가 프로젝트를 탐색하고, 기존 코드 패턴을 파악하고, 수정이 필요한 파일 목록을 제시한다.
2단계 - 계획 수립:
"JWT 기반 인증을 구현하려고 해. 구현 계획을 세워줘.
파일 구조, 필요한 패키지, API 엔드포인트를 포함해서"Claude Code가 프로젝트의 기존 패턴에 맞는 구현 계획을 제안한다. TodoWrite로 작업 목록도 만든다.
3단계 - 구현:
"계획대로 인증 미들웨어부터 구현해줘"Claude Code가 파일을 생성하고, 코드를 작성하고, 기존 파일을 수정한다. 각 변경 사항에 대해 승인을 요청한다.
4단계 - 테스트:
"작성한 인증 코드에 대한 테스트를 작성하고 실행해줘"Claude Code가 테스트 파일을 작성하고, 테스트를 실행하고, 실패하면 원인을 분석하여 수정한다.
5단계 - 배포:
"변경사항을 커밋하고, PR 설명문을 작성해줘"Claude Code가 적절한 커밋 메시지를 생성하고, PR 템플릿에 맞는 설명문을 작성한다.
6. 프로젝트 초기화
/init 명령어
새 프로젝트에 Claude Code를 도입하거나, 기존 프로젝트에서 처음 사용할 때 /init 명령어를 실행한다.
/init이 명령어를 실행하면 Claude Code가 다음 작업을 수행한다:
- 프로젝트 구조 분석 - 디렉토리 구조, 사용 언어, 프레임워크를 파악한다
- 빌드/테스트 명령 탐지 - package.json, Makefile, Cargo.toml 등에서 빌드 방법을 추출한다
- 코딩 컨벤션 파악 - 기존 코드의 스타일, 네이밍 규칙, import 패턴을 분석한다
- CLAUDE.md 생성 - 위 분석 결과를 담은 프로젝트 지침 파일을 생성한다
CLAUDE.md란?
CLAUDE.md는 Claude Code가 프로젝트를 이해하기 위해 읽는 지침 파일이다. Claude Code가 대화를 시작할 때 자동으로 읽는다. 이 파일에 프로젝트의 빌드 방법, 테스트 실행 방법, 코딩 규칙 등을 적어두면, Claude Code가 해당 프로젝트에 맞게 동작한다.
markdown
# CLAUDE.md 예시
## 빌드
npm run build
## 테스트
npm test
## 코딩 규칙
- TypeScript strict 모드 사용
- 함수형 컴포넌트만 사용
- 테스트 파일은 __tests__ 디렉토리에 배치CLAUDE.md에 대한 자세한 내용은 05장(메모리 관리)에서 다룬다.
7. Claude Code의 동작 흐름
사용자가 프롬프트를 입력했을 때 Claude Code 내부에서 어떤 일이 일어나는지 이해하면, 더 효과적으로 활용할 수 있다.
이 흐름에서 주목할 점:
- 컨텍스트 수집이 먼저 일어난다. CLAUDE.md, 프로젝트 구조, 이전 대화 이력이 모두 컨텍스트에 포함된다.
- 도구 호출은 반복된다. 한 번의 프롬프트에 대해 Claude가 여러 도구를 순차적으로 호출할 수 있다. 예를 들어 "버그 수정해줘"라고 하면, 먼저 파일을 읽고(Read), 문제를 분석하고, 코드를 수정하고(Edit), 테스트를 실행한다(Bash).
- 승인은 위험한 도구에만 필요하다. 읽기 도구는 자동 실행되고, 쓰기/실행 도구만 사용자 승인을 거친다.
8. 핵심 단축키 및 팁
Claude Code와의 대화를 효율적으로 진행하기 위한 핵심 단축키와 팁이다.
대화 제어
| 단축키 | 기능 | 설명 |
|---|---|---|
| Esc | 작업 중단 | Claude Code가 도구를 실행 중일 때 즉시 중단한다. 잘못된 방향으로 가고 있을 때 사용한다. |
| 방향키 위 | 이전 프롬프트 복원 | 마지막으로 입력한 프롬프트를 다시 불러온다. 약간 수정해서 다시 보낼 때 유용하다. |
| Esc 2번 | 프롬프트 이력 탐색 | 이전에 입력한 프롬프트 목록을 탐색할 수 있다. |
입력 편의
| 단축키 | 기능 | 설명 |
|---|---|---|
| Shift+Enter | 줄바꿈 | 프롬프트 안에서 여러 줄을 입력할 때 사용한다. Enter만 누르면 전송된다. |
| @파일명 | 파일 참조 | 특정 파일을 명시적으로 컨텍스트에 포함시킨다. @src/auth.ts 이 파일의 버그를 찾아줘처럼 사용한다. |
화면 제어
| 단축키 | 기능 | 설명 |
|---|---|---|
| Ctrl+R | 숨겨진 내용 확대/축소 | Claude Code가 긴 출력을 접어서 보여줄 때, 전체 내용을 펼쳐 볼 수 있다. |
실용 팁
Esc 키를 적극 활용하자. Claude Code가 잘못된 방향으로 작업을 진행하고 있다면, Esc를 눌러 즉시 중단하고 방향을 재설정하는 것이 토큰을 아끼는 가장 좋은 방법이다. 잘못된 작업이 끝날 때까지 기다리면 토큰만 낭비된다.
@파일명으로 정확한 컨텍스트를 제공하자. Claude Code가 스스로 파일을 찾아 읽을 수도 있지만, 미리 관련 파일을 @로 지정해주면 불필요한 탐색 없이 바로 핵심 작업에 들어갈 수 있다.
세션을 자주 이어가자. claude --continue를 습관화하면, 이전 대화에서 쌓은 맥락을 유지하면서 작업을 이어갈 수 있다. 새 세션을 열 때마다 Claude Code는 프로젝트를 처음부터 파악해야 하므로 토큰이 더 소비된다.
9. 정리
이 챕터에서 배운 핵심 내용을 정리한다.
| 개념 | 핵심 포인트 |
|---|---|
| Claude Code의 정체 | 터미널 기반 AI 개발 파트너. 코드 생성기가 아니라 워크플로우 전체를 함께하는 도구 |
| 도구 체계 | 읽기(자동 승인), 쓰기(승인 필요), 실행(승인 필요), 관리, 웹 도구로 분류 |
| 실행 방법 | 프로젝트 디렉토리에서 claude 실행. --continue로 세션 이어가기 |
| 워크플로우 | 분석 - 계획 - 구현 - 테스트 - 배포의 반복 사이클을 가속 |
| 초기화 | /init으로 프로젝트 분석 및 CLAUDE.md 자동 생성 |
| 동작 원리 | 컨텍스트 수집 - 모델 추론 - 도구 호출 반복 - 최종 응답 |
다음 챕터(02. 권한 시스템)에서는 Claude Code의 3계층 권한 구조와 4가지 실행 모드를 상세히 다룬다.