Claude Code 2.1 업데이트 정리 (클로드 코드 2.1 업데이트 리뷰)

안녕하세요. 갓대희 입니다.

오늘은 Claude Code 2.1 업데이트에 대해 정리해보려고 한다.

 

 

Claude Code 2.1: 비동기 서브에이전트와 스킬 핫 리로드를 도입한 대규모 업데이트
Anthropic이 Claude Code 2.1.0을 공식 릴리스했다.
이번 업데이트에는 비동기 서브에이전트, 스킬 핫 리로드, 컨텍스트 포크 등 에이전틱 코딩 워크플로우를 크게 개선하는 기능들이 추가되었다. 이후 2.1.x 버전들(2.1.3, 2.1.4 등)에서 지속적인 안정화 작업이 이루어지고 있다.

Anthropic의 공식 CLI 기반 AI 코딩 어시스턴트인 Claude Code가 2.1 버전으로 대폭 업그레이드되었다.
이번 릴리스의 핵심 테마는 "병렬성과 효율성"이다. 백그라운드에서 서브에이전트를 실행하고, 스킬을 재시작 없이 업데이트하며, 현재 컨텍스트를 분기하여 독립적인 탐색이 가능해졌다. 특히 대규모 코드베이스에서 멀티태스킹이 필요한 개발자들에게 유용한 기능들이 대거 추가되었다.

출처
이 글의 모든 정보는 Anthropic 공식 문서와 GitHub CHANGELOG를 기반으로 한다.
GitHub - Claude Code CHANGELOG
Anthropic Docs - Claude Code

 

Claude Code란?

Claude Code는 Anthropic이 개발한 에이전틱 CLI 코딩 도구다. 터미널에서 직접 Claude와 대화하며 코드를 작성, 수정, 분석하고 Git 작업까지 수행할 수 있다. 기존의 IDE 플러그인이나 웹 기반 코딩 어시스턴트와 달리, 터미널 네이티브 환경에서 파일 시스템에 직접 접근하여 작업한다.

Claude Code는 단순한 코드 자동완성을 넘어, 서브에이전트 위임, 병렬 작업 실행, MCP(Model Context Protocol) 서버 통합 등 복잡한 개발 워크플로우를 자동화할 수 있는 강력한 기능을 제공한다.

Claude Code의 핵심 특징

• 터미널 네이티브: CLI 환경에서 직접 실행, 파일 시스템 접근 가능
• 에이전틱 실행: 사용자 개입 없이 복잡한 작업을 자율적으로 수행
• MCP 통합: 외부 서비스와 도구를 Model Context Protocol로 연결
• 200K 컨텍스트: 대규모 코드베이스 분석 가능
• 권한 제어: 도구 실행 전 사용자 승인 요청 옵션

 

설치 방법

Claude Code는 여러 방법으로 설치할 수 있다.

# macOS/Linux - 설치 스크립트
curl -fsSL https://claude.ai/install.sh | bash

# macOS - Homebrew
brew install --cask claude-code

# npm (Node.js 18+ 필요)
npm install -g @anthropic-ai/claude-code

# Windows - PowerShell
irm https://claude.ai/install.ps1 | iex

설치 후 claude 명령어로 실행할 수 있다.

 

기본 설치 및 사용방법은 이미 다른 글에서 자세히 작성했으니 설치 및 기본 설정방법은 아주 간단히만 작성하고 넘어간다. ( 해당글에서 1.0 > 2.0 업그레이드에 대한 내용도 다루었었다.)

[AI/Claude] - Claude Code 2.0(클로드 코드 2.0) 설치 - (Claude Code 1.0에서 2.0 업그레이드 하기)

 

프로젝트 설정

프로젝트별로 Claude Code의 동작을 커스터마이징할 수 있다.

.claude 디렉터리 구조

프로젝트 루트에 .claude 폴더를 생성하면 프로젝트별 설정을 관리할 수 있다.

