Claude Code 튜토리얼: 설정, 리팩터링, 디버깅 실전 가이드

Claude Code란?

Claude Code는 터미널에서 직접 동작하며, 코드베이스를 이해하고 자연어 명령으로 개발 작업을 지원하는 도구입니다. 설정이 최소화되어 개발 환경에 손쉽게 통합되므로, 코드 작성과 개선에 집중할 수 있습니다.

Claude Code의 핵심 기능은 다음과 같습니다.

• 편집과 리팩터링: AI 기반 제안으로 코드베이스를 수정, 최적화, 개선합니다.
• 버그 수정: 오류, 누락된 의존성, 성능 병목을 식별하고 해결합니다.
• 코드 이해: 아키텍처, 로직, 의존성에 대해 질문할 수 있습니다.
• 자동 테스트와 린팅: 실패한 테스트를 실행하고 수정하며, 린팅을 수행해 코드 품질을 높입니다.
• Git 통합: Git 기록 검색, 머지 충돌 해결, 커밋 생성, PR 작성까지 손쉽게 처리합니다.

오픈 소스 프로젝트든 엔터프라이즈급 코드베이스든, Claude Code는 코딩 스타일과 프로젝트 요구에 맞춰 지능적으로 자동화합니다. 최근 업데이트로 오토 모드(권한 요청 간소화), 플랜 모드(디자인 우선 워크플로), 루틴(로컬 머신이 꺼져 있어도 트리거로 동작하는 예약형 클라우드 에이전트)이 추가되었습니다.

이 서비스가 특히 유용한 사용자:

• 소프트웨어 개발자: 코드 품질과 유지보수성 향상
• 오픈 소스 기여자: 낯선 코드베이스 이해와 개선
• DevOps 엔지니어: 코드 리뷰 및 린팅 작업 자동화

Claude Code는 현재 Max 및 Team Premium 플랜에서 기본 Claude Opus 4.7을 사용합니다. Pro 사용자는 기본 Sonnet 4.6으로 시작하지만, 고난도 작업에는 Opus 모델로 전환할 수 있습니다. 세션 중 /model 명령으로 모델을 바꾸거나 /effort 슬라이더로 추론 강도를 조절할 수 있습니다. 또한 Claude Agents SDK로 독립형 AI 에이전트를 구축할 수도 있습니다.

Anthropic은 또한 코딩을 넘어 일상적인 파일·문서 작업을 돕는 에이전트형 도우미인 Cowork을 도입했습니다. Claude 데스크톱 앱에서 모든 유료 플랜(Pro, Max, Team, Enterprise) 구독자가 이용할 수 있습니다.

xAI의 터미널 에이전트와 Claude Code를 비교 중이라면, 동일 과제로 테스트한 Grok Build vs. Claude Code 비교 글을 참고하세요.

이제 실습 프로젝트를 시작해 보겠습니다.

1단계: Claude Code 설정

Claude Code를 시작하려면 터미널, 작업할 코드 프로젝트, 그리고 Claude 구독(Pro/Max/Teams/Enterprise) 또는 활성 결제가 설정된 Claude Console 계정이 필요합니다.​

운영체제와 터미널에 따라 아래 명령 중 하나를 터미널에서 실행하여 간단히 설치하세요.

macOS / Linux / WSL: 

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

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

참고: npm install -g @anthropic-ai/claude-code를 통한 설치는 여전히 가능하지만 더 이상 권장되지 않으므로 위의 네이티브 설치 방식을 사용하는 것이 좋습니다. 과거에 npm으로 설치했다면 claude install로 마이그레이션할 수 있습니다.

설치가 완료되면 프로젝트 디렉터리로 이동하여 다음을 실행해 Claude를 시작하세요.

cd your-project-directory
claude

인증 단계에서 유료 구독 기반으로 사용할지, API 사용량 결제로 사용할지 선택하도록 안내됩니다.

이후 터미널에 입력할 인증 코드가 포함된 로그인 링크를 받게 됩니다. 코드를 입력하면 설정이 완료되며, "Claude Code" 전용 워크스페이스가 자동으로 생성되어 사용량 추적과 비용 관리를 지원합니다.

