Claude Code 사용 가이드: 실무 개발 워크플로우를 위한 모범 사례

Anthropic의 에이전트형 코딩 어시스턴트인 Claude Code를 실제 개발 워크플로우에 효과적으로 사용하는 실용적인 안내서입니다. 이 저장소는 Claude Code를 터미널 기반 코딩 환경에 통합하기 위한 모범 사례, 패턴 및 예시들을 담고 있습니다.

Claude Code는 Claude의 추론 및 코딩 기능에 직접 접근할 수 있게 해주는 커맨드라인 도구입니다. 이는 에이전트형 코딩(agentic coding)을 위해 설계되었는데, 이 방식에서는 Claude가 프로젝트 전반에 걸쳐 코드를 자율적으로 탐색하고, 수정하며, 설명합니다. 마치 사용자의 저장소 구조, 코딩 컨벤션 및 워크플로우를 이해하는 협업 AI 페어 프로그래머와 같습니다.

• 🛠️ 설정 팁 (Setup Tips)

  • Claude Code를 위한 환경 구성 방법

• 🧠 프롬프트 설계 및 컨텍스트 처리 (Prompt Design & Context Handling)

  • 코드 생성, 리팩토링 또는 디버깅을 위해 Claude에게 요청하는 효과적인 방법들
  • 프로젝트 컨텍스트를 미리 로드하기 위해 CLAUDE.md 사용

• 🧪 테스트 및 디버깅 (Testing & Debugging)

  • CLI에서 테스트 실행, 실패 수정, 코드 린팅까지 모두 수행

• 🔄 Git 워크플로우 (Git Workflows)

  • Claude를 사용하여 커밋 생성, PR 열기, 병합 충돌 해결

• ⚙️ 후크 및 자동화 (Hooks & Automation)

  • 명명 규칙, 테스트 프로토콜, 아키텍처 규칙 강제 적용

• 🛡️ 안전성 및 제어 (Safety & Control)

  • Claude Code가 읽기 전용 접근 및 도구 권한을 처리하는 방법
  • 사용자의 도구, 표준, 저장소와 연동하여 작동

• 🧰 실제 예시 (Real Examples)

  • Claude Code의 동작을 보여주는 스크립트 및 터미널 세션들

Claude Code는 자율성과 인지 능력을 가지고 행동하는 AI인 에이전트형 코딩에 최적화되어 있습니다:

• 코드베이스 구조 및 의존성을 이해합니다
• 파일 전반에 걸쳐 조정된 수정(coordinated edits)을 수행합니다
• GitHub, GitLab, VS Code, JetBrains IDEs와 통합됩니다
• 유연성, 투명성, 개발자 제어에 중점을 두고 설계되었습니다.

이 저장소에는 Claude Code를 사용하여 개발 워크플로우를 간소화하도록 설계된 사용자 지정 슬래시 명령어 모음이 포함되어 있습니다. 사용 가능한 모든 명령어에 대한 자세한 정보를 얻으려면 /help-commands를 사용하세요.

/custom-init

자동으로 프로젝트 구조, 기술 스택, 개발 패턴을 분석하여 포괄적인 CLAUDE.md 파일을 생성합니다.

• /help-commands
  사용 가능한 모든 사용자 지정 명령어에 대한 종합적인 도움말 문서를 제공하며, 사용 예시와 모범 사례를 포함합니다.

• /commit
  자동 스테이징, diff 분석 및 원자적 커밋(atomic commit) 권장 사항을 통해 모범 사례를 따르는 잘 형식화된 컨벤셔널 커밋(conventional commits)을 생성합니다. .gitmessage와 .github/COMMIT_CONVENTION.md에서 표준화된 커밋 템플릿을 사용합니다.

• /issue
  GitHub Flow에 따른 엔드투엔드 GitHub 이슈 해결 프로세스로, 자동 계획 수립, 브랜치 생성 및 점진적 구현을 수행합니다. .github/pull_request_template.md의 GitHub PR 템플릿과 통합됩니다.

• /reviewpr
  CI/CD 검사, 코드 품질 분석, GitHub CLI를 통한 구조화된 피드백이 포함된 포괄적인 풀 리퀘스트(Pull Request) 검토 프로세스입니다.

/test
프레임워크 감지, 타겟 테스트 실행, 커버리지 분석 및 자동 수정 기능을 통해 포괄적인 테스트 실행 및 개선을 수행합니다.

이 저장소에는 모든 개발 워크플로우 전반에 걸쳐 도메인별 전문 지식을 제공하는 10개의 특화된 AI 에이전트 모음이 포함되어 있습니다. 이 에이전트들은 명령어와 함께 작동하여 아키텍처, 개발 및 품질 보증(QA) 분야에서 전문가 수준의 역량을 제공합니다.

참고: 명령어들은 복잡한 다단계 분석 및 파일 검색을 위해 Claude Code에 내장된 general-purpose 에이전트를 활용하기도 합니다. 이는 Claude Code와 함께 제공되므로 이 저장소에는 정의되어 있지 않습니다.

