Claude Code의 모든 기능 활용법

8 hours ago 2

Claude Code를 개인 프로젝트와 기업용 모노레포 환경에서 광범위하게 활용하며, 핵심 구성요소와 고급 기능의 실제 사용 방식을 정리
효과적인 에이전트 운용의 핵심은 출력 스타일이나 UI가 아닌 최종 PR의 품질에 있으며, "설정 후 방치(shoot and forget)" 방식의 위임이 목표
코드베이스의 중심은 CLAUDE.md 파일로, 에이전트의 행동 규칙과 도구 사용법을 정의하는 “헌법” 역할 수행
컨텍스트 관리, 슬래시 명령어, 서브에이전트, Hooks, GitHub Action(GHA) 등 다양한 기능을 통해 협업과 자동화 수준 향상
Skills와 MCP(Model Context Protocol) 의 관계를 구분해, 스크립팅 중심의 유연한 에이전트 구조를 강조
Claude Code를 단순한 CLI 도구가 아닌 엔터프라이즈급 AI 개발 인프라로 확장할 수 있는 실질적 가이드 제공

Cladude 코드를 매우 많이 사용함
- 취미 프로젝트는 VM에서 주 여러 번 실행, --dangerously-skip-permissions로 떠오르는 아이디어를 즉시 코드화
- 업무에선 팀에서 AI-IDE 규칙 및 도구를 구축하며, 우리 엔지니어링 팀이 코드 생성만으로 월 수십억 토큰 소비
CLI 에이전트 시장은 Claude Code, Gemini CLI, Cursor, Codex CLI로 혼잡하지만 실질적 경쟁은 Anthropic과 OpenAI 둘이 경쟁
- 하지만 개발자들과 대화 해보면 도구 선택은 표면적 요소에 의존함
  - "운 좋은" 기능 구현 이나 선호하는 시스템 프롬프트의 "Vibe" 등
- 현 시점에서 이러한 도구들은 모두 상당히 우수한 상태임
일부는 출력 스타일이나 UI에 대한 과도한 집중을 하기도 함
- "you're absolutely right!" 같은 아첨은 주목할 만한 버그가 아님
- 오히려 사용자가 과도하게 루프에 관여하고 있다는 신호
나의 핵심 사용 철학은 "Shoot and Forget" 임
- 위임, 컨텍스트 설정, 작업 수행 순서로 진행
- 도구는 최종 PR로 판단하며, 도달 과정이 아닌 결과물로 평가
이 글음 지난 몇 개월간 Claude Code 사용 경험 기반 생태계 전체에 대한 성찰 임
- 내가 사용하는 거의 모든 기능 (그리고 사용하지 않는 기능)
- 기본적인 CLAUDE.md 파일
- 커스텀 슬래시 커맨드
- Subagent, Hook, GitHub Actions의 강력한 세계
글이 상당히 길어져서 전체 읽기보다는 레퍼런스로 활용 권장

CLAUDE.md: 에이전트의 헌법

루트 CLAUDE.md는 레포지토리 작동 방식에 대한 에이전트의 주요 진실 공급원
- 취미 프로젝트: Claude가 원하는 대로 자유롭게 작성
- 엔터프라이즈 모노레포: 13KB 규모로 엄격 관리 (25KB까지 확장 가능)
- 엔지니어 30% 이상이 사용하는 도구만 문서화
- 각 내부 도구 문서화에 최대 토큰 수 할당 ("광고 공간" 판매 방식)
- 도구를 간결하게 설명하지 못하면 CLAUDE.md 준비 미완료
팁과 일반적 안티패턴
- 가드레일로 시작, 매뉴얼 아님: Claude가 잘못하는 부분 기반으로 소규모 문서화 시작
- @-파일 문서화 금지
  - 다른 곳의 광범위한 문서를 @-언급하면 매 실행마다 전체 파일이 컨텍스트 윈도우에 임베딩되어 비대화
  - 단순히 경로만 언급하면 Claude가 무시하는 경향
  - 에이전트에게 파일을 읽어야 하는 이유와 시점을 "제안" 해야 함
  - 예: "복잡한 사용법이나 FooBarError 발생 시 고급 문제 해결을 위해 path/to/docs.md 참조"
- "절대 안 됨"만 말하지 말 것
  - "절대 --foo-bar 플래그 사용하지 말 것" 같은 부정형 제약 회피
  - 에이전트가 해당 플래그를 사용해야 한다고 생각할 때 막힘
  - 항상 대안 제시