이제 Claude Code를 사용할 준비가 되었습니다.

2단계: 개발 환경 설정

이번 데모에서는 Supabase와 상호작용하는 오픈 소스 Python 클라이언트인 supabase-py를 사용합니다. Supabase는 PostgreSQL 기반의 BaaS로, 인증, 실시간 구독, 스토리지, 자동 생성 API 등 다양한 도구를 제공합니다.

리포지토리를 클론하고 개발 환경을 설정해 보겠습니다.

1. 터미널을 열고 Supabase-py 리포지토리를 클론할 디렉터리(예: cd Desktop)로 이동한 후 다음 명령을 실행합니다.

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. 다음으로, 가상 환경을 만들고 필요한 의존성을 설치합니다. 아래 명령을 터미널에서 한 줄씩 실행하세요.

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

이제 Supabase 라이브러리를 실행하는 데 필요한 모든 의존성이 갖춰진 Python 환경이 구성되었으며, 리포지토리 탐색을 시작할 수 있습니다. 

3단계: 기여 영역 파악

기여를 시작하는 좋은 방법은 GitHub의 Issues 탭을 살펴보는 것입니다. Supabase 리포지토리에서 가독성, 구조, 의미 있는 주석 부족과 관련된 client.py 이슈를 확인했습니다.

Claude Code로 다음을 수행하겠습니다.

• 코드의 가독성, 유지보수성, 구조를 높이도록 리팩터링합니다.
• 모듈·함수의 목적을 명확히 하는 도크스트링과 인라인 주석을 추가합니다.
• 이슈와 잠재적 오류를 분석해 버그를 식별하고 수정합니다.

4단계: Claude Code로 실험하기

이미 supabase-py 폴더에 있는 상태라면, client.py 파일이 있는 supabase 디렉터리로 이동해 Claude Code를 실행합니다.

cd supabase
claude

이제 Claude Code는 Supabase-py 폴더 내 모든 파일과 폴더에 접근할 수 있습니다. 실험을 시작해 보겠습니다.

코드 리팩터링

Supabase Python SDK 개선의 일환으로 client.py를 리팩터링해 가독성, 유지보수성, 구성도를 높여 보겠습니다. 다음 프롬프트를 커맨드 라인에 입력하세요.

프롬프트: Supabase 폴더에 있는 client.py의 코드를 리팩터링해 주세요.

진행 전에 Claude가 확인을 요청합니다. 변경 승인에는 Enter 키를 누르세요. 완료되면 파일이 업데이트되고, 터미널에 변경 사항이 표시되며 요약이 제공됩니다.

Claude Code를 사용해 client.py에 다음과 같은 개선을 적용했습니다.

• 임포트 정리:  관련 임포트를 논리적 섹션(인증 오류, API 타입, 함수 오류)으로 그룹화하고, 가독성을 위해 이름을 정리했으며, 일관성을 위해 불필요한 별칭을 제거했습니다.
• 가독성 향상: 임포트를 구분하는 섹션 주석을 추가하고, 더 깔끔한 구성을 위해 __all__ 목록의 중복을 제거했습니다.
• 클라이언트 옵션 단순화: 유사한 임포트를 한 문장으로 결합해 여러 줄을 줄였습니다.

아래는 원본과 리팩터링 코드의 비교입니다.

코드 문서화

리팩터링 외에도 Claude Code는 프로젝트 전반의 코드 문서를 생성, 업데이트, 표준화할 수 있습니다. 문서화되지 않은 부분을 찾아 구조화된 도크스트링이나 주석을 생성하고, 프로젝트 문서 표준 준수 여부를 점검합니다.

Claude Code로 client.py의 문서를 개선한 결과는 다음과 같습니다.

• 파일 목적을 설명하는 모듈 수준 도크스트링 추가
• 임포트를 분류하는 상세 섹션 주석(오류 타입, 클라이언트 구현, 스토리지 서비스)
• 오류 타입, 클라이언트 함수, 핵심 구성요소를 설명하는 인라인 주석