my-project/
├── .claude/
│   ├── settings.json    # 프로젝트별 설정
│   ├── skills/          # 커스텀 스킬 (명령어)
│   │   └── deploy.md
│   └── rules/           # 코딩 규칙
│       └── style.md
├── CLAUDE.md            # 프로젝트 컨텍스트 (권장)
└── src/

 

CLAUDE.md 파일

프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude가 프로젝트를 더 잘 이해한다. 기술 스택, 코딩 컨벤션, 주요 규칙 등을 기록하자.

# CLAUDE.md 예시

# 프로젝트: My App

## 기술 스택
- Python 3.11
- FastAPI
- PostgreSQL
- Redis

## 코딩 컨벤션
- PEP 8 스타일 가이드 준수
- 타입 힌트 필수
- 함수/클래스에 docstring 작성

## 주요 규칙
- 테스트 없이 PR 금지
- 환경 변수는 .env 파일 사용
- 커밋 메시지는 Conventional Commits 형식

 

기본 슬래시 명령어

자주 사용하는 내장 명령어들이다.

명령어	설명
/help	도움말 및 사용 가능한 명령어 목록
/clear	대화 기록 초기화
/compact	컨텍스트 압축 (토큰 절약)
/config	설정 변경
/cost	현재 세션의 API 비용 확인
/bug	버그 리포트 제출
/plan	계획 모드 진입 (2.1 신규)
/tasks	백그라운드 작업 목록 확인 (2.1 신규)
/agents	서브에이전트 관리 인터페이스 (2.1 신규)

 

2.0에서 추가된 주요 기능

2.1 이전 버전에서 추가된 핵심 기능들이다.

2.1 업데이트 내역은 아니지만 해당 기능들은 중요하다보니 잠깐 기술하고 넘어간다. 

 

Plugin 시스템 (2.0.12)

커스텀 명령어, 에이전트, 훅, MCP 서버를 플러그인으로 확장할 수 있다.

# 플러그인 관리 명령어
/plugin                                    # 플러그인 매니저 열기 (Discover/Installed/Create 탭)
/plugin marketplace add [marketplace]      # 마켓플레이스 추가 (예: anthropics/claude-code)
/plugin install [플러그인명]@[마켓플레이스]  # 플러그인 설치

# CLI에서 직접 설치
claude plugin install [플러그인명]

자세한 내용: 공식 플러그인 문서

Administration[8] : Claude Code 설정 - 플러그인 마켓플레이스(Create and distribute a plugin marketplace)

 

LSP 지원 (2.0.74)

Language Server Protocol을 지원하여 IDE급 코드 인텔리전스를 제공한다:

• Go to Definition: 정의로 이동
• Find References: 참조 찾기
• Hover Documentation: 호버 시 문서 표시

 

Chrome 통합 (2.0.72, Beta)

Chrome 확장 프로그램과 연동하여 터미널에서 브라우저를 제어할 수 있다:

• 페이지 열기, 클릭, 폼 채우기
• 스크린샷 촬영
• E2E 테스트 자동화

Chrome 확장: https://claude.com/chrome (Beta)

 

2.1 버전 주요 변경사항

Claude Code 2.1.0은 대규모 기능 업데이트다. 핵심 변경사항을 살펴보자.

사실 2.0에서 실험적 기능으로 max plan 사용자들에게만 제공되는 기능과 많이 겹치는 부분이 있다.

 

1. 비동기 서브에이전트 (Async Sub-agents)

가장 주목할 만한 기능이다. 이제 서브에이전트를 백그라운드에서 실행하고 메인 작업을 계속할 수 있다. 이전에는 서브에이전트가 완료될 때까지 기다려야 했다.

주요 특징

• Ctrl+B 단축키: 현재 작업을 백그라운드로 전환
• 완료 알림: 백그라운드 작업 완료 시 자동 알림
• 병렬 실행: 여러 에이전트를 동시에 실행 가능
• 결과 확인: 작업 완료 후 결과를 메인 컨텍스트로 가져올 수 있음

예를 들어, 테스트 실행을 백그라운드에 맡기고 다른 코드 작업을 계속할 수 있다. 테스트가 완료되면 알림을 받고 결과를 확인하면 된다.

