이 페이지는 일상적인 개발을 위한 실용적인 워크플로우를 다룹니다: 낯선 코드 탐색, 디버깅, 리팩토링, 테스트 작성, PR 생성 및 세션 관리입니다. 각 섹션에는 자신의 프로젝트에 맞게 조정할 수 있는 예제 프롬프트가 포함되어 있습니다. 더 높은 수준의 패턴과 팁은 Best practices를 참조하십시오.
새로운 코드베이스 이해하기
코드베이스의 빠른 개요 얻기
새로운 프로젝트에 방금 참여했고 그 구조를 빠르게 이해해야 한다고 가정해봅시다.
높은 수준의 개요 요청
> give me an overview of this codebase
특정 구성 요소에 대해 더 깊이 있게 살펴보기
> explain the main architecture patterns used here
> what are the key data models?
> how is authentication handled?
팁:
- 광범위한 질문으로 시작한 다음 특정 영역으로 좁혀나가기
- 프로젝트에서 사용되는 코딩 규칙과 패턴에 대해 질문하기
- 프로젝트별 용어 용어집 요청하기
관련 코드 찾기
특정 기능이나 기능과 관련된 코드를 찾아야 한다고 가정해봅시다.
Claude에게 관련 파일을 찾도록 요청
> find the files that handle user authentication
구성 요소가 어떻게 상호작용하는지에 대한 컨텍스트 얻기
> how do these authentication files work together?
실행 흐름 이해하기
> trace the login process from front-end to database
팁:
- 찾고 있는 것에 대해 구체적으로 설명하기
- 프로젝트의 도메인 언어 사용하기
- 언어에 대한 code intelligence plugin을 설치하여 Claude에게 정확한 “정의로 이동” 및 “참조 찾기” 네비게이션 제공하기
효율적으로 버그 수정하기
오류 메시지가 나타났고 그 원인을 찾아 수정해야 한다고 가정해봅시다.
Claude와 오류 공유하기
> I'm seeing an error when I run npm test
수정 권장사항 요청하기
> suggest a few ways to fix the @ts-ignore in user.ts
수정 적용하기
> update user.ts to add the null check you suggested
팁:
- Claude에게 문제를 재현하는 명령과 스택 추적을 알려주기
- 오류를 재현하는 단계 언급하기
- 오류가 간헐적인지 일관적인지 Claude에게 알려주기
코드 리팩토링
오래된 코드를 현대적인 패턴과 관행을 사용하도록 업데이트해야 한다고 가정해봅시다.
리팩토링할 레거시 코드 식별
> find deprecated API usage in our codebase
리팩토링 권장사항 얻기
> suggest how to refactor utils.js to use modern JavaScript features
안전하게 변경사항 적용하기
> refactor utils.js to use ES2024 features while maintaining the same behavior
리팩토링 검증하기
> run tests for the refactored code
팁:
- Claude에게 현대적인 접근 방식의 이점을 설명하도록 요청하기
- 필요할 때 변경사항이 하위 호환성을 유지하도록 요청하기
- 작고 테스트 가능한 증분으로 리팩토링 수행하기
특화된 subagents 사용하기
특정 작업을 더 효과적으로 처리하기 위해 특화된 AI subagents를 사용하고 싶다고 가정해봅시다.
사용 가능한 subagents 보기
이것은 모든 사용 가능한 subagents를 표시하고 새로운 것을 만들 수 있게 해줍니다. 자동으로 subagents 사용하기
Claude Code는 자동으로 적절한 작업을 특화된 subagents에게 위임합니다:> review my recent code changes for security issues
> run all tests and fix any failures
명시적으로 특정 subagents 요청하기
> use the code-reviewer subagent to check the auth module
> have the debugger subagent investigate why users can't log in
워크플로우를 위한 사용자 정의 subagents 만들기
그런 다음 “Create New subagent”를 선택하고 프롬프트를 따라 다음을 정의합니다:
- subagent의 목적을 설명하는 고유 식별자 (예:
code-reviewer, api-designer).
- Claude가 이 agent를 사용해야 할 때
- 액세스할 수 있는 도구
- agent의 역할과 동작을 설명하는 시스템 프롬프트
팁:
- 팀 공유를 위해
.claude/agents/에 프로젝트별 subagents 만들기
- 자동 위임을 활성화하기 위해 설명적인
description 필드 사용하기
- 각 subagent가 실제로 필요한 것으로 도구 액세스 제한하기
- 자세한 예제는 subagents documentation을 확인하기
Plan Mode를 사용하여 안전한 코드 분석
Plan Mode는 Claude에게 읽기 전용 작업으로 코드베이스를 분석하여 계획을 세우도록 지시하며, 코드베이스 탐색, 복잡한 변경 계획 또는 코드 안전한 검토에 완벽합니다. Plan Mode에서 Claude는 AskUserQuestion을 사용하여 계획을 제안하기 전에 요구사항을 수집하고 목표를 명확히 합니다.
Plan Mode를 사용할 때
- 다단계 구현: 기능이 많은 파일을 편집해야 할 때
- 코드 탐색: 무엇이든 변경하기 전에 코드베이스를 철저히 조사하고 싶을 때
- 대화형 개발: Claude와 방향을 반복하고 싶을 때
Plan Mode 사용 방법
세션 중에 Plan Mode 켜기
Shift+Tab을 사용하여 세션 중에 Plan Mode로 전환할 수 있습니다.
Normal Mode에 있으면 Shift+Tab은 먼저 Auto-Accept Mode로 전환되며, 터미널 하단에 ⏵⏵ accept edits on으로 표시됩니다. 그 다음 Shift+Tab은 Plan Mode로 전환되며, ⏸ plan mode on으로 표시됩니다. agent team이 활성화되어 있으면 사이클에 Delegate Mode도 포함됩니다.
Plan Mode에서 새 세션 시작하기
Plan Mode에서 새 세션을 시작하려면 --permission-mode plan 플래그를 사용합니다:
claude --permission-mode plan
-p를 사용하여 Plan Mode에서 직접 쿼리를 실행할 수도 있습니다 (즉, “headless mode”에서):
claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
예제: 복잡한 리팩토링 계획하기
claude --permission-mode plan
> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
> What about backward compatibility?
> How should we handle database migration?
계획을 기본 텍스트 편집기에서 열려면 Ctrl+G를 누르고, Claude가 진행하기 전에 직접 편집할 수 있습니다.
Plan Mode를 기본값으로 구성하기
// .claude/settings.json
{
"permissions": {
"defaultMode": "plan"
}
}
테스트 작업하기
적용되지 않은 코드에 대한 테스트를 추가해야 한다고 가정해봅시다.
테스트되지 않은 코드 식별
> find functions in NotificationsService.swift that are not covered by tests
테스트 스캐폴딩 생성
> add tests for the notification service
의미 있는 테스트 케이스 추가
> add test cases for edge conditions in the notification service
테스트 실행 및 검증
> run the new tests and fix any failures
Pull Request 만들기
Claude에게 직접 요청하거나 (create a pr for my changes) /commit-push-pr skill을 사용하여 pull request를 만들 수 있으며, 이는 한 단계에서 커밋, 푸시 및 PR을 엽니다.
Slack MCP server가 구성되어 있고 CLAUDE.md에서 채널을 지정한 경우 (예: “post PR URLs to #team-prs”), skill은 자동으로 PR URL을 해당 채널에 게시합니다.
프로세스를 더 잘 제어하려면 Claude를 단계별로 안내하거나 자신의 skill을 만드십시오:
변경사항 요약하기
> summarize the changes I've made to the authentication module
검토 및 정제하기
> enhance the PR description with more context about the security improvements
gh pr create를 사용하여 PR을 만들면 세션이 자동으로 해당 PR에 연결됩니다. 나중에 claude --from-pr <number>로 재개할 수 있습니다.
Claude가 생성한 PR을 제출하기 전에 검토하고 Claude에게 잠재적 위험이나 고려사항을 강조하도록 요청하십시오.
문서 처리하기
코드에 대한 문서를 추가하거나 업데이트해야 한다고 가정해봅시다.
문서화되지 않은 코드 식별
> find functions without proper JSDoc comments in the auth module
문서 생성
> add JSDoc comments to the undocumented functions in auth.js
검토 및 개선
> improve the generated documentation with more context and examples
문서 검증
> check if the documentation follows our project standards
팁:
- 원하는 문서 스타일 지정하기 (JSDoc, docstrings 등)
- 문서에 예제 요청하기
- 공개 API, 인터페이스 및 복잡한 로직에 대한 문서 요청하기
이미지 작업하기
코드베이스에서 이미지로 작업해야 하고 Claude의 이미지 콘텐츠 분석 도움을 원한다고 가정해봅시다.
대화에 이미지 추가하기
다음 방법 중 하나를 사용할 수 있습니다:
- Claude Code 창으로 이미지를 드래그 앤 드롭하기
- 이미지를 복사하고 ctrl+v로 CLI에 붙여넣기 (cmd+v를 사용하지 마십시오)
- Claude에게 이미지 경로 제공하기. 예: “Analyze this image: /path/to/your/image.png”
Claude에게 이미지 분석 요청하기
> What does this image show?
> Describe the UI elements in this screenshot
> Are there any problematic elements in this diagram?
컨텍스트를 위해 이미지 사용하기
> Here's a screenshot of the error. What's causing it?
> This is our current database schema. How should we modify it for the new feature?
시각적 콘텐츠에서 코드 제안 얻기
> Generate CSS to match this design mockup
> What HTML structure would recreate this component?
팁:
- 텍스트 설명이 불명확하거나 번거로울 때 이미지 사용하기
- 더 나은 컨텍스트를 위해 오류, UI 디자인 또는 다이어그램의 스크린샷 포함하기
- 대화에서 여러 이미지로 작업할 수 있습니다
- 이미지 분석은 다이어그램, 스크린샷, 목업 등과 함께 작동합니다
- Claude가 이미지를 참조할 때 (예:
[Image #1]), Cmd+Click (Mac) 또는 Ctrl+Click (Windows/Linux)을 링크에 클릭하여 기본 뷰어에서 이미지를 엽니다
파일 및 디렉토리 참조하기
@를 사용하여 Claude가 읽을 때까지 기다리지 않고 파일이나 디렉토리를 빠르게 포함합니다.
단일 파일 참조하기
> Explain the logic in @src/utils/auth.js
디렉토리 참조하기
> What's the structure of @src/components?
MCP 리소스 참조하기
> Show me the data from @github:repos/owner/repo/issues
팁:
- 파일 경로는 상대 또는 절대 경로일 수 있습니다
- @ 파일 참조는 파일의 디렉토리 및 상위 디렉토리에서
CLAUDE.md를 컨텍스트에 추가합니다
- 디렉토리 참조는 내용이 아닌 파일 목록을 표시합니다
- 단일 메시지에서 여러 파일을 참조할 수 있습니다 (예: “@file1.js and @file2.js”)
확장된 사고 사용하기 (thinking mode)
Extended thinking은 기본적으로 활성화되어 있으며, Claude가 응답하기 전에 복잡한 문제를 단계별로 추론할 수 있는 공간을 제공합니다. 이 추론은 Ctrl+O로 전환할 수 있는 verbose mode에서 볼 수 있습니다.
또한 Opus 4.6은 적응형 추론을 도입합니다: 고정된 thinking token 예산 대신 모델은 effort level 설정에 따라 동적으로 thinking을 할당합니다. Extended thinking과 적응형 추론은 함께 작동하여 응답하기 전에 Claude가 얼마나 깊이 있게 추론할지에 대한 제어를 제공합니다.
Extended thinking은 복잡한 아키텍처 결정, 어려운 버그, 다단계 구현 계획 및 다양한 접근 방식 간의 트레이드오프 평가에 특히 유용합니다.
“think”, “think hard”, “ultrathink” 및 “think more”와 같은 구문은 일반 프롬프트 지시로 해석되며 thinking tokens을 할당하지 않습니다.
Thinking mode 구성하기
Thinking은 기본적으로 활성화되어 있지만 조정하거나 비활성화할 수 있습니다.
| 범위 | 구성 방법 | 세부사항 |
|---|
| Effort level | /model에서 조정하거나 CLAUDE_CODE_EFFORT_LEVEL 설정 | Opus 4.6에 대한 thinking 깊이 제어: low, medium, high (기본값). Adjust effort level 참조 |
| Toggle shortcut | Option+T (macOS) 또는 Alt+T (Windows/Linux) 누르기 | 현재 세션에 대해 thinking 켜기/끄기 (모든 모델). terminal configuration을 활성화해야 할 수 있습니다 |
| Global default | /config를 사용하여 thinking mode 전환 | 모든 프로젝트에서 기본값 설정 (모든 모델).
~/.claude/settings.json에 alwaysThinkingEnabled로 저장됨 |
| Limit token budget | MAX_THINKING_TOKENS 환경 변수 설정 | thinking 예산을 특정 토큰 수로 제한 (Opus 4.6에서는 0으로 설정하지 않으면 무시됨). 예: export MAX_THINKING_TOKENS=10000 |
Ctrl+O를 눌러 verbose mode를 전환하고 회색 이탤릭 텍스트로 표시된 내부 추론을 확인하십시오.
Extended thinking 작동 방식
Extended thinking은 Claude가 응답하기 전에 수행하는 내부 추론의 양을 제어합니다. 더 많은 thinking은 솔루션을 탐색하고, 엣지 케이스를 분석하고, 실수를 자체 수정할 수 있는 더 많은 공간을 제공합니다.
Opus 4.6을 사용하면, thinking은 적응형 추론을 사용합니다: 모델은 선택한 effort level (low, medium, high)에 따라 thinking tokens을 동적으로 할당합니다. 이것은 속도와 추론 깊이 간의 트레이드오프를 조정하는 권장 방법입니다.
다른 모델을 사용하면, thinking은 출력 예산에서 최대 31,999 토큰의 고정 예산을 사용합니다. MAX_THINKING_TOKENS 환경 변수로 이를 제한하거나 /config 또는 Option+T/Alt+T 전환을 통해 thinking을 완전히 비활성화할 수 있습니다.
MAX_THINKING_TOKENS는 Opus 4.6을 사용할 때 무시됩니다. 적응형 추론이 thinking 깊이를 제어하기 때문입니다. 한 가지 예외: MAX_THINKING_TOKENS=0을 설정하면 모든 모델에서 thinking을 완전히 비활성화합니다.
Claude 4 모델이 요약된 thinking을 표시하더라도 사용된 모든 thinking tokens에 대해 요금이 청구됩니다
이전 대화 재개하기
Claude Code를 시작할 때 이전 세션을 재개할 수 있습니다:
claude --continue는 현재 디렉토리에서 가장 최근 대화를 계속합니다claude --resume은 대화 선택기를 열거나 이름으로 재개합니다claude --from-pr 123은 특정 pull request에 연결된 세션을 재개합니다
활성 세션 내에서 /resume을 사용하여 다른 대화로 전환합니다.
세션은 프로젝트 디렉토리별로 저장됩니다. /resume 선택기는 worktrees를 포함하여 동일한 git repository의 세션을 표시합니다.
세션 이름 지정하기
나중에 찾을 수 있도록 세션에 설명적인 이름을 지정합니다. 이것은 여러 작업이나 기능을 작업할 때 모범 사례입니다.
현재 세션 이름 지정하기
세션 중에 /rename을 사용하여 기억하기 쉬운 이름을 지정합니다:선택기에서 세션 이름을 바꿀 수도 있습니다: /resume을 실행하고, 세션으로 이동한 다음 R을 누릅니다. 나중에 이름으로 재개하기
명령줄에서:claude --resume auth-refactor
세션 선택기 사용하기
/resume 명령 (또는 인수 없이 claude --resume)은 다음 기능이 있는 대화형 세션 선택기를 엽니다:
선택기의 키보드 단축키:
| 단축키 | 작업 |
|---|
↑ / ↓ | 세션 간 이동 |
→ / ← | 그룹화된 세션 확장 또는 축소 |
Enter | 강조 표시된 세션 선택 및 재개 |
P | 세션 콘텐츠 미리보기 |
R | 강조 표시된 세션 이름 바꾸기 |
/ | 세션을 필터링하기 위해 검색 |
A | 현재 디렉토리와 모든 프로젝트 간 전환 |
B | 현재 git branch의 세션으로 필터링 |
Esc | 선택기 또는 검색 모드 종료 |
- 세션 이름 또는 초기 프롬프트
- 마지막 활동 이후 경과 시간
- 메시지 수
- Git branch (해당하는 경우)
포크된 세션 (/rewind 또는 --fork-session으로 생성됨)은 루트 세션 아래에 그룹화되어 관련 대화를 더 쉽게 찾을 수 있습니다.
팁:
- 세션 조기 이름 지정: 별개의 작업을 시작할 때
/rename을 사용합니다—나중에 “payment-integration”을 찾는 것이 “explain this function”보다 훨씬 쉽습니다
- 현재 디렉토리에서 가장 최근 대화에 빠르게 액세스하려면
--continue 사용
- 필요한 세션을 알 때
--resume session-name 사용
- 검색하고 선택해야 할 때
--resume (이름 없이) 사용
- 스크립트의 경우
claude --continue --print "prompt"를 사용하여 비대화형 모드에서 재개
- 선택기에서
P를 눌러 재개하기 전에 세션을 미리봅니다
- 재개된 대화는 원본과 동일한 모델 및 구성으로 시작됩니다
작동 방식:
- 대화 저장: 모든 대화는 전체 메시지 기록과 함께 자동으로 로컬에 저장됩니다
- 메시지 역직렬화: 재개할 때 전체 메시지 기록이 복원되어 컨텍스트를 유지합니다
- 도구 상태: 이전 대화의 도구 사용 및 결과가 보존됩니다
- 컨텍스트 복원: 대화는 모든 이전 컨텍스트와 함께 재개됩니다
Git worktrees를 사용하여 병렬 Claude Code 세션 실행하기
여러 작업을 동시에 수행해야 하며 Claude Code 인스턴스 간에 완전한 코드 격리가 필요하다고 가정해봅시다.
Git worktrees 이해하기
Git worktrees를 사용하면 동일한 repository에서 여러 branch를 별도의 디렉토리로 체크아웃할 수 있습니다. 각 worktree는 동일한 Git 기록을 공유하면서 격리된 파일이 있는 자체 작업 디렉토리를 가집니다. official Git worktree documentation에서 자세히 알아보십시오. 새 worktree 만들기
# 새 branch를 사용하여 새 worktree 만들기
git worktree add ../project-feature-a -b feature-a
# 또는 기존 branch를 사용하여 worktree 만들기
git worktree add ../project-bugfix bugfix-123
각 worktree에서 Claude Code 실행하기
# worktree로 이동
cd ../project-feature-a
# 이 격리된 환경에서 Claude Code 실행
claude
다른 worktree에서 Claude 실행하기
cd ../project-bugfix
claude
worktrees 관리하기
# 모든 worktrees 나열
git worktree list
# 완료되면 worktree 제거
git worktree remove ../project-feature-a
팁:
- 각 worktree는 자체 독립적인 파일 상태를 가지므로 병렬 Claude Code 세션에 완벽합니다
- 한 worktree에서 만든 변경사항은 다른 worktree에 영향을 주지 않으므로 Claude 인스턴스가 서로 간섭하지 않습니다
- 모든 worktrees는 동일한 Git 기록 및 원격 연결을 공유합니다
- 장기 실행 작업의 경우 한 worktree에서 Claude가 작업하는 동안 다른 worktree에서 개발을 계속할 수 있습니다
- 각 worktree가 어떤 작업을 위한 것인지 쉽게 식별할 수 있도록 설명적인 디렉토리 이름을 사용합니다
- 각 새 worktree에서 프로젝트의 설정에 따라 개발 환경을 초기화해야 합니다. 스택에 따라 다음이 포함될 수 있습니다:
- JavaScript 프로젝트: 종속성 설치 실행 (
npm install, yarn)
- Python 프로젝트: 가상 환경 설정 또는 패키지 관리자로 설치
- 기타 언어: 프로젝트의 표준 설정 프로세스 따르기
Claude를 unix 스타일 유틸리티로 사용하기
검증 프로세스에 Claude 추가하기
Claude Code를 linter 또는 코드 검토자로 사용하고 싶다고 가정해봅시다.
빌드 스크립트에 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. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
}
}
팁:
- CI/CD 파이프라인에서 자동 코드 검토를 위해 Claude 사용
- 프롬프트를 사용자 정의하여 프로젝트와 관련된 특정 문제 확인
- 다양한 유형의 검증을 위해 여러 스크립트 만들기 고려
파이프 인, 파이프 아웃
Claude로 데이터를 파이프하고 구조화된 형식으로 데이터를 다시 얻고 싶다고 가정해봅시다.
Claude를 통해 데이터 파이프하기:
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
팁:
- 파이프를 사용하여 Claude를 기존 shell 스크립트에 통합
- 강력한 워크플로우를 위해 다른 Unix 도구와 결합
- 구조화된 출력을 위해 —output-format 사용 고려
출력 형식 제어하기
특히 Claude Code를 스크립트나 다른 도구에 통합할 때 특정 형식의 Claude 출력이 필요하다고 가정해봅시다.
텍스트 형식 사용 (기본값)
cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt
JSON 형식 사용
cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
스트리밍 JSON 형식 사용
cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json
팁:
- Claude의 응답만 필요한 간단한 통합을 위해
--output-format text 사용
- 전체 대화 로그가 필요할 때
--output-format json 사용
- 각 대화 차례의 실시간 출력을 위해
--output-format stream-json 사용
Claude의 기능에 대해 Claude에게 물어보기
Claude는 자신의 문서에 대한 기본 제공 액세스 권한을 가지고 있으며 자신의 기능 및 제한사항에 대한 질문에 답할 수 있습니다.
예제 질문
> can Claude Code create pull requests?
> how does Claude Code handle permissions?
> what skills are available?
> how do I use MCP with Claude Code?
> how do I configure Claude Code for Amazon Bedrock?
> what are the limitations of Claude Code?
Claude는 이러한 질문에 대해 문서 기반 답변을 제공합니다. 실행 가능한 예제 및 실습 시연을 위해 위의 특정 워크플로우 섹션을 참조하십시오.
팁:
- Claude는 사용 중인 버전에 관계없이 항상 최신 Claude Code 문서에 액세스할 수 있습니다
- 자세한 답변을 얻으려면 구체적인 질문을 하십시오
- Claude는 MCP 통합, 엔터프라이즈 구성 및 고급 워크플로우와 같은 복잡한 기능을 설명할 수 있습니다
다음 단계
