목록으로

Claude Code 실전 가이드: CLI부터 Agent Teams까지

작성자 seokchol hong

들어가며

Claude Code는 Anthropic이 만든 AI 기반 코딩 어시스턴트로, 터미널에서 직접 코드를 작성, 디버깅, 리팩토링하고 Git까지 관리할 수 있는 도구다. Anthropic 내부에서도 Claude Code를 사용하면서 엔지니어 1인당 코드 생산량이 지난 1년간 200% 증가했다고 밝힐 만큼, 실제 생산성에 미치는 영향이 크다.

2025년 첫 출시 이후 빠르게 진화하고 있으며, Skills 시스템, Memory, Hooks, Auto Mode, Agent Teams, 1M Context 등 기능이 속속 추가되고 있다. 이 글에서는 Claude Code의 설치부터 고급 활용까지 실전에서 필요한 모든 것을 다룬다.

1. 설치 및 기본 설정

Mac/Linux 설치

npm install -g @anthropic-ai/claude-code
cd your-project
claude

Windows 설치 (WSL 미사용)

Windows에서는 WSL 없이도 직접 설치가 가능하다. Node.js 18+ 설치 후 동일하게 npm install -g @anthropic-ai/claude-code로 설치한다.

기본 사용 흐름

  1. 프로젝트 디렉토리에서 claude 명령어로 시작
  2. 자연어로 작업 요청 (예: "이 함수에 에러 핸들링을 추가해줘")
  3. Claude가 코드를 분석하고 수정안을 제안
  4. 사용자가 승인하면 파일에 직접 적용

2. CLI 핵심 명령어

기본 명령어

  • claude — 대화형 모드 시작
  • claude "질문" — 원샷 질문
  • claude -p "프롬프트" — 파이프라인 모드 (stdin/stdout 활용)
  • claude commit — AI가 커밋 메시지를 자동 생성
  • claude review — PR 리뷰

고급 CLI 명령어

  • claude --model opus — 모델 지정 (sonnet, opus, haiku)
  • claude --dangerously-skip-permissions — 모든 권한 확인 스킵 (주의 필요)
  • claude mcp add <name> -- <command> — MCP 서버 추가
  • /memory — 메모리 관리 메뉴
  • /compact — 컨텍스트 압축

3. Auto Mode: 승인 팝업 없이 자동 실행

Claude Code를 쓰면서 가장 짜증나는 순간 — ls 하나에도 "허용하시겠습니까?", grep 한 번에도 "허용하시겠습니까?". 그래서 --dangerously-skip-permissions를 켜고 사용하는 사람이 많은데, 이 경우 Claude가 뭘 하든 무조건 통과라 불안하다.

2026년 3월에 추가된 Auto Mode가 이 문제를 해결한다. --dangerously-skip-permissions의 "전부 통과" 방식이 아니라, 안전한 명령은 자동 승인하고 위험한 명령만 사용자에게 확인을 요청하는 중간 지점이다.

설정에서 "자동으로 허용할 도구 패턴"을 지정할 수 있어, 읽기 작업(파일 읽기, grep, git status 등)은 자동 승인하고 쓰기 작업(파일 수정, git push 등)은 수동 승인으로 설정하는 것이 권장된다.

4. Skills 시스템

2026년 1월(v2.1.0)에 도입된 Skills 시스템은 Claude Code의 행동 패턴을 커스터마이징하는 기능이다. 기존 Custom Commands를 대체하며, 프로젝트나 개인 수준에서 AI의 동작 방식을 정의할 수 있다.

Bundled Skills (내장 스킬)

  • /simplify — 변경된 코드의 재사용성, 품질, 효율성을 검토하고 개선
  • /batch — 여러 작업을 일괄 처리
  • /debug — 에러 분석 및 디버깅 지원

Custom Skills

프로젝트의 .claude/skills/ 디렉토리에 마크다운 파일로 작성한다. 예를 들어 "이 프로젝트에서는 항상 TypeScript를 사용하고, 함수는 화살표 함수로 작성하며, 테스트는 vitest를 사용한다"는 스킬을 정의할 수 있다.

Skills vs Plugins

Skills는 텍스트 기반 지시사항(프롬프트 확장)이고, Plugins는 실행 가능한 코드다. Skills는 AI의 "사고 방식"을 바꾸고, Plugins는 AI의 "능력"을 확장한다. 대부분의 경우 Skills만으로도 충분하며, 외부 시스템 연동이 필요할 때만 Plugins(MCP 서버)를 사용한다.

Agent Skills의 확산

Anthropic이 만든 Skills 시스템이 OpenAI Codex와 Google Gemini CLI에서도 채택되면서, CLAUDE.md 같은 파일 기반 스킬 정의가 업계 사실상의 표준이 되어가고 있다. 한 번 정의한 스킬이 여러 AI 코딩 도구에서 통용되는 시대가 열리고 있다.

5. Memory 시스템

Claude Code의 Memory는 세션 간에 컨텍스트를 유지하는 기능이다. 프로젝트의 컨벤션, 사용자의 선호도, 작업 히스토리 등을 기억하게 해서 매번 같은 설명을 반복하지 않아도 된다.

Memory 구성 요소

  • CLAUDE.md: 프로젝트 루트에 위치하는 메인 메모리 파일. 프로젝트 컨벤션, 빌드 명령어, 아키텍처 설명 등을 기록
  • 사용자 메모리: ~/.claude/ 디렉토리에 저장되는 개인 선호도
  • 프로젝트 메모리: .claude/ 디렉토리에 저장되는 프로젝트별 메모리

Auto Memory vs Auto Dream