# 사용 예시
> 전체 테스트 실행해줘
[테스트 시작됨...]
[Ctrl+B 누르기] → 백그라운드로 전환

> 이제 다른 작업 가능
[백그라운드 작업 완료 알림 수신]
> 테스트 결과 보여줘

# /tasks로 백그라운드 작업 관리 (2.1 신규)
> /tasks
┌─────────────┬──────────────────┬──────────┐
│ Task ID     │ Description      │ Status   │
├─────────────┼──────────────────┼──────────┤
│ task_abc123 │ 전체 테스트 실행  │ running  │
│ task_def456 │ 빌드 프로세스     │ completed│
└─────────────┴──────────────────┴──────────┘

팁: 백그라운드 작업 비활성화
백그라운드 작업 기능을 비활성화하려면 환경 변수를 설정한다:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

ex) 

 

2. 스킬 핫 리로드 (Skills Hot Reload)

커스텀 스킬(명령어)을 수정한 후 Claude Code를 재시작하지 않아도 변경사항이 즉시 반영된다. 스킬 개발 시 반복 작업이 크게 줄어든다.

# .claude/skills/my-skill.md 파일 수정 후
# 재시작 없이 바로 /my-skill 명령어 사용 가능

 

2-1. 커스텀 서브에이전트와 Skills 연동 (2.1 신규)

2.1에서 추가된 핵심 기능이다. 커스텀 서브에이전트를 정의하고, 해당 서브에이전트가 특정 Skills를 사용하도록 설정할 수 있다.

중요
서브에이전트는 메인 대화의 Skills를 자동으로 상속하지 않는다. 서브에이전트가 특정 Skills를 사용하려면 반드시 skills: 필드에 명시해야 한다.

커스텀 서브에이전트 정의

.claude/agents/ 디렉토리에 YAML 형식으로 서브에이전트를 정의한다:

# .claude/agents/db-admin.yml
---
name: db-admin
description: 데이터베이스 관리 및 마이그레이션 작업을 수행하는 전문 에이전트
tools:
  - Bash
  - Read
  - Write
model: sonnet           # 선택적: haiku, sonnet, opus, inherit (부모 모델 상속)
skills:
  - database-migration  # 이 서브에이전트가 사용할 스킬들
  - postgres-ops
  - sql-review
permissionMode: auto    # 도구 승인 모드: auto (자동), ask (매번 물어봄)
allowed-tools:          # 허용할 도구 명시적 지정 (선택적)
  - "Bash(psql *)"
  - "Bash(pg_dump *)"
  - "Read(migrations/**/*)"
---

## 역할
데이터베이스 스키마 변경, 마이그레이션 스크립트 작성, 쿼리 최적화를 담당합니다.

서브에이전트 Frontmatter 필드 (2.1 신규)

필드	설명
model	사용할 모델. inherit로 부모 세션 모델 상속
skills	자동 로드할 스킬 목록 (2.1 신규)
permissionMode	도구 승인 동작: auto / ask (2.1 신규)
allowed-tools	허용할 도구 패턴 (Wildcard 지원)
tools	생략 시 부모 세션의 도구 상속 (MCP 포함)

디렉토리 구조 예시

my-project/
├── .claude/
│   ├── agents/              # 커스텀 서브에이전트 정의
│   │   ├── db-admin.yml
│   │   ├── test-runner.yml
│   │   └── code-reviewer.yml
│   ├── skills/              # 스킬 정의
│   │   ├── database-migration/
│   │   │   └── SKILL.md
│   │   ├── postgres-ops/
│   │   │   └── SKILL.md
│   │   └── deploy/
│   │       └── SKILL.md
│   └── settings.json
└── ...

사용 예시

# 정의된 서브에이전트 목록 확인
> /agents

# 특정 서브에이전트로 작업 위임
> @db-admin users 테이블에 email 컬럼 추가해줘

[db-admin 서브에이전트가 database-migration, postgres-ops 스킬을 사용하여 작업 수행]

 

