Claude Code 가이드: 명령어 편

작성 배경

개발자들 사이에서 뜨겁게 집중받고 있는 클로드 코드

 

개발자들 사이에서 핫한 도구 중 하나인 Claude Code! 저도 자주 활용하는 도구 중 하나입니다. 저는 간단한 코드 작업이나 가독성이 낮거나 방대한 의존성을 가진 코드를 분석하는 용도로만 사용하고 있었는데요.

 

하지만 다른 개발자 분들이 Claude Code에게 지침을 내리고 여러 오픈소스와 연동하며 효율적으로 사용하는 것을 보고 Claude Code의 10%도 활용하지 못하고 있었다는 생각에 좀 더 깊이있게 활용할 수 있는 방법에 대해 글로 정리해보려고 합니다.

Claude Code 설치 방법

사전 준비사항

Claude Code를 설치하기 전에 다음 요구사항을 확인하세요:

• Node.js 18 이상 (권장: LTS 버전)
• npm 또는 yarn 패키지 매니저
• Anthropic API 키 (유료 구독 필요)

설치 과정

1. Node.js 설치

# NVM을 통한 설치 (권장)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# 또는 직접 다운로드
# https://nodejs.org/ko/download 에서 설치

💡 Tip: NVM을 사용하면 프로젝트별로 다른 Node 버전을 쉽게 관리할 수 있습니다.

2. Claude Code 설치

# npm을 통한 전역 설치
npm install -g @anthropic-ai/claude-code

# yarn을 선호하시는 경우
yarn global add @anthropic-ai/claude-code

3. 로그인 또는 API 키 설정

# 첫 실행 시 API 키 입력 또는 로그인
claude

# 또는 환경 변수로 설정
export ANTHROPIC_API_KEY="your-api-key-here"

 

 

Claude Code 초기 환경 세팅하기

CLAUDE.md 파일 생성

프로젝트 루트에서 초기 설정 파일을 생성합니다:

# 프로젝트 디렉토리로 이동
cd /path/to/your/project

# Claude Code 실행
claude

# 초기화 명령어 실행 (지원하는 경우)
/init

⚠️ 주의: /init 명령어의 자동 생성 기능은 Claude Code 버전과 설정에 따라 다를 수 있습니다. 사용자가 직접 프로젝트 루트에 CLAUDE.md 파일을 생성하고 작성하는 것을 추천드립니다.

# 수동으로 CLAUDE.md 파일 생성
touch CLAUDE.md
# 또는 편집기로 직접 생성
nano CLAUDE.md

 

CLAUDE.md의 역할과 활용법

왜 CLAUDE.md가 중요한가요?

Claude Code는 세션이 끊어지면 프로젝트 컨텍스트를 잃어버립니다. CLAUDE.md는 이러한 문제를 해결하는 핵심 설정 파일입니다.
CLAUDE.md파일을 읽고 세션을 시작하여 불필요한 스캔이나 지시를 피할 수 있기 때문에 코드 컨벤션, 코드 생성 시 주의사항, 디렉토리 구조 등 코드를 작성하기 전에 공통적으로 알아야하는 컨텍스트는 미리 정의하여 활용하는 것을 추천드립니다.

CLAUDE.md 구조 예시

# Project Overview
이 프로젝트는 Next.js 기반 전자상거래 플랫폼입니다.

## Tech Stack
- Frontend: Next.js 14, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, React Testing Library

## Code Conventions
- 컴포넌트 파일명: PascalCase (예: UserProfile.tsx)
- 함수명: camelCase (예: getUserData)
- 상수: UPPER_SNAKE_CASE (예: API_BASE_URL)
- 들여쓰기: 2 spaces

## Testing Rules
- 모든 새로운 컴포넌트는 테스트 파일 필수
- 테스트 커버리지 최소 80% 유지
- E2E 테스트는 Cypress 사용

## Important Notes
- `/api/legacy/*` 경로의 파일은 수정하지 말 것
- 환경 변수는 `.env.example` 참조
- DB 마이그레이션은 반드시 순차적으로 실행

## Commit Convention
- feat: 새로운 기능
- fix: 버그 수정
- refactor: 코드 리팩토링
- docs: 문서 수정
- test: 테스트 코드 추가/수정

글로벌 설정

모든 프로젝트에 적용할 규칙이 있다면:

# 글로벌 CLAUDE.md 생성
mkdir -p ~/.claude
nano ~/.claude/CLAUDE.md

 

Claude Code 기본 명령어 마스터하기

일반 프롬프트

# 코드베이스 이해
> 이 프로젝트의 전체 구조를 설명해줘
> authentication 로직이 어떻게 동작하는지 분석해줘

# 디버깅
> npm test 실행 시 발생하는 에러를 해결해줘
> TypeScript 컴파일 에러를 수정해줘

# 코드 생성
> UserProfile 컴포넌트에 대한 테스트 코드 작성해줘
> REST API를 GraphQL로 마이그레이션해줘

승인 모드 종류

1. Yes (일반적으로 Enter): 의도대로 작업이 진행될 때
2. Yes, for this session (일반적으로 Shift+Tab): 반복 작업이나 문서 작업 시
3. No, refine (일반적으로 Esc): 의도와 달라 수정이 필요할 때

💡 Tip: 키 조작은 사용 환경과 개인 설정에 따라 다를 수 있습니다. claude --help 또는 /help 명령어로 현재 환경의 키 바인딩을 확인하세요.

실행 중단

1. esc: 현재 진행하고 있는 작업을 중단합니다. (작업 처음부터 의도한 작업과 다를 때 적합)
2. esc + esc: 현재까지 작업을 남기고 작업을 중단합니다. (작업 중간에 의도하지 않은 작업시 적합)

권한 설정 커스터마이징

만약 승인이 필요하지 않은 파일이나 디렉토리를 설정하고 싶은 경우 아래의 명령어를 통해 실행할 수 있습니다.

# 권한 설정 열기
/permissions

