Claude Code 공식문서 리뷰 - Claude Code 개요, Cladue Code 빠르게 시작하기, 일반적인 워크 플로우
-
728x90
안녕하세요! 갓대희입니다.
Claude Code Docs 공식 문서 >> Getting Started 섹션의 내용을 살펴 보려고 합니다.
이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.
저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.
용어 설명: MCP (Model Context Protocol) Claude가 외부 데이터 소스(Google Drive, Figma, Slack 등)에 접근할 수 있게 해주는 프로토콜이다. MCP를 통해 Claude Code는 로컬 파일뿐 아니라 다양한 서비스의 데이터를 읽고 활용할 수 있다.
4. 반복 작업 자동화
린트 이슈 수정, 머지 충돌 해결, 릴리스 노트 작성 등 반복적인 작업을 자동화할 수 있다. CI 환경에서도 실행 가능하다.
// 린트 에러 자동 수정
claude -p "모든 린트 에러를 수정해줘"
// 머지 충돌 해결
claude -p "현재 머지 충돌을 분석하고 해결해줘"
개발자들이 Claude Code를 선호하는 이유
터미널에서 바로 작동
별도의 채팅 창이나 IDE가 아니라, 이미 사용하고 있는 터미널에서 작동한다. 익숙한 환경에서 바로 시작할 수 있다.
직접 행동한다
단순히 코드를 제안하는 것이 아니라:
파일을 직접 수정하고
명령어를 실행하고
커밋을 생성한다
Unix 철학: 조합 가능하고 스크립트 작성 가능
다른 CLI 도구들과 파이프로 조합할 수 있다:
// 로그 모니터링하다가 이상 발견 시 Slack 알림
tail -f app.log | claude -p "이 로그 스트림에서 이상 징후가 보이면 Slack으로 알려줘"
// CI에서 번역 자동화
claude -p "새로운 텍스트 문자열이 있으면 프랑스어로 번역하고 @lang-fr-team 리뷰를 위한 PR을 생성해줘"
실전 팁: 파이프라인 활용 Claude Code의 -p (또는 --print) 플래그를 사용하면 결과만 출력하고 종료한다. 이를 통해 다른 명령어와 쉽게 조합할 수 있다. 자동화 스크립트나 CI/CD 파이프라인에서 유용하다.
Claude Code는 계정이 필요하다. 대화형 세션을 시작하면 자동으로 로그인 프롬프트가 나타난다:
claude
# 첫 실행 시 로그인 프롬프트가 표시된다
옵션
설명
추천 대상
Claude.ai
구독 플랜
개인 개발자, 일반 사용 (권장)
Claude Console
API 접근 (선불 크레딧)
팀, 엔터프라이즈
참고 Claude Console 계정으로 처음 인증하면 "Claude Code"라는 워크스페이스가 자동 생성된다. 이를 통해 비용을 중앙에서 추적하고 관리할 수 있다.
Step 3: 첫 세션 시작하기
프로젝트 디렉토리에서 터미널을 열고 실행:
cd /path/to/your/project
claude
Claude Code 시작 화면이 나타난다:
세션 정보
최근 대화 목록
최신 업데이트
기본 명령어:
/help - 사용 가능한 명령어 보기
/resume - 이전 대화 이어하기
Step 4: 첫 번째 질문하기
Claude에게 코드베이스를 분석하게 해보자:
> 이 프로젝트가 뭐하는 거야?
다른 예시 질문들:
> 이 프로젝트에서 어떤 기술을 사용해?
> 메인 진입점이 어디야?
> 폴더 구조 설명해줘
> Claude Code로 뭘 할 수 있어?
> 슬래시 명령어 어떻게 써?
컨텍스트 자동 로딩 Claude는 필요한 파일을 자동으로 읽는다. 수동으로 컨텍스트를 추가할 필요가 없다!
Step 5: 첫 코드 변경 만들기
간단한 작업을 시도해보자:
> 메인 파일에 hello world 함수 추가해줘
Claude Code가 수행하는 작업:
적절한 파일 찾기
제안된 변경 사항 보여주기
승인 요청
편집 적용
권한 시스템 Claude Code는 파일 수정 전에 항상 허가를 요청한다. 개별 변경을 승인하거나, 세션 동안 "모두 수락" 모드를 활성화할 수 있다.
계속 글을 살펴보면 나오겠지만, 반대로 허가 요청을 항상 무시하는 모드도 있다. (이 부분은 잠깐 기록하고 넘어 가도록 한다.)
claude --dangerously-skip-permissions
실제 예시
> 사용자 등록 폼에 입력 유효성 검사 추가해줘
Claude Code가 하는 일:
관련 코드 찾기
컨텍스트 이해하기
솔루션 구현하기
가능하면 테스트 실행하기
Step 6: Git과 함께 사용하기
Claude Code는 Git 작업을 대화형으로 만든다:
> 내가 변경한 파일이 뭐야?
> 변경 사항을 설명적인 메시지로 커밋해줘
> feature/quickstart라는 새 브랜치 만들어줘
> 최근 5개 커밋 보여줘
> 머지 충돌 해결 좀 도와줘
실전 팁: 커밋 자동화 claude commit 명령어를 사용하면 변경 사항을 분석하고 적절한 커밋 메시지를 자동 생성한다. 일일이 메시지를 작성하는 수고를 덜 수 있다.
ex) 자연어를 통해 git 작업 요청 - 프로젝트 통합 및 하드 푸시 작업
( 처음에는 이렇게 claude code로 자연어를 통해 git 관련 작업을 진행 해보다 향후 본인이 원하는 스타일대로 custom command 또는 스킬 등을 만들어 쓰게 되려면 이와 같은 방법을 많이 활용 해보는것이 좋은 것 같다.) 자연어를 통해 git 작업을 해보자.
Step 7: 버그 수정하기
자연어로 원하는 것을 설명하면 된다:
> 사용자가 빈 폼을 제출할 수 있는 버그가 있어 - 고쳐줘
// 또는 에러 메시지를 직접 붙여넣기
> TypeError: Cannot read property 'map' of undefined 에러 고쳐줘
Step 8: 다양한 워크플로우 시도하기
코드 리팩토링
> 인증 모듈을 콜백 대신 async/await로 리팩토링해줘
테스트 작성
> 계산기 함수들에 대한 단위 테스트 작성해줘
문서 업데이트
> README에 설치 방법 추가해줘
코드 리뷰
> 내 변경 사항 리뷰하고 개선점 제안해줘
기억하자 Claude Code는 AI 페어 프로그래머다. 도움이 되는 동료에게 말하듯이 대화하면 된다.
필수 명령어 정리
명령어
설명
예시
claude
대화형 모드 시작
claude
claude "작업"
일회성 작업 실행
claude "빌드 에러 고쳐줘"
claude -p "질문"
질문 후 종료
claude -p "이 함수 설명해줘"
claude -c
최근 대화 이어하기
claude -c
claude commit
Git 커밋 생성
claude commit
/clear
대화 기록 지우기
> /clear
/help
사용 가능한 명령어 보기
> /help
exit 또는 Ctrl+C
Claude Code 종료
> exit
초보자를 위한 프로 팁
이 내용이 사실 매우 중요한 개념이 아닐까?
초창기에는 편하게 자연어로 데충 데충 일을 시키게 된다. 하지만 하기 작업이 매우 중요하고 습관을 들여야 하는 기본이다.
1. 요청은 구체적으로
// 이렇게 말고:
> 버그 고쳐줘
// 이렇게:
> 로그인할 때 잘못된 비밀번호 입력하면 빈 화면이 나오는 버그 고쳐줘
2. 복잡한 작업은 단계별로
> 1. 사용자 프로필용 새 데이터베이스 테이블 만들어줘
> 2. 사용자 프로필 조회/수정 API 엔드포인트 만들어줘
> 3. 사용자가 프로필 보고 수정할 수 있는 웹페이지 만들어줘
3. 먼저 분석하게 하기
변경을 요청하기 전에 Claude가 코드를 이해하게 하자:
> 데이터베이스 스키마 분석해줘
> 이 프로젝트의 인증 흐름 설명해줘
4. 단축키 활용하기
? - 모든 키보드 단축키 보기
Tab - 명령어 자동완성
↑ - 명령어 히스토리
/ - 모든 슬래시 명령어 보기
흔한 문제와 해결법
흔한 에러: 로그인 실패 Error: Authentication failed
해결법:
/logout 실행 후 다시 /login
브라우저에서 claude.ai에 로그인되어 있는지 확인
인터넷 연결 확인
흔한 에러: 파일을 찾을 수 없음 Could not find the file you mentioned
Claude Code 일반 워크플로우 가이드 Claude Code CLI를 활용한 다양한 개발 작업 패턴을 다룬다. 코드베이스 분석, 버그 수정, 리팩토링, 테스트 작성, PR 생성 등 실무에서 자주 사용하는 워크플로우를 단계별로 설명한다.
Claude Code는 터미널에서 동작하는 AI 코딩 어시스턴트다. 단순한 코드 생성을 넘어 코드베이스 분석, 디버깅, 리팩토링, 문서화 등 개발 전 과정에서 활용할 수 있다. 이 문서에서는 실무에서 자주 사용하는 워크플로우를 상황별로 정리했다.
새로운 코드베이스 이해하기
새 프로젝트에 투입되거나 오픈소스 코드를 분석할 때 Claude Code를 활용하면 빠르게 전체 구조를 파악할 수 있다.
코드베이스 빠르게 파악하기
단계별 진행 방법
프로젝트 루트 디렉토리로 이동: cd /path/to/project
Claude Code 시작: claude
전체적인 개요 질문: "이 코드베이스 개요 설명해줘"
특정 컴포넌트 심화 분석: 아키텍처 패턴, 데이터 모델, 인증 처리 방식 등 구체적 질문
// 코드베이스 분석을 위한 예시 프롬프트
> 이 코드베이스 개요 설명해줘
> 여기서 사용된 주요 아키텍처 패턴 설명해줘
> 핵심 데이터 모델이 뭐야?
> 인증은 어떻게 처리되고 있어?
효과적인 질문 순서 넓은 질문에서 시작해 점점 좁혀가는 것이 효과적이다. 프로젝트의 코딩 컨벤션과 패턴을 먼저 파악하고, 프로젝트 고유 용어를 정리해두면 이후 작업이 수월해진다.
관련 코드 찾기
특정 기능과 관련된 파일들을 찾을 때는 구체적으로 설명하는 것이 좋다.
> 사용자 인증을 처리하는 파일들 찾아줘
> 이 인증 파일들이 어떻게 함께 작동하는지 설명해줘
> 프론트엔드에서 데이터베이스까지 로그인 프로세스 추적해줘
버그 효율적으로 수정하기
버그 수정은 문제 공유, 해결책 검토, 적용의 3단계로 진행한다.
버그 수정 워크플로우
에러 공유: 에러 메시지와 재현 조건을 Claude에게 전달
수정 방법 검토: 여러 해결책 중 최적의 방법 선택
수정 적용: 선택한 방법으로 코드 수정 요청
// 버그 수정 예시
> npm test 실행할 때 에러가 나와
> user.ts에서 @ts-ignore 수정하는 방법 몇 가지 제안해줘
> user.ts에 네가 제안한 null 체크 추가해줘
버그 리포트 작성 요령 문제 재현 명령어와 스택 트레이스를 함께 제공하면 더 정확한 진단이 가능하다. 에러가 간헐적인지 일관적인지도 중요한 정보다.
코드 리팩토링
리팩토링은 대상 식별, 방법 검토, 적용, 검증의 4단계로 진행한다. 작고 테스트 가능한 단위로 나누어 진행하는 것이 안전하다.
리팩토링 단계
리팩토링 대상 식별: deprecated API 사용처, 레거시 코드 등 개선이 필요한 부분 탐색
리팩토링 방법 검토: 여러 접근법의 장단점 비교
안전하게 변경 적용: 기존 동작 유지를 보장하면서 코드 수정
리팩토링 검증: 테스트 실행으로 정상 동작 확인
> 코드베이스에서 deprecated API 사용처 찾아줘
> utils.js를 최신 JavaScript 기능으로 리팩토링하는 방법 제안해줘
> utils.js를 ES2024 기능으로 리팩토링하되 동일한 동작 유지해줘
> 리팩토링된 코드에 대해 테스트 실행해줘
서브에이전트 활용하기
용어 설명: 서브에이전트 (Sub-agent) Claude Code가 특정 작업을 수행하기 위해 호출하는 전문화된 AI 에이전트다. 코드 리뷰, 디버깅, 테스트 실행 등 각 분야에 특화된 서브에이전트가 있으며, 작업 특성에 맞는 에이전트가 자동 또는 수동으로 호출된다.
서브에이전트는 복잡한 작업을 분업화하여 처리할 수 있게 해준다. /agents 명령으로 사용 가능한 서브에이전트 목록을 확인할 수 있다.
// 서브에이전트 활용 예시
> /agents # 사용 가능한 에이전트 목록
> 최근 코드 변경사항에서 보안 문제 검토해줘 # 자동 에이전트 선택
> code-reviewer 서브에이전트로 인증 모듈 검토해줘 # 특정 에이전트 지정
ex)
커스텀 서브에이전트 팀 공유를 위해 .claude/agents/에 프로젝트별 서브에이전트를 정의할 수 있다. description 필드를 명확히 작성하면 자동 위임 시 적절한 에이전트가 선택된다. 자연어로 생성할수도 있고, 다른 사람들이 사용중인것들을 공유할수도 있는데, 각각의 세세한 생성 방법 등등의 내용은 추후 상세히 다뤄보자.
플랜 모드로 안전하게 코드 분석하기
용어 설명: 플랜 모드 (Plan Mode) Claude가 읽기 전용 작업만으로 코드베이스를 분석하고 계획을 수립하는 모드다. 파일 수정이나 명령 실행 없이 분석만 수행하므로 안전하다.
플랜 모드 사용 시점
상황
설명
다단계 구현
여러 파일을 수정해야 하는 기능 개발 시
코드 탐색
변경 전에 코드베이스를 철저히 조사하고 싶을 때
대화형 개발
Claude와 방향을 반복적으로 조율하고 싶을 때
플랜 모드 활성화 방법
세션 중 플랜 모드 전환
Shift+Tab으로 권한 모드를 순환할 수 있다:
accept edits on - 자동 수락 모드
plan mode on - 플랜 모드 (읽기 전용)
// 플랜 모드로 새 세션 시작
claude --permission-mode plan
// 플랜 모드로 헤드리스 쿼리 실행
claude --permission-mode plan -p "인증 시스템을 분석하고 개선 사항을 제안해줘"
ex) 권한 무시 모드
ex) 플랜 모드
.claude/settings.json - 플랜 모드 기본값 설정
{
"permissions": {
"defaultMode": "plan"
}
}
테스트 작업하기
Claude는 기존 테스트 파일을 분석하여 프로젝트의 테스트 스타일, 프레임워크, assertion 패턴을 자동으로 파악한다.
테스트 작성 워크플로우
테스트 커버리지 분석: 테스트가 없는 함수들 식별
테스트 스캐폴딩 생성: 기본 테스트 구조 자동 생성
엣지 케이스 추가: 경계값, 예외 상황 테스트 보강
테스트 실행 및 검증: 실패 시 자동 수정
> NotificationsService.swift에서 테스트가 없는 함수들 찾아줘
> 알림 서비스에 테스트 추가해줘
> 알림 서비스의 엣지 케이스에 대한 테스트 케이스 추가해줘
> 새 테스트 실행하고 실패하면 수정해줘
확장 사고 모드 사용하기
용어 설명: 확장 사고 (Extended Thinking) Claude가 복잡한 문제를 단계별로 추론하도록 출력 토큰 예산의 일부를 예약하는 기능이다. 더 깊은 분석과 신중한 판단이 필요할 때 활성화한다.
확장 사고가 유용한 상황
복잡한 아키텍처 결정
어려운 버그 분석
다단계 구현 계획 수립
다양한 접근 방식 간 트레이드오프 평가
설정
사고 토큰
설명
비활성화
0
일반 응답 모드
활성화
최대 31,999
내부 추론에 토큰 할당
커스텀
사용자 지정
MAX_THINKING_TOKENS 환경 변수
// 요청별 확장 사고 활성화 (ultrathink 키워드)
> ultrathink: API용 캐싱 레이어 설계해줘
// 환경 변수로 토큰 예산 설정
export MAX_THINKING_TOKENS=1024
ex) 설정 파일 일부 캡쳐
주의 ultrathink 키워드는 MAX_THINKING_TOKENS가 설정되지 않았을 때만 작동한다. 환경 변수가 설정되어 있으면 해당 값이 우선 적용된다.