3. 컨텍스트 포크 (Context Fork)

스킬의 프론트매터에 context: fork를 추가하면 현재 컨텍스트를 분기(fork)하여 독립적인 탐색이 가능하다. 메인 대화에 영향을 주지 않고 실험적인 작업을 수행할 수 있다.

# .claude/skills/explore.md
---
context: fork
---

# Explore Skill
현재 컨텍스트를 분기하여 코드베이스를 탐색합니다.

 

4. 에이전트 스코프 훅 (Agent-Scoped Hooks)

2.1에서는 훅 시스템이 확장되어 서브에이전트 수준에서 훅을 설정할 수 있다. 다음 훅 타입들이 지원된다:

훅 타입	설명
PreToolUse	도구 실행 전 호출
PostToolUse	도구 실행 후 호출
Stop	에이전트 종료 시 호출
SubagentStart	서브에이전트 시작 시 호출 (2.1 신규)
SubagentStop	서브에이전트 종료 시 호출 - agent_id, agent_transcript_path 제공 (2.1 신규)

훅은 .claude/settings.json에서 설정한다:

// .claude/settings.json 예시
{
  "hooks": {
    "PreToolUse": {
      "Bash": "echo '명령어 실행 전 로깅: $TOOL_INPUT'"
    },
    "PostToolUse": {
      "Write": "./scripts/auto-format.sh $FILE_PATH"
    },
    "SubagentStart": "./scripts/log-agent-start.sh $AGENT_NAME",
    "SubagentStop": "./scripts/log-agent-stop.sh $AGENT_ID $AGENT_TRANSCRIPT_PATH"
  }
}

 

5. 세션 텔레포트 & 원격 환경 (Teleport & Remote-env)

claude.ai 웹/모바일에서 시작한 세션을 로컬 CLI로 이어받는 기능이다. 세션 전환은 웹 → CLI 단방향으로만 가능하다.

⚠️ 방향 주의: 세션 핸드오프는 웹 → CLI 단방향만 지원

claude.ai에서 시작한 대화를 CLI로 가져올 수 있지만, CLI 세션을 웹으로 보내는 것은 & 프리픽스로 새 세션 생성 방식만 가능

웹 → CLI (텔레포트)

• /teleport 또는 /tp - 웹 세션 목록에서 가져올 세션 선택 (인터랙티브 피커)
• claude --teleport - 커맨드라인에서 직접 세션 선택
• claude --teleport <session-id> - 특정 세션 ID로 직접 가져오기

CLI → 웹 (새 세션 생성)

• & 프리픽스 - 현재 컨텍스트로 새 웹 세션 생성 (예: & 이 작업 계속해줘)

원격 환경 설정

• /remote-env - 텔레포트 세션을 위한 원격 환경 설정 (SSH 연결 등)

# 웹 세션을 CLI로 가져오기
$ claude --teleport                    # 인터랙티브 피커로 세션 선택
$ claude --teleport session_abc123     # 특정 세션 직접 가져오기

# CLI 내에서 /teleport 명령어 사용
> /teleport                            # 또는 /tp
# → 웹 세션 목록이 표시되고 선택 가능

# 현재 컨텍스트로 새 웹 세션 시작
> & 이 코드를 리팩토링해줘
# → claude.ai에서 새 세션이 열림

더 자세한 내용은 다음 글을 참고:

Claude Code Web - 설치 없이 브라우저만으로 코드 자동화, 병렬 작업 해보기

 - 해당글의 "웹 → CLI 세션 전환" 내용을 참고.

 

6. 응답 언어 설정

Claude Code의 응답 언어를 설정할 수 있는 옵션이 추가되었다. 한국어 사용자라면 한국어로 응답받을 수 있다.

설정 방법

방법 1: /config 실행 → Language 항목 선택 → 원하는 언어 선택

방법 2: ~/.claude/settings.json에 직접 설정

// ~/.claude/settings.json
{
  "language": "korean"
}