# 예시: 특정 파일/폴더 자동 승인
Allow write to: src/components/*
Allow execute: npm run test
Deny modify: src/core/*

 

기타 명령어

• /model: 클로드 코드 모델 선택
• /login: 엔트로픽 다른 계정 로그인
• /logout: 엔트로픽 로그아웃

 

Claude Code 고급 명령어와 테크닉

모드 전환 (Shift + Tab)

1. 기본 모드 (Default)

일반적인 개발 작업에 적합합니다. 모든 변경사항에 대해 확인을 요청.

? for shortcuts

2. 자동 수락 모드 (Auto-accept)

빠른 프로토타이핑이나 문서 작성 시 유용합니다.

⏵⏵ accept edits on

⚠️ 주의: 자동 수락 모드는 편리하지만, 코드 품질과 보안을 위해 중요한 변경사항은 반드시 기본 모드나 계획 모드로 전환하여 검토하는 것을 권장합니다.

3. 계획 모드 (Plan)

복잡한 리팩토링이나 아키텍처 변경과 같이 개발 전 먼저 설계, 리펙토링 계획 등읠 정의한 뒤 작업하고 싶을 때 유용합니다.

⏸ plan mode on

컨텍스트 관리 명령어

명령어	설명	실전 예시
@{파일명}	특정 파일 참조하기 위해 사용	@src/utils/auth.js를 참고하여 권한 체크 로직 개선
/compact {상세 지시}	대화 내용 요약	/compact 리팩토링 패턴 중심으로 요약
/review	코드 리뷰 진행	최근 변경사항에 대한 상세 리뷰
/bug	버그 리포트(클로드 코드 기능 문제 시)	Claude Code 자체 버그 신고

파일 및 URL 참조

# 외부 파일 참조 (드래그 앤 드롭 또는 경로 입력)
> `/Users/dev/Documents/design-specs.pdf`를 참고하여 UI 구현

# URL 참조
> https://docs.api.com/v2를 참고하여 API 클라이언트 업데이트

# 이미지 참조 (드래그 앤 드롭)
> [이미지 드롭] 이 디자인대로 컴포넌트 생성

 

 

기타 - 커스텀해서 활용하기

클로드의 강력한 도구라고 불리는 이유는 바로 커스텀이 가능하기 때문입니다. 명령어부터 시작해서 커스텀한 에이전트, mcp 연동 등 다양하게 확장될 수 있도록 구현되어 있기 때문에 필요에 따라 커스텀하여 활용하시면 더 높은 생산성을 만들 수 있습니다.

📌 참고: 아래 커스텀 설정 예시들은 Claude Code 버전과 환경에 따라 지원 여부가 다를 수 있습니다. 최신 정보는 공식 문서를 확인하세요.

1. 프로젝트별 커스텀 명령어 만들기

.claude/commands/ 디렉토리에 마크다운 파일로 프롬프트를 정의하여 커스텀 명령어를 정의할 수 있습니다:

# 커스텀 명령어 디렉토리 생성
mkdir -p .claude/commands

 

테스트 실행 명령어 예시: .claude/commands/test.md 파일 생성

# Test Runner Command

Run all tests with coverage report

## Command
npm test -- --coverage --watchAll=false

## Description
This command runs:
1. All unit tests
2. Integration tests
3. Generates coverage report
4. Exits after completion

 

리팩토링 명령어 예시: .claude/commands/refactor.md 파일 생성

# Refactoring Assistant

Helps refactor code following clean code principles

## Instructions
1. Analyze the current code structure
2. Identify code smells
3. Apply SOLID principles
4. Ensure backward compatibility
5. Add or update tests

## Rules
- Preserve all public APIs
- Maintain existing functionality
- Improve readability and maintainability

사용 방법

# 정의한 커스텀 명령어 실행
> /test  # test.md 명령어 실행
> /refactor @src/legacy/code.js  # refactor 명령어와 함께 파일 지정

2. 클로드 코드 설정

1. 설정 파일 계층 구조

• 사용자 설정: ~/.claude/settings.json 모든 프로젝트에 공유합니다.
• 프로젝트 설정: .claude/settings.json: 팀이 공유합니다.
• 로컬 설정: .claude/settings.local.json: 본인만 사용합니다.
• 엔터프라이즈 정책: 기업/IT에서 관리, 사용자-프로젝트 설정보다 우선시 합니다.

💡 자세한 내용은 링크를 참고하길 바립니다.

3. 성능 최적화 및 토큰 절약 팁

CLAUDE.md 파일 최적화하기

• CLAUDE.md에서 핵심 내용만 작성
• 필수 정보만을 담고, 상세 내용은 /docs 디렉토리를 만들어서 작성

대화 컨텍스트 관리

• /clear: 새로운 작업 시작 시 (컨텍스트 완전 초기화)
• /compact: 기존 대화 요약하여 토큰 절약

/compact 습관화 하기

• 기능 개발 완료 후
• 버그 수정 후 
• 커밋 완료 후

파일 참조 최적화

• 특정 파일만 참조하여 불필요한 컨텍스트 방지:
  •  @src/components/Header.tsx 이 파일만 리팩토링해줘
• 대규모 파일은 섹션별로 나누어 작업
  • {복사/붙여놓기 또는 메서드나 코드 줄을 지정} 기능만 분석해서 기능을 구현해줘

 

실전 활용 시나리오

시나리오 1: 레거시 코드 리팩토링

> @src/legacy/user-manager.js 이 파일을 TypeScript로 마이그레이션하고 최신 패턴 적용
> 단위 테스트도 함께 작성해줘
> 마이그레이션 가이드 문서도 만들어줘

시나리오 2: 버그 수정 워크플로우

# 1. 버그 재현
> ~./logs/2025-04-02.log 로그를 분석해서 버그 원인 파악

# 2. 테스트 작성
> 이 버그를 재현하는 테스트 코드 작성

# 3. 수정
> 테스트를 통과하도록 코드 수정

# 4. 리뷰
/review

시나리오 3: 복잡한 새 기능 개발

# 계획 모드로 전환
[Shift + Tab × 2]

> 사용자 인증 시스템을 OAuth 2.0으로 업그레이드
> 기존 세션 기반 인증과 호환성 유지
> 단계별 마이그레이션 계획 수립

 

마무리

지금까지 클로드 코드를 효과적으로 활용할 수 있는 방법들을 살펴보았습니다. Git, Docker, Kubernetes 등 많은 개발 도구들이 그렇듯이, 클로드 코드 역시 간단한 용도로는 쉽게 시작할 수 있지만 깊이 파고들면 무궁무진한 가능성을 제공합니다. 

 

이런 특성 때문에 본인의 필요에 맞는 기능들을 선별해서 단계적으로 활용해나가는 것이 중요하다고 생각합니다. 긴 글 끝까지 읽어주셔서 감사드리며, 다음 챕터에서는 클로드 코드와 같이 사용하면 좋다고 하는 슈퍼 클로드에 대해 다뤄보도록 하겠습니다. 감사합니다.