Claude Code의 모든 기능을 효과적으로 활용하는 방법

 

CodeDeck - 개발자를 위한 코드 학습 카드 뉴스

 

AI 기반 코딩 도구들이 우후죽순 쏟아지고 있는 요즘, Claude Code는 단순히 코드를 생성하는 것을 넘어서 실제 프로덕션 환경에서 활용 가능한 강력한 기능들을 제공합니다. 이 글에서는 Claude Code의 핵심 기능들을 실전 관점에서 깊이 있게 다루어 보겠습니다.

CLAUDE.md: 에이전트의 헌법

프로젝트에서 가장 중요한 파일은 바로 루트 디렉토리의 CLAUDE.md입니다. 이 파일은 Claude Code가 여러분의 코드베이스를 이해하는 핵심 문서입니다.

효과적인 CLAUDE.md 작성 원칙

1. 가드레일부터 시작하기

처음부터 완벽한 매뉴얼을 작성하려 하지 마세요. Claude가 실수하는 부분을 발견할 때마다 조금씩 추가하는 방식이 훨씬 효과적입니다.

# 프로젝트 구조

## Python 설정
- 항상 Poetry를 사용하여 의존성 관리
- 테스트는 `poetry run pytest tests/` 명령으로 실행
- 타입 체킹은 `mypy src/` 로 검증

## API 호출 규칙
- 절대 `requests` 라이브러리를 직접 사용하지 말 것
- 대신 `src/api/client.py`의 `APIClient` 클래스 사용
- 에러 처리는 `src/errors.py`의 커스텀 예외 활용

2. 파일 전체를 @-멘션하지 않기

다른 곳에 자세한 문서가 있다고 해서 @docs/api.md 같은 식으로 전체 파일을 언급하면 컨텍스트 윈도우가 불필요하게 커집니다. 대신, 언제 그 파일을 읽어야 하는지 구체적으로 안내하세요.

## 데이터베이스 마이그레이션

기본적인 마이그레이션은 `alembic revision --autogenerate` 사용

복잡한 데이터 전환이나 `IntegrityError`가 발생하면 
`docs/database/migrations.md`의 고급 패턴 참조

3. "절대 ~하지 마"만 쓰지 않기

부정형 제약만 두면 에이전트가 막다른 골목에 빠집니다. 항상 대안을 제시하세요.

❌ 나쁜 예:
- 절대 `--force` 플래그를 사용하지 마세요

✅ 좋은 예:
- `--force` 플래그 대신 `--safe-mode`를 사용하세요
- 충돌이 발생하면 먼저 `git fetch origin`으로 최신 상태를 확인

4. CLAUDE.md를 코드 개선의 강제 함수로 활용

복잡한 CLI 명령어를 장황하게 설명하기보다는, 간단한 래퍼 스크립트를 만들고 그것을 문서화하세요.

## 배포 프로세스

복잡한 배포 명령어 대신 간단한 스크립트 사용:

```bash
./scripts/deploy.sh staging  # 스테이징 환경 배포
./scripts/deploy.sh production --with-migrations  # 프로덕션 배포 + 마이그레이션

이렇게 하면 CLAUDE.md도 간결해지고, 실제 개발자들도 더 쉽게 사용할 수 있습니다.

컨텍스트 윈도우 관리

Claude Code는 200k 토큰의 컨텍스트 윈도우를 제공하지만, 이것도 금방 찹니다. /context 명령어로 현재 사용량을 확인할 수 있습니다.

컨텍스트 리셋 전략

1. /compact (비추천)

자동 압축은 불투명하고 오류가 많습니다. 가급적 피하세요.

2. /clear + /catchup (기본 재시작)

가장 많이 사용하는 방법입니다:

# 커스텀 slash 명령어 정의
# ~/.claude/commands.json
{
  "catchup": {
    "prompt": "현재 git 브랜치에서 변경된 모든 파일을 읽고 요약해줘"
  }
}

세션이 복잡해지면 /clear로 초기화하고 /catchup으로 변경사항만 빠르게 파악합니다.

3. Document & Clear (복잡한 재시작)

대규모 작업에는 이 방법을 씁니다:

1. Claude에게 현재 진행상황과 계획을 .md 파일로 작성하게 함
2. /clear로 컨텍스트 초기화
3. 새 세션에서 그 .md 파일을 읽고 이어서 진행

예시:

# progress.md

## 완료된 작업
- ✅ User 모델에 email_verified 필드 추가
- ✅ 이메일 인증 API 엔드포인트 구현
- ✅ 단위 테스트 작성 완료

## 다음 단계
1. 프론트엔드에서 이메일 인증 플로우 구현
2. 인증 이메일 템플릿 디자인 개선
3. 통합 테스트 추가

## 주의사항
- email_verified 체크는 login 엔드포인트에도 추가 필요
- 기존 유저들은 verified=True로 마이그레이션

Slash 명령어: 심플하게 유지하기

Slash 명령어는 자주 쓰는 프롬프트의 단축키일 뿐입니다. 복잡하게 만들지 마세요.

// ~/.claude/commands.json
{
  "catchup": {
    "prompt": "git diff origin/main을 보고 변경된 모든 파일을 읽어서 현재 작업을 요약해줘"
  },
  "pr": {
    "prompt": "코드를 정리하고, 테스트를 실행한 후, git add/commit/push하고 PR 생성을 준비해줘"
  },
  "test": {
    "prompt": "변경된 코드와 관련된 모든 테스트를 찾아서 실행하고 결과를 보고해줘"
  }
}

안티패턴: 수십 개의 복잡한 slash 명령어를 만들어서 문서화하는 것. 그러면 팀원들이 또 다른 명령어 세트를 배워야 합니다. Claude의 핵심 가치는 자연어로 소통하는 것입니다.

Subagent: 내장 Task() 기능 활용하기

커스텀 서브에이전트는 이론적으로는 강력하지만, 실전에서는 두 가지 문제가 있습니다:

1. 컨텍스트 차단: 특정 작업(예: 테스트)을 서브에이전트에 위임하면, 메인 에이전트는 그 컨텍스트를 잃습니다.
2. 강제된 워크플로우: 인간이 정의한 위임 방식에 갇히게 됩니다.

더 나은 접근: Master-Clone 아키텍처

모든 핵심 컨텍스트를 CLAUDE.md에 넣고, 메인 에이전트가 자체적으로 Task(...) 기능을 써서 클론을 생성하게 하세요.

# Claude의 내부 동작 (예시)
# 여러분이 직접 호출하는 것이 아닙니다

# 메인 에이전트의 추론:
"이 변경사항은 3개 모듈에 영향을 줌. 병렬로 테스트하자"

Task("module_a/tests 실행")
Task("module_b/tests 실행")  
Task("module_c/tests 실행")

이렇게 하면:

• 모든 에이전트가 동일한 컨텍스트(CLAUDE.md)를 가짐
• 에이전트가 스스로 작업 분배를 결정
• 유연한 동적 오케스트레이션

Hooks: 커밋 시점에 검증하기

Hooks는 엔터프라이즈 환경에서 필수적입니다. 에이전트가 "반드시" 지켜야 하는 규칙을 강제합니다.

Block-at-Submit 패턴

가장 효과적인 패턴은 커밋 시점에 검증하는 것입니다:

# .claude/hooks/pre_tool_use.py

def handle_pre_tool_use(tool_name, tool_input):
    if tool_name == "Bash" and "git commit" in tool_input.get("command", ""):
        # 테스트 통과 플래그 확인
        if not os.path.exists("/tmp/agent-pre-commit-pass"):
            return {
                "block": True,
                "message": "테스트가 통과하지 않았습니다. 먼저 `npm test`를 실행하세요."
            }
    
    return {"block": False}

테스트 스크립트는 성공 시 플래그 파일을 생성:

#!/bin/bash
# test-and-flag.sh

npm test
if [ $? -eq 0 ]; then
    touch /tmp/agent-pre-commit-pass
    echo "✅ 모든 테스트 통과"
else
    rm -f /tmp/agent-pre-commit-pass
    echo "❌ 테스트 실패"
    exit 1
fi

피해야 할 패턴: Block-at-Write

파일 편집 중간에 막지 마세요. 에이전트를 혼란스럽게 만듭니다. 작업을 끝내고 최종 결과를 검증하는 것이 훨씬 효과적입니다.

Planning Mode: 큰 작업은 계획부터

복잡한 기능을 개발할 때는 항상 Planning Mode를 사용하세요:

claude --plan "사용자 프로필 페이지에 아바타 업로드 기능 추가"

Planning Mode는:

1. 구현 전에 Claude와 계획을 정렬
2. 중간 체크포인트 정의 (언제 멈춰서 보여줄지)
3. 최소 컨텍스트로 좋은 계획을 만드는 감각 개발

엔터프라이즈 환경에서의 커스텀 플래닝

회사에서는 Claude Code SDK로 커스텀 플래닝 도구를 만들 수 있습니다:

# custom_planner.py (의사코드)

def generate_plan(feature_description):
    plan = claude_code_sdk.plan(
        prompt=f"""
        다음 기능을 우리의 기술 스택으로 계획하세요:
        {feature_description}
        
        우리의 아키텍처 원칙:
        - Clean Architecture 패턴 사용
        - 모든 외부 호출은 Repository 패턴으로
        - 비즈니스 로직은 UseCase 레이어에
        - 보안: 모든 사용자 입력은 검증 필수
        """,
        context_files=["CLAUDE.md", "docs/architecture.md"]
    )
    
    return format_as_tech_design(plan)

Skills vs MCP: 새로운 패러다임

Skills는 MCP보다 더 중요할 수 있습니다. 에이전트 자율성의 진화:

1. Single Prompt (단일 프롬프트)
   └─> 모든 컨텍스트를 한 번에 제공
   
2. Tool Calling (도구 호출)
   └─> 수작업으로 만든 도구로 현실 추상화
   
3. Scripting (스크립팅) 🎯
   └─> 원시 환경 접근, 에이전트가 즉석에서 코드 작성

Skills는 바로 이 "Scripting" 레이어를 공식화한 것입니다.

Skills의 실제 사용

# /mnt/skills/myproject/deployment/SKILL.md

# 배포 스킬

이 스킬은 애플리케이션 배포를 자동화합니다.

## 사용 가능한 도구

- `./scripts/deploy.sh <env>`: 특정 환경에 배포
- `./scripts/rollback.sh <version>`: 이전 버전으로 롤백
- `./scripts/health-check.sh`: 배포 후 헬스체크

## 배포 프로세스

1. 변경사항 검증 (테스트, 린트)
2. 빌드 생성
3. 스테이징에 먼저 배포
4. 헬스체크 통과 후 프로덕션 배포

## 예제

스테이징 배포:
```bash
./scripts/deploy.sh staging
./scripts/health-check.sh staging