※ 공식 문서에는 "japanese" 예시만 있으며, 정확한 언어 코드는 /config UI에서 확인 가능

ex) /config

 

7. 터미널 지원 개선

Shift+Enter 입력이 더 많은 터미널에서 지원된다: (줄바꿈 기능)

• iTerm2
• Kitty
• Ghostty
• WezTerm

또한 Vim 모션 확장이 추가되어 터미널 내 텍스트 편집이 더욱 편리해졌다.

 

8. 새 슬래시 명령어

명령어	설명
/plan	계획 모드 진입, 구현 전 설계 단계
/remote-env	텔레포트 세션을 위한 원격 환경 설정
/tasks	백그라운드 작업 목록 및 상태 확인 (2.1 신규)
/agents	서브에이전트 관리 인터페이스 - 생성, 편집, 조회 (2.1 신규)

# /plan 사용 예시
> /plan 사용자 인증 시스템 구현

[계획 모드 진입]
Claude: 사용자 인증 시스템 구현 계획을 작성합니다.

## 구현 계획
1. User 모델 생성 (email, password_hash, created_at)
2. JWT 토큰 기반 인증 미들웨어
3. /auth/register, /auth/login 엔드포인트
4. 비밀번호 해싱 (bcrypt)

이 계획으로 진행할까요? (y/n)

 

9. Code Simplifier 플러그인

Anthropic이 오픈소스로 공개한 코드 정리 플러그인이다. Claude Code 팀이 내부적으로 사용하는 것과 동일한 에이전트로, 긴 세션 후 복잡해진 코드를 정리하거나 리팩토링할 때 유용하다.

중요: 서브에이전트로 작동
Code Simplifier는 슬래시 명령어(/code-simplifier)가 아닌 서브에이전트로 작동한다. 설치 후 Claude Code를 재시작해야 사용 가능하며, Opus 모델에서 실행된다.

설치 방법

# 방법 1: 공식 마켓플레이스에서 직접 설치
/plugin install code-simplifier@claude-plugins-official

# 방법 2: 마켓플레이스 업데이트 후 설치
/plugin marketplace update claude-plugins-official
/plugin install code-simplifier

# 방법 3: Discover UI 사용
/plugin > Discover > code-simplifier 검색 > 설치

# ⚠️ 설치 후 Claude Code 재시작 필요 (라이브 로드 미지원)

ex) /plugin marketplace update claude-plugins-official

 - 설치할 범위 지정 (프로젝트 단위, 해당 유저 전체 단위 등)

 

사용 방법

# 서브에이전트로 호출 (예시)
> code-simplifier 에이전트로 최근 수정한 코드 정리해줘

# 또는 긴 코딩 세션 후 전체 정리 요청
> 방금 작성한 코드들 code-simplifier로 정리해줘

[Opus 모델로 코드 분석 중...]
[최근 수정된 코드 식별]
[중복 제거, 네이밍 개선, 일관성 향상 적용]
[⚠️ 기능은 절대 변경하지 않음 - 동작 보존]

ex) code-simplifier 에이전트로 '/Users/lf/work/workspace/ai/slackBot/deploy/deploy.sh'  코드 정리해줘

 - 시간이 소요되는것 같아 ctrl + b 로 백그라운드 작업으로 전환 ( 하기에 보면 background task 확인 가능 )

  - 결과 예시

