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

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

업데이트됨 2026년 7월 21일 · 12분 읽다

AI로 탐색하기

ChatGPT에서 열기 Claude에서 열기 Perplexity에서 열기

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 명령을 사용하세요.
자연어로 코드베이스 전반의 리팩터링, 문서화, 디버깅을 수행하세요.
주요 기능은 플랜 모드, 오토 모드, 훅, 플러그인, Routines(예약형 클라우드 에이전트)입니다.
/model로 모델 전환, /effort로 추론 강도를 조절합니다.

Claude Code란?

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

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

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

오픈 소스 프로젝트든 엔터프라이즈급 코드베이스든, Claude Code는 코딩 스타일과 프로젝트 요구에 맞춰 적응하는 지능형 자동화를 제공합니다. 최근에는 오토 모드(권한 확인 감소), 플랜 모드(설계 우선 워크플로), Routines(로컬 머신 없이 트리거로 동작하는 예약형 클라우드 에이전트)가 추가되었습니다.

이 서비스를 추천할 만한 대상은 다음과 같습니다.

소프트웨어 개발자: 코드 품질과 유지보수성 향상
오픈 소스 기여자: 낯선 코드베이스의 이해 및 개선
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) 구독자가 사용할 수 있습니다.

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

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

설치가 끝나면 프로젝트 디렉터리로 이동해 다음을 실행하세요.

cd your-project-directory
claude

인증 단계에서 유료 구독 기반으로 사용할지, API 과금으로 사용할지 선택하라는 안내가 표시됩니다.

다음으로 로그인 링크를 받아 인증 코드를 확인하고, Claude Code가 실행 중인 터미널에 입력합니다. 그러면 설정이 완료되고, 전용 “Claude Code” 워크스페이스가 자동으로 생성되어 사용 추적과 비용 관리를 도와줍니다.

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

2단계: 개발 환경 설정

이번 데모에서는 오픈 소스 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`	세션, 캐시, 컨텍스트 등 사용 한도를 유발하는 요소 표시

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

고급 Claude Code 기능

리팩터링과 디버깅의 기본에 익숙해지면, 동작 방식을 커스터마이징해 Claude Code의 기능을 확장할 수 있습니다. Hooks와 Plugins 를 통해 반복 작업을 자동화하고 외부 시스템과 통합할 수 있습니다.

Claude Code 훅

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

훅은 이벤트-액션 시스템을 사용하며, 다음 세 가지를 정의합니다.

이벤트: 훅이 언제 트리거되나요?
매처: 어떤 동작에 영향을 주나요?
명령: 트리거 시 무엇을 실행하나요?

예를 들어, Claude가 Python 파일을 쓴 뒤 자동으로 black을 실행해 코드를 포맷하도록 설정할 수 있습니다. 훅은 발생한 일에 대한 JSON 컨텍스트를 받아 파일 타입이나 경로에 따라 지능적으로 판단합니다. 결과를 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를 확장 가능한 플랫폼으로 만들 수 있습니다.

기타 고급 기능

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

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

마무리

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

Claude Code는 플랜 모드, 오토 모드, Routines 등 기능이 계속 발전 중입니다. 직접 프로젝트에 적용해 워크플로와의 적합성을 시험해 보세요.

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

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

Claude Code는 특정 언어에만 작동하나요, 아니면 모든 언어를 지원하나요?

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

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

팀 환경에서도 Claude Code를 사용할 수 있나요, 아니면 개인용인가요?

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