[클로드 코드 공식 문서] 3. Common workflows

MostlyFor·2026년 1월 30일
AI Native

AI Native

목록 보기
3/4

참고 자료
https://code.claude.com/docs/en/common-workflows

해당 글은 일상적인 개발을 위한 낯선 코드 탐색, 디버깅, 리팩터링, 테스트 작성, PR 만들기, 세션 관리 등을 포함한 실전 워크플로우를 다룬다.

공식문서에서 예시 프롬프트가 등장하는데 솔직히 좋은 프롬프트인지는 잘 모르겠다.

상위 레벨에서의 패턴과 팁은 다음 글인 4. Best Practices에 등장한다.

1. Understand new codebases

만약 새로운 프로젝트에 합류하게 되었고, 해당 프로젝트의 구조를 빨리 이해해야 하는 경우

Get a quick codebase overview

  1. 루트 리렉토리로 이동
  2. 클로드 코드 시작
  3. high-level overview 부탁 - 예시 프롬프트) give me an overview of this codebase
  4. 특정 컴포넌트 탐색 - > explain the main architecture patterns used here

공식문서 팁
1. 넓은 범위 -> 좁은 범위로 질문
2. 해당 프로젝트에서 사용된 coding conventions와 patterns 질문
3. 해당 프로젝트에서 쓰이는 용어집 정리 요청

Find relevent code

특정 기능을 하는 코드를 찾아야 하는 경우

  1. 관련된 파일 찾기 - > find the files that handle user authentication
  2. 컴포넌트 동작 맥락 알기 -> how do these authentication files work together?
  3. 실행 flow 이해하기 - > trace the login process from front-end to database

공식문서 팁
1. 내가 찾는 부분을 구체적으로 명시
2. 도메인 용어를 사용해라
3. a code intelligence plugin을 설치해서 활용하라

2. Fix bugs efficiently

에러 메시지를 발견해 해당 부분을 찾고 수정해야 하는 경우

  1. 클로드에게 에러 공유 -> I'm seeing an error when I run npm test
  2. 에러를 고치는 여러 방법들 요청하기 -> suggest a few ways to fix the @ts-ignore in user.ts
  3. 방법 적용하기 -> update user.ts to add the null check you suggested

공식문서 팁
1. 버그를 재현할 수 있는 명령어와 스택 트레이스를 클로드에게 알리기
2. 버그를 만드는 steps이 있다면 절차를 알려주기
3. 오류가 항상 발생하는지 간헐적으로 발생하는지 알려주기

3. Refactor code

modern pattern과 practices로 바꿔야 하는 경우

  1. 리팩터링 대상 코드 식별 -> find deprecated API usage in our codebase
  2. 리팩터링 방향 제안 받기 -> suggest how to refactor utils.js to use modern JavaScript features
  3. 안전하게 변화 적용 -> refactor utils.js to use ES2024 features while maintaining the same behavior
  4. 리팩터링 검증하기 -> run tests for the refactored code

공식문서 팁
1. modern approach의 장점이 무엇인지 물어보기
2. 필요한 경우 backward compatibility을 유지하도록 변경 요청
3. 작고, 테스트 가능한 단위로 나눠서 리팩터링 진행

4. Use Specialized subagents

특정 기능에 특화된 subagent를 사용하고 싶은 경우

  1. 가능한 서브에이전트 확인 -> /agents

  2. 서브에이전트 자동 사용

  • Claude Code는 자동으로 적절하게 서브 에이전트에게 위임
    -> review my recent code changes for security issues, > run all tests and fix any failures

  1. 명시적으로 서브에이전트 요청 -> use the code-reviewer subagent to check the auth module

  2. 커스텀 서브에이전트 만들기 -> /agents

공식문서 팁

  • 팀과 공유할 수 있도록 프로젝트 전용 서브에이전트는 .claude/agents/에 생성
  • 자동 위임이 잘 되도록 description을 명확하게
  • 각 서브에이전트는 역할 수행에 필요한 도구들만 접근 허용
  • subagents documentation 확인하기

5. Use Plan Mode for safe code analysis

플랜 모드는 read-only operation만 사용해서 코드 베이스를 분석하는 모드라 코드베이스를 탐색하거나 복잡한 변경을 계획하거나, 코드를 안전하게 리뷰할 때 적합하다.