⏺ ✅ deploy.sh 코드 정리 완료

  code-simplifier 에이전트가 slackBot/deploy/deploy.sh 파일을 성공적으로 정리했습니다.

  ---
  📋 주요 변경 사항
  ┌──────────┬───────────────┬─────────────────────────────┐
  │   영역   │    변경 전    │           변경 후           │
  ├──────────┼───────────────┼─────────────────────────────┤
  │ 설정값   │ 하드코딩      │ readonly 상수로 분리        │
  ├──────────┼───────────────┼─────────────────────────────┤
  │ 로깅     │ echo "..."    │ log_info(), log_done() 함수 │
  ├──────────┼───────────────┼─────────────────────────────┤
  │ 함수명   │ do_build() 등 │ build() 등 (간결화)         │
  ├──────────┼───────────────┼─────────────────────────────┤
  │ 사용법   │ 다중 echo     │ heredoc 기반 show_usage()   │
  ├──────────┼───────────────┼─────────────────────────────┤
  │ 헬스체크 │ 인라인 코드   │ check_health() 함수 분리    │
  └──────────┴───────────────┴─────────────────────────────┘
  ---
  🔍 개선된 코드 구조

  # Configuration (상수 정의)
  readonly HEALTH_URL="http://localhost:8000/health"
  readonly LOG_TAIL_LINES=100

  # Logging (출력 함수)
  log_info() / log_done()

  # Docker operations (핵심 기능)
  build() / start() / stop() / restart() / check_health()

  # Main (명령어 처리)
  case "$1" in ...

  ---
  ★ Insight ─────────────────────────────────────
  1. readonly 키워드: Bash에서 상수를 선언할 때 사용합니다. 스크립트 실행 중 값 변경을 방지하여 설정값의 무결성을 보장합니다.
  2. Heredoc (cat << EOF): 여러 줄의 텍스트를 깔끔하게 출력할 때 유용합니다. 다중 echo보다 유지보수가 쉽고, 들여쓰기와 포맷이 보존됩니다.
  3. 함수 분리 원칙: check_health()처럼 특정 로직을 함수로 분리하면 테스트가 용이하고, 나중에 로직 변경 시 한 곳만 수정하면 됩니다.
  ─────────────────────────────────────────────────

 

ex) 캡쳐 예시

Code Simplifier 주요 원칙

• 기능 보존: 코드의 동작은 절대 변경하지 않음. 모든 원본 기능, 출력, 동작 유지
• 최근 코드 집중: 기본적으로 최근 수정된 코드만 분석 (별도 지시가 없으면 광범위한 검토 회피)
• 프로젝트 표준 적용: CLAUDE.md의 코딩 규칙 준수, ES modules, 일관된 네이밍 등
• 명확성 우선: 중첩 삼항 연산자 회피, 불필요한 복잡성 제거, 가독성 향상
• 과도한 단순화 방지: 유지보수성을 해치는 "영리한" 솔루션 회피

참고: GitHub - code-simplifier 플러그인

 

10. Ask User Question Tool

Claude가 불확실한 상황에서 추측하지 않고 먼저 질문하는 기능이다. 모호한 요청에 대해 사용자에게 명확한 정보를 요청한다.

# 예시: 모호한 요청 시
> 로그인 기능 추가해줘

[Claude의 질문]
로그인 기능 구현을 위해 몇 가지 확인이 필요합니다:
1. 인증 방식: JWT vs 세션 기반?
2. OAuth 연동이 필요한가요? (Google, GitHub 등)
3. 비밀번호 재설정 기능도 포함할까요?

 

11. Denied Tool Use 지속

도구 실행 권한을 거부해도 작업이 중단되지 않고 계속 진행된다. 이전에는 권한 거부 시 전체 작업이 멈췄지만, 이제는 해당 작업만 건너뛰고 다음 단계로 넘어간다.

# 예시
> 프로젝트 전체 리팩토링해줘

[파일 수정 권한 요청: config.py]
> n (거부)

[Claude: config.py는 건너뛰고 다음 파일 진행합니다]
[파일 수정 권한 요청: utils.py]
> y (승인)

 

12. TypeScript 자동 검증

TypeScript 프로젝트에서 파일 수정 후 자동으로 tsc를 실행하여 타입 오류를 즉시 감지한다. 빌드 전에 타입 에러를 미리 잡아낼 수 있다.

# 예시: TypeScript 파일 수정 시 자동 검증
> utils.ts 파일에 새 함수 추가해줘

[파일 수정 완료: utils.ts]
[tsc 자동 실행 중...]
[타입 에러 발견: line 45 - 'string' 타입은 'number'에 할당 불가]
[Claude: 타입 에러를 수정하겠습니다...]

 

