Claude Code Deep Dive - 1(Overview)

Claude Code Deep Dive

오늘은 가시다님과 함께하는 스터디 중에 Claude Code 를 사용하면서 학습을 하는 내용을 작성해 본다. 해당 내용의 경우 AWS 최우형 님의 github 자료를 통해 실습을 진행한다.

Claude Code 란

Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며 개발도구와 통합되는 Anthropic의 Agentic Coding 도구입니다. 자연어 지시를 받아 멀티 스텝 작업을 자율적으로 완수합니다.

클로드 코드의 모델

클로드 코드의 모델은 다음과 같은 모델들이 있습니다.

Claude Code에서는 작업의 성격에 따라 서로 다른 Claude 모델을 선택할 수 있다. 모델마다 추론 능력과 응답 속도, 사용량에 차이가 있으므로 상황에 맞게 선택하는 것이 좋다.

다만 Claude Code에서는 정확한 모델 버전 대신 opus, sonnet, haiku와 같은 모델 별칭(alias) 을 주로 사용한다. 별칭이 가리키는 실제 모델은 Claude Code 업데이트나 사용 중인 플랫폼에 따라 변경될 수 있다.

모델 별칭은 정확한 버전 번호를 기억할 필요 없이 모델 설정을 선택하는 편리한 방법을 제공한다. 아래는 공식 문서에서 별칭 부분을 복사해서 가지고 왔다.

opus 및 sonnet 별칭이 확인되는 버전은 제공자에 따라 다릅니다:

Claude Code를 실행한 후 다음 명령을 입력하면 모델 선택 화면을 열 수 있다.

/model

현재 세션에서 특정 모델을 선택할 수도 있다.

/model sonnet
/model opus
/model haiku

Claude Code를 실행할 때부터 모델을 지정하는 방법도 있다.

claude --model sonnet
claude --model opus
claude --model opusplan

모델 지정에는 다음과 같은 우선순위가 적용된다.

1. 실행 중 /model 명령으로 선택한 모델
2. claude --model 옵션으로 지정한 모델
3. ANTHROPIC_MODEL 환경 변수
4. Claude Code 설정 파일의 model 값
5. 계정에 지정된 기본 모델

일반적인 실습과 코드 작성에는 sonnet이 무난하다. 복잡한 설계나 원인 파악이 어려운 문제에는 opus가 유리하지만, 상대적으로 사용량을 더 빠르게 소모할 수 있다.

모델 별칭과 실제 버전은 Claude Code 업데이트 및 플랫폼에 따라 변경될 수 있다. 따라서 워크숍 자료의 모델 표는 참고용으로 보고, 실제 환경에서는 /model과 /status 명령으로 확인하는 것이 좋다.

Claude Code 실습 환경 구성

Claude Code는 단순한 챗봇이 아니다. 현재 디렉터리의 파일을 읽고 수정하며, 필요한 경우 셸 명령까지 실행하는 Agentic Coding 도구다.

실습 환경과 개인 PC의 파일을 분리하고, 실습이 끝난 후에도 동일한 환경을 유지하기 위해 Proxmox에 Ubuntu VM을 별도로 생성했다. VS Code의 Remote SSH 기능을 사용하면 로컬 PC에서 작업하는 것과 비슷한 방식으로 VM의 프로젝트를 편집할 수도 있다.

이번 실습에 사용한 VM 사양은 다음과 같다.

이름: claude-lab-01

OS: Ubuntu Server 24.04 LTS

CPU: 4코어, Type=host

RAM: 8GB

디스크: 50GB, local-lvm

디스크 컨트롤러: VirtIO SCSI

네트워크: VirtIO

QEMU Guest Agent: 활성화

VM 생성 후 SSH를 설정하고 VS Code에서 접속할 수 있도록 구성했다. 이번 실습은 내부 네트워크와 VPN을 통해 접속하는 형태로 진행했다.

Claude Code 설치

AWS 최우형 님의 실습 자료와 Claude Code 공식 문서를 참고하여 위에서 생성한 리눅스 머신에 설치를 진행했다.

Claude Code는 여러 가지 설치 방법을 제공하지만, 공식 문서에서는 Native Installer 사용을 권장한다.

Native Installer는 Node.js를 미리 설치하지 않아도 되며 Claude Code 업데이트도 자동으로 처리한다.

아래의 명령어를 입력하여 cluade code 를 설치한다.

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

위 명령은 최신 버전의 Claude Code를 설치한다. 최신 기능보다 안정적인 버전을 우선하고 싶다면 stable 채널을 지정할 수도 있다.

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

설치가 끝났는데 claude 명령을 찾지 못한다면 실행 파일이 설치된 경로를 PATH에 추가한다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

PATH가 정상적으로 적용되었는지 확인한다.

command -v claude
claude --version

Claude Code의 설치 상태와 환경 문제는 다음 명령으로 진단할 수 있다.

claude doctor

정상적으로 설치되었다면 Claude Code의 경로와 버전 정보가 출력된다.

Native Installer로 설치한 Claude Code는 백그라운드에서 자동으로 업데이트된다. 필요하다면 다음 명령으로 직접 업데이트를 확인할 수도 있다.

claude update

Claude Code는 무료 Claude 계정만으로는 사용할 수 없다. Claude Pro, Max, Team, Enterprise 구독이나 Anthropic Console 계정, 또는 Bedrock·Vertex AI·Foundry와 같은 외부 모델 제공 환경이 필요하다.