- CLAUDE.md를 강제 함수로 활용
  - CLI 명령이 복잡하고 장황하면 설명 문단을 작성하지 말 것 (인간 문제 패치)
  - 대신 명확하고 직관적인 API를 가진 간단한 bash 래퍼 작성 후 래퍼 문서화
  - CLAUDE.md를 최대한 짧게 유지하는 것은 코드베이스와 내부 도구 단순화를 위한 환상적인 강제 함수
예시 구조
# Monorepo ## Python - Always ... - Test with <command> ... 10개 항목 ... ## <Internal CLI Tool> ... 80% 사용 사례에 집중한 10개 불릿 ... - <usage example> - Always ... - Never <x>, prefer <Y> 복잡한 사용법이나 오류 시 path/to/<tool>_docs.md 참조
AGENTS.md 파일과 동기화하여 엔지니어가 사용하는 다른 AI IDE와 호환성 유지
추가 팁: "AI Can't Read Your Docs", "AI-powered Software Engineering", "How Cursor (AI IDE) Works" 참조

Compact, Context, Clear: 컨텍스트 윈도우 관리

/context 명령으로 200k 토큰 윈도우 사용 현황 확인
- Sonnet-1M에서도 전체 컨텍스트 윈도우가 효과적으로 사용되는지 불확실
- 모노레포 새 세션 기본 ~20k 토큰(10%) 소비, 나머지 180k는 변경 작업용 (빠르게 소진)
세 가지 주요 워크플로우
- /compact (회피): 자동 압축은 불투명, 오류 발생, 최적화 부족으로 최대한 회피
- /clear + /catchup (단순 재시작): 기본 재부팅 방식, /clear로 상태 지운 후 커스텀 /catchup으로 git 브랜치의 모든 변경 파일 읽기
- "Document & Clear" (복잡한 재시작): 대규모 작업용, Claude가 계획과 진행상황을 .md에 덤프 → /clear → 새 세션에서 .md 읽고 계속

커스텀 슬래시 커맨드

슬래시 커맨드는 자주 사용하는 프롬프트의 단순 바로가기, 그 이상도 이하도 아님
최소 설정
- /catchup: git 브랜치의 모든 변경 파일 읽기 프롬프트
- /pr: 코드 정리, 스테이징, PR 준비 헬퍼
복잡한 커스텀 명령 리스트는 안티패턴
- Claude 같은 에이전트의 핵심: 거의 모든 자연어 입력으로 유용하고 병합 가능한 결과 생성
- 엔지니어(또는 비엔지니어)에게 작업 수행을 위한 "매직 커맨드" 필수 리스트 학습 강요 = 실패
- 더 직관적인 CLAUDE.md와 더 나은 도구를 갖춘 에이전트 구축이 목표

커스텀 Subagent

이론상 강력한 컨텍스트 관리 기능
- 복잡한 작업: X 토큰 입력 컨텍스트 + Y 토큰 작업 컨텍스트 + Z 토큰 답변
- N개 작업 = 메인 윈도우에서 (X + Y + Z) * N 토큰
- Subagent 솔루션: (X + Y) * N 작업을 특화 에이전트에 위임, 최종 Z 토큰 답변만 반환
실전에서 커스텀 Subagent가 만드는 두 가지 새 문제
- 컨텍스트 게이트키핑: PythonTests Subagent 생성 시 메인 에이전트에서 모든 테스트 컨텍스트 숨김 → 전체적 추론 불가능 → 자체 코드 검증 방법 알기 위해 Subagent 호출 강제
- 인간 워크플로우 강제: Claude를 경직된 인간 정의 워크플로우로 강제 → 위임 방법 지시 = 에이전트가 해결해야 할 문제 자체
개인적으로는 Task(...) 기능 선호
- Claude 빌트인 Task(...) 기능으로 범용 에이전트 복제본 생성
  - CLAUDE.md에 모든 핵심 컨텍스트 배치
  - 메인 에이전트가 자체 복사본에 작업 위임 시점과 방법을 결정
  - Subagent의 컨텍스트 절약 이점은 유지하면서 단점은 제거
  - 에이전트가 자체 오케스트레이션을 동적으로 관리
- "Building Multi-Agent Systems (Part 2)"에서 "Master-Clone" 아키텍처라 명명
  - 커스텀 Subagent가 유도하는 "Lead-Specialist" 모델보다 강력히 선호

Resume, Continue, History