13. Wildcard 도구 권한 (2.1 신규)

도구 권한 설정에서 와일드카드 패턴을 사용할 수 있다. 반복적인 권한 설정이 간소화된다.

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm *)",        // npm으로 시작하는 모든 명령 허용
      "Bash(git *)",        // git으로 시작하는 모든 명령 허용
      "Bash(*-h*)",         // -h 플래그가 포함된 명령 허용 (help)
      "Read(src/**/*)",     // src 디렉토리 내 모든 파일 읽기 허용
      "Write(tests/**/*)"   // tests 디렉토리 내 파일 쓰기 허용
    ],
    "deny": [
      "Bash(rm -rf *)",     // 위험한 삭제 명령 차단
      "Write(.env*)"        // 환경 변수 파일 수정 차단
    ]
  }
}

와일드카드 패턴 문법

• * - 모든 문자열 매칭 (단일 레벨)
• ** - 모든 경로 매칭 (다중 레벨)
• ? - 단일 문자 매칭

 

2.0 vs 2.1 비교

기능	2.0	2.1
서브에이전트 실행	동기 (블로킹)	비동기 (Ctrl+B)
스킬 업데이트	재시작 필요	핫 리로드
컨텍스트 분기	미지원	context: fork
훅 스코프	글로벌만	에이전트 스코프
원격 환경 연결	미지원	/remote-env
컨텍스트 크기	200K	200K
Code Simplifier	미지원	플러그인 지원
사용자 질문 도구	추측 후 진행	먼저 질문
권한 거부 시	작업 중단	건너뛰고 계속
TypeScript 검증	수동	자동 tsc 실행
서브에이전트 Skills 연동	미지원	skills: 필드 지원
도구 권한 패턴	개별 지정	Wildcard 패턴
백그라운드 작업 관리	미지원	/tasks 명령어
에이전트 관리 UI	미지원	/agents 명령어
서브에이전트 훅	미지원	SubagentStart/Stop
에이전트별 권한 모드	글로벌만	permissionMode 필드

 

후속 업데이트 (2.1.x)

2.1.0 이후 여러 패치 버전(2.1.3, 2.1.4, 2.1.5 등)이 릴리스되었다. 주요 개선 방향은 다음과 같다:

• CLI 안정성 개선
• 에러 핸들링 강화
• 백그라운드 에이전트 관리 개선
• 다양한 버그 수정

상세 변경사항은 GitHub CHANGELOG에서 확인할 수 있다.

 

활용 팁

백그라운드 에이전트 활용하기

테스트나 빌드처럼 시간이 오래 걸리는 작업은 백그라운드로 보내자:

1. 작업 요청 (예: "테스트 전체 실행해줘")
2. 작업이 시작되면 Ctrl+B로 백그라운드 전환
3. 다른 작업 진행
4. 완료 알림 받으면 결과 확인

스킬 개발 워크플로우

핫 리로드 덕분에 스킬 개발이 훨씬 빨라졌다:

1. .claude/skills/ 폴더에 마크다운 파일 생성
2. 스킬 내용 작성
3. 저장 후 바로 /my-skill로 테스트
4. 수정하고 다시 저장 - 재시작 불필요

컨텍스트 포크로 안전하게 실험하기

메인 대화를 유지하면서 실험적인 탐색을 하고 싶다면:

1. context: fork가 설정된 스킬 호출
2. 분기된 컨텍스트에서 자유롭게 탐색
3. 원하는 결과만 메인 컨텍스트로 가져오기

서브에이전트 + Skills 활용하기 (2.1 신규)

전문화된 서브에이전트에 관련 스킬을 연결하면 도메인별 작업 효율이 크게 향상된다:

1. .claude/agents/에 도메인별 서브에이전트 정의
2. 관련 스킬들을 skills: 필드에 지정
3. @agent-name으로 해당 서브에이전트에 작업 위임

예: DB 관리 에이전트 + SQL 스킬, 테스트 에이전트 + 테스트 스킬 조합

 

트러블슈팅 (자주 발생하는 문제)

