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

Anthropic의 Claude Code를 활용해 Supabase Python 라이브러리를 예제로 소프트웨어 개발 워크플로를 개선하는 방법을 배워보세요.

업데이트됨 2026년 5월 28일 · 12분 읽다

Claude Code는 Anthropic이 개발한 터미널 기반 에이전트형 코딩 도구로, 리팩터링, 문서화, 디버깅을 효율적으로 도와줍니다. 전체 코드베이스를 이해하여 소프트웨어 개발 생애주기 전반의 워크플로를 단순화합니다. 2026년 1월부터 Anthropic은 Max 요금제의 기본 모델로 Claude Code 2.1, Claude Cowork, 그리고 Claude Opus 4.7을 제공하고 있습니다.

이 튜토리얼에서는 Claude Code를 사용해 리팩터링, 문서화, 디버깅을 통해 소프트웨어 개발 워크플로를 개선하는 방법을 설명합니다. 구체적으로 다음을 진행합니다.

코드 가독성과 유지보수성을 높이기 위해 supabase-py 리포지토리의 파일을 리팩터링합니다.
기존 코드베이스에 대한 이해를 높이기 위해 문서와 인라인 주석을 추가합니다.
Claude Code의 디버깅 기능을 사용해 오류를 식별하고 해결합니다.

개발 프로세스에 Claude Code를 통합해 더 효율적이고 자동화된 경험을 얻는 방법을 배우게 됩니다.

Claude Code가 완전히 처음이시라면, 이 튜토리얼과 함께 Claude Code 101 과정을 수강하시길 권합니다.

요약

Claude Code는 Anthropic의 터미널 기반 에이전트형 코딩 어시스턴트로, Max 요금제에서 현재 Claude Opus 4.7을 기본으로 사용합니다.
설치는 macOS/Linux에서는 curl -fsSL https://claude.ai/install.sh | bash, Windows에서는 동등한 PowerShell/CMD 명령을 사용하세요.
자연어로 전체 코드베이스에 걸쳐 리팩터링, 문서화, 디버깅을 수행합니다.
주요 기능으로는 계획 모드, 자동 모드, 훅, 플러그인, 루틴(예약된 클라우드 에이전트)이 있습니다.
/model로 모델을 전환하고 /effort로 추론 강도를 조절하세요.

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 Desktop 앱에서 유료 요금제(Pro, Max, Team, Enterprise) 사용자 모두 이용할 수 있습니다.

그럼 실습 프로젝트를 시작해 보겠습니다.

1단계: Claude Code 설정

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

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

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로 마이그레이션할 수 있습니다.

설치가 완료되면 프로젝트 디렉터리로 이동해 다음을 실행하세요:

cd your-project-directory
claude

인증 단계에서 유료 구독 기반으로 사용할지, API 사용량 과금으로 사용할지 선택하게 됩니다.

이후 로그인 링크와 함께 검증 코드가 제공되며, 이를 Claude Code를 실행 중인 터미널에 입력하면 됩니다. 완료되면 전용 “Claude Code” 워크스페이스가 자동으로 생성되어 사용량 추적과 비용 관리를 할 수 있습니다.

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

2단계: 개발 환경 구성

이번 데모에서는 Supabase Python 라이브러리인 supabase-py를 사용합니다. 이는 PostgreSQL 기반의 백엔드 서비스 Supabase와 상호작용하는 오픈 소스 Python 클라이언트입니다. Supabase는 인증, 실시간 구독, 스토리지, 자동 생성 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가 파일을 업데이트하고, 터미널에 변경 사항을 표시하며, 수정 요약을 제공합니다.

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

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

아래는 원본 코드와 리팩터링된 코드를 나란히 비교한 모습입니다.

코드 문서화

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

Claude Code로 client.py의 문서를 개선해 다음과 같은 결과를 얻었습니다.

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

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

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

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

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

버그 수정

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

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

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

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

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

아래는 원본 코드와 수정된 코드를 비교한 모습입니다.

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

Claude Code 명령어

Claude에서 시도해 볼 만한 몇 가지 명령은 다음과 같습니다.

명령어	동작
`/model`	사용 가능한 모델 간 전환(Opus 4.7, Sonnet 4.6, Haiku 4.5)
`/effort`	추론 강도 조절(low, medium, high, xhigh, max)
`/plan`	계획 모드로 진입하여 코드를 작성하기 전에 설계
`/ultrareview`	멀티 에이전트 코드 리뷰
`/clear`	대화 기록을 지우고 컨텍스트 확보
`/compact`	대화 기록을 지우되 요약은 컨텍스트에 유지
`/cost`	현재 세션의 총 비용과 소요 시간 표시
`/doctor`	Claude Code 설치 상태 점검(버전 및 업데이트 상태 포함)
`/help`	도움말과 사용 가능한 명령 표시
`/init`	코드베이스 문서가 담긴 `CLAUDE.md` 파일 초기화
`/hooks`	자동화 훅 설정 및 관리
`/review`	풀 리퀘스트 검토
`/config`	권한을 포함한 Claude Code 구성 보기 및 변경
`/usage`	사용 한도를 유발하는 요소 표시(세션, 캐시, 컨텍스트)

또한 Anthropic 공식 튜토리얼과 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용 공식 확장으로 인라인 diff, 체크포인트, 멀티 세션을 지원합니다.
원격 제어와 채널: 휴대폰이나 다른 디바이스에서 Claude Code 세션을 실행하고 상호작용할 수 있습니다.

마무리

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

Claude Code는 계획 모드, 자동 모드, 루틴 등 기능이 계속 발전하고 있으므로, 본인의 프로젝트에 적용해 워크플로와의 궁합을 시험해 보시길 권합니다.

다음 단계로, Claude의 컨텍스트 윈도우를 최대한 활용하는 방법을 다룬 Claude Code 모범 사례 튜토리얼을 읽어보세요. 처음부터 프로젝트를 구축하고 싶다면 Spec-Driven Development with Claude Code 튜토리얼을 추천합니다.

Claude Code를 사용하려면 유료 Claude 구독이 필요한가요?

Claude Code는 특정 언어만 지원하나요, 아니면 어떤 언어에도 사용할 수 있나요?

Claude Code 훅과 플러그인의 차이는 무엇인가요?

Claude Code는 내 전체 코드베이스에 접근하나요?

개인용이 아니라 팀에서도 Claude Code를 사용할 수 있나요?

Claude Code는 팀 환경에서도 잘 작동합니다. 프로젝트의 .claude/settings.json 파일에 MCP 서버와 훅 같은 구성을 저장해 버전 관리에 커밋하면, 팀 차원에서 공유할 수 있습니다. 팀 전체에 설치된 플러그인은 일관된 동작을 보장합니다. 단, 각 팀원은 자신의 Claude 구독 또는 API 과금이 필요합니다. 엔터프라이즈 환경을 위해 Anthropic은 중앙 관리와 공유 워크스페이스를 제공하는 Teams 및 Enterprise 요금제를 제공합니다.