• general-solution-architect
  아키텍처 분석, 기술 스택 결정, 확장성 계획 및 분산 시스템 설계.

• general-technical-writer
  문서 생성, API 문서화, 형식 지정 및 기술 콘텐츠 구성.

• general-pm
  제품 관리 감독 — 이슈 생성, 우선순위 지정, 진행 상황 추적 및 라이프사이클 관리.

• general-fullstack-developer

데이터베이스, API 및 프론트엔드 계층을 아우르는 엔드투엔드(End-to-end) 기능 구현과 원활한 통합.

• general-backend-developer

API 개발, 데이터베이스 설계, 서버 측 로직, 그리고 백엔드 성능 최적화.

• general-frontend-developer

UI/UX 구현, 컴포넌트 패턴(component patterns), 브라우저 자동화, 그리고 모던 JavaScript 프레임워크.

• general-devops

인프라 자동화, CI/CD 파이프라인 설계, 컨테이너 오케스트레이션(container orchestration), 그리고 신뢰성 공학(reliability engineering).

• general-qa

테스팅 전략, 테스트 자동화, 포괄적인 검증, 그리고 품질 보증 방법론(quality assurance methodologies).

• general-code-quality-debugger

코드 리뷰, 체계적인 디버깅, 리팩토링 가이드, 그리고 기술 부채 감소.

• general-technical-project-lead

보안 평가, 전략적 기술 결정, 성능 최적화, 그리고 아키텍처 리더십.

에이전트 통합(Agent Integration): 이러한 전문 에이전트는 모든 사용자 지정 명령어와 원활하게 작동하며, 필요할 때 자동으로 도메인 전문 지식을 제공합니다. /issue, /reviewpr, 및 /test와 같은 명령어는 여러 에이전트를 활용하여 포괄적이고 전문가 수준의 결과를 제공합니다.

스킬(Skills)은 모델 호출 가능 기능입니다: 슬래시 명령어에 의해 트리거되는 대신, Claude Code가 작업이 스킬의 description과 일치할 때 자동으로 이를 로드합니다. 각 스킬은 .claude/skills/<name>/SKILL.md에 존재하며 YAML 프론매터(name, description)와 본문에 지침을 포함합니다.

이 리포지토리에는 하나의 예시가 포함되어 있습니다:

conventional-commits
커밋 메시지를 작성할 때마다 프로젝트의 커밋 형식을 자동으로 강제 적용하며 — 별도의 명령어가 필요하지 않습니다.

스킬 대 명령어 대 에이전트:

스킬(Skill) 대 명령어(Command) 대 에이전트(Agent):

스크립트 번들링 및 참조 파일과 함께 SKILL.md를 통해 작성하는 상세 내용은 Skills 문서를 참고하세요.

저장소에는 두 가지 가장 유용한 프로젝트 수준 구성 메커니즘을 시연하는 체크인된 .claude/settings.json이 포함되어 있습니다:

• 범위 지정 allow / ask / deny 규칙: Claude Code가 프롬프트 없이 안전하고 일상적인 명령어(git status, gh pr view 등)를 실행하도록 허용하고, 위험도가 높은 명령어(git push)에 대해서는 확인을 요구하며, 민감한 파일(.env, secrets/ 등)의 읽기를 차단할 수 있습니다. 이 설정을 팀의 위험 허용도에 맞게 조정하세요. 설정은 사용자, 프로젝트, 로컬 범위를 병합하여 적용됩니다.

• 훅 (Hooks): 라이프사이클 이벤트(PreToolUse, PostToolUse, Stop 등) 발생 시 자동으로 실행되는 셸 명령어를 등록합니다. 번들된 예시는 매 턴 끝에 항상 변경 사항을 확인할 수 있도록 Stop 훅을 사용하여 git status --short를 출력합니다. 다른 일반적인 패턴:

  • PostToolUse / Edit|Write: Claude가 파일을 편집한 후 자동으로 포맷하거나 린트(lint)합니다.
  • PreToolUse / Bash: 위험한 명령어가 실행되기 전에 차단합니다.
  • Stop: Claude가 장기 작업을 완료했을 때 데스크톱/Slack 알림을 보냅니다.

전체 이벤트 목록과 JSON 스키마는 Hooks 문서를 참고하세요.

클로드 코드(Claude Code)는 에이전트 기반 코딩을 위한 명령줄 도구입니다. 이 글에서는 다양한 코드베이스, 언어 및 환경에서 Claude Code를 사용하는 데 효과적임이 입증된 팁과 트릭들을 다룹니다.

일반적인 워크플로우(Common Workflows)

Claude Code의 일반적인 워크플로우에 대해 알아보세요. 이 문서의 각 작업에는 명확한 지침, 예시 명령어 및 Claude Code를 최대한 활용하는 데 도움이 되는 모범 사례가 포함되어 있습니다.
Git 워크트리(Worktrees)를 사용해 병렬 Claude Code 세션 실행하기