처음 Claude Code를 사용할 때 자주 겪는 문제와 해결 방법이다.

1. API 키 인증 실패

Error: Invalid API key provided

원인: API 키가 설정되지 않았거나 올바르지 않음

해결 방법:

1. 환경 변수 확인: echo $ANTHROPIC_API_KEY
2. 키가 sk-ant-로 시작하는지 확인
3. 키에 공백이나 따옴표가 잘못 포함되지 않았는지 확인
4. Anthropic Console에서 키가 활성 상태인지 확인

2. claude 명령어를 찾을 수 없음

command not found: claude

원인: PATH에 설치 경로가 추가되지 않음

해결 방법:

# npm 전역 설치 경로 확인
npm config get prefix

# PATH에 추가 (~/.zshrc 또는 ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"

# 변경사항 적용
source ~/.zshrc

3. 파일 권한 에러

Error: EACCES: permission denied

원인: Claude Code가 파일을 읽거나 쓸 권한이 없음

해결 방법:

• 프로젝트 폴더의 소유권 확인: ls -la
• 필요시 권한 수정: chmod 755 ./your-file
• sudo 없이 실행하는 것이 권장됨

4. 훅(Hook) 실행 실패

Hook failed: [hook-name]

원인: 훅 스크립트 오류 또는 권한 문제

해결 방법:

• 훅 스크립트의 문법 오류 확인
• 스크립트에 실행 권한 부여: chmod +x hook-script.sh
• 스크립트를 터미널에서 직접 실행하여 에러 메시지 확인
• 훅 설정 파일(settings.json)의 JSON 형식 검증

5. 컨텍스트 크기 초과

Context window exceeded

원인: 대화가 길어져 200K 토큰 한도 초과

해결 방법:

• /compact 명령어로 컨텍스트 압축
• /clear로 대화 초기화 후 새로 시작
• 한 번에 너무 많은 파일을 분석하지 않기
• 큰 작업은 여러 세션으로 나누어 진행

6. 네트워크 연결 에러

Error: Network error / Connection timeout

원인: 네트워크 문제 또는 프록시 설정

해결 방법:

• 인터넷 연결 상태 확인
• 회사/학교 네트워크의 경우 프록시 설정 필요할 수 있음
• VPN 사용 중이라면 일시적으로 비활성화 후 테스트
• 방화벽에서 api.anthropic.com 허용 여부 확인

팁: 디버깅 모드
문제 원인을 파악하기 어려울 때는 claude --debug로 실행하면 상세한 로그를 볼 수 있다. 버그 리포트 시 이 로그가 도움이 된다.

주의사항

• API 키 필요: Claude Code 사용에는 Anthropic API 키가 필요하다.
• 비용 발생: API 호출에 따른 비용이 발생한다. 사용량을 모니터링하자.
• 권한 설정: 파일 수정, 명령 실행 등 민감한 작업에 대한 권한 설정을 확인하자.
• 백그라운드 작업: 백그라운드 에이전트도 API 호출을 하므로 비용에 주의하자.

 

마무리

Claude Code 2.1은 에이전틱 코딩의 새로운 가능성을 열었다. 비동기 서브에이전트로 병렬 작업이 가능해졌고, 스킬 핫 리로드로 커스터마이징이 편리해졌으며, 컨텍스트 포크로 안전한 실험이 가능해졌다.

특히 대규모 프로젝트에서 테스트, 빌드, 코드 분석을 동시에 진행해야 하는 개발자들에게 백그라운드 에이전트 기능이 유용할 것으로 보인다.

앞으로도 Claude Code의 업데이트를 지켜보며 추가 내용이 있으면 업데이트하겠다.

참고 자료

• GitHub - Claude Code CHANGELOG
• Claude Code 공식 문서
• GitHub - Claude Code Repository
• Claude Code Skills 문서
• Skills, Subagents, Hooks 상세 가이드 (alexop.dev)

작성일: 2026-01-12 (2026-01-13 보완)
기준 버전: Claude Code 2.1.5