일반적인 워크플로우

코드베이스 탐색, 버그 수정, 리팩토링, 테스트, PR 생성 등 일상적인 개발 작업을 위한 단계별 가이드입니다.

각 섹션에는 실제 프로젝트에 맞게 응용할 수 있는 예시 프롬프트가 포함되어 있습니다. 고수준 패턴과 팁은 모범 사례를 참조하세요.

새 코드베이스 이해하기

빠른 코드베이스 개요 파악

새 프로젝트에 참여해서 구조를 빠르게 파악해야 하는 경우:

1. 프로젝트 루트 디렉토리로 이동

cd /path/to/project

2. Claude Code 시작

claude

3. 개요 요청

> 이 코드베이스의 개요를 알려줘

4. 특정 컴포넌트 심층 탐색

> 여기서 사용된 주요 아키텍처 패턴을 설명해줘
> 주요 데이터 모델은 무엇인가?
> 인증은 어떻게 처리되나?

팁: 넓은 질문으로 시작해서 특정 영역으로 좁혀가세요. 프로젝트 전용 용어 사전을 요청하면 도움이 됩니다.

버그 효율적으로 수정하기

> npm test를 실행할 때 오류가 발생해
> user.ts의 @ts-ignore를 수정하는 몇 가지 방법을 제안해줘
> 제안한 null 체크를 추가해줘

팁: 문제를 재현하는 명령어를 알려주고 스택 트레이스를 제공하세요.

코드 리팩토링

> 코드베이스에서 사용 중단된 API 사용 방법을 찾아줘
> utils.js를 모던 JavaScript 기능을 사용하도록 리팩토링하는 방법을 제안해줘
> 동일한 동작을 유지하면서 ES2024 기능을 사용하도록 utils.js를 리팩토링해줘
> 리팩토링된 코드의 테스트를 실행해줘

팁: 모던 접근 방식의 이점을 설명하도록 요청하고, 필요한 경우 하위 호환성을 유지하도록 요청하세요.

특화된 서브에이전트 사용하기

사용 가능한 서브에이전트 보기

> /agents

모든 사용 가능한 서브에이전트를 표시하고 새로운 것을 만들 수 있습니다.

자동 위임

Claude Code는 적절한 작업을 자동으로 특화된 서브에이전트에게 위임합니다:

> 최근 코드 변경 사항의 보안 문제를 검토해줘
> 모든 테스트를 실행하고 실패한 것을 수정해줘

특정 서브에이전트 명시적 요청

> code-reviewer 서브에이전트를 사용해서 auth 모듈을 확인해줘
> debugger 서브에이전트로 사용자가 로그인할 수 없는 이유를 조사해줘

플랜 모드로 안전한 코드 분석하기

플랜 모드는 Claude가 읽기 전용 작업으로 코드베이스를 분석하도록 지시합니다. 복잡한 변경을 계획하거나 코드를 안전하게 검토하는 데 적합합니다.

플랜 모드 사용 시기

다단계 구현: 많은 파일을 편집해야 하는 기능
코드 탐색: 변경 전에 코드베이스를 철저히 연구
인터랙티브 개발: Claude와 방향을 반복적으로 조정

플랜 모드 사용법

세션 중 플랜 모드 전환 Shift+Tab으로 권한 모드 간 전환합니다.

새 세션을 플랜 모드로 시작

claude --permission-mode plan

헤드리스 모드에서 플랜 모드 실행

claude --permission-mode plan -p "인증 시스템을 분석하고 개선 사항을 제안해줘"

예시: 복잡한 리팩토링 계획

claude --permission-mode plan

> OAuth2를 사용하도록 인증 시스템을 리팩토링해야 해. 상세한 마이그레이션 계획을 만들어줘

// .claude/settings.json - 플랜 모드를 기본값으로 설정
{
  "permissions": {
    "defaultMode": "plan"
  }
}

테스트 작업