Claude Code 인스턴스 간에 완벽한 코드 격리가 필요한 여러 작업을 동시에 처리해야 한다고 가정해 보세요.

클로드의 메모리 관리(Manage Claude's Memory)

다양한 메모리 위치와 모범 사례를 통해 세션 전반에 걸쳐 Claude Code의 메모리를 관리하는 방법을 알아보세요. Claude Code는 스타일 가이드라인이나 워크플로우 내 일반 명령어 등 사용자의 선호도를 세션 간에도 기억할 수 있습니다.
훅(Hooks)

셸 명령어를 등록하여 Claude Code의 동작을 사용자 정의하고 확장하세요.
서브 에이전트(Sub-agents)

작업별 워크플로우 및 개선된 컨텍스트 관리를 위해 Claude Code에서 전문화된 AI 서브 에이전트를 생성하고 사용하세요.
Claude Code 서브에이전트 모음(Claude Code Subagents Collection)
by davepoon

도메인별 전문 지식을 통해 개발 워크플로우를 향상시키도록 설계된 Claude Code용 특화된 AI 서브 에이전트의 포괄적인 모음입니다.
GitHub Actions

Claude Code GitHub Actions를 사용하여 개발 워크플로우에 Claude Code를 통합하는 방법을 알아보세요. Claude Code GitHub Actions는 AI 기반 자동화를 GitHub 워크플로우로 가져옵니다. PR이나 이슈에서 간단히 @claude를 언급하기만 하면, Claude가 프로젝트 표준을 따르면서 코드를 분석하고, 풀 리퀘스트를 생성하며, 기능을 구현하고, 버그를 수정할 수 있습니다.
나의 Claude Code 워크플로우 및 개인 팁(My Claude Code Workflow and Personal Tips)
by paradite

제가 로드맵과 태스크 파일을 사용하여 Claude Code를 관리하는 방법과 효과적인 Claude Code 사용을 위한 개인적인 팁들입니다.
Playwright MCP 서버

모델 컨텍스트 프로토콜(Model Context Protocol) 서버로, Playwright를 사용하여 브라우저 자동화 기능을 제공합니다. 이를 통해 Claude가 웹 페이지와 상호 작용하고, 양식을 채우고, 스크린샷을 찍으며, 실제 브라우저에서 엔드투엔드 검사를 실행할 수 있게 합니다. 이전 버전인 Puppeteer MCP 서버는 보관되었으며, Playwright MCP가 유지되는 대체재입니다.

The Claude Code WORKFLOW with GitHub to Build Complex Apps

by gregbaugues

"Claude Code를 사용해 앱을 만드는 데 어려움을 겪고 있다면, 아마도 더 나은 프로세스가 필요하기 때문일 것입니다. 코드를 작성하는 것은 복잡한 소프트웨어를 출시하는 것 중 한 부분에 불과합니다. 다행히도, 저희는 복잡한 소프트웨어를 구축하는 데 도움이 되는 워크플로우를 가지고 있으며, 이는 Claude Code와 훌륭하게 작동합니다."
How to Give Claude Code a Better "Memory" of Your Project

by iannuttall

"이 영상에서는 제가 만든 사용자 지정 슬래시 명령 세트를 보여드리는데, 이 명령어들은 Claude Code로 수행한 모든 변경 사항을 /compact를 사용하는 것보다 훨씬 좋은 단순 메모리 시스템에 기록하는 데 도움이 될 것입니다."
Claude Code Multitasking Made EASY

by CasJam

"이 영상은 Git Worktrees 사용법과 여러 Claude Code 에이전트를 동시에 실행하기 위해 새로운 worktree를 설정하는 워크플로우 자동화 방법을 보여줍니다."
Claude Code Hooks is AMAZING: "Text Message Me When AI Agent is Done"

by AllAboutAI-YT

AI 코딩 에이전트가 작업을 완료했을 때 문자 메시지를 보내는 방법—셸 명령을 사용하여 알림을 자동화하는 방법을 보여주는 실습 데모입니다.
My Claude Code Sub Agents BUILD THEMSELVES

by disler

"Claude Code Sub Agents를 잘못 사용하고 계신가요? 제가 여러분께 큰 아이디어가 있습니다. 서브 에이전트(Sub Agents)는 AI 코딩의 모든 것을 바꿨습니다. 올바른 접근 방식을 사용하면, 이제 여러분의 에이전트들이 스스로 구축할 수 있게 되었습니다."

Awesome Claude Code

by hesreallyhim

"이것은 Claude Code 워크플로우, 생산성, 분위기를 향상시키기 위한 슬래시 명령, CLAUDE.md 파일, CLI 도구 및 기타 리소스와 가이드가 선별된 목록입니다."
SuperClaude Framework

by SuperClaude-Org

클로드 코드에 전문화된 명령어, 페르소나 및 MCP 서버 통합 기능을 확장하는 프레임워크입니다. Agent OS

by buildermethods

"Agent OS는 AI 코딩 에이전트를 혼란스러운 인턴에서 생산적인 개발자로 변모시킵니다."