Claude Code 활용 가이드 핵심 정리
핵심 요약
Claude Code는 터미널·에디터 환경에서 코드 이해, 수정, 테스트, PR 작성까지 개발 전 과정을 도와주는 도구다.
코드베이스 탐색, 버그 해결, 리팩터링, 자동 테스트/문서화, CI 연동, 커스텀 명령어 등 다양한 기능을 제공하므로, 작업 목적에 맞춰 모드와 기능을 조합해서 쓰는 것이 중요하다.
새로운 코드베이스 빠르게 이해하기
처음 보는 프로젝트에 들어갔을 때 Claude Code는 "가이드 투어" 역할을 한다.
프로젝트 루트 디렉토리에서 claude를 실행한 뒤, 먼저 "이 코드베이스의 전반적인 구조를 설명해 달라"는 식의 넓은 질문을 던지면 폴더 구조, 주요 모듈, 핵심 기능 흐름을 한눈에 볼 수 있다.
그 다음에는 "여기서 어떤 아키텍처 패턴을 쓰는지", "핵심 데이터 모델이 무엇인지", "인증은 어떻게 처리하는지"처럼 영역을 좁혀 가며 묻는 것이 좋다.
또한 해당 프로젝트에서 자주 쓰이는 용어, 약어, 도메인 개념을 모아 용어집을 요청하면, 팀 문화를 빠르게 흡수하는 데 도움이 된다.
필요한 코드 빠르게 찾기
특정 기능을 담당하는 코드를 찾고 싶다면 인간의 '감' 대신 Claude의 검색·분석 능력을 활용할 수 있다.
예를 들어 "사용자 인증을 담당하는 파일들을 찾아 달라"고 하면 관련 파일 목록을, 이어서 "이 파일들이 서로 어떻게 상호작용하는지"를 묻으면 모듈 간 의존 관계를 설명해 준다.
또 "로그인 요청이 프론트엔드에서 DB까지 어떻게 흐르는지 추적해 달라"고 요청하면, 라우팅 → 컨트롤러 → 서비스 → 리포지토리(또는 ORM)로 이어지는 전체 실행 흐름을 서술해 준다.
이때 프로젝트 도메인 언어(예: "결제 승인", "알림 발송")를 그대로 사용해 질문하면, Claude가 더 정확히 관련 코드를 좁혀 갈 수 있다.
버그를 효율적으로 찾고 고치기
버그를 고칠 때는 우선 에러 상황에 대한 최대한의 정보를 Claude에게 제공하는 것이 핵심이다.
예를 들어 "npm test를 실행했더니 이런 에러가 난다"와 함께 에러 로그, 스택 트레이스를 붙여 주면, Claude가 어느 파일·어느 줄에서 문제가 시작됐는지 빠르게 짚어 줄 수 있다.
그 다음에는 "이 @ts-ignore를 없앨 수 있는 수정 방안을 몇 가지 제안해 달라"처럼 구체적인 수정 전략을 요청하고, 마음에 드는 방안을 골라 "해당 파일에 널 체크를 추가해 달라"처럼 실제 수정을 맡길 수 있다.
에러가 간헐적인지, 항상 재현되는지, 어떤 명령이나 단계에서 발생하는지도 알려주면, 재현과 원인 추적에 필요한 탐색 범위를 줄여 준다.
안전하게 리팩터링하기
레거시 코드를 현대적인 스타일로 바꾸고 싶을 때, Claude Code는 "리팩터링 가이드 + 자동 수정 도구" 역할을 한다.
먼저 "이 코드베이스에서 더 이상 쓰지 말아야 할 API나 Deprecated 사용 사례를 찾아 달라"고 하면 위험 지점을 리스트업할 수 있다.
이후 "utils.js를 최신 JavaScript(예: ES2024) 스타일로 바꾸는 방안을 제안해 달라"고 전략을 묻고, 이어서 "동일 동작을 유지한 채 ES2024 기능을 사용하도록 리팩터링해 달라"고 요청하면 한 번에 수정까지 진행된다.
리팩터링 후에는 "관련 테스트를 실행해 달라"고 요청하여 동작 유지 여부를 확인하고, 필요하다면 추가 테스트 생성도 함께 맡길 수 있다.
큰 리팩터링은 여러 파일을 한 번에 바꾸기보다, 기능별·모듈별로 작은 단위를 나눠 진행하고, 매 단계마다 테스트와 리뷰를 거치는 방식이 안전하다.
서브에이전트로 역할 분담하기
Claude Code는 하나의 AI가 모든 일을 다 하는 대신, 역할이 분리된 "서브에이전트"들을 둘 수 있다.
/agents를 실행하면 사용 가능한 서브에이전트 목록과, 새 에이전트를 만드는 인터페이스를 볼 수 있다. 보안 코드 리뷰 전용, API 설계 전용, 디버깅 전용 등 특정 목적을 가진 에이전트를 정의할 수 있다.
일반 대화 중에도 "최근 코드 변경 사항을 보안 관점에서 리뷰해 달라", "모든 테스트를 실행하고 실패한 테스트를 고쳐 달라"고 하면 적절한 서브에이전트가 자동으로 호출될 수 있다.
또 "code-reviewer 에이전트를 사용해 auth 모듈을 검토해 달라"처럼 특정 에이전트를 명시적으로 지목할 수도 있다.
프로젝트 전용 서브에이전트를 .claude/agents/에 정의해 두면 팀원 모두가 공유할 수 있고, 각 에이전트가 사용할 수 있는 도구 범위를 최소한으로 제한해 보안과 안전성을 높일 수 있다.
Plan Mode로 읽기 전용 분석·설계하기
Plan Mode는 "코드는 읽을 수 있지만, 직접 수정은 하지 않는" 모드로, 위험한 변경 없이 설계와 분석에 집중하고 싶을 때 유용하다.
여러 파일을 동시에 수정해야 하는 대규모 기능, 복잡한 리팩터링, 혹은 아직 방향을 정하지 못한 상태에서 코드베이스를 탐색할 때 Plan Mode를 켜 두면 안심하고 시나리오를 논의할 수 있다.
터미널 하단 모드 표시를 보며 Shift+Tab으로 권한 모드를 순환할 수 있고, claude --permission-mode plan으로 처음부터 Plan Mode 세션을 시작할 수도 있다.
예를 들어 "현재 인증 시스템을 OAuth2로 마이그레이션하는 자세한 계획을 세워 달라"고 요청하면, Claude는 기존 구조를 분석한 뒤 단계별 마이그레이션 플랜, 데이터베이스 마이그레이션 전략, 기존 사용자와의 호환성을 포함한 계획을 제안한다.
이렇게 마련한 계획을 바탕으로, 실제 코드를 수정할 때는 Normal 모드나 Auto-accept 모드로 전환해 실행하면 된다. 필요하다면 .claude/settings.json에서 기본 권한 모드를 "plan"으로 설정해 항상 읽기 전용으로 시작할 수도 있다.
테스트 작성과 품질 관리 자동화
테스트는 귀찮지만 필수적인 작업인데, Claude를 이용하면 반복 작업을 크게 줄일 수 있다.
먼저 "NotificationsService.swift에서 테스트가 없는 함수들을 찾아 달라"고 요청해 테스트 공백 구간을 파악한다. 이어서 "알림 서비스에 대한 테스트 코드를 추가해 달라"고 하면 기존 테스트 스타일·프레임워크에 맞춰 기본 골격을 만들어 준다.
그 다음에는 "엣지 케이스를 포함한 테스트 케이스를 더 추가해 달라"고 요청해 오류 상황, 경계값, 비정상 입력 등의 시나리오를 보강할 수 있다.
마지막으로 "새로 추가된 테스트를 실행하고 실패 시 고쳐 달라"고 하면, 생성된 테스트가 실제로 통과하는지 검증하고 필요한 수정까지 이어서 진행된다.
이 과정을 반복하면, 테스트 커버리지가 낮은 프로젝트에도 비교적 빠르게 안정적인 테스트 층을 쌓을 수 있다.
PR, 문서, 이미지까지 한 번에 처리하기
코드 변경을 마무리할 때 필요한 PR 작성, 변경 요약, 문서 보완 작업도 Claude에게 맡길 수 있다.
먼저 "인증 모듈에서 내가 수행한 변경 사항을 요약해 달라"고 하면 diff를 기반으로 주요 변경점을 정리해 준다. 이후 "PR을 만들어 달라"라고 요청하면 제목, 설명, 체크리스트 등이 포함된 PR 초안을 자동으로 작성해 준다.
보안·성능·리스크 관점 설명이 부족하다면 "보안 개선 관점에서 설명을 강화해 달라", "테스트 방법과 결과를 설명에 추가해 달라"고 구체적으로 주문해 PR 내용을 다듬으면 된다.
문서화 측면에서는 "auth 모듈에서 JSDoc이 없는 함수들을 찾아 달라", "auth.js의 함수에 JSDoc을 채워 달라"고 요청해 기본 주석을 채우고, 이어 "설명과 사용 예제를 더 풍부하게 만들어 달라"고 요구해 품질을 끌어올릴 수 있다.
또한 스크린샷, 디자인 시안, 다이어그램을 드래그 앤 드롭하거나 파일 경로로 넘겨 "이 UI의 구성 요소를 설명해 달라", "이 디자인에 맞는 HTML/CSS를 생성해 달라", "이 DB 스키마에 새 기능을 추가하려면 어떻게 바꿔야 할지" 등 시각 정보를 활용한 개발 지원도 받을 수 있다.
파일·디렉터리·외부 리소스 참조하기
Claude가 필요한 파일을 직접 찾아 읽도록 기다리는 대신, @경로로 필요한 자원을 명시하면 더 빠르고 정확하게 대화할 수 있다.
예를 들어 "@src/utils/auth.js의 로직을 설명해 달라"고 하면 해당 파일 전체가 즉시 컨텍스트에 포함되고, 이 기반으로 세밀한 분석을 받을 수 있다.
디렉터리를 지정해 "@src/components 구조를 설명해 달라"고 하면 실제 파일 내용 대신 디렉터리 트리와 파일 메타 정보(이름, 크기 등)를 보여주며 전체 구조를 파악하게 해 준다.
또 MCP 서버와 연동된 환경이라면 "@github:repos/owner/repo/issues 데이터를 보여 달라"처럼 외부 시스템의 리소스를 바로 불러와 함께 분석할 수 있다.
여러 파일을 동시에 참조하고 싶을 때는 "@file1.js와 @file2.js를 비교해 달라"처럼 한 문장에 복수 경로를 나열해 동시 분석을 요청하면 편리하다.
확장 사고(Extended Thinking)와 ultrathink
복잡한 설계, 난해한 버그, 여러 선택지 사이의 트레이드오프를 논의할 때는 Claude의 "생각량"을 늘려 주는 것이 유리하다.
Extended Thinking(사고 확장)은 응답 토큰 일부를 내부 추론에 예약해, Claude가 여러 접근법을 비교하고 엣지 케이스를 점검하며 스스로 검증할 수 있도록 한다. Sonnet 4.5, Opus 4.5에서는 기본적으로 이 모드가 켜져 있다.
전역 설정(/config)에서 생각 모드를 켜거나, 환경 변수 MAX_THINKING_TOKENS로 사용할 최대 생각 토큰 수를 직접 지정할 수 있다. 이 값이 설정되어 있으면 모든 요청에 동일한 생각 예산이 적용된다.
특정 질문에만 깊은 사고를 쓰고 싶다면 메시지 앞에 ultrathink: 키워드를 붙여 "이 요청만 깊게 생각해 달라"고 명시할 수 있다. 예:
ultrathink: 우리 API를 위한 캐싱 레이어 설계를 해줘이 경우 Claude는 더 많은 추론 토큰을 사용해 다양한 설계 옵션, 장단점, 구현 단계 등을 자세히 서술한다. 다만 생각 토큰은 비용에 포함되니, 정말 복잡한 문제에만 선택적으로 사용하는 것이 좋다.
세션 관리와 Git worktree를 활용한 병렬 작업
Claude Code와의 대화는 "세션" 단위로 저장되며, 이를 잘 관리하면 장기적인 작업에도 큰 도움이 된다.
최근 대화를 그대로 이어 가고 싶다면 claude --continue를, 이전에 작업하던 대화를 찾아서 재개하고 싶다면 claude --resume 또는 세션 안에서 /resume을 사용하면 된다.
세션에 /rename auth-refactor처럼 이름을 붙여 두면 "예전 인증 리팩터링 논의" 같은 대화를 다시 찾기 쉽다. /resume은 인터랙티브 세션 선택기를 열어, 세션 이름, 마지막 활동 시각, 메시지 수, Git 브랜치 등 메타데이터를 보여주고, 키보드만으로 검색·미리보기·이름 변경을 할 수 있게 한다.
여러 기능을 동시에 개발해야 할 때는 Git worktree와 결합하면 유용하다. 하나의 저장소에서 여러 브랜치를 서로 다른 디렉토리로 체크아웃한 뒤, 각 worktree 디렉토리에서 각각 claude를 실행하면 완전히 독립된 코드 상태에서 병렬로 Claude를 활용할 수 있다.
예를 들어 feature-a용 worktree와 bugfix-123용 worktree를 만들고, 각 디렉토리에서 Claude를 띄워 두면 기능 개발과 버그 수정에 대한 대화를 분리해 관리할 수 있다.
유닉스 스타일 유틸리티로 통합 활용하기
Claude Code는 인터랙티브 채팅뿐 아니라, CLI 유틸리티처럼 다른 도구와 파이프로 연결해 쓸 수 있다.
예를 들어 package.json의 스크립트에 다음과 같이 추가하면, 빌드 과정에서 "Claude 기반 맞춤형 린터"를 한 줄로 돌릴 수 있다.
"scripts": {
"lint:claude": "claude -p 'you are a linter. ...'"
}이 방식으로 철자 검사, 간단한 코드 스타일 점검, 보안 취약점 힌트 등 다양한 자동 리뷰 작업을 CI 단계에 포함시킬 수 있다.
또 cat build-error.txt | claude -p '이 빌드 에러의 근본 원인을 간단히 설명해줘' > output.txt처럼 로그 파일을 파이프로 전달해 분석 결과를 텍스트 파일로 저장하는 식의 활용도 가능하다.
--output-format 옵션을 사용하면 출력 형식을 세밀하게 조절할 수 있다. 단순 텍스트만 필요할 때는 text(기본값), 비용·시간 등 메타데이터를 포함한 전체 대화 로그가 필요할 때는 json, 실시간으로 JSON 조각을 스트리밍 받고 싶을 때는 stream-json을 사용할 수 있다.
이 조합을 이용하면 쉘 스크립트, CI 파이프라인, 다른 개발 도구와 Claude를 유연하게 연결할 수 있다.
슬래시 명령어로 나만의 도구 만들기
반복해서 쓰는 프롬프트는 "슬래시 명령어"로 만들어 두면 생산성이 크게 올라간다.
프로젝트 안에 .claude/commands 디렉토리를 만들고, 그 안에 optimize.md 같은 마크다운 파일을 하나 생성하면, 그 파일 내용이 그대로 /optimize 명령어의 프롬프트가 된다.
예를 들어 optimize.md에 "이 코드의 성능을 분석하고 세 가지 최적화 방안을 제안해 달라"라는 문장을 적어 두면, 이후 세션에서 /optimize만 입력해도 동일한 요청을 반복해서 보낼 수 있다.
명령어 템플릿 안에 $ARGUMENTS를 넣어 두면, /fix-issue 123처럼 뒤에 붙인 텍스트가 해당 위치에 삽입된다. 이는 특정 이슈 번호, 함수명, 파일 경로를 매번 바꿔 가며 반복 작업을 할 때 특히 유용하다.
개인용 명령어는 ~/.claude/commands에 두면 모든 프로젝트에서 사용할 수 있고, 이 경우 /help 목록에서 "(user)"라고 표시된다. 팀 전체가 공유해야 하는 워크플로는 프로젝트 내 .claude/commands에, 개인이 쓰는 습관 명령은 홈 디렉토리에 두는 식으로 분리하면 관리가 쉽다.
Claude에게 직접 능력을 물어보기
Claude Code는 자신의 공식 문서를 스스로 참조할 수 있기 때문에, 기능을 일일이 외울 필요는 없다.
"PR을 만들 수 있는지", "권한 관리는 어떻게 되는지", "어떤 기본 슬래시 명령을 제공하는지", "MCP를 어떻게 연동하는지", "Bedrock 환경에서 어떻게 설정하는지" 등 궁금한 점을 자연어로 물으면 관련 문서를 바탕으로 최신 정보를 요약해 준다.
따라서 특정 기능의 이름이나 세부 설정이 기억나지 않을 때는 별도로 브라우저를 열기보다 Claude에게 질문하는 쪽이 더 빠를 수 있다.
인사이트
Claude Code는 "코드를 대신 짜 주는 도구"라기보다, 코드 이해·설계·리뷰·문서화·자동화까지 개발 사이클 전반을 지원하는 "개발 파트너"에 가깝다.
효율적으로 사용하려면,
Plan Mode로 먼저 안전하게 조사·설계를 하고
서브에이전트와 슬래시 명령어로 반복 작업을 자동화하며
테스트·PR·문서화를 꾸준히 Claude에 위임하고
필요할 때 Extended Thinking과 파이프/출력 포맷 설정으로 CI·스크립트에 통합하는 전략이 좋다.
처음에는 단순 질문·요약부터 시작하되, 익숙해질수록 프로젝트 전용 에이전트와 명령어를 만들어 "우리 팀만의 개발 보조 인프라"로 발전시키면 투자 대비 효과가 크게 커진다.
출처 및 참고 : Common workflows - Claude Code Docs