> NotificationsService.swift에서 테스트로 커버되지 않은 함수를 찾아줘
> 알림 서비스에 테스트를 추가해줘
> 알림 서비스의 엣지 케이스에 대한 테스트 케이스를 추가해줘
> 새 테스트를 실행하고 실패하는 것을 수정해줘

PR 만들기

> /commit-push-pr

또는 단계별로:

> 인증 모듈에서 변경한 사항을 요약해줘
> PR을 만들어줘
> 보안 개선에 대한 더 많은 컨텍스트로 PR 설명을 보강해줘

gh pr create로 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 claude --from-pr <번호>로 재개할 수 있습니다.

이미지 작업하기

Claude Code에 이미지를 추가하는 방법:

이미지를 Claude Code 창으로 드래그 앤 드롭
이미지를 복사하고 ctrl+v로 CLI에 붙여넣기
이미지 경로 제공: 이 이미지를 분석해줘: /path/to/image.png

> 이 스크린샷이 무엇을 보여주나?
> 이 오류 스크린샷이 있어. 무엇이 원인인가?
> 이 디자인 목업과 일치하는 CSS를 생성해줘

파일 및 디렉토리 참조하기

@를 사용해서 파일이나 디렉토리를 빠르게 포함합니다:

> @src/utils/auth.js의 로직을 설명해줘
> @src/components의 구조가 어떻게 되나?
> @github:repos/owner/repo/issues의 데이터를 보여줘

Extended Thinking (사고 모드) 사용하기

Extended Thinking은 기본적으로 활성화되어 있어 Claude가 복잡한 문제를 단계별로 추론할 수 있습니다.

Ctrl+O로 상세 모드를 토글하면 내부 추론을 볼 수 있습니다.

범위	설정 방법
노력 수준	`/model`에서 조정 또는 `CLAUDE_CODE_EFFORT_LEVEL` 설정
토글 단축키	`Option+T` (macOS) 또는 `Alt+T` (Windows/Linux)
전역 기본값	`/config`로 토글

이전 대화 재개하기

claude --continue    # 가장 최근 대화 재개
claude --resume      # 대화 선택기 열기
claude --from-pr 123 # 특정 PR에 연결된 세션 재개

세션 선택기 단축키:

단축키	동작
`↑` / `↓`	세션 간 이동
`Enter`	선택한 세션 재개
`P`	세션 내용 미리보기
`R`	세션 이름 변경
`/`	검색

Git Worktree로 병렬 세션 실행하기

여러 작업을 동시에 진행할 때는 각 Claude 세션이 자체 코드베이스 복사본을 가져야 충돌이 없습니다.

# feature-auth라는 이름의 워크트리에서 Claude 시작
claude --worktree feature-auth

# 별도 워크트리에서 다른 세션 시작
claude --worktree bugfix-123

# 이름 없이 자동 생성
claude --worktree

워크트리 정리

변경 없음: 워크트리와 브랜치가 자동으로 제거됨
변경 또는 커밋 있음: 유지 또는 제거 여부 확인 프롬프트 표시

Unix 유틸리티로 Claude 사용하기

빌드 스크립트에 Claude 추가

// package.json
{
  "scripts": {
    "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos.'"
  }
}

파이프 입출력

cat build-error.txt | claude -p '이 빌드 오류의 근본 원인을 간결하게 설명해줘' > output.txt

출력 형식 제어

# 텍스트 형식 (기본)
cat data.txt | claude -p '이 데이터를 요약해줘' --output-format text

# JSON 형식
cat code.py | claude -p '이 코드의 버그를 분석해줘' --output-format json

# 스트리밍 JSON
cat log.txt | claude -p '이 로그 파일에서 오류를 파싱해줘' --output-format stream-json

다음 단계

모범 사례 - Claude Code를 최대한 활용하는 패턴
Claude Code 작동 방식 - 에이전트 루프와 컨텍스트 관리
기능 확장 - 스킬, 훅, MCP, 서브에이전트, 플러그인 추가