프로덕션 배포 (마이그레이션 포함):

./scripts/deploy.sh production --with-migrations
./scripts/health-check.sh production

에러 해결

• Database connection failed: docs/troubleshooting.md 참조
• Health check timeout: --timeout 300 옵션 사용

CLI를 선호하는 이유가 여기 있습니다. 에이전트가 스크립트를 보고 즉석에서 조합할 수 있습니다.

## MCP의 새로운 역할

Skills가 등장했다고 MCP가 죽은 것은 아닙니다. 역할이 달라졌을 뿐입니다.

**과거 (나쁜 패턴):**
```javascript
// 수십 개의 도구로 REST API 미러링
mcp.tool("read_user", ...)
mcp.tool("read_users", ...)
mcp.tool("update_user", ...)
mcp.tool("delete_user", ...)
mcp.tool("read_post", ...)
// ... 50개 더

현재 (좋은 패턴):

// 소수의 강력한 고수준 도구
mcp.tool("query_database", async (filters) => {
  // 인증, 네트워킹, 보안 경계 관리
  const data = await securelyFetchData(filters)
  return data  // 에이전트가 스크립트로 처리
})

mcp.tool("execute_in_sandbox", async (code) => {
  // 샌드박스 환경에서 코드 실행
  return await runInIsolatedEnv(code)
})

MCP는 인증, 네트워킹, 보안 경계를 관리하는 게이트웨이입니다. 현실을 추상화하는 것이 아닙니다.

Claude Code SDK: 범용 에이전트 프레임워크

SDK는 대화형 CLI를 넘어서는 강력한 도구입니다.

1. 대규모 병렬 스크립팅

#!/bin/bash
# mass-refactor.sh

# 100개 파일을 병렬로 리팩토링
find src/ -name "*.py" | xargs -P 10 -I {} \
  claude -p "{}에서 모든 'old_function'을 'new_function'으로 변경"

2. 내부 챗 도구 구축

# installer_with_ai.py

def install_package(package_name):
    try:
        subprocess.run(["pip", "install", package_name], check=True)
    except subprocess.CalledProcessError as e:
        # 실패 시 Claude Code SDK로 문제 해결
        print("설치 실패. AI가 문제를 해결합니다...")
        fix_prompt = f"pip install {package_name} 실패: {e}. 원인을 파악하고 해결해줘"
        claude_code_sdk.chat(fix_prompt)

3. 신속한 에이전트 프로토타이핑

# threat_investigation_agent.py

from claude_code import Agent

agent = Agent(
    tools=["security_log_analyzer", "network_scanner"],
    prompt="""
    보안 위협 조사 에이전트입니다.
    의심스러운 활동을 발견하면:
    1. 로그 분석
    2. 네트워크 스캔
    3. 위협 보고서 생성
    """
)

agent.run("최근 24시간 동안의 비정상적인 로그인 시도 조사")

GitHub Actions: 운영 자동화의 정점

Claude Code GitHub Action은 가장 저평가된 기능입니다.

# .github/workflows/ai-pr.yml

name: AI Bug Fix

on:
  issues:
    types: [labeled]

jobs:
  auto-fix:
    if: github.event.label.name == 'ai-fix'
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            이슈 #${{ github.event.issue.number }}를 읽고
            버그를 수정한 후 PR을 생성하세요.
            
            수정 전 반드시:
            1. 모든 테스트 실행
            2. 린트 체크
            3. 타입 체킹
          
          hooks: |
            .claude/hooks/enforce-tests.py
          
          max-cost: 5.00

Slack/Jira 통합 예시

# Slack 명령어로 PR 생성
on:
  repository_dispatch:
    types: [slack-command]

jobs:
  handle-slack-request:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: ${{ github.event.client_payload.message }}

로그 분석으로 자기 개선

# 지난 5일간의 에이전트 실수 분석
$ query-claude-gha-logs --since 5d | \
  claude -p "다른 Claude들이 자주 막힌 부분을 분석하고, 
             CLAUDE.md와 도구들을 개선해서 PR 올려줘"

이것이 진정한 데이터 기반 플라이휠입니다:

버그 발견 → CLAUDE.md 개선 → 더 나은 에이전트 → 더 적은 버그

settings.json 고급 설정

// ~/.claude/settings.json
{
  // 디버깅용 프록시
  "HTTPS_PROXY": "http://localhost:8888",
  
  // 타임아웃 증가 (복잡한 명령어용)
  "MCP_TOOL_TIMEOUT": 300000,
  "BASH_MAX_TIMEOUT_MS": 600000,
  
  // 엔터프라이즈 API 키 (사용량 기반 요금)
  "ANTHROPIC_API_KEY": "${apiKeyHelper}",
  
  // 자동 승인할 명령어 (보안 주의)
  "permissions": {
    "autoApprove": [
      "npm test",
      "git status",
      "git diff"
    ]
  }
}

프록시 디버깅 팁

# mitmproxy로 트래픽 검사
$ mitmproxy -p 8888

# Claude Code 실행하면 모든 API 호출이 보임
$ claude -p "간단한 함수 작성해줘"

실전 활용 패턴 요약

1. 호비 프로젝트

# 빠른 프로토타이핑
$ claude --dangerously-skip-permissions \
  -p "React로 실시간 채팅 앱 만들어줘"

2. 팀 프로젝트

1. CLAUDE.md 공유 유지 (13KB 정도)
2. Hooks로 테스트 강제
3. Planning Mode 필수 사용
4. 정기적인 로그 리뷰

3. 엔터프라이즈

1. 커스텀 플래닝 도구
2. GHA로 자동화 (Slack/Jira 통합)
3. 사용량 기반 라이선스
4. 지속적인 CLAUDE.md 개선 프로세스

마치며

Claude Code는 단순한 코드 생성 도구가 아닙니다. 제대로 활용하면 팀의 생산성을 근본적으로 변화시킬 수 있는 플랫폼입니다.

핵심은:

• CLAUDE.md를 살아있는 문서로 관리
• 에이전트를 신뢰하되, 검증은 철저히 (Hooks)
• 단순함 유지 (복잡한 커스텀 명령어보다 좋은 도구)
• 스크립팅 모델 수용 (Skills > MCP)