Claude Code 활용 예시 — 탐색·디버그·리팩터·테스트·PR 워크플로

Claude Code는 터미널에서 동작하는 CLI 에이전트로, 저장소를 읽고 파일을 편집하고 명령을 실행하며(파괴적 작업 전에는 확인을 요청합니다), 일상적인 개발 작업을 자연어 지시로 처리합니다. 이 글은 Claude 공식 문서가 제시하는 대표 활용 패턴을 프롬프트 예시와 함께 정리합니다. (기능·플래그는 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)

코드 탐색 — 낯선 코드를 빠르게 파악

새 프로젝트에 합류했거나 특정 기능의 위치를 찾아야 할 때, Claude에게 구조를 설명하거나 관련 코드를 찾아달라고 요청할 수 있습니다. 변경 없이 읽기만 하므로 부담이 없습니다.

디버그와 리팩터

버그는 에러 메시지와 함께 원인 추적·수정을 요청합니다. 리팩터는 레거시 코드를 더 현대적인 패턴으로 바꾸는 데 유용합니다. 공식 문서와 실무 권장은 점진적 리팩터입니다 — 한 파일을 고치고 테스트를 돌려 검증한 뒤 다음으로 넘어가는 식으로, 한 번에 여러 파일을 휩쓰는 변경은 피하는 것이 안전합니다.

테스트 작성

Claude는 프로젝트의 기존 테스트 파일을 살펴 스타일·프레임워크·assertion 패턴을 맞춰 테스트를 생성합니다. 무엇을 검증할지 구체적으로 알려줄수록 좋고, "놓치기 쉬운 엣지 케이스를 찾아달라"고 하면 에러 조건·경계값·예상 밖 입력에 대한 테스트도 제안받을 수 있습니다.

PR과 문서

변경이 준비되면 "내 변경으로 PR을 만들어줘"처럼 직접 요청하거나 단계별로 진행할 수 있습니다. gh CLI가 있으면 gh pr create로 PR을 만들 때 세션이 그 PR에 자동으로 연결되고, 나중에 claude --from-pr <number>로 돌아오거나 PR URL을 /resume 검색에 붙여넣어 이어갈 수 있습니다. 문서화도 모듈을 훑어 주석이 없는 함수를 찾아 표준 포맷으로 생성하게 할 수 있습니다.

# 코드 탐색
이 프로젝트의 전체 구조를 설명해줘
결제(payment) 기능과 관련된 코드를 찾아줘

# 디버그 / 리팩터
이 에러의 원인을 추적하고 고쳐줘: [에러 메시지 붙여넣기]
@src/legacy/parser.js 를 더 현대적인 패턴으로 리팩터해줘

# 테스트 / PR
@src/utils/format.ts 의 테스트를, 기존 테스트 스타일에 맞춰 엣지 케이스까지 작성해줘
create a pr for my changes

더 잘 쓰는 패턴

• 먼저 탐색, 그다음 편집: 변경 전 읽기 전용 탐색(Plan Mode)으로 맥락을 잡고 계획을 검토한 뒤 구현하면, 엉뚱한 방향의 코드가 쌓이는 것을 막을 수 있습니다.
• @파일 참조: 처리 전에 특정 파일 내용을 컨텍스트에 포함시킵니다(예: @src/utils/format.ts).
• 이전 대화 재개·병렬 작업: 작업을 여러 세션에 나눠 이어가거나, git worktree로 병렬 세션을 띄워 동시 편집 충돌을 피할 수 있습니다.
• 스크립트·CI 연동: -p로 targeted 프롬프트를 주어 Claude를 스크립트에 파이프해 CI 코드 리뷰·배치 처리에 쓸 수 있습니다.
• 컨텍스트 관리: 큰 작업을 마칠 때마다 /compact로 정리하고, 무관한 작업은 새 세션으로 시작하는 것이 권장됩니다.

정리

핵심: ① 탐색·디버그·리팩터·테스트·PR·문서가 대표 활용이다, ② "먼저 읽고 계획한 뒤 고치는" 흐름이 안전하다, ③ @파일·gh 연동·-p 파이프·/compact 같은 도구로 효율을 높인다. 각 패턴의 프롬프트 레시피는 Claude Code 공식 워크플로 문서에 있습니다.

로컬 작업을 넘어 리포 안에서 자동으로 쓰려면 GitHub 연동(@claude)으로 PR 생성·코드 리뷰를 자동화할 수 있습니다.

코드 오류를 깊이 파고들려면 Claude로 코드 오류 디버깅하기를 참고하세요.

이 글은 Claude Code 공식 문서(code.claude.com, support.claude.com)의 활용 패턴을 토대로 작성했습니다. Claude Code는 자주 업데이트되므로, 버전별 명령·플래그는 공식 문서에서 확인하세요. 생성된 코드·PR은 제출 전 반드시 검토하시기 바랍니다. (공식 출처: code.claude.com/docs)

관련 글

• Claude Code GitHub 연동 — @claude 멘션으로 PR·리뷰 자동화
• Claude Code 슬래시 명령어 — 내장 명령 + 커스텀 명령 만들기
• Claude Code 서브에이전트 — 곁작업을 분리하는 전문 AI 만들기
• Claude Code 훅(Hooks) — 매번 자동 실행되는 작업 규칙 만들기
• Claude Code 단축키 & 슬래시 명령어 치트시트 — 초보자를 위한 핵심 정리
• Claude Code 헤드리스 모드(claude -p)로 반복 작업 자동화하기
• Claude Code 실전 예제 모음 — 자동화·MCP·훅·헤드리스 한눈에 보기