아래는 리팩터링 코드와 문서화된 코드의 비교입니다.

프롬프트: 이해를 돕도록 client.py 코드에 주석을 추가해 문서화해 주세요.

문서화를 마친 뒤에는 다음과 같이 프롬프트를 입력해 프로젝트 표준 준수 여부를 확인할 수 있습니다.

프롬프트: 문서가 우리 프로젝트 표준을 따르는지 확인해 주세요.

버그 수정

디버깅은 시간이 오래 걸릴 수 있지만, Claude Code는 오류 메시지를 분석해 근본 원인을 파악하고 수정안을 제시함으로써 사이클을 단축합니다. 누락된 임포트, 런타임 오류, 로직 문제 등에서 검색 범위를 좁히고 정밀한 수정을 제안합니다.

Claude Code로 디버깅하는 방법은 다음과 같습니다.

1. 문제 식별:  오류 메시지를 Claude에 공유합니다.
2. 수정안 받기: 가능한 해결책을 요청합니다.
3. 적용 및 검증:  제안된 수정을 적용하고 문제가 해결됐는지 확인합니다.

Claude Code는 client.py의 임포트 관련 문제를 해결하기 위해 다음과 같이 조치했습니다. 

• 타입 무시 주석: 해결되지 않은 임포트에 대한 IDE 및 타입 검사 경고를 억제하기 위해 # type: ignore 주석을 추가했습니다.
• 일관된 오류 분류: 인증, 데이터베이스, 스토리지, 함수 관련 오류 임포트를 명확히 그룹화했습니다.
• 가독성 유지: 임포트를 제거하는 대신 무시 이유를 설명하는 주석을 추가했습니다.

아래는 원본 코드와 수정된 코드의 비교입니다.

프롬프트: 'Import gotrue.errors'를 해결할 수 없음 등 버그가 보입니다. client.py의 모든 오류를 고칠 수 있도록 도와주세요.

Claude Code 명령어

Claude에서 시도해 볼 수 있는 몇 가지 명령어입니다.

더 자세한 내용은 Claude Code 슬래시 명령어 가이드를 참고하세요.

고급 Claude Code 기능

리팩터링과 디버깅의 기본에 익숙해졌다면, 동작 방식을 커스터마이즈하여 Claude Code의 기능을 확장할 수 있습니다. 훅과 플러그인은 반복 작업을 자동화하고 외부 시스템과 통합하도록 합니다.

Claude Code 훅

Claude Code 훅은 세션 중 특정 이벤트가 발생할 때 셸 명령을 실행하는 자동 트리거입니다. 코드 포매팅, 테스트 실행, 보안 점검 등 Claude가 생략할 수 있는 반복 작업을 자동화합니다.

훅은 이벤트-액션 방식으로 동작하며, 다음 세 가지를 정의합니다.

• 이벤트: 언제 훅이 트리거되는가?

• 매처: 어떤 작업에 적용되는가?

• 명령: 트리거 시 무엇을 실행하는가?

예를 들어, Claude가 Python 파일을 쓴 뒤 자동으로 black을 실행해 포매팅하도록 설정할 수 있습니다. 훅은 발생한 일에 대한 JSON 컨텍스트를 받아 파일 유형이나 경로에 따라 지능적으로 판단합니다. 결과를 Claude 대화 기록에 출력하거나 오류 메시지를 Claude로 전달해 작업을 차단할 수도 있습니다.

일반적인 활용 예는 다음과 같습니다.

• 코드 포매팅: 코드 작성 후 자동으로 린터와 포매터 실행

• 테스트: 수정 후 테스트 스위트를 실행해 조기 버그 포착

• 보안: 운영 설정이나 API 키 같은 민감 파일의 변경 차단

• 문서화: 소스 변경 시 API 문서 자동 생성

• Git 자동화: 스마트 커밋 생성 및 브랜치 보호 정책 검증

• 알림: 중요 파일 변경 시 Slack으로 팀에 알림