또한, 플랜 모드는 AskUserQuestion을 사용해서 계획을 제안하기 전에 요구사항을 수집하고 목표를 명확히 한다.

플랜 모드는 언제 쓸까?

  • Multi-step implementation
    내가 개발하고자 하는 기능이 여러 파일을 수정해야 할 때
  • Code exploration
    코드베이스를 충분히 이해하고자 할 때
  • Interactive development
    클로드와 상호작용 하면서 개발하고 싶을 때

플랜 모드 어떻게 쓸까?

세션 중 shift-tap으로 플랜 모드로 변경하거나 아예 새로운 세션 시작 claude --permision-mode plan

공식문서 팁

  • Ctrl + G를 눌러서 클로드의 계획을 실행하기 전에 직접 수정할 수 있다.

Plan Mode를 디폴트로 사용하는 방법

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

6. Work with tests

테스트를 해야할 때

  1. 테스트 필요한 코드 식별 -> find functions in NotificationsService.swift that are not covered by tests
  2. 테스트 scaffold 생성 -> add tests for the notification service
  3. 테스트 케이스 추가 -> add test cases for edge conditions in the notification service
  4. 테스트 실행 및 검증 -> run the new tests and fix any failures
  • 클로드는 프로젝트의 기존 테스트 스타일이나 규칙을 살펴, 일관된 형식으로 테스트 생성 가능
  • 요청할 땐 구체적으로 명시할 것
  • 클로드는 테스트 케이스를 제안할 수 있다 (테스트 케이스도 만들어 달라고 하면 될듯)

7. Create pull requests

pr 날리는 방법은
1. 클로드한테 요청
2. /commit-push-pr 스킬 사용
3. 스킬 만들기

클로드한테 요청하는 방법
1. 변경 사항 요약 -> summarize the changes I've made to the authentication module
2. PR 생성 -> create a pr
3. PR 검토 및 개선 -> enhance the PR description with more context about the security improvements

공식문서 팁

  • 클로드 PR은 제출하기 전에 꼭 검토
  • 잠재적 리스크나 고려해야 할 점을 Claude에게 따로 강조해서 찾기

8. Handle documentation

프로젝트 코드에 대해 문서를 만들 때

  1. 문서가 없는 코드 식별 -> auth 모듈에서 적절한 JSDoc 주석이 없는 함수들을 찾아줘
  2. 문서 생성 -> add JSDoc comments to the undocumented functions in auth.js
  3. 검토 및 개선 -> improve the generated documentation with more context and examples
  4. 문서 검증 -> check if the documentation follows our project standards

공식문서 팁

  • 내가 원하는 문서 형식 명시할 것 (docstrings, JSDoc)
  • 문서에 사용 예시 포함 요청
  • 공개 API, interface, 복잡한 로직에 대해서는 문서 요청

9. Work with images

코드베이스에서 이미지를 다루는 경우

1.대화에 이미지 추가하기

  • 경로를 전달해도 되고, CLI에 붙여넣어도 됨
  1. 이미지 분석 요청 -> What does this image show?
  2. 이미지 맥락 활용하기 -> Here's a screenshot of the error. What's causing it?
    4. 이미지로 코드 추천받기 -> What HTML structure would recreate this component?

공식문서 팁

  • 텍스트로 설명하기 어려운 경우 이미지 활용할 것
  • 에러 화면, UI 디자인, 다이어그램 등이 맥락 풍부하게 함
  • 여러 이미지를 한 대화에서 사용 가능
  • 스크린샷, 다이어그램, 목업 등 다양한 형식 이미지 지원
  • 이미지 참조할 때 cmd+Click으로 이미지 열어볼 수 있다.

10. Reference files and directories

@를 활용하면 클로드가 파일을 읽어올 때까지 기다리지 않고 파일이나 디렉터리 빠르게 context로 줄 수 있다.

  1. 단일 파일 참조 -> Explain the logic in @src/utils/auth.js
  2. 디렉터리 참조 -> What's the structure of @src/components?
  3. MCP 리소스 참조 -> Show me the data from @github:repos/owner/repo/issues

공식문서 팁

  • 파일 경로는 상대 경로와 절대 경로 둘 다 가능
  • @로 파일 참조 시 연관된(상위까지 포함) CLAUDE.md도 같이 context 추가
  • 디렉터리 참조의 경우 파일 내용은 없이 목록만 보여줌
  • 여러 파일 동시 참조 가능