기본 수준 활용
- claude --resume과 claude --continue 빈번히 사용
- 버그가 있는 터미널 재시작 또는 오래된 세션 빠른 재부팅
- 며칠 전 세션 claude --resume하여 특정 오류 극복 방법 요약 → CLAUDE.md 및 내부 도구 개선
심화 활용
- Claude Code는 모든 세션 히스토리를 ~/.claude/projects/에 저장
- 원시 히스토리 세션 데이터 활용 스크립트 보유
- 로그에 대한 메타 분석 실행: 공통 예외, 권한 요청, 오류 패턴 검색 → 에이전트 대상 컨텍스트 개선

Hooks

엔터프라이즈 레포에서 핵심적: 취미 프로젝트에서는 미사용
CLAUDE.md의 "should-do" 제안을 보완하는 결정론적 "must-do" 규칙
두 가지 유형
- 커밋 단계 차단 Hook (Block-at-Submit): 주요 전략
  - PreToolUse Hook으로 모든 Bash(git commit) 명령 래핑
  - /tmp/agent-pre-commit-pass 파일 확인 (테스트 스크립트가 모든 테스트 통과 시에만 생성)
  - 파일 없으면 커밋 차단 → 빌드 성공까지 Claude를 "테스트-수정" 루프로 강제
- 힌트 Hook: 단순한 비차단 Hook, 에이전트가 차선책 수행 시 "fire-and-forget" 피드백 제공
쓰기 단계 차단 Hook 의도적 미사용 (Edit 또는 Write 시)
- 계획 중간에 에이전트 차단 시 혼란 또는 "좌절" 유발
- 작업 완료 후 커밋 단계에서 최종 완료 결과 확인이 훨씬 효과적

플래닝 모드

AI IDE로 "대규모" 기능 변경 시 플래닝 필수
취미 프로젝트: 빌트인 플래닝 모드 독점 사용
- Claude 시작 전 정렬 방법
- 빌드 방법과 작업 중단 및 결과 표시 필요한 "검사 체크포인트" 정의
- 정기적 사용으로 Claude가 구현을 망치지 않고 좋은 계획 얻는 데 필요한 최소 컨텍스트에 대한 강한 직관 구축
엔터프라이즈 모노레포: Claude Code SDK 기반 커스텀 플래닝 도구 롤아웃 시작
- 네이티브 플랜 모드와 유사하지만 기존 기술 설계 포맷에 출력 정렬하도록 집중 프롬프트
- 내부 모범 사례 강제 (코드 구조부터 데이터 프라이버시, 보안까지) 기본 제공
- 엔지니어가 시니어 아키텍트처럼 새 기능 "vibe plan" 가능 (적어도 그것이 제안)

Skills

Simon Willison의 의견에 동의함: Skills는 (아마도) MCP보다 큰 딜
에이전트 자율성 멘탈 모델 3단계 진화
- Single Prompt: 에이전트에 모든 컨텍스트를 하나의 거대한 프롬프트로 제공 (취약, 확장 불가)
- Tool Calling: "클래식" 에이전트 모델, 도구 수작업 제작 및 에이전트를 위한 현실 추상화 (개선됐지만 새로운 추상화와 컨텍스트 병목 생성)
- Scripting: 에이전트에 원시 환경 접근 제공 (바이너리, 스크립트, 문서) → 에이전트가 즉석에서 코드 작성하여 상호작용
Agent Skills는 명백한 다음 기능: "Scripting" 레이어의 공식 제품화
CLI를 MCP보다 선호했다면 이미 암묵적으로 Skills의 이점 획득
- SKILL.md 파일은 이러한 CLI와 스크립트를 문서화하고 에이전트에 노출하는 더 조직화되고 공유 가능하며 발견 가능한 방법
Skills는 올바른 추상화: MCP가 나타내는 경직된 API 같은 모델보다 더 견고하고 유연한 "스크립팅" 기반 에이전트 모델을 공식화

MCP (Model Context Protocol)

Skills가 있다고 MCP가 죽은 것은 아님 ("Everything Wrong with MCP" 참조)
이전 문제점: 많은 이들이 REST API 미러링하는 수십 개 도구로 끔찍하고 컨텍스트 무거운 MCP 구축 (read_thing_a(), read_thing_b(), update_thing_c())
"Scripting" 모델(Skills로 공식화)이 더 나은 방식이지만 환경 접근을 위한 안전한 방법 필요 → MCP의 새롭고 더 집중된 역할
MCP의 새로운 역할: 데이터 게이트웨이
- 비대한 API 대신 몇 가지 강력한 고수준 도구를 제공하는 단순하고 안전한 게이트웨이
  - download_raw_data(filters…)
  - take_sensitive_gated_action(args…)
  - execute_code_in_environment_with_state(code…)
- MCP의 역할: 에이전트를 위한 현실 추상화가 아닌 인증, 네트워킹, 보안 경계 관리 후 방해하지 않기
  - 에이전트용 진입점 제공 → 에이전트는 스크립팅과 markdown 컨텍스트로 실제 작업 수행
- 현재 사용 중인 유일한 MCP: Playwright (복잡하고 상태 저장 환경이라 타당)
  - 모든 무상태 도구 (Jira, AWS, GitHub)는 단순 CLI로 마이그레이션

Claude Code SDK

Claude Code는 대화형 CLI일 뿐 아니라 코딩 및 비코딩 작업 모두를 위한 완전히 새로운 에이전트 구축용 강력한 SDK
대부분의 새 취미 프로젝트에서 LangChain/CrewAI 같은 도구보다 기본 에이전트 프레임워크로 사용 시작
세 가지 주요 사용 방식
- 대규모 병렬 스크립팅: 대규모 리팩토링, 버그 수정, 마이그레이션 시 대화형 채팅 미사용
  - claude -p "in /pathA change all refs from foo to bar" 병렬 호출하는 단순 bash 스크립트 작성
  - 메인 에이전트가 수십 개 Subagent 작업 관리하도록 하는 것보다 훨씬 확장 가능하고 제어 가능
- 내부 채팅 도구 구축: 비기술 사용자를 위해 복잡한 프로세스를 단순 채팅 인터페이스로 래핑하는 데 완벽
  - 예: 오류 시 Claude Code SDK로 폴백하여 사용자 문제 해결하는 인스톨러
  - 예: 디자인 팀이 사내 UI 프레임워크로 목업 프론트엔드를 vibe-code할 수 있는 사내 "v0-at-home" 도구 (아이디어 고충실도 보장, 프론트엔드 프로덕션 코드에서 더 직접 사용 가능)
- 신속한 에이전트 프로토타이핑: 가장 일반적 사용 사례, 코딩 전용 아님
  - 에이전트 작업 아이디어 (예: 커스텀 CLI 또는 MCP 사용 "위협 조사 에이전트")가 있을 때
  - 전체 배포 스캐폴딩 커밋 전 Claude Code SDK로 프로토타입 빠르게 구축 및 테스트

Claude Code GitHub Action (GHA)

가장 좋아하고 과소평가된 기능 중 하나: 단순 개념 (GHA에서 Claude Code 실행)이지만 이 단순함이 강력함의 원천
Cursor의 백그라운드 에이전트 또는 Codex 관리형 웹 UI와 유사하지만 훨씬 더 커스터마이즈 가능
- 전체 컨테이너와 환경 제어 → 데이터 접근성 향상
- 다른 제품보다 훨씬 강력한 샌드박싱 및 감사 제어
- Hook, MCP 같은 모든 고급 기능 지원
활용 사례
- 커스텀 "어디서나 PR" 도구 구축
  - Slack, Jira, 심지어 CloudWatch 알림에서 PR 트리거 가능
  - GHA가 버그 수정 또는 기능 추가 후 완전히 테스트된 PR 반환
- 데이터 기반 플라이휠
  - GHA 로그 = 전체 에이전트 로그
  - 회사 수준에서 정기적으로 로그 검토: 공통 실수, bash 오류, 정렬되지 않은 엔지니어링 관행 발견
  - 플라이휠: 버그 → CLAUDE.md/CLI 개선 → 더 나은 에이전트
  - $ query-claude-gha-logs --since 5d | claude -p "see what the other claudes were getting stuck on and fix it, then put up a PR"

settings.json

취미 및 업무 작업 모두에 필수적인 특정 구성
HTTPS_PROXY/HTTP_PROXY: 디버깅용
- 원시 트래픽 검사로 Claude가 전송하는 정확한 프롬프트 확인
- 백그라운드 에이전트용으로는 세밀한 네트워크 샌드박싱 강력한 도구
MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS: 값 증가
- 길고 복잡한 명령 실행 선호, 기본 타임아웃이 종종 너무 보수적
- bash 백그라운드 작업 이후 여전히 필요한지 불확실하지만 만약을 위해 유지
ANTHROPIC_API_KEY: 업무에서 엔터프라이즈 API 키 사용 (apiKeyHelper 통해)
- "좌석당" 라이선스에서 "사용량 기반" 가격으로 전환 (작업 방식에 훨씬 나은 모델)
- 개발자 사용량의 막대한 차이 고려 (엔지니어 간 1:100배 차이 확인)
- 엔지니어가 단일 엔터프라이즈 계정으로 비Claude-Code LLM 스크립트 실험 가능
"permissions": Claude가 자동 실행 허용한 명령 리스트 주기적 자체 감사