일반 워크플로

Claude Code로 코드베이스 탐색, 버그 수정, 리팩터링, 테스트, 그 밖의 일상 태스크를 수행하는 단계별 가이드입니다. 프롬프팅·컨텍스트 관리에 대한 상위 수준 안내는 Best practices를 참고하세요. 이 페이지는 일상 개발용 짧은 레시피를 모읍니다.

출처: 공식문서

본문

이 페이지는 코드 탐색·버그 수정·리팩터링·테스트·PR·문서용 프롬프트 레시피, 이전 대화 재개, 워크트리 병렬 세션, 편집 전 계획, 서브에이전트에 연구 위임, 스크립트로 파이프하는 방법을 다룹니다.

프롬프트 레시피

새 코드베이스 이해

모노레포·대형 코드베이스 구성은 Monorepos and large repos 참고.

빠른 코드베이스 개요:

cd /path/to/project
claude

give me an overview of this codebase

더 깊이:

explain the main architecture patterns used here

what are the key data models?

how is authentication handled?

팁: 넓은 질문으로 시작해 특정 영역으로 좁히고, 프로젝트의 코딩 관례·패턴을 묻고, 프로젝트 고유 용어 용어집을 요청하세요.

버그 효율적으로 수정

에러 메시지를 만나 소스를 찾고 고칩니다:

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

팁: 재현 명령과 스택 트레이스를 알려주고, 재현 단계를 언급하고, 에러가 산발적인지 일관적인지 알려주세요.

코드 리팩터링

전체 코드베이스를 새 언어로 포팅하는 것은 blog의 AI code migration 참고.

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

팁: 현대 접근의 이점을 설명하게 하고, 필요 시 하위 호환성 유지를 요청하고, 소규모·테스트 가능한 증분으로 리팩터링하세요.

테스트 작업

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

Claude는 프로젝트의 기존 패턴·관례를 따르는 테스트를 생성합니다. 검증할 동작을 구체적으로 지정하면 기존 테스트 파일을 분석해 스타일·프레임워크·어서션 패턴을 맞춥니다. 포괄 커버리지를 위해 놓친 엣지 케이스를 식별하게 하세요.

풀 리퀘스트 만들기

직접 질문("create a pr for my changes")하거나 단계별로 안내할 수 있습니다:

summarize the changes I've made to the authentication module

create a pr

enhance the PR description with more context about the security improvements

나중에 세션을 찾으려면 claude --from-pr 1234(자신의 PR 번호)로 그 PR과 연결된 세션으로 필터링된 세션 피커를 열거나, PR URL을 /resume 피커 검색에 붙여넣으세요. Claude가 gh pr create·glab mr create로 만들거나 기존 PR 작업 시 세션을 PR에 연결합니다. 제출 전 생성된 PR을 검토하고 잠재 위험을 강조하게 하세요.

문서 처리

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, docstring 등)을 지정하고, 문서에 예시를 요청하고, 공개 API·인터페이스·복잡한 로직 문서를 요청하세요.

노트·비코드 폴더에서 작업

Claude Code는 어떤 디렉터리에서든 작동합니다. 노트 보관소, 문서 폴더, 마크다운 파일 모음에서 실행하면 코드처럼 검색·편집·재구성합니다. .claude/ 디렉터리와 CLAUDE.md는 다른 도구의 구성 디렉터리와 충돌 없이 나란히 있습니다. Claude는 각 도구 호출 시 파일을 새로 읽으므로 다른 앱에서 한 편집을 다음 읽기 때 봅니다.

이미지 작업

이미지를 대화에 추가하려면: 드래그 앤 드롭, Ctrl+V로 복사·붙여넣기(Windows·WSL은 Alt+V), 또는 경로 제공("Analyze this image: /path/to/your/image.png"). 그다음 분석을 요청합니다:

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]처럼 이미지를 참조하면 Mac Cmd+Click·Windows/Linux Ctrl+Click으로 기본 뷰어에서 엽니다.

파일·디렉터리 참조

@로 파일·디렉터리를 빠르게 포함합니다:

Explain the logic in @src/utils/auth.js

What's the structure of @src/components?

Show me the data from @github:repos/owner/repo/issues

(@github:...는 @server:resource 형식으로 연결된 MCP 서버에서 데이터를 가져옵니다. MCP resources 참고.) 팁: 경로는 상대·절대 모두 가능. @를 입력해 경로 제안 메뉴를 열고 Enter·Tab으로 강조된 경로를 수락한 뒤 다시 Enter로 전송. @ 파일 참조는 해당 파일의 CLAUDE.md와 상위 디렉터리 CLAUDE.md를 컨텍스트에 추가. 디렉터리 참조는 내용이 아니라 파일 목록을 보여줍니다. 한 메시지에서 여러 파일을 참조할 수 있습니다("@file1.js and @file2.js").