설치 방법에 관한 자세한 내용은 Claude Code 고급 설치 공식 문서에서 확인할 수 있다.

설치 후 인증

나는 구독형이라, 인증을 로그인을 통해서 하였다. 클로드를 실행시키고, 링크가 표출이 되는데, 그 링크를 PC 에서 열어 인증하고 그 다음에 인증이 성공하면 브라우저에 나온 일회성 인증 코드를 claude code 내에 입력하면 인증이 완료된다.

인증이 성공적으로 완료 되면 다음과 같은 형태로 로그인이 되어 사용할 준비가 된다.

클로드 코드 사용

REPL

Claude Code를 실행하면 터미널에서 Claude와 대화할 수 있는 REPL 환경이 시작된다.

claude 를 실행해서 여러가지 작업을 단순 cli 에서 테스트 해 본다.

작업 흐름에 따른 슬래시 명령

Claude Code에는 프로젝트 설정, 컨텍스트 관리, 작업 분산, 코드 검토 등 다양한 기능을 제어할 수 있는 슬래시 명령이 있다.

명령어를 모두 외우기보다는 실제 개발 작업의 어느 단계에서 사용하는지를 기준으로 구분하면 이해하기 쉽다.

아래는 github 기준의 명령어들을 정리해 보았다.

첫 번째 프로젝트에서는 /init을 실행해 CLAUDE.md를 생성하고, /permissions로 Claude Code가 실행할 수 있는 도구의 권한을 확인한다.

규모가 있는 작업을 시작할 때는 /plan으로 먼저 구현 계획을 세울 수 있다.

대화가 길어지면 /context로 컨텍스트 사용 현황을 확인하고, /compact로 지금까지의 대화를 요약해 컨텍스트를 확보한다.

아래는 /context 입력시의 스크린 샷이다.

코드 수정이 끝난 후에는 /diff로 변경 사항을 확인한다. /code-review와 /security-review를 이용하면 코드 품질과 보안 관점의 검토도 요청할 수 있다.

예를 들어 다음과 같은 흐름으로 사용할 수 있다.

/init
/permissions
/plan 사용자 인증 기능을 추가해 주세요.
 
/context
/diff
/code-review
/security-review

작업 중 문제가 발생했다면 /rewind로 이전 체크포인트를 확인하거나, /doctor와 /debug를 사용해 설치 상태와 실행 문제를 진단할 수 있다.

사용할 수 있는 명령은 Claude Code 버전과 계정 플랜, 플랫폼에 따라 달라질 수 있다. 현재 환경에서 지원되는 명령은 입력창에 /를 입력하거나 /help를 실행해 확인하는 것이 가장 정확하다. 자세한 내용은 Claude Code Commands 공식 문서에서 확인할 수 있다.

프롬프트와 첫 실습

프롬프트의 경우 모호하게 주는 것이 아니라 구체적으로 지시를 주어야 한다.

먼저 실습을 위해 아래 저장소를 다운받아 본 후 실행해 본다.

git clone --depth 1 https://github.com/mdn/express-locallibrary-tutorial.git
cd express-locallibrary-tutorial
claude

claude code cli 가 열리면 다음과 같이 입력 해 본다.

이 프로젝트의 디렉터리 구조와 실행 방법을 설명해 주세요.
아직 파일은 수정하지 말고, 근거가 되는 파일 경로도 함께 알려 주세요.

해당 프롬프트 두 줄로 아래와 같이 프로젝트가 간단히 분석 된 것을 확인 해 볼 수 있다.

에러 수정

다음과 같은 프롬프트로 에러에 대한 수정 요청을 할 수 있다.

GET /users/999 요청에서 오류가 발생합니다.
 
1. 관련 코드를 찾아 원인을 분석해 주세요.
2. 아직 코드를 수정하지 말고 수정 계획을 먼저 설명해 주세요.
3. 승인을 받은 후 코드를 수정하고 테스트를 실행해 주세요.

위와 같은 형태로 리팩토링 및 테스트 코드 작성도 가능하다.

PLAN 모드

실행 중에는 Shift+Tab을 눌러 Manual → Accept Edits → Plan 모드를 순환할 수 있다.

소스코드를 수정하지 않고, 탐색 및 설계만 수행하는 단계이다.

나는 새로운 프로젝트를 예시로 들기 위해 신규 폴더를 만들고 plan 모드를 작성해 보았다.

위와 같이 어떻게 만들지 사용자에게 질문을 하면서 구체화 해 가는 것을 확인 할 수 있다.

세션 관리

claude -c 를 입력 시, 폴더 내에서 가장 최근 세션을 불러온다.

--continue 옵션을 주면 위 -c 와 같고 --resume 은 세션 목록에서 실행을 할 수 있다.

CLAUDE.md 실습

프로젝트 루트에서 /init 을 실행한다.

신규 프로젝트를 만들어 보기 위해 새 폴더에서 실행했더니, claude.md 를 프로그램을 만든 다음에 생성한다고 한다.

한참 지난 이후 claude code 가 프로젝트를 생성하고 다음 CLAUDE.md 파일을 생성하였다.

실습으로 간단한 HTML 사이트를 만들었고, 해당 프로그램의 링크를 공유한다. https://pomodoro.devchanki.com/