• 컴플라이언스: 변경 허용 전 라이선스 헤더나 코딩 표준 강제

훅은 Claude Code에서 /hooks 명령으로 설정하거나 ~/.claude/settings.json 파일을 직접 편집해 구성할 수 있습니다.

Claude Code 플러그인

플러그인은 Claude Code를 외부 도구, 서비스, API와 연결하는 확장 기능입니다. 훅이 로컬 셸 명령 자동화에 초점을 맞춘다면, 플러그인은 CI/CD 파이프라인, 프로젝트 관리 도구, 팀 커뮤니케이션 플랫폼 등 더 넓은 개발 생태계와의 통합을 담당합니다.

플러그인은 서브에이전트(특정 작업에 특화된 Claude 보조), MCP 서버(표준화된 도구 통합), 훅 등을 하나의 패키지로 묶어 오케스트레이션할 수 있습니다.

예를 들어, 코드 변경을 분석해 Jira에 이슈를 자동 등록하거나 내부 테스트 인프라와 연결할 수 있습니다. 플러그인은 훅과 동일한 이벤트에 반응하되, 데이터를 외부 서비스로 전송하고 응답을 처리해 Claude의 워크플로에 영향을 줍니다.

Claude Code 플러그인이 특히 유용한 작업은 다음과 같습니다.

• CI/CD 통합: 파일 변경 시 빌드, 테스트, 배포 트리거

• 프로젝트 관리: Jira, GitHub, Linear에서 이슈 자동 생성·업데이트

• 팀 커뮤니케이션: 변경 발생 시 Slack이나 Teams에 업데이트 게시

• 코드 리뷰: PR 자동 생성 및 GitHub/GitLab 리뷰 관리

• 외부 분석: 엔터프라이즈 코드 스캐닝을 위해 SonarQube, CodeClimate, Snyk 호출

• 맞춤형 도구: 사내 시스템과 워크플로 통합

• IDE 확장: 사용자 정의 명령과 내비게이션 도우미 추가

플러그인은 레지스트리에서 설치하거나 조직 내부에서 제작해 사용할 수 있으며, 반응할 이벤트를 구성합니다. 훅과 플러그인을 함께 사용하면 기존 인프라에 맞춰 확장 가능한 플랫폼을 구축할 수 있습니다.

기타 고급 기능

Claude Code는 2026년에 활용 범위를 넓히는 주요 기능을 여럿 추가했습니다.

• 플랜 모드: 코드를 작성하기 전 상세 구현 계획을 수립하는 디자인 우선 워크플로. 복잡한 작업에 권장합니다.
• 오토 모드: 권한 분류기를 사용해 승인 요청을 줄이는 모드로, 파일 쓰기마다 승인하고 싶지 않은 장기 작업에 유용합니다.
• 루틴: 크론 스케줄, GitHub 이벤트(PR 생성 등), 웹훅 트리거로 실행되는 예약형 클라우드 에이전트. 로컬 머신이 켜져 있을 필요가 없습니다.
• IDE 통합: VS Code, Cursor, JetBrains IDE용 공식 확장 제공. 인라인 디프, 체크포인트, 멀티 세션 지원.
• 원격 제어와 채널: 휴대폰이나 다른 기기에서 Claude Code 세션을 실행하고 상호작용합니다.

마무리

이 튜토리얼에서는 Supabase Python SDK의 한 파일을 Claude Code로 리팩터링, 문서화, 디버깅했습니다. 코드 가독성을 개선하고 구조화된 문서를 추가했으며, 임포트 문제를 해결했습니다.

Claude Code는 플랜 모드, 오토 모드, 루틴 등 계속 진화하고 있습니다. 자신의 프로젝트에 적용해 워크플로에 어떻게 맞는지 실험해 보세요.

다음 단계로, Claude의 컨텍스트 윈도를 최대한 활용하는 방법을 다룬 Claude Code 모범 사례 튜토리얼을 읽어 보세요. 처음부터 프로젝트를 구축하고 싶다면 Claude Code로 하는 스펙 주도 개발 튜토리얼을 권장합니다.