이 문서는 Claude Code를 활용하여 개발 작업을 효율적으로 수행하는 방법에 대한 포괄적인 가이드라인을 제공합니다. Claude Code는 대화형 AI assistant로서 코드베이스 탐색, 버그 수정, 리팩토링, 테스트 작성, PR 생성, 문서화, 이미지 분석 및 세션 관리와 같은 일상적인 개발 워크플로우를 지원합니다.

문서의 핵심 방법론과 기능은 다음과 같습니다:

1. 대화형 워크플로우 및 컨텍스트 관리 (Interactive Workflow and Context Management): Claude Code는 터미널 기반의 대화형 인터페이스를 통해 사용자와 상호작용합니다. 사용자의 질문과 코드 변경 요청을 처리하며, 현재 작업 디렉토리의 파일 시스템에 접근하여 코드 파일의 내용을 읽고, 수정하고, 새로운 파일을 생성할 수 있습니다. 이는 대화의 흐름에 따라 필요한 컨텍스트를 자동으로 관리하여 사용자가 추가적인 정보를 제공하지 않아도 Claude가 코드베이스를 이해하고 작업을 수행할 수 있게 합니다.

2. 코드베이스 탐색 (Codebase Exploration):
   • 빠른 개요 (Quick Overview): give me an overview of this codebase와 같은 광범위한 질문으로 시작하여 코드베이스의 고수준 아키텍처, 주요 데이터 모델, 인증 방식 등 특정 구성 요소로 질문을 좁혀나갈 수 있습니다.
   • 관련 코드 찾기 (Finding Relevant Code): 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을 설치하면 "정의로 이동" 및 "참조 찾기"와 같은 정확한 코드 네비게이션을 지원합니다.

3. 디버깅 (Debugging): 사용자로부터 오류 메시지, 스택 트레이스, 재현 단계 등의 정보를 받아 문제를 분석하고, suggest a few ways to fix...와 같이 수정 권장 사항을 제공합니다. 이어서 update user.ts to add the null check you suggested와 같은 명령을 통해 직접 코드 수정도 수행합니다.

4. 리팩토링 (Refactoring): find deprecated API usage를 통해 레거시 코드를 식별하고, 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로 검증합니다.

5. 특화된 Subagents (Specialized Subagents): Claude Code는 특정 작업을 더 효과적으로 처리하기 위해 "subagents"라는 특화된 AI 에이전트를 지원합니다. /agents 명령을 통해 사용 가능한 subagent를 확인하거나 새로운 subagent를 생성할 수 있습니다. Claude Code는 review my recent code changes for security issues와 같은 요청 시 자동으로 적절한 subagent (예: code-reviewer)에게 작업을 위임하며, 사용자는 use the code-reviewer subagent to check the auth module과 같이 명시적으로 특정 subagent를 요청할 수도 있습니다. Custom subagent는 목적, 사용 시점, 접근 가능한 도구, 시스템 프롬프트 등을 정의하여 생성할 수 있습니다.

6. Plan Mode (계획 모드): Plan Mode는 Claude가 읽기 전용 작업으로 코드베이스를 분석하고 계획을 세우도록 지시하는 특수 모드입니다. 이는 복잡한 변경 계획, 심층적인 코드 탐색, 또는 코드 안전 검토에 적합합니다. Plan Mode에서는 Claude가 AskUserQuestion 도구를 사용하여 사용자로부터 요구사항을 수집하고 목표를 명확히 합니다.
   • 활성화: 세션 중 Shift+Tab을 연속으로 눌러 전환하거나, claude --permission-mode plan 플래그로 새 세션을 시작할 수 있습니다. -p 플래그와 함께 "headless" 쿼리도 가능합니다.
   • 용도: 다단계 구현, 코드 탐색, 대화형 개발에 유용하며, Ctrl+G를 눌러 Claude가 제안한 계획을 텍스트 편집기에서 직접 수정할 수 있습니다.

7. 테스트 작업 (Working with Tests): find functions in NotificationsService.swift that are not covered by tests를 통해 테스트되지 않은 코드를 식별하고, add tests for the notification service로 테스트 스캐폴딩을 생성합니다. 기존 테스트 파일을 분석하여 프로젝트의 스타일, 프레임워크 및 어설션 패턴에 맞는 테스트를 생성하며, add test cases for edge conditions로 엣지 케이스 테스트 케이스를 추가하고 run the new tests and fix any failures로 실행 및 검증합니다.

8. Pull Request 생성 (Pull Request Creation): summarize the changes I've made to the authentication module로 변경 사항을 요약하고, /commit-push-pr skill을 사용하거나 create a pr 명령을 통해 PR을 생성합니다. Claude가 생성한 PR을 제출하기 전에 사용자가 검토하고 정제하도록 돕습니다. $claude --from-pr <number>$를 사용하여 특정 PR에 연결된 세션을 재개할 수 있습니다.