11. Use extended thinking (thinking mode)

개인적인 생각

  • 동적으로 필요한 곳에는 thinking 예산 늘리면 어떨지..?

extended thinking은 기본으로 활성화 되어 있고, 복잡한 문제 추론을 위해 31999 토큰까지 추론에 할당한다.

extended thinking은 특히 다음 상황에서 가치가 크다.

  • 복잡한 아키텍처 의사결정
  • 해결하기 까다로운 버그
  • 여러 단계로 이루어진 구현 계획 수립
  • 다른 접근 방식 사이의 트레이드오프 평가

공식문서 팁

  • think hard, think more 같은 phrase들은 일반적인 지시문으로 처리된다. 이런 곳에 토큰 비용쓰지 마라.

Configure thinking mode

토큰 예산 제한 방법

  • 환경 변수를 통해 해당 모드의 예산을 조절할 수 있다.
    Example: export MAX_THINKING_TOKENS=10000

How extended thinking token budgets work

Extended thinking의 토큰 예산은 내부 추론의 양을 제한

더 큰 토큰 예산이 제공하는 것

  • 여러 해결 방법을 단게별로 탐색할 수 있는 여유
  • 엣지 케이스 분석과 트레이드오프 평가를 충분히 할 수 있는 공간
  • 추론을 되돌아보고 수정하며 자기 오류를 교정할 수 있는 능력

Thinking 예산 제한하기

  • MAX_THINKING_TOKENS 환경 변수를 사용해 thinking 예산의 상한을 설정할 수 있다
  • 유효한 토큰 범위는 extended thinking 문서 참고

12. Resume previous conversations

기본 방법

  • calude --continue (가장 최근)
  • claude --resume (session picket 열거나 이름으로 바로 시작)

현재 활성 세션에서도 resume을 이용하면 전환 가능

세션에 이름 붙이기

여러 작업을 할 때 세션에 이름 붙이는게 best practice

  1. 현재 세션 이름 정하기 -/rename auth-refactor

session picker 이용하기

/resume 명령이나 claude --resume으로 열 수 있음

단축키동작
↑ / ↓세션 간 이동
→ / ←그룹된 세션 펼치기 / 접기
Enter선택된 세션 재개
P세션 내용 미리보기
R선택된 세션 이름 변경
/검색하여 세션 필터링
A현재 디렉토리 / 전체 프로젝트 세션 전환
B현재 git 브랜치의 세션만 필터
Esc선택기 또는 검색 모드 종료

공식문서 팁

  • 세션 초기에 이름 붙이기
  • 내부 동작 방식
    1. 대화 저장
    - 모든 대화는 로컬에 전체 메시지 기록과 함께 저장
    1. 메시지 역직렬화
      • 재개 시, 전체 히스토리 복원으로 context 유지
    2. 도구 상태 유지
      • 사용한 도구와 결과도 보존
    3. 컨텍스트 복원
      • 모든 context 그대로 유지

13. Run parallel Calude Code sessions with Git worktrees

동시에 여러 작업을 해야하는데 완전히 격리된 코드로 작업을 해야할 때

  1. git worktrees 이해하기
  • 여러 브랜치에 대해 각각 다른 디렉토리로 체크아웃 할 수 있게 해주는 도구

  1. 새 worktree 생성하기

  2. 각 worktree에서 클로드 코드 실행하기

  3. worktree 관리하기

  • 작업이 끝난 worktree 제거

공식문서 팁

  • 각 worktree는 독립된 파일 상태를 가지므로, 병렬 세션에 최적
  • 모든 worktree는 같은 git 히스토리와 원격 저장소 공유
  • 디렉토리 이름을 작업 목적이 드러나게 짓기 - project-feature-a
  • 새 worktree를 만들면 개발 환경 초기화를 잊지 말 것! (파이썬의 경우 가상환경 생성 및 패키지 설치)

# 14. Use Claude as a unix-style utility

15. Ask Claude about its capabilities

클로드는 클로드 공식 문서에 대한 접근 권한을 가지고 있어서 할 수 있는 것과 한계를 물어보면 된다.

profile
MostlyFor
이전 포스트

[클로드 코드 공식 문서] 2. Extend Claude Code

다음 포스트

[클로드 코드 공식 문서] 4. Best Practices for Claude Code

0개의 댓글