스케줄로 Claude 실행

매일 아침 열린 PR 리뷰, 주간 의존성 감사, 밤새 CI 실패 확인 같은 반복 작업을 자동으로 처리하려면 위치에 따라 옵션을 고르세요:

옵션	실행 위치	최적
Routines	클라우드, 기본 Anthropic 관리	컴퓨터가 꺼져도 실행돼야 하는 태스크. 스케줄 외에 API 호출·GitHub 이벤트로도 트리거. claude.ai/code/routines에서 구성
Desktop scheduled tasks	데스크톱 앱으로 내 머신	로컬 파일·도구·커밋되지 않은 변경에 직접 접근이 필요한 태스크
GitHub Actions	내 CI 파이프라인	열린 PR 같은 레포 이벤트나 워크플로 구성 옆에 둬야 할 cron 스케줄
`/loop`	현재 CLI 세션	세션이 열려 있는 동안 빠른 폴링. 새 대화를 시작하면 태스크 중지, `--resume`·`--continue`가 만료되지 않은 것 복원

예약 태스크 프롬프트를 쓸 때는 성공이 무엇처럼 보이는지·결과로 무엇을 할지 명시하세요. 태스크는 자율 실행되어 명확화 질문을 할 수 없습니다. 예: "Review open PRs labeled needs-review, leave inline comments on any issues, and post a summary in the #eng-reviews Slack channel."

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는 문서 기반 답변을 제공합니다. 실습 데모는 /powerup(애니메이션 데모가 있는 인터랙티브 레슨)을 실행하세요. Claude는 사용 중인 버전과 무관하게 항상 최신 Claude Code 문서에 접근할 수 있습니다.

이전 대화 재개

태스크가 여러 번에 걸치면 컨텍스트를 다시 설명하는 대신 중단한 곳부터:

claude --continue

현재 디렉터리의 최근 세션을 재개하고, 없으면 No conversation found to continue를 출력하고 종료합니다. 목록에서 고르려면 claude --resume, 실행 중인 세션 안에서 /resume. 명명·브랜칭·전체 피커 참조는 Manage sessions.

워크트리 병렬 세션

한 터미널에서 기능을 작업하고 다른 터미널에서 Claude가 버그를 고치게 하며 편집이 충돌하지 않게 합니다. 각 git worktree는 기존 커밋에서 만든 자체 브랜치의 별도 체크아웃이므로, 레포에 커밋이 하나 이상 필요합니다.

claude --worktree feature-auth

두 번째 터미널에서 다른 이름으로 같은 명령을 실행해 격리된 병렬 세션을 시작합니다. 커밋이 없는 레포는 Failed to resolve base branch "HEAD": git rev-parse failed로 실패합니다. 정리·.worktreeinclude·비-git VCS 지원은 Worktrees 참고. 별도 터미널 대신 한 화면에서 병렬 세션을 모니터링하려면 background agents.

편집 전 계획

디스크에 닿기 전에 리뷰할 변경은 plan 모드로 전환합니다. Claude는 파일을 읽고 플랜을 제안하지만 승인 전까지 편집하지 않습니다. plan 모드 활성 중 상태 바는 ⏸ plan mode on을 보여줍니다.

claude --permission-mode plan

세션 중 Shift+Tab을 눌러 상태 바에 ⏸ plan mode on이 나올 때까지 순환해도 됩니다. 승인 흐름·텍스트 에디터에서 플랜 편집은 Plan mode 참고.

서브에이전트에 연구 위임

대형 코드베이스 탐색은 파일 읽기로 컨텍스트를 채웁니다. 발견만 돌아오도록 탐색을 위임하세요:

use a subagent to investigate how our auth system handles token refresh

서브에이전트는 자체 컨텍스트 윈도우에서 파일을 읽고 요약을 보고합니다. 자체 도구·프롬프트를 가진 커스텀 에이전트 정의는 Subagents.

스크립트로 파이프

CI, pre-commit 훅, 배치 처리용 비대화형 실행:

git log --oneline -20 | claude -p "summarize these recent commits"

출력 형식·권한 플래그·팬아웃 패턴은 Non-interactive mode.

다음 단계

Best practices(최대 활용 패턴), Manage sessions(대화 재개·명명·브랜치), Worktrees(격리 병렬 세션), Extend Claude Code(스킬·훅·MCP·서브에이전트·플러그인 추가).

더 알아보기

Best practices — 프롬프팅·컨텍스트 관리 상위 지침
Manage sessions — 대화 재개·명명·브랜치
Worktrees — 격리된 병렬 세션
Subagents — 연구 위임·커스텀 에이전트
Extend Claude Code — 스킬·훅·MCP·서브에이전트·플러그인