9. 문서 처리 (Handling Documentation): find functions without proper JSDoc comments로 문서화되지 않은 코드를 식별하고, add JSDoc comments to the undocumented functions를 통해 문서를 생성합니다. 생성된 문서를 검토하고 improve the generated documentation with more context and examples로 개선하며, check if the documentation follows our project standards로 유효성을 검사합니다.

10. 이미지 작업 (Working with Images): Claude Code 창으로 이미지를 드래그 앤 드롭하거나, 붙여넣기, 또는 경로를 제공하여 이미지를 대화에 추가할 수 있습니다. What does this image show?, Describe the UI elements in this screenshot와 같은 요청을 통해 이미지 콘텐츠를 분석하거나, Here's a screenshot of the error. What's causing it?와 같이 컨텍스트를 위해 이미지를 사용합니다. 또한 Generate CSS to match this design mockup처럼 시각적 콘텐츠에서 코드 제안을 얻을 수도 있습니다.

11. 파일 및 디렉토리 참조 (@ Referencing Files and Directories): @ 심볼을 사용하여 파일이나 디렉토리를 대화에 빠르게 포함할 수 있습니다. Explain the logic in @src/utils/auth.js는 파일의 전체 내용을 포함하며, What's the structure of @src/components?는 디렉토리의 파일 목록을 제공합니다. 또한 @github:repos/owner/repo/issues와 같이 MCP 리소스도 참조할 수 있습니다.

12. 확장된 사고 (Extended Thinking): Extended thinking (일명 "thinking mode")은 Claude가 응답하기 전에 복잡한 문제를 단계별로 추론할 수 있는 내부 프로세스입니다. Opus 4.6 모델에서는 "적응형 추론(adaptive reasoning)"을 사용하여 effort level (low, medium, high)에 따라 thinking tokens을 동적으로 할당합니다. 다른 모델의 경우 고정된 thinking token 예산을 사용하며, MAX_THINKING_TOKENS 환경 변수로 제한하거나 Option+T (또는 Alt+T), /config 명령으로 활성화/비활성화할 수 있습니다. Ctrl+O를 눌러 verbose mode를 토글하면 Claude의 내부 추론 과정을 회색 이탤릭 텍스트로 볼 수 있습니다.

13. 이전 대화 재개 (Resuming Previous Conversations): claude --continue (현재 디렉토리에서 가장 최근 대화), claude --resume (대화 선택기 또는 이름으로 재개), claude --from-pr 123 (특정 PR에 연결된 세션 재개) 명령을 통해 이전에 저장된 세션을 재개할 수 있습니다. /rename 명령으로 세션에 이름을 지정하여 나중에 쉽게 찾을 수 있으며, /resume 선택기에서는 키보드 단축키를 통해 세션 간 이동, 그룹화, 미리보기, 이름 변경, 필터링이 가능합니다. 모든 대화는 로컬에 메시지 기록과 도구 상태를 포함하여 자동으로 저장됩니다.

14. Git Worktrees를 사용한 병렬 세션 (Parallel Sessions with Git Worktrees): Git worktree는 동일한 Git repository에서 여러 branch를 별도의 디렉토리로 체크아웃하여 격리된 파일 상태를 가진 작업 환경을 제공합니다. 이는 여러 작업을 동시에 수행하면서 각 Claude Code 인스턴스 간의 완전한 코드 격리가 필요할 때 유용합니다. git worktree add ../project-feature-a -b feature-a 명령으로 새 worktree를 생성하고 각 worktree에서 독립적으로 Claude Code를 실행할 수 있습니다.

15. Unix 스타일 유틸리티로 사용 (Using as Unix-style Utility): Claude Code는 "headless mode"로 실행될 수 있어 빌드 스크립트에 통합되거나 다른 Unix 도구와 파이프(|)를 통해 데이터를 주고받는 데 사용될 수 있습니다. $cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt$와 같이 데이터를 파이프하고 결과를 얻을 수 있습니다. 또한 --output-format 플래그를 사용하여 텍스트(기본값), JSON, 또는 스트리밍 JSON 형식으로 출력을 제어할 수 있습니다.

16. 자체 문서화 (Self-Documentation): Claude는 자신의 기능 및 제한사항에 대해 질문에 답할 수 있도록 내장된 문서에 접근할 수 있습니다. can Claude Code create pull requests?와 같은 질문을 통해 사용자에게 유용한 정보를 제공합니다.

이 문서는 개발자들이 Claude Code를 일상적인 코딩 작업에 통합하여 생산성을 향상시키는 데 필요한 실용적인 지침을 제공합니다.