"Claude Code Memory 2.0"이라는 표현이 커뮤니티에서 돌고 있다. "Auto Dream"이라는 기능이 나와서 AI가 잠자면서 기억을 정리한다는 것인데, 결론부터 말하면 "Memory 2.0"은 공식 용어가 아니고, Auto Dream은 공식 문서에는 없다. 하지만 코드 안에는 실제로 존재한다. /memory 메뉴에서 확인할 수 있으며, 세션이 끝날 때 AI가 자동으로 중요 정보를 메모리에 기록하는 기능이다.

6. 1M Context 윈도우

2026년 3월 13일부로 정식 지원이 시작된 1M(100만) 토큰 컨텍스트 윈도우. Opus 4.6부터 Max, Team, Enterprise 플랜에서 기본 활성화되었다. 추가 요금도, Rate Limit 불이익도 없다.

실무적 의미

  • 대규모 코드베이스 전체를 한 번에 분석 가능
  • 수십 개 파일을 동시에 참조하며 리팩토링
  • 긴 문서나 로그를 통째로 넣어서 분석

주의점

컨텍스트가 크다고 무조건 좋은 것은 아니다. 정보가 너무 많으면 "Lost in the Middle" 현상이 발생할 수 있고, 토큰 비용도 증가한다. 실무에서는 필요한 파일만 선별적으로 컨텍스트에 넣는 것이 더 효과적인 경우가 많다.

7. Claude Code Review

Anthropic이 내부에서 사용하던 AI 코드 리뷰 시스템을 공개한 것이다. Team과 Enterprise 플랜에서 사용 가능하며, GitHub PR에 자동으로 리뷰를 달아준다.

왜 필요한가

Claude Code 덕분에 코드 생산량은 200% 증가했지만, 리뷰어의 인지 용량은 그대로다. PR 리뷰 큐가 쌓이고, "이 정도면 괜찮겠지" 하는 훑어보기 리뷰가 늘어나면서 한 줄짜리 인증 버그가 숨어 들어오는 상황이 발생한다.

AI 시대의 코드 리뷰 원칙

Simon Willison이 제시하는 원칙: AI가 코드를 짜는 시대에 개발자의 책임은 "코드를 작성하는 것"에서 "코드를 검증하는 것"으로 이동한다. AI가 생성한 코드라도 반드시 사람이 검토해야 하며, 이 검토 과정 자체를 AI가 보조할 수 있다.

8. cmux: AI 에이전트를 위한 터미널

Claude Code, OpenAI Codex, Gemini CLI 등 여러 AI 에이전트를 터미널에서 병렬로 돌리다 보면 tmux만으로는 한계를 느끼게 된다. cmux는 AI 에이전트를 위해 설계된 터미널 멀티플렉서다.

cmux vs tmux

  • tmux: 사람을 위한 터미널 관리. 세션, 윈도우, 패인 관리
  • cmux: AI 에이전트를 위한 터미널 관리. 에이전트 간 상태 공유, 브라우저 기반 UI, 에이전트별 격리 환경

여러 에이전트를 동시에 실행하고, 각 에이전트의 진행 상황을 한 화면에서 모니터링하며, 에이전트 간 컨텍스트를 공유할 수 있다.

9. SuperClaude

SuperClaude는 Claude Code의 기본 기능을 확장하는 커뮤니티 프로젝트다. CLAUDE.md에 특정 지시사항을 추가하여 Claude Code의 코딩 품질, 아키텍처 결정, 코드 스타일 등을 세밀하게 제어할 수 있다.

React 프로젝트에서 화면 버그를 수정하는 등의 실전 사례에서 기본 Claude Code보다 더 구조적이고 일관된 결과를 보여준다는 평가가 있다. 다만 프롬프트가 길어지면서 토큰 소비가 증가하는 트레이드오프가 있다.

10. 실전 팁

  • CLAUDE.md를 잘 관리하라: 프로젝트의 빌드 명령어, 테스트 방법, 코드 컨벤션, 아키텍처 설명을 CLAUDE.md에 정리해두면 매 세션마다 일관된 결과를 얻을 수 있다.
  • 컨텍스트를 관리하라: 대화가 길어지면 /compact로 컨텍스트를 압축하라. 불필요한 정보가 쌓이면 성능이 떨어진다.
  • MCP와 결합하라: GitHub MCP, Playwright MCP, Supabase MCP 등을 붙이면 Claude Code의 활용 범위가 크게 확장된다.
  • Auto Mode를 활용하라: 읽기 작업은 자동 승인, 쓰기 작업은 수동 승인으로 설정하면 승인 피로도를 줄이면서 안전성을 유지할 수 있다.
  • 커밋은 AI에게 맡겨라: claude commit으로 AI가 diff를 분석해 커밋 메시지를 자동 생성한다. 일관되고 상세한 커밋 히스토리를 유지할 수 있다.

마무리

Claude Code는 단순한 코드 자동완성 도구를 넘어, 개발 워크플로우 전체를 아우르는 AI 코딩 파트너로 진화하고 있다. Skills로 행동을 커스터마이징하고, Memory로 맥락을 유지하며, MCP로 외부 도구와 연결하고, Agent Teams로 여러 에이전트를 동시에 운영하는 — 이것이 2026년의 개발 환경이다.

가장 중요한 것은 AI가 코드를 대신 짜주는 것이 아니라, 개발자가 AI와 함께 더 빠르고 정확하게 목표를 달성하는 것이다. Claude Code를 잘 쓴다는 것은 도구를 잘 아는 것 이상으로, 어떤 작업을 AI에게 맡기고 어떤 작업을 직접 할지를 판단하는 능력이다.

목록으로