Claude Code 핵심 정리

# 설치 및 구성

Claude Code 빠른 시작(Quickstart) 문서를 참고해, 사용하는 운영체제 및 터미널에 맞게 다음 명령을 실행해서 설치합니다.

1
2
3
4
5
6
7
8
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

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

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

설치가 완료되면 터미널을 재시작해서 다음과 같이 Claude Code CLI의 버전을 확인합니다.
버전이 보이면 정상적으로 설치되었습니다.

1
2
claude -v
# 2.1.294 (Claude Code)

설치가 성공했지만, claude를 실행할 때 command not found 또는 not recognized 오류가 발생하면 우선 터미널을 재부팅해서 다시 시도합니다.
그래도 문제가 해결되지 않으면, 설치 디렉토리의 PATH 환경변수 확인이 필요합니다.
사용하는 운영체제 및 터미널에 맞게 다음 명령을 실행합니다.
그리고 터미널을 재시작해서 다시 Claude Code CLI 버전을 확인하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# macOS - Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# macOS - Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows - PowerShell
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# Windows - CMD
echo %PATH% | findstr /i "local\bin"

# 첫 실행 및 로그인

처음 claude 명령을 실행하면 자동으로 로그인 프롬프트가 표시됩니다.

1
claude

먼저 테마를 선택합니다.
아래에 표시되는 코드 미리보기를 보고 사용하는 터미널에서 잘 보이는 쪽을 고르면 되고, 나중에 /theme 명령으로 다시 바꿀 수 있습니다.

테마 선택

그리고 Claude 계정을 연결해야 합니다.
구독 계정, API 사용량으로 과금되는 Console 계정, Amazon Bedrock이나 Vertex AI 같은 서드파티 플랫폼 중에서 선택합니다.
여기에서는 구독 계정을 연결하며, 미리 브라우저에서 로그인하고 나서 시도하는 게 좋습니다.

계정 연결

계정 연결 방법을 선택하면 브라우저로 이동하고 승인을 요청합니다.

연결 승인

승인하면 연결이 완료됩니다.

연결 완료

다시 Claude Code로 이동하면 로그인이 완료됩니다.
Enter 키를 눌러 시작합니다.

로그인 성공

시작하면 다음과 같은 첫 화면이 표시됩니다.

Claude Code 첫 화면

Claude Code 화면의 상단에는 버전, 현재 모델과 플랜, 작업 디렉토리가 표시됩니다.
하단의 ❯ 표시가 있는 곳이 프롬프트 입력창이고, 그 아래 상태줄(Statusline)에는 현재 승인 모드와 자주 쓰는 단축키 안내 등이 표시됩니다.

인증 정보는 안전하게 저장되며(macOS는 시스템 키체인, Windows는 C:\Users\사용자이름\.claude\.credentials.json 파일), 이후 세션에서는 다시 로그인할 필요가 없습니다.
/login, /logout 명령으로 로그인/로그아웃할 수 있습니다.

1
2
3
4
5
# 대화형 세션 안에서 입력
/login

# 로그아웃
/logout

# 내장 슬래시 명령

Claude Code에서 /로 시작하는 명령을 내장 슬래시 명령(Built-in Slash Commands)이라고 합니다.
입력창에 /만 입력해도 사용할 수 있는 명령 목록과 설명이 자동 완성되므로, 다 외울 필요는 없습니다.

슬래시 명령 자동 완성

대부분 내장 명령은 Claude AI가 아닌 클라이언트(CLI)가 직접 처리하므로 대화 컨텍스트를 소비하지 않습니다.

자주 사용하는 기본 명령은 다음과 같습니다.
사용하는 상황이 비슷한 명령끼리 세션, 대화, 모델, 상태와 계정, 설정 순서로 묶었습니다.

더 많은 명령과 인수, 별칭은 Claude Code 내장 슬래시 명령어 핵심 정리를 참고하세요.

# 이전 세션 이어가기

Claude Code는 이전 대화 세션을 이어서 진행할 수 있습니다.
--continue 플래그를 사용하면 가장 최근 세션을 자동으로 불러옵니다.
작업 중 터미널을 실수로 닫았거나, 이전 대화에서 이어가고 싶을 때 유용합니다.
세션 히스토리는 로컬에 저장되므로, 같은 기기에서만 이전 세션을 이어갈 수 있습니다.

1
2
claude --continue
claude -c # 축약

만약 특정 세션을 선택해서 이어가려면, --resume 플래그를 사용합니다.
인수 없이 사용하면 최근 세션 목록이 표시되고 원하는 세션을 선택할 수 있습니다.
혹은 세션 ID나 이름을 인수로 전달하면 해당 세션을 직접 재개합니다.

1
2
3
4
5
6
7
# 인수 없이 사용해 세션 목록에서 선택
claude --resume
claude -r # 축약

# 세션 ID 또는 이름으로 직접 재개
claude --resume "세션ID"
claude -r "세션ID"

대화형 세션 안에서는 /resume 명령으로도 같은 세션 목록을 확인할 수 있습니다.
/rename 명령으로 현재 세션에 이름을 추가해 두면 나중에 찾기 쉽습니다.

# 특수 문자 단축

프롬프트에서 사용할 수 있는 특수 문자입니다.

1
2
@src/components/Header.tsx 영화 검색 페이지로 이동하는 버튼 추가해 줘
@src/stores/ 스토어 파일들을 타입스크립트로 리팩토링해 줘

@ 뒤에 경로를 입력하기 시작하면 일치하는 파일과 폴더 목록이 자동 완성으로 표시되므로, 정확한 경로를 몰라도 골라서 넣을 수 있습니다.

파일 경로 자동 완성

!로 실행한 터미널 명령의 출력은 대화 컨텍스트에 자동으로 추가됩니다.
추가를 원하지 않으면 ESC 키로 취소합니다.

1
2
! npm test
! git status

# CLAUDE.md

CLAUDE.md는 Claude Code가 프로젝트에 대한 지침과 컨텍스트를 기억하는 메모리 파일입니다.
세션 간에 스타일 가이드라인, 일반 명령, 프로젝트 정보 등을 유지할 수 있습니다.

일반적인 AI 채팅에서는 새로운 세션을 시작할 때마다 프로젝트 구조, 코딩 스타일, 특별한 규칙 등을 다시 설명해야 합니다.
하지만 CLAUDE.md 파일을 사용하면 이러한 정보가 매 세션마다 자동으로 Claude에게 전달됩니다.
프로젝트 루트에 CLAUDE.md 파일을 작성해두면, Claude가 세션 시작 시 이 파일을 읽고 프로젝트의 맥락을 파악합니다.

지침 파일은 넓은 범위에서 좁은 범위 순으로 로드되며, 서로 덮어쓰지 않고 모두 이어 붙여집니다.
따라서 아래로 갈수록 Claude가 나중에 읽는, 더 구체적인 지침이 됩니다.

지침 파일이 세션에 로드되는 순서

Claude Code의 메모리에는 위 표의 CLAUDE.md 계열 외에 자동 메모리(Auto memory)가 하나 더 있습니다.
사람이 작성하는 CLAUDE.md와 달리, Claude가 작업하면서 알게 된 빌드 명령이나 디버깅 요령을 스스로 기록하는 파일입니다.
~/.claude/projects/프로젝트이름/memory/MEMORY.md에 저장되며 매 세션 시작 시 함께 로드되는데, 파일 전체가 아니라 앞의 200줄 또는 25KB까지만 읽습니다.
저장 위치가 Git 저장소 단위로 결정되어 사용자나 프로젝트 같은 범위 구분이 없고, 기기 사이에도 동기화되지 않습니다.
/memory 명령으로 내용을 확인하거나 기능을 끌 수 있습니다.
현재 세션에 로드된 지침 파일의 위치도 이 화면에서 함께 확인할 수 있습니다.

/memory 화면

# 프로젝트 초기화

/init 명령을 사용해, 프로젝트를 초기화할 수 있습니다.
이 과정에서 현재 경로에서 프로젝트를 분석하고 프로젝트 루트에 CLAUDE.md 파일을 생성할 수 있습니다.
이는 프로젝트에 대한 지침과 컨텍스트(Context)를 기억하는 메모리 파일로, 각 대화 세션에서 프로젝트의 가이드라인, 일반 명령, 기타 정보 등을 유지할 수 있습니다.
CLAUDE.md가 이미 있으면 덮어쓰지 않고 개선할 내용을 제안하며, .cursorrules나 .github/copilot-instructions.md 같은 다른 도구의 규칙 파일이 있으면 그 내용도 반영합니다.
Cursor 같은 다른 AI 코딩 도구에서 옮겨 오는 경우에는 지침과 MCP 서버, 스킬을 한 번에 가져오는 /import 명령도 있습니다.

1
/init

빈 프로젝트에서 시작하는 경우, Claude Code는 다음과 같이 새로운 프로젝트 생성을 유도합니다.
원하는 프로젝트에 대해서 프롬프트를 작성하고 Enter 키를 눌러 입력을 완료합니다.

프롬프트를 입력하면 작업이 초기화 작업이 시작됩니다.

1
TypeScript와 Next.js를 사용해서 로그인 가능한 Todo 앱을 만들어 줘.

# 파일 가져오기

CLAUDE.md에서 @path/to/file 구문으로 다른 파일을 가져올 수 있습니다.
상대 경로와 절대 경로 모두 사용할 수 있습니다.
가져온 파일 내 경로로 다시 다른 파일을 가져올 수도 있으며, 이렇게 이어지는 깊이는 최대 4단계입니다.

1
2
3
4
5
프로젝트 개요는 @README 참조.
npm 명령은 @package.json 참조.

## 추가 지침
- git 워크플로우 @docs/git-instructions.md

# 작성 팁

효과적인 CLAUDE.md를 작성하면 Claude가 프로젝트를 더 잘 이해하고 일관된 결과를 제공합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# 프로젝트 개요

이 프로젝트는 React + TypeScript 기반의 이커머스 플랫폼입니다.

## 기술 스택

- Frontend: React 18, TypeScript, Tailwind CSS
- State: Zustand
- API: REST, React Query
- Testing: Jest, React Testing Library

## 코딩 컨벤션

- 컴포넌트는 함수형으로 작성
- 상태 관리는 Zustand 사용
- API 호출은 src/api/ 폴더에 분리
- 스타일은 Tailwind CSS 클래스 사용

## 프로젝트 구조

src/
├── components/  # 재사용 가능한 컴포넌트
├── pages/       # 페이지 컴포넌트
├── api/         # API 관련 코드
├── stores/      # Zustand 스토어
└── utils/       # 유틸리티 함수

## 자주 사용하는 명령어

- `npm run dev`: 개발 서버 실행
- `npm run test`: 테스트 실행
- `npm run build`: 프로덕션 빌드

## 주의사항

- .env 파일은 절대 커밋하지 마세요
- API 키는 환경 변수로 관리합니다
- 새 컴포넌트 추가 시 스토리북도 함께 작성해 주세요

작성할 때는 다음 사항을 참고하세요.

1. 간결하게 유지: 핵심 정보만 포함, 너무 길면 컨텍스트를 낭비
2. 구체적으로 작성: '좋은 코드를 작성' 같은 추상적 표현보다, '함수는 20줄 이내로 작성' 같은 구체적 표현 사용
3. 예시 포함: 원하는 코드 스타일이 있다면 예시 첨부
4. 파일 참조 활용: 상세 내용은 @docs/guide.md 같이 파일 참조
5. 정기적 업데이트: 프로젝트가 변경되면 CLAUDE.md도 업데이트

작성해 둔 지침이 낡았는지 점검하려면 /doctor prompt-audit 명령을 실행합니다(2.1.283 이상).
CLAUDE.md, AGENTS.md, 규칙, 스킬, 에이전트 파일에서 이전 모델에 맞춰 작성한 지침, 존재하지 않는 파일이나 명령의 참조, 서로 모순되는 지침을 찾아서 수정안과 함께 보고합니다.
보고만 하고 파일은 바꾸지 않으므로, 수정안을 확인한 뒤 반영을 요청합니다.

1
/doctor prompt-audit

# Karpathy Guidelines

OpenAI 창립 멤버이자 테슬라 AI 총괄을 지낸 안드레이 카파시(Andrej Karpathy)가 지적한 LLM 코딩의 문제점을, 네 가지 지침으로 정리한 CLAUDE.md입니다.

• 코딩 전에 가정을 명시하고, 불명확하면 멈추고 질문합니다.
• 요청받지 않은 기능이나 추상화를 만들지 않습니다.
• 요청과 무관한 코드는 건드리지 않습니다.
• 검증 가능한 성공 기준을 정하고, 통과할 때까지 반복합니다.

특정 프로젝트가 아니라 코드를 작성하는 방식 자체를 다루므로, User 범위에 두고 프로젝트별 지침과 함께 사용하기 좋습니다.

https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md

# 내장 도구

Claude Code는 다양한 내장 도구를 통해 파일 시스템, 터미널, 웹에 접근합니다.
이 도구들은 Claude가 단순히 코드를 생성하는 것을 넘어, 실제로 프로젝트를 탐색하고 수정할 수 있게 해줍니다.
각 도구는 특정 작업에 최적화되어 있으며, Claude는 상황에 따라 적절한 도구를 자동으로 선택합니다.

예를 들어 프로젝트의 스크립트 목록을 물어보면, Claude는 먼저 Read 도구로 package.json을 읽은 뒤 그 내용을 바탕으로 답합니다.
화면에는 사용한 도구와 대상이 접힌 상태로 표시되며, 선택하면 상세 내용을 펼쳐서 볼 수 있습니다.

도구를 사용해서 답하는 과정

위 표는 자주 쓰이는 도구를 추린 것으로, 실제 내장 도구는 이보다 많습니다.
--tools 플래그로 사용 가능한 도구를 제한할 수 있습니다.

1
2
3
4
5
6
7
8
# 지정한 도구만 허용
claude --tools "Bash,Edit,Read"

# 모든 내장 도구 비활성화
claude --tools ""

# 모든 내장 도구 허용 (기본값)
claude --tools "default"

# 승인 모드

Claude Code는 작업 실행 전에 사용자 승인을 요청하는 방식에 따라 여러 모드로 동작합니다.
터미널과 VS Code에서 시작하는 대화형 세션은 따로 지정하지 않으면 플랜과 상관없이 Auto 모드로 시작하고(2.1.283 이상), claude -p 같은 비대화형 실행은 Manual 모드로 시작합니다.

Manual 모드에서 Claude가 파일을 수정하려고 하면 다음과 같이 변경 내용을 먼저 보여 주고 승인을 요청합니다.
Yes를 선택하면 이번 한 번만 허용하고, 두 번째 항목을 선택하면 이 세션 동안 파일 편집을 자동으로 승인하는 Accept Edits 모드로 전환합니다.

파일 편집 승인 요청

승인 모드의 범위

Shift + Tab을 누를 때마다 default, acceptEdits, plan 순서로 모드가 바뀌고, Auto 모드에서 누르면 먼저 default로 바뀝니다.
auto는 사용할 수 있는 모델과 환경일 때, bypassPermissions는 해당 플래그나 설정으로 세션을 시작했을 때만 plan 다음 순서로 순환에 합류합니다.
dontAsk는 순환에 나타나지 않으므로 CLI 플래그로 지정해야 합니다.
모드를 바꾸면 하단 상태줄의 표시가 함께 바뀌므로, 지금 어떤 모드인지는 상태줄에서 확인합니다.

모드에 따라 달라지는 상태줄

셸 명령은 Accept Edits 모드에서도 승인을 요청합니다.
이때 두 번째 항목을 선택하면 같은 명령을 이 프로젝트에서 다시 묻지 않도록 허용 규칙으로 저장하며, 규칙은 로컬 설정(.claude/settings.local.json)에 기록됩니다.
자주 실행하는 테스트나 빌드 명령은 이렇게 한 번씩 허용해 두면 이후 작업이 끊기지 않습니다.

셸 명령 승인 요청

Claude Code를 시작할 때 CLI 플래그(Flag)로 모드를 설정할 수도 있습니다.

1
2
3
4
5
6
7
8
9
# Plan 모드로 시작
claude --permission-mode plan

# Don't Ask 모드로 시작
claude --permission-mode dontAsk

# Bypass Permissions 모드로 시작
claude --permission-mode bypassPermissions
claude --dangerously-skip-permissions

Claude Code를 시작할 때마다 적용되는 기본 승인 모드는 설정 파일의 permissions.defaultMode 옵션으로 지정할 수 있습니다.
Auto 모드 대신 매번 승인하는 방식으로 시작하려면 default(또는 manual)를 지정합니다.
auto와 bypassPermissions 값은 프로젝트 설정이나 로컬 설정에서는 적용되지 않으므로 사용자 설정(~/.claude/settings.json)에 지정합니다.

1
2
3
4
5
{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

dontAsk와 bypassPermissions 모두 권한 요청 프롬프트를 띄우지 않지만, 승인이 필요한 상황을 처리하는 방향이 서로 반대입니다.
dontAsk는 사전 승인되지 않은 도구 호출을 자동으로 거부하고, bypassPermissions는 자동으로 승인합니다.
허용 목록에 등록한 작업만 실행되도록 통제하려면 dontAsk를 사용하고, 컨테이너나 가상 머신(VM)처럼 격리된 환경에서 모든 작업을 제약 없이 실행하려면 bypassPermissions를 사용합니다.

# 모델과 사고 깊이

/model 명령으로 세션에서 사용할 모델을 바꿀 수 있습니다.
기본 모델은 모든 플랜에서 Opus 5.5이며, 2.1.280 버전부터 Pro와 Team Standard 플랜도 Sonnet 대신 Opus를 기본으로 사용합니다.
가장 어렵고 오래 걸리는 작업에는 Fable 5.1, 일상적인 작업에는 Opus 5.5, 범위가 분명한 작업을 더 빠르고 저렴하게 처리하려면 Sonnet 5.5, 요약이나 분류처럼 단순하고 반복적인 작업에는 Haiku 5.5를 선택합니다.
sonnet과 haiku 별칭은 각각 2.1.284, 2.1.293 버전부터 Sonnet 5.5와 Haiku 5.5를 가리킵니다.
계정에 따라 목록 아래쪽에 Sonnet 5, Opus 5 같은 이전 모델이 함께 표시되며, 목록에 없는 모델은 /model claude-opus-4-5처럼 전체 모델 이름으로 지정합니다.
같은 화면에서 ←, → 키로 사고 깊이도 함께 조절할 수 있고, Enter는 새 세션의 기본값으로 저장하며 s는 이번 세션에만 적용합니다.

모델 선택

확장 사고(Extended Thinking)는 Claude가 응답하기 전에 먼저 추론하는 과정입니다.
지원하는 모델에서는 기본으로 켜져 있으며, 얼마나 깊이 추론할지는 사고 깊이(Effort) 설정으로 정해집니다.
Opus 5.5, Sonnet 5.5, Haiku 5.5와 Fable 모델은 확장 사고를 끌 수 없고, 사고 깊이에 따라 단계마다 얼마나 추론할지를 모델이 정합니다.
세션 전체의 사고 깊이는 /effort 명령이나 claude --effort 플래그로 지정하며, low부터 max까지의 단계 중에서 선택합니다.
Opus 5.5, Sonnet 5.5, Haiku 5.5의 기본값은 medium이며, Haiku 5.5는 사고 깊이를 조절할 수 있는 첫 Haiku 모델입니다.
/effort 화면에서 Tab을 누르면 워크플로우를 자동으로 사용하는 ultracode를 켜고 끌 수 있으며, 2.1.284 버전부터는 사고 깊이와 별개의 토글이라 어느 단계에서든 함께 켤 수 있습니다.

사고 깊이 선택

단계가 높을수록 더 깊이 추론해서 성능은 오르지만, 사용하는 토큰이 많아져 비용도 함께 늘어납니다.
다음은 모델마다 발표 페이지에 있는 사고 깊이별 벤치마크 그래프에서, 함께 표시된 다른 모델은 빼고 그 모델의 결과만 모아 하나로 겹친 것입니다.
벤치마크마다 점수 단위와 비용 규모가 달라서, 성능은 그 모델의 최고점을 100으로, 작업당 비용은 그 모델의 max 비용을 100%로 맞췄습니다.
진한 선은 벤치마크별 결과의 중앙값이며, 점마다 성능과 비용을 함께 표시했습니다.

Fable 5.1 발표 페이지의 벤치마크는 Terminal-Bench-Science 0.1, Terminal-Bench 4.0, Humanity's Last Exam, CursorBench 3.2.0 4개이며, Humanity's Last Exam은 도구를 사용한 결과와 사용하지 않은 결과를 각각 하나의 선으로 그렸습니다.

Fable 5.1의 사고 깊이별 성능과 비용

Fable 5.1은 low에서도 최고 성능의 87% 정도를 내고, 단계를 올려도 성능은 조금씩만 오릅니다.
반면 low의 비용도 max의 29% 정도라서, 낮은 단계를 선택해도 아낄 수 있는 비용이 다른 모델보다 적습니다.

Opus 5.5 발표 페이지의 벤치마크는 Terminal-Bench 4.0, FrontierCode, CursorBench, GDPval-AA, AutomationBench, WANDR 6개입니다.

Opus 5.5의 사고 깊이별 성능과 비용

기본값인 medium은 max 비용의 약 4분의 1로 최고 성능의 87% 정도를 내고, high는 약 3분의 1의 비용으로 95% 정도를 냅니다.
xhigh와 max는 비용이 2~3배로 늘어나지만 성능은 5% 정도만 오릅니다.

Sonnet 5.5 발표 페이지의 벤치마크는 Terminal-Bench 4.0, FrontierCode, CursorBench, AA-Briefcase 4개입니다.

Sonnet 5.5의 사고 깊이별 성능과 비용

Sonnet 5.5의 medium은 max 비용의 6% 정도로 최고 성능의 55% 정도를 냅니다.
high에서 74%, xhigh에서 91%로 단계를 올릴 때마다 성능이 크게 오르고, xhigh의 비용도 max의 37% 정도입니다.

Haiku 5.5 발표 페이지의 벤치마크는 OSWorld 2.1, GDPval-AA, Humanity's Last Exam, Terminal-Bench 4.0 4개입니다.

Haiku 5.5의 사고 깊이별 성능과 비용

Haiku 5.5도 Sonnet 5.5와 비슷하게 medium은 max 비용의 12% 정도로 최고 성능의 63% 정도를 내고, xhigh에서 87%까지 오릅니다.

정리하면 Opus 5.5는 평소에 medium이나 high를 사용하고, 정말 어려운 작업에만 더 높은 단계를 사용하는 것이 효율적입니다.
Sonnet 5.5에 어려운 작업을 맡길 때는 사고 깊이를 xhigh 이상으로 올려야 Opus 5.5에 가까운 결과를 기대할 수 있습니다.
Haiku 5.5는 코딩 작업에서는 다른 모델과 점수 차이가 크지만, 일반 업무에서는 높은 단계로 올려도 비용이 적게 들어 효율적입니다.
다만 두 벤치마크의 결과라서 작업의 종류에 따라 순서는 달라질 수 있습니다.

한 번의 요청에만 더 깊은 추론이 필요하다면 프롬프트에 ultrathink 키워드를 포함합니다.

1
ultrathink 결제 로직에서 동시성 문제가 생길 수 있는 지점을 모두 찾아 줘

키워드는 프롬프트의 어느 위치에 넣어도 되고, 대소문자를 구분하지 않습니다.
세션의 사고 깊이 설정은 그대로 두고, 이번 요청에 한해 더 깊이 추론하라는 지시를 컨텍스트에 추가하는 방식입니다.
입력창에서 키워드가 강조 표시되면 적용된 것이며, 효과는 그 요청 하나로 끝나므로 다음 요청에도 필요하면 다시 입력합니다.

ultrathink 키워드가 적용된 입력창

사고한 내용도 출력 토큰으로 계산되어 컨텍스트를 차지하고 비용에 포함됩니다.
모든 요청에 사용하기보다 원인이 잘 잡히지 않는 버그나 설계 판단처럼 어려운 작업에 사용합니다.
사고 과정은 화면에서 기본으로 접혀 있으며, Ctrl + O로 상세 표시를 켜면 회색 글씨로 확인할 수 있습니다.

이름이 비슷한 ultracode는 사고 깊이가 아니라 워크플로우를 사용하게 하는 설정이자 키워드이며, 자세한 내용은 Dynamic Workflows에서 살펴봅니다.

모델을 통째로 바꾸는 대신, 판단이 필요한 순간에만 더 강한 모델의 의견을 빌리는 방법도 있습니다.
/advisor 명령으로 자문 모델(Advisor)을 지정하면, Claude는 복잡한 결정이나 원인이 잡히지 않는 실패처럼 판단이 필요한 시점에 그 모델에게 조언을 구한 뒤 작업을 이어 갑니다.
자문 모델은 메인 모델과 같거나 더 강한 모델이어야 하며, Anthropic은 메인 모델로 Sonnet을, 자문 모델로 Opus를 조합하는 구성을 대표 예시로 안내합니다.
실험적 기능이라 추가 토큰이 사용되고, 구독 플랜에서 자문 사용량은 플랜 사용량에 포함되지만 Fable을 자문 모델로 지정하면 플랜에 따라 사용량 크레딧으로 과금될 수 있습니다.

자문 모델 선택

반대로 응답 속도가 더 중요하면 /fast 명령으로 빠른 모드(Fast Mode)를 켤 수 있습니다.
더 작은 모델로 바꾸는 것이 아니라 같은 Opus 모델을 최대 2.5배 빠른 출력 속도로 사용하는 방식이며, Opus 5.5, Opus 5, Opus 4.8에서만 지원하고 기본은 Opus 5.5입니다.
토큰 단가가 높고(Opus 5.5 기준 100만 토큰당 입력 8달러, 출력 40달러) 구독 플랜에서는 플랜 사용량과 별도로 사용량 크레딧(Usage credits)에서 과금되므로, 빠른 반복 작업이나 실시간 디버깅처럼 응답 속도가 비용보다 중요한 상황에서만 켜는 것이 좋습니다.

# 구성 파일

Claude Code의 설정은 settings.json 파일에 작성하며, 적용 범위에 따라 이 파일을 다음 세 위치에 둘 수 있습니다.
이 글에서는 세 파일을 각각 사용자 설정, 프로젝트 설정, 로컬 설정이라고 부릅니다.

1
2
3
# Claude Code 개인 파일 (커밋하지 않음)
.claude/settings.local.json
CLAUDE.local.md

• 프로젝트 설정(.claude/settings.json): 팀 전체가 공유해야 하는 권한 규칙, 허용된 도구 등을 정의합니다. Git에 커밋하여 팀원 모두가 동일한 설정을 사용합니다.
• 로컬 설정(.claude/settings.local.json): 개인별 API 키 경로, 개인 선호 설정 등을 저장합니다. .gitignore에 추가하여 커밋하지 않습니다.

여러 위치에 같은 설정이 있으면 다음 순서로 우선 적용됩니다.

1. Managed (최고, 변경 불가)
2. 명령줄 인수
3. Local
4. Project
5. User (최저)

설정이 겹칠 때의 우선순위

다음은 프로젝트 설정에서 도구 권한을 관리하는 예시입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(src/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(curl *)"
    ]
  }
}

전체 디렉토리 구조:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
~/.claude/
├── settings.json       # 사용자 설정
├── CLAUDE.md           # 사용자 전역 메모리
├── agents/             # 사용자 커스텀 에이전트
│   └── my-agent.md
├── skills/             # 사용자 스킬 (슬래시 명령어 포함)
│   └── my-skill/
│       └── SKILL.md
├── rules/              # 사용자 전역 규칙
│   └── my-rule.md
├── output-styles/      # 사용자 커스텀 출력 스타일
│   └── my-style.md
└── hooks/              # 사용자 Hook 스크립트
    └── my-hook.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
./your-project/
├── .claude/
│   ├── settings.json       # 프로젝트 설정
│   ├── settings.local.json # 로컬 설정 ❌ gitignore
│   ├── CLAUDE.md           # 프로젝트 메모리
│   ├── agents/             # 프로젝트 커스텀 에이전트
│   │   └── code-reviewer.md
│   ├── skills/             # 프로젝트 스킬 (슬래시 명령어 포함)
│   │   └── pdf-processing/
│   │       ├── SKILL.md        # 필수: 메타데이터와 지침
│   │       ├── scripts/        # 선택: 유틸리티 스크립트
│   │       │   └── extract.py
│   │       └── references/     # 선택: 참조 문서
│   │           └── api-guide.md
│   ├── rules/              # 프로젝트 규칙
│   │   ├── code-style.md
│   │   └── testing.md
│   ├── output-styles/      # 프로젝트 커스텀 출력 스타일
│   │   └── verbose.md
│   └── hooks/              # 프로젝트 Hook 스크립트
│       └── pre-commit.sh
├── .mcp.json               # MCP 서버 설정
├── CLAUDE.md               # 프로젝트 메모리
└── CLAUDE.local.md         # 개인 프로젝트 메모리 ❌ gitignore

각 파일과 폴더의 용도를 정리하면 다음과 같습니다.

# 컨텍스트 관리

컨텍스트는 Claude가 현재 대화에서 기억하고 있는 모든 정보입니다.
컨텍스트 윈도우의 크기는 1M(100만) 토큰이며, 여기에는 입력(메시지, 파일, CLAUDE.md)과 출력(응답, 코드)이 모두 포함됩니다.
버전 5 이상의 모델(Opus는 4.7부터)은 종류와 플랜에 상관없이 모두 1M 윈도우로 실행되므로, 모델마다 윈도우 크기를 따로 확인할 필요가 없습니다.
Opus 4.6, Sonnet 4.6 같은 이전 모델만 기본이 200K 토큰이고, [1m] 변형을 선택해야 1M을 사용할 수 있습니다.
200K를 넘는 구간에도 토큰 단가는 같지만, Haiku 5.5만은 프롬프트가 100K 토큰을 넘으면 API 단가가 올라갑니다.

시스템 프롬프트와 도구 설명, 지침 파일처럼 매 요청마다 실리는 고정 부분이 있고, 그 뒤로 대화와 도구 실행 결과가 계속 쌓입니다.
쌓인 양이 자동 압축 지점에 도달하면 앞선 대화를 요약으로 바꿔서 공간을 확보합니다.

컨텍스트 윈도우가 차고 압축되는 과정

/context를 실행하면 시스템 프롬프트, 도구 설명, 스킬 목록, 대화가 각각 얼마나 차지하는지 확인할 수 있습니다.
연결한 MCP 서버와 설치한 스킬이 많을수록 대화를 시작하기도 전에 고정 부분이 커지므로, 컨텍스트가 빨리 차는 것 같으면 이 화면부터 확인합니다.

/context 화면

토큰 사용량이 임계치에 도달하면 Autocompact가 자동으로 컨텍스트를 압축합니다.
이 임계치는 고정 퍼센트가 아니라 컨텍스트 윈도우에 남은 여유 토큰으로 정해지며, /autocompact 명령으로 조절할 수 있습니다(2.1.288 버전부터 모델별로 따로 저장).
윈도우가 200K이면 약 84%, 1M이면 약 97% 지점에서 트리거됩니다.
Context is 80% full 경고는 압축이 임박했다는 예고일 뿐 실제 압축 시점이 아닙니다.
자동 압축이 잦아지면 요약 과정에서 맥락이 뭉개질 수 있으므로, 작업이 일단락됐다면 /clear로 새 세션을 시작하세요.

/compact 뒤에 지시를 덧붙이면 요약의 초점을 지정할 수 있지만, /compact 자체가 파일을 만들지는 않습니다.
내용을 파일로 남기려면 Claude에게 저장을 요청한 뒤 새 세션에서 그 파일을 참조합니다.

1
2
지금까지의 진행 상황을 session_history.md 파일로 정리해 줘
그리고 @session_history.md를 참고해 현재 상태를 분석해 줘

대화가 잘못된 방향으로 흘러갔을 때는 /rewind 명령으로 특정 시점으로 되돌릴 수 있습니다.
프롬프트마다 코드와 대화의 상태가 기록되어 있어서, 코드만 되돌리거나 대화만 되돌리거나 둘 다 그 시점으로 복구할 수 있습니다.
잘못된 수정을 되돌리면서 그 이후의 대화도 함께 정리되므로 컨텍스트를 관리하는 방법으로도 유용합니다.

/rewind 화면

# 프롬프트 캐싱

프롬프트 캐싱(Prompt Caching)은 반복되는 컨텍스트를 캐시에 올려 두고 재사용해서 비용을 낮추는 기능입니다.
Claude Code가 알아서 관리하므로 따로 켜고 끌 필요는 없지만, 캐시가 언제 살아 있고 언제 깨지는지 알아 두면 같은 작업을 더 적은 비용으로 처리할 수 있습니다.

Claude Code는 요청을 보낼 때마다 지금까지의 대화 전체를 다시 보냅니다.
이때 앞부분이 직전 요청과 같으면 그 부분은 캐시에서 읽고 새로 추가된 부분만 제값으로 처리하는 것이 캐싱의 원리입니다.

요청마다 앞부분은 캐시에서 읽는 구조

캐시에 처음 올리는 Write는 기본 입력보다 비싸고, 올려 둔 것을 다시 읽는 Read는 훨씬 저렴합니다.

간단한 대화 세 번으로 비용이 어떻게 쌓이는지 계산해 보겠습니다.
메시지의 토큰 수는 설명을 위해 어림한 값이고, 1토큰 가격도 계산하기 쉽게 입력 $1, 출력 $5로 단순화합니다.
실제 가격은 100만 토큰 단위로 매겨지지만, 출력이 입력의 5배라는 비율은 실제 모델 가격과 같습니다.

캐싱이 없으면 요청마다 지금까지의 대화 전체가 다시 입력으로 처리됩니다.
세 번째 메시지는 6토큰뿐이지만 앞의 대화를 모두 포함하므로, 세 번째 요청의 입력은 41토큰이 됩니다.
여기에 응답의 출력 비용이 더해져 요청별 비용은 $52, $115, $291로 늘어나고, 세 번의 대화에 드는 비용은 모두 $458입니다.

캐싱 없이 대화할 때의 요청별 비용

캐싱을 사용하면 직전 요청에서 보낸 부분은 캐시에서 읽고, 그 뒤에 새로 붙은 직전 응답과 새 메시지만 캐시에 씁니다.
캐시 쓰기는 5분 TTL의 1.25배, 캐시 읽기는 표의 기본값인 0.1배를 적용했습니다.

캐싱을 사용할 때의 요청별 비용

첫 번째와 두 번째 요청은 캐시 쓰기의 추가 비용 때문에 오히려 각각 $0.5, $1.45 더 비쌉니다.
캐시에서 읽는 앞부분이 커지는 세 번째 요청에서는 비용이 $7 줄어들어, 전체로는 $5.05를 절약합니다.
이 예시는 대화가 짧고 출력 비용의 비중이 커서 절약 폭이 작지만, 대화가 길어질수록 캐시에서 읽는 앞부분이 커지므로 절약 폭도 함께 커집니다.
실제 Claude Code의 요청에는 시스템 프롬프트, 도구 설명, 지침 파일, 읽은 파일처럼 매번 다시 보내는 입력이 이 예시보다 훨씬 많으므로, 캐싱으로 줄어드는 비용도 그만큼 큽니다.

즉 캐시는 재사용이 실제로 일어나야 이득이 되는 구조입니다.
5분 TTL은 1회 Read부터, 1시간 TTL은 2회 Read부터 손익분기를 넘습니다.

TTL은 5분과 1시간 두 가지이며, Claude Code가 요청 종류와 과금 방식에 따라 나누어 사용합니다.
구독 플랜 사용량 안에서 주고받는 메인 대화는 1시간을 사용하고, 서브에이전트나 워크플로우, 압축처럼 메인 대화 밖에서 이뤄지는 요청은 5분을 사용합니다.
플랜 한도를 넘겨 사용량 크레딧으로 과금되기 시작하면 메인 대화도 5분으로 내려가며, API 키로 연결한 경우에는 처음부터 5분입니다.

캐시는 Hit될 때마다 TTL이 무료로 갱신되므로, 연속해서 작업하는 동안에는 계속 살아 있습니다.
반대로 TTL이 지나도록 Hit가 없으면 만료되고, 다음 질문에서 쌓여 있던 토큰이 전부 Write 비용으로 다시 청구됩니다.

시간뿐만 아니라 세션 도중의 특정 동작도 캐시를 무효화합니다.
/model로 모델을 바꾸거나 /effort로 사고 단계를 바꾸면 각각 캐시가 따로 관리되므로 대화 전체를 다시 읽습니다.
다만 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1은 구독과 API 키 사용 모두, 사고 깊이를 바꿔도 캐시가 유지됩니다.
/compact도 대화 구조 자체를 교체하기 때문에 누적된 캐시가 전부 무효화됩니다.
그래서 잘못된 방향으로 흘러간 대화를 되돌릴 때는 /compact 대신 /rewind를 사용하는 것이 캐시를 유지하는 데 유리합니다.

캐시가 실제로 얼마나 활용되고 있는지는 /usage의 세션 블록에 있는 Prompt cache (main) 줄에서 확인할 수 있습니다.
요청 수와 캐시에서 읽은 입력 토큰의 비율, 캐시가 아직 살아 있는지(warm)가 함께 표시됩니다.

캐시를 무효화하는 동작과 유지하는 동작의 전체 목록, 그리고 토큰 사용량을 줄이는 다른 전략은 Claude Code 토큰 다이어트를 위한 최적화 핵심 전략 글에서 다룹니다.

# MCP

MCP(Model Context Protocol)는 AI와 외부 도구를 연결하기 위한 오픈 표준입니다.
Claude Code는 파일과 터미널, 웹까지는 내장 도구로 다루지만, Notion 페이지를 읽거나 Slack에 메시지를 보내거나 데이터베이스를 조회하는 일은 MCP로 연결한 서버를 통해서 처리합니다.
연결한 서버의 기능은 내장 도구와 같은 방식으로 사용되므로, "Notion에서 이번 주 회의록을 찾아서 정리해 줘"처럼 평소와 같이 요청하면 됩니다.

내장 도구와 MCP로 연결한 외부 서비스

# 커넥터

가장 간단한 연결 방법은 claude.ai의 커넥터(Connectors)를 사용하는 것입니다.
claude.ai 설정에서 Gmail, Google Calendar, Google Drive, Notion, Slack 같은 서비스를 한 번 연결하면, 같은 계정으로 로그인한 Claude Code에서도 별도의 설정 없이 그대로 사용할 수 있습니다.
인증은 claude.ai에서 한 번만 처리되고, 서버 주소나 API 키를 직접 다룰 일이 없습니다.
구독 계정으로 로그인했을 때만 동작하며, API 키로 연결한 세션에는 커넥터가 표시되지 않습니다.

/mcp 명령을 실행하면 claude.ai 항목 아래에 연결된 커넥터와 각 커넥터가 제공하는 도구의 수가 표시됩니다.

/mcp 화면에 표시되는 claude.ai 커넥터

커넥터를 선택하면 제공하는 도구 목록을 확인하거나, 인증을 다시 하거나, 이 프로젝트에서 사용하지 않도록 끌 수 있습니다.
도구의 상세 설명은 실제로 사용할 때 로드되지만 도구 이름 목록은 항상 컨텍스트에 실리므로, 코딩 작업에 필요 없는 커넥터는 꺼 두는 것이 좋습니다.
커넥터를 아예 사용하지 않으려면 disableClaudeAiConnectors 설정을 true로 지정합니다.

1
2
Slack의 #frontend 채널에서 어제 논의한 버그를 찾아서 재현 절차를 정리해 줘
Google Drive에 있는 API 명세서를 참고해서 src/api/ 클라이언트 코드를 작성해 줘

# 서버 직접 등록

커넥터 목록에 없는 서비스나 팀 내부의 도구는 claude mcp add 명령으로 직접 등록합니다.
원격 서버는 HTTP 주소만 있으면 되고, 내 컴퓨터에서 실행하는 로컬 서버는 실행 명령을 함께 지정합니다.

1
claude mcp add --transport http notion https://mcp.notion.com/mcp

1
2
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

로그인이 필요한 원격 서버는 등록한 뒤 /mcp에서 해당 서버를 선택하거나 claude mcp login 서버이름 명령으로 브라우저 인증을 진행합니다.
연결에 실패했거나 인증이 필요한 서버가 여러 개라면 세션 안에서 /mcp reconnect all을 실행해 한 번에 다시 연결할 수 있습니다.
등록한 서버는 다음 명령으로 확인하고 관리합니다.

1
2
3
4
5
6
7
8
9
10
11
# 서버 목록
claude mcp list

# 서버 상세 정보
claude mcp get notion

# 서버 제거
claude mcp remove notion

# Claude Desktop에서 MCP 서버 가져오기
claude mcp add-from-claude-desktop

서버를 등록할 때는 어디까지 공유할지 범위를 정할 수 있습니다.

1
2
3
4
5
# 프로젝트 범위 서버 추가 (팀 공유용)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 사용자 범위 서버 추가 (개인용, 모든 프로젝트)
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

프로젝트 범위로 공유하는 .mcp.json 파일에서는 ${VAR} 구문으로 환경 변수를 참조할 수 있어서, API 키 같은 값을 파일에 직접 작성하지 않고 팀원마다 다르게 관리할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

# 브라우저 제어

Claude in Chrome은 Chrome 확장 프로그램으로 Claude Code와 브라우저를 연결하는 기능입니다.
연결하면 Claude가 새 탭을 열어서 페이지를 이동하고, 버튼을 클릭하고, 폼을 채우고, 스크린샷을 찍고, 콘솔 로그와 네트워크 요청을 확인합니다.
브라우저의 로그인 상태를 그대로 공유하므로, 이미 로그인한 서비스라면 별도의 API 연동 없이 바로 작업할 수 있습니다.
로그인 페이지나 CAPTCHA를 만나면 멈추고 사용자에게 직접 처리해 달라고 요청합니다.

사용하려면 다음 조건이 필요합니다.

• Google Chrome, Microsoft Edge 또는 Brave, Arc, Vivaldi, Opera 같은 Chromium 계열 브라우저 (WSL은 지원하지 않음)
• Chrome 웹 스토어의 Claude in Chrome 확장 프로그램 1.0.36 이상
• Pro, Max, Team, Enterprise 플랜과 /login으로 연결한 구독 계정 (API 키나 claude setup-token으로 발급한 토큰으로는 동작하지 않음)

처음 구성하는 순서는 다음과 같습니다.

1. 브라우저에서 claude.ai/chrome에 접속해서 확장 프로그램을 설치하고, 확장 프로그램에서 Claude 계정으로 로그인합니다.
2. 터미널에서 claude --chrome으로 Claude Code를 시작합니다. 처음 한 번은 다음과 같은 안내 화면이 표시되며, Enter를 누르면 확장 프로그램과 연결합니다.
3. 브라우저 작업을 요청합니다. 브라우저 동작마다 Claude in Chrome wants to로 시작하는 승인 요청이 표시되고, 해당 사이트의 모든 동작을 이 세션 동안 허용하는 선택지도 함께 제공됩니다.

1
claude --chrome

claude --chrome 첫 실행 안내

1
2
localhost:3000을 열어서 로그인 폼에 잘못된 값을 넣고 에러 메시지가 제대로 표시되는지 확인해 줘
대시보드 페이지를 열고 로드될 때 콘솔에 에러가 있는지 확인해 줘

연결 상태는 /chrome 명령으로 확인하고 관리합니다.
Status: Enabled와 Extension: Installed가 표시되면 정상이고, 확장 프로그램이 감지되지 않으면 다음과 같이 설치 항목이 먼저 표시됩니다.

/chrome 화면

Enabled by default를 켜면 매번 플래그를 붙이지 않아도 되지만, 브라우저 도구 설명이 모든 세션의 컨텍스트에 실립니다.
브라우저 작업이 가끔만 필요하다면 그때만 --chrome으로 시작하는 것이 컨텍스트를 아낍니다.
Claude Code를 시작할 때 설치된 확장 프로그램이 감지되면 브라우저 도구를 켤지 한 번 물어보고, 브라우저가 필요한 작업인데 확장 프로그램이 없으면 Claude wants to use your browser 설치 안내가 표시됩니다.

어느 사이트에서 무엇을 할 수 있는지는 Claude Code가 아니라 확장 프로그램의 사이트별 권한 설정을 그대로 따릅니다.
Plan 모드에서는 페이지를 읽거나 스크린샷을 찍는 읽기 전용 호출만 승인 없이 실행되고, 클릭, 입력, 페이지 이동처럼 상태를 바꾸는 호출은 승인을 요청합니다.
사용할 수 있는 브라우저 도구의 전체 목록은 /mcp에서 claude-in-chrome을 선택하고 View tools로 확인합니다.

Playwright나 Chrome DevTools MCP 플러그인도 브라우저를 조작하지만, 별도의 브라우저 인스턴스를 띄우므로 로그인 상태를 공유하지 않습니다.
이미 로그인한 서비스를 다루거나 사용자가 보고 있는 화면을 그대로 확인해야 한다면 Claude in Chrome을, 헤드리스 테스트나 성능 측정처럼 격리된 환경이 필요하다면 플러그인을 사용합니다.

# 컴퓨터 제어

컴퓨터 제어(Computer Use)는 Claude가 화면을 보면서 마우스와 키보드로 macOS 앱을 직접 조작하는 기능입니다.
방금 작성한 Swift 앱을 빌드해서 실행하고 버튼을 하나씩 눌러 보거나, iOS 시뮬레이터에서 온보딩 화면을 넘겨 보거나, CLI나 API가 없는 GUI 도구를 다루는 것처럼 터미널 밖에서 손으로 해야 했던 작업을 같은 대화 안에서 맡길 수 있습니다.

Claude는 가장 정확한 도구부터 순서대로 시도하므로, 컴퓨터 제어는 다른 방법이 없을 때만 사용됩니다.

1. 해당 서비스의 MCP 서버가 있으면 MCP를 사용합니다.
2. 셸 명령으로 처리할 수 있으면 Bash 도구를 사용합니다.
3. 브라우저 작업이고 Claude in Chrome이 구성되어 있으면 브라우저 제어를 사용합니다.
4. 그 외의 네이티브 앱, 시뮬레이터, API가 없는 도구는 컴퓨터 제어를 사용합니다.

컴퓨터 제어는 computer-use라는 이름의 내장 MCP 서버로 제공되며 기본으로 꺼져 있습니다.
/mcp를 실행하면 목록 하단의 Built-in MCPs 항목에서 확인할 수 있습니다.

/mcp 화면의 내장 MCP 서버

computer-use를 선택하고 Enable을 고르면 활성화됩니다.
이 설정은 프로젝트마다 저장되므로, 컴퓨터 제어를 사용할 프로젝트에서 한 번씩만 켜면 됩니다.
조건을 만족하는 환경이 아니면 이 항목 자체가 표시되지 않습니다.

computer-use 서버 활성화

Claude가 처음 화면을 사용하려고 하면 macOS 권한 두 가지를 요청하는 프롬프트가 터미널에 표시됩니다.
손쉬운 사용(Accessibility)은 클릭, 입력, 스크롤에 필요하고, 화면 기록(Screen Recording)은 화면을 보는 데 필요합니다.
프롬프트의 항목을 선택하면 시스템 설정의 해당 화면이 열리며, 둘 다 허용한 뒤 Try again을 선택합니다.
화면 기록 권한은 허용한 뒤에 Claude Code를 다시 시작해야 반영되는 경우가 있습니다.

권한을 허용해도 Claude가 모든 앱을 마음대로 다룰 수 있는 것은 아닙니다.
세션에서 특정 앱이 처음 필요할 때마다 다음과 같은 승인 프롬프트가 표시되고, 어떤 앱을 제어하려는지, 클립보드 같은 추가 권한을 요청하는지, 작업 중에 몇 개의 다른 앱이 숨겨지는지 확인한 뒤 Allow for this session이나 Deny를 선택합니다.
승인은 현재 세션 동안만 유지됩니다.

앱 제어 승인 요청

터미널, IDE, Finder, 시스템 설정처럼 영향 범위가 넓은 앱에는 경고가 함께 표시됩니다.
차단되는 것은 아니지만, 작업에 그 정도의 접근 권한이 필요한지 판단하고 승인합니다.

앱의 종류에 따라 제어 수준도 달라집니다.
브라우저와 트레이딩 플랫폼은 보기 전용이고, 터미널과 IDE는 클릭만 가능하며, 나머지 앱은 전체 제어가 가능합니다.
브라우저를 조작하려면 컴퓨터 제어가 아니라 브라우저 제어를 사용해야 합니다.

승인이 끝나면 다음과 같이 요청합니다.

1
2
앱 타겟을 빌드하고 실행한 다음, 탭을 하나씩 눌러서 크래시가 없는지 확인해 줘. 에러 화면이 있으면 스크린샷을 찍어 줘
설정 모달이 좁은 창에서 푸터가 잘려. 창을 줄여서 재현하고 스크린샷을 찍은 다음 모달 컨테이너의 CSS를 확인해 줘

작업 중에는 다음과 같이 동작합니다.

• 한 번에 하나의 세션만 컴퓨터를 제어할 수 있습니다. 첫 동작에서 잠금을 잡고 세션이 종료될 때 풀리므로, 다른 세션에서 사용하려면 먼저 그 세션을 종료합니다.
• Claude가 화면을 제어하는 동안 승인하지 않은 앱은 숨겨지고, 작업이 끝나면 자동으로 복원됩니다. 터미널 창은 계속 보이지만 스크린샷에서는 제외되므로 Claude가 자신의 출력을 보지 않습니다.
• 스크린샷은 자동으로 축소해서 모델에 전달하므로 디스플레이 해상도를 낮출 필요가 없습니다. 글자가 너무 작아서 읽지 못하면 앱 안에서 글자 크기를 키웁니다.
• 제어가 시작되면 Claude is using your computer 알림이 표시되고, 어디에서든 Esc를 누르거나 터미널에서 Ctrl + C를 누르면 즉시 중단됩니다.

같은 엔진을 사용하는 데스크톱 앱과는 몇 가지 차이가 있습니다.

# Hooks

Hooks는 Claude Code의 생명주기 특정 시점에 자동으로 실행되는 사용자 정의 셸 명령 또는 LLM 프롬프트입니다.
Git의 pre-commit, post-commit 훅과 유사한 개념으로, Claude가 특정 작업을 수행하기 전후에 자동으로 스크립트를 실행할 수 있습니다.
이를 통해 위험한 명령 차단, 코드 스타일 검사, 로깅, 알림 등 다양한 자동화를 구현할 수 있습니다.

세션이 시작되고, 프롬프트를 제출하고, 도구를 실행하고, 응답이 끝나는 흐름의 각 지점에 Hook을 끼워 넣는다고 생각하면 됩니다.
특히 도구 실행 전에 동작하는 PreToolUse는 실행 자체를 막을 수 있어서 위험한 명령을 차단하는 데 사용합니다.

세션 흐름과 Hook이 끼어드는 시점

이벤트는 세션의 흐름에 따라 다음과 같이 나뉩니다.

/hooks 명령을 실행하면 등록된 Hook이 이벤트별로 묶여서 어디에 정의됐는지와 함께 표시되고, 목록 끝의 All events를 선택하면 Hook이 없는 이벤트까지 전체 목록을 확인할 수 있습니다.
이 화면은 읽기 전용이므로, Hook을 추가하거나 수정하려면 설정 파일을 직접 편집하거나 Claude에게 요청합니다.

/hooks 화면

Hooks는 여러 유형의 핸들러를 지원합니다.

Hook 설정은 사용자 설정(~/.claude/settings.json), 프로젝트 설정(.claude/settings.json), 로컬 설정(.claude/settings.local.json) 중 하나에 저장됩니다.
다음은 Bash 명령 실행 전에 검증 스크립트를 실행하는 구성입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-command.sh"
          }
        ]
      }
    ]
  }
}

# Stop Hook으로 완료 알림 받기

오래 걸리는 작업을 지시해 두고 다른 일을 하다 보면, 응답이 끝난 줄 모르고 지나치기 쉽습니다.
응답이 완료되는 Stop 시점에 동작하는 Hook을 등록하면 작업 완료를 놓치지 않습니다.
Stop은 특정 도구에 반응하는 이벤트가 아니라 응답이 끝나는 시점에 동작하므로, matcher는 지정하지 않아도 됩니다.

먼저 응답이 완료되면 시스템 사운드를 재생해 보겠습니다.

1. 프로젝트 설정(.claude/settings.json)을 열고 Stop Hook에 사운드 재생 명령을 등록합니다.
2. macOS는 afplay, Windows는 powershell 명령으로 시스템 사운드를 재생하도록 작성합니다.
3. Claude Code를 실행하고 /hooks 명령으로 Stop Hook이 등록됐는지 확인합니다.
4. 가벼운 작업을 지시하고 응답이 완료되는 시점에 사운드가 재생되는지 확인합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -WindowStyle Hidden -c \"(New-Object Media.SoundPlayer 'C:/Windows/Media/Windows Notify System Generic.wav').PlaySync()\""
          }
        ]
      }
    ]
  }
}

이번에는 응답이 완료되면 Slack 채널로 완료 메시지를 보내 보겠습니다.
자리를 비운 동안에도 작업이 끝났다는 알림을 받을 수 있습니다.

1. Slack 워크스페이스에서 Incoming Webhook을 발급받고 URL을 복사합니다.
2. .claude/hooks/notify-slack.mjs 파일을 작성합니다.
3. 프로젝트 설정(.claude/settings.json)의 Stop Hook에 node 명령으로 이 파일을 실행하도록 등록합니다.
4. Claude Code를 실행하고 /hooks 명령으로 Stop Hook이 등록됐는지 확인합니다.
5. 가벼운 작업을 지시하고 응답이 완료되는 시점에 완료 메시지가 수신되는지 확인합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import { readFileSync } from 'node:fs'
import https from 'node:https'

// 훅 입력(JSON)을 읽기
let input = ''
try { input = readFileSync(0, 'utf8') }
catch {}

let data = {}
try { data = JSON.parse(input) }
catch {}

const msg = (data.last_assistant_message || '(응답 텍스트 없음)').slice(0, 3000)
const payload = JSON.stringify({
  text: `✅ Claude Code 작업 완료\n\n${msg}`
})

// https 모듈로 전송
const req = https.request(
  'https://hooks.slack.com/services/<YOUR_WEBHOOK>',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Content-Length': Buffer.byteLength(payload)
    },
    agent: false
  },
  (res) => {
    res.resume() // 응답 본문을 소비해 소켓이 닫히도록
  }
)

req.on('error', () => {}) // 알림 실패가 작업을 막지 않도록 무시
req.end(payload)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/notify-slack.mjs"
          }
        ]
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node C:/Users/사용자이름/.claude/hooks/notify-slack.mjs"
          }
        ]
      }
    ]
  }
}

Windows에서는 ~가 확장되지 않을 수 있으므로 node C:/Users/사용자이름/.claude/hooks/notify-slack.mjs처럼 절대 경로로 지정합니다.

# Skills

Skills는 Claude의 기능을 확장하는 모듈식 기능입니다.
각 스킬은 Claude가 관련 작업 시 자동으로 사용하는 지침, 메타데이터, 선택적 리소스(스크립트, 템플릿)를 패키징합니다.
반복적으로 수행하는 복잡한 작업(예: 특정 형식의 문서 생성, 팀의 코드 리뷰 프로세스, 배포 절차 등)을 스킬로 정의하면, 매번 상세한 지침을 입력할 필요 없이 일관된 결과를 얻을 수 있습니다.

Skills는 Model-invoked 방식으로 작동합니다.
즉, 사용자가 명시적으로 호출하지 않아도 Claude가 문맥에 맞는 스킬을 자동으로 발견하고 활용합니다.
또한 사용자가 /스킬명으로 직접 호출할 수도 있어, 자동 발견과 명시적 호출을 모두 지원합니다.
현재 세션에서 사용할 수 있는 스킬 목록은 /skills 명령으로 확인합니다.
직접 작성하지 않고 공개된 스킬을 설치하거나 Claude에게 스킬 작성을 맡기는 방법은 스킬 설치와 생성에서 설명합니다.

1
2
3
4
5
이 PDF에서 표를 추출해 줘
# → pdf-processing 스킬이 자동으로 활성화

/my-skill 인수
# → 명시적으로 스킬 호출

스킬을 사용하면 다음과 같은 이점이 있습니다.

• Claude 전문화: 도메인별 작업에 맞게 기능 맞춤화
• 반복 감소: 한 번 생성하면 자동으로 사용
• 기능 조합: 스킬을 조합하여 복잡한 워크플로우 구축

# 스킬 구조

1
2
3
4
5
your-skill-name/
├── SKILL.md          # 필수: 메타데이터와 지침
├── scripts/          # 선택: 유틸리티 스크립트
├── references/       # 선택: 참조 문서
└── assets/           # 선택: 이미지 등 리소스

스킬 폴더는 다음 위치에 저장합니다.

Claude 계정에서 켠 스킬은 Claude Code가 자동으로 내려받으며, Claude 계정 스킬 동기화에서 설명합니다.
다른 AI 에이전트와 같은 스킬을 함께 사용하려면 원본을 .agents/skills/에 두고 링크하는 방법이 있으며, 다른 에이전트와 스킬 공유에서 설명합니다.

명명 규칙은 다음과 같습니다.

• SKILL.md 파일명: 정확히 SKILL.md여야 함 (대소문자 구분, skill.md 불가)
• 스킬 폴더명: kebab-case만 사용 (notion-project-setup ✅, Notion_Setup ❌)
• README.md 금지: 스킬 폴더 내에 README.md를 포함하지 마세요
• synced 금지: 동기화용으로 예약된 이름이라 대소문자와 상관없이 synced 폴더는 오류 없이 건너뜀

# SKILL.md 작성

SKILL.md는 YAML frontmatter와 Markdown 본문으로 구성됩니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
name: my-skill
description: 무엇을 하는지. 언제 사용하는지.
---

# 스킬 이름

## 지침

1. 첫 번째 단계
2. 두 번째 단계

## 예시

사용자: "스킬 사용해 줘"
동작:
1. ...
2. ...

frontmatter의 주요 필드는 다음과 같습니다.

자동 호출을 끄고 /스킬명으로만 사용하려면 disable-model-invocation: true를 설정합니다.
반대로 슬래시 명령에 노출하지 않고 자동 호출만 허용하려면 user-invocable: false를 설정합니다.

description은 Claude가 스킬을 자동으로 선택하는 데 사용됩니다.
스킬의 자동 발견(auto-discovery)이 정확하게 작동하려면 description을 잘 작성해야 합니다.
항상 3인칭으로 작성하고, 무엇을 하는지와 언제 사용하는지를 모두 포함하세요.

한국어로 작성해도 되지만, 사용자가 영어로 말할 법한 핵심 키워드를 함께 넣으면 매칭 정확도가 높아집니다.

1
2
3
4
5
6
7
# 좋은 예시
description: |
  PDF 파일에서 텍스트와 표를 추출하고, 양식을 채우고, 문서를 병합합니다.
  PDF 파일을 다루거나 사용자가 PDF를 언급할 때 사용하세요. PDF, extract, merge.

# 나쁜 예시
description: 문서 작업을 도와줍니다  # 너무 일반적

description에 포함하면 좋은 요소:

• 무엇을 하는지: "PDF에서 텍스트 및 표 추출"
• 언제 사용하는지: "PDF 파일, 양식, 문서 추출 시"
• 트리거 키워드: "PDF", "텍스트 추출", "문서"

사용 시점 설명이 길어지면 when_to_use 필드로 분리해 보조할 수 있습니다.

allowed-tools 필드로 스킬이 사용할 수 있는 도구를 제한하여 안전성을 높일 수 있습니다.
예를 들어, 코드 리뷰 스킬은 파일을 읽기만 하고 수정하지 않도록 제한할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
---
name: safe-code-reviewer
description: |
  코드를 변경하지 않고 모범 사례 관점에서 검토합니다.
  코드 리뷰를 요청하거나 변경 없는 분석이 필요할 때 사용하세요. code review, read-only.
allowed-tools: Read, Grep, Glob
---

# 안전한 코드 리뷰어

이 스킬은 파일을 읽기만 하고 수정하지 않습니다.
변경 없이 분석과 개선 제안만 제공합니다.

allowed-tools를 지정하면 해당 스킬이 활성화됐을 때 목록의 도구를 승인 없이 바로 사용할 수 있습니다.
다른 도구의 사용을 막는 것은 아니며, 사용을 제한하려면 disallowed-tools나 권한 설정의 deny 규칙을 사용합니다.

# 점진적 로딩

스킬은 3단계로 로딩되어 컨텍스트를 효율적으로 사용합니다.
세션이 시작될 때는 설치된 모든 스킬의 이름과 설명만 실리고, 본문은 그 스킬이 호출될 때, 참조 파일은 본문에서 필요하다고 판단할 때 읽습니다.

스킬이 단계적으로 로드되는 구조

이 구조 덕분에 많은 스킬을 설치해도 실제로 사용되는 스킬만 컨텍스트를 소비합니다.

참조 파일은 SKILL.md 본문에 경로와 함께 언제 읽을지를 작성합니다.
Claude는 작업에 필요한 파일만 골라서 읽습니다.

1
2
- 색상 코드가 필요하면 `references/colors.md`를 읽습니다.
- 서체 정보가 필요하면 `references/fonts.md`를 읽습니다.

# 작성 팁

보안 고려사항:

• 신뢰할 수 있는 소스의 스킬만 사용
• 설치 전 SKILL.md와 스크립트 내용 검토
• 도구 제한이 필요하면 disallowed-tools나 권한 deny 규칙 사용 (allowed-tools는 제한이 아니라 사전 승인 목록)

모범 사례:

• SKILL.md 본문은 500줄 미만으로 유지, 상세 내용은 references/ 폴더로 분리
• 폴더명은 동명사 형태 권장 (processing-pdfs ✅, helper ❌)
• 복잡한 작업은 체크리스트 형태로 정의

# Claude 계정 스킬 동기화

Claude 앱의 채팅과 Cowork는 Claude 계정에 저장한 스킬을 함께 사용합니다.
Claude Code도 같은 계정으로 로그인하면(2.1.273 이상) 계정에서 켠 스킬을 ~/.claude/skills/synced/에 자동으로 내려받습니다.
직접 만들거나 켠 스킬뿐 아니라 조직에서 배포한 스킬과 pdf, xlsx 같은 Anthropic의 내장 스킬도 함께 내려받습니다.

동기화는 세션을 시작할 때 백그라운드에서 진행되고, 세션 중에는 작업하는 동안 약 10분, 세션을 사용하지 않는 동안 약 40분마다 변경 사항을 확인합니다.
claude.ai에서 스킬을 추가, 수정하거나 끄면 Claude Code를 다시 시작하지 않아도 반영됩니다.
/skills 목록에서는 claude.ai sync 항목 아래에 표시되며, API 키나 Amazon Bedrock 같은 서드파티 플랫폼으로 연결한 세션에서는 동기화하지 않습니다.

동기화한 스킬은 /anthropic-skills:스킬명으로 호출하고, 같은 이름의 다른 스킬이나 명령이 없으면 /스킬명으로도 호출할 수 있습니다.
예를 들어 ~/.claude/skills/에도 frontend-design 스킬이 있으면, /frontend-design은 로컬 스킬을 실행하고 /anthropic-skills:frontend-design은 계정 스킬을 실행합니다.

동기화는 계정에서 내려받기만 하는 한 방향입니다.
Claude Code에서 만든 스킬은 계정으로 올라가지 않고, ~/.claude/skills/synced/의 파일을 수정해도 계정에 저장되지 않으며 다음 동기화 때 덮어써집니다.
이 폴더에 직접 만든 스킬 폴더를 넣어도 스킬로 인식되지 않고, 다음 동기화 때 ~/.claude/skills/.trash/로 옮겨집니다.
계정 스킬을 바꾸려면 claude.ai의 사용자 지정(Customize) > 스킬에서 수정하거나 끄고, 로컬 스킬을 채팅이나 Cowork에서도 사용하려면 스킬 폴더를 ZIP 파일로 압축해서 계정에 업로드합니다.
업로드하는 스킬의 프론트매터 조건은 Claude Cowork 핵심 정리에서 설명합니다.

동기화를 끄려면 사용자 설정(~/.claude/settings.json)에서 syncClaudeAiSkills를 false로 지정합니다.
이미 내려받은 스킬은 다음 실행 때 ~/.claude/skills/.trash/로 옮겨지고 더 이상 로드되지 않습니다.
.claude/settings.local.json에 지정하면 그 프로젝트에서만 꺼지며, 팀과 공유하는 프로젝트 설정(.claude/settings.json)에 지정한 false는 무시됩니다.

1
2
3
{
  "syncClaudeAiSkills": false
}

스킬을 공유할 때는 사용하는 환경의 공유 범위와 런타임 제약도 함께 고려하세요.
Claude API에 업로드한 스킬은 Claude 계정의 스킬과 별개로 관리됩니다.

# 다른 에이전트와 스킬 공유

Anthropic이 개발한 Agent Skills는 AI 에이전트의 기능을 확장하는 오픈 표준입니다.
SKILL.md 형식이 같으므로, Claude Code에서 만든 스킬을 OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, xAI의 Grok Build 등에서도 사용할 수 있습니다.

문제는 도구마다 스킬을 읽는 폴더가 다르다는 점입니다.
대부분의 도구가 공통으로 읽는 위치는 프로젝트의 .agents/skills/와 개인의 ~/.agents/skills/입니다.
그런데 Claude Code는 .claude/skills/와 ~/.claude/skills/만 읽고 .agents/skills/는 읽지 않습니다.

그래서 스킬을 여러 도구에서 함께 사용하려면, 원본은 .agents/skills/에 두고 Claude Code에는 심볼릭 링크만 추가하는 구성을 권장합니다.
Claude Code는 .claude/skills/ 안의 항목이 다른 폴더를 가리키는 심볼릭 링크여도 링크를 따라가서 SKILL.md를 읽습니다.
파일은 한 곳에만 있으므로 수정도 한 번이면 됩니다.

.agents/skills 원본과 심볼릭 링크로 스킬을 공유하는 구조

심볼릭 링크는 ln -s 명령으로 직접 만들 수 있지만, macOS와 리눅스에서만 동작하고 스킬마다 링크 위치 기준의 상대 경로를 맞춰야 합니다.
@heropy/symlink를 사용하면 운영체제와 상관없이 두 폴더의 스킬을 한 번에 연결할 수 있습니다.
설치 없이 npx로 실행할 수 있고, Node.js 20.19 이상이 필요합니다.
라이브러리의 추가 설명은 하나의 스킬을 여러 AI 에이전트에 동기화하기를 확인해 보세요.

프로젝트 스킬은 다음과 같이 구성합니다.

1
2
3
4
5
6
7
# .agents/skills/commit-helper/SKILL.md 작성 후

npx @heropy/symlink .agents/skills .claude/skills
## mkdir  .claude/skills
## link   .claude/skills/commit-helper -> ../../.agents/skills/commit-helper
##
## 1 linked

.agents/skills/의 스킬마다 .claude/skills/에 링크가 생성되고, 없는 .claude/skills/ 폴더도 함께 생성됩니다.
macOS와 리눅스에서는 링크가 상대 경로로 생성되므로, 커밋한 저장소를 다른 위치에 복제해도 링크가 깨지지 않습니다.
스킬을 추가했다면 같은 명령을 다시 실행합니다.
이미 연결된 스킬은 그대로 유지되고 새 스킬만 연결됩니다.

User Scope 스킬도 같은 방식으로 macOS에서는 ~/.agents/skills/에 두고 ~/.claude/skills/에 연결합니다.
Windows PowerShell에서는 ~ 대신 사용자 홈 경로가 저장된 $HOME 변수를 사용합니다.

1
2
3
4
5
# macOS
npx @heropy/symlink ~/.agents/skills ~/.claude/skills

# Windows PowerShell
npx @heropy/symlink $HOME\.agents\skills $HOME\.claude\skills

.claude/skills/ 폴더를 세션 도중에 새로 만들었다면 Claude Code를 다시 시작해야 인식합니다.
/skills에서 링크한 스킬이 project나 user 범위로 표시되면 정상입니다.

심볼릭 링크로 연결한 스킬이 /skills에 표시된 화면

다른 도구에서도 문제없이 읽히려면 SKILL.md의 frontmatter는 표준에 정의된 name, description, license, compatibility, metadata, allowed-tools 여섯 필드만 사용합니다.
disable-model-invocation, context, paths처럼 Claude Code에서만 동작하는 필드는 다른 도구에서 무시되거나, claude.ai에 업로드할 때 오류가 발생합니다.
셸 스크립트는 POSIX 호환으로 작성하고, 지침도 특정 도구의 기능을 전제하지 않는 범용적인 마크다운으로 작성합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
---
name: commit-helper
description: Git 변경사항을 분석하여 Conventional Commits 형식으로 메시지 생성
---

## 역할
Git 커밋 메시지 작성 전문가

## type 종류
- feat: 새로운 기능
- fix: 버그 수정
- docs: 문서 변경
- refactor: 코드 리팩토링

# 스킬 설치와 생성

필요한 스킬을 모두 직접 작성할 필요는 없습니다.
다른 사람이 공개한 스킬을 찾아서 설치하거나, 스킬을 만드는 스킬을 사용해서 Claude에게 작성을 맡길 수 있습니다.

skills.sh는 Vercel이 운영하는 공개 스킬 목록 사이트입니다.
GitHub 저장소에 공개된 스킬을 설치 수 순위로 보여 주며, 순위는 skills CLI로 설치할 때 수집되는 익명 통계로 집계합니다.
스킬 페이지에서는 설치 명령과 SKILL.md 내용, 원본 저장소, 보안 검사 결과를 확인할 수 있습니다.

skills.sh의 스킬 순위 화면

skills.sh의 스킬은 skills CLI로 설치합니다.
owner/repo 형식으로 GitHub 저장소를 지정하고, 저장소에 스킬이 여러 개 있으면 --skill 옵션으로 설치할 스킬을 지정합니다.
옵션으로 지정하지 않은 스킬과 에이전트는 실행 중에 선택합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
# 현재 프로젝트에 설치
npx skills add vercel-labs/skills --skill find-skills

# 모든 프로젝트에서 사용하도록 개인 범위에 설치
npx skills add vercel-labs/skills --skill find-skills -g

# 저장소에 포함된 스킬 목록만 확인
npx skills add anthropics/skills --list

# 설치한 스킬 확인, 업데이트, 제거
npx skills list
npx skills update
npx skills remove find-skills

설치 위치는 선택한 에이전트에 따라 달라집니다.
Claude Code만 선택하면 .claude/skills/에 스킬이 바로 복사되고, 다른 에이전트와 함께 선택하면 원본을 .agents/skills/에 설치한 뒤 .claude/skills/에 심볼릭 링크를 생성합니다.
다른 에이전트와 스킬 공유에서 설명한 구성을 자동으로 만드는 것이며, -g 옵션을 사용하면 같은 구성이 ~/.agents/skills/와 ~/.claude/skills/에 만들어집니다.
프로젝트에 설치하면 설치한 스킬의 출처가 skills-lock.json 파일에 기록됩니다.

skills.sh에서 설치 수가 가장 많은 find-skills는 필요한 스킬을 찾아 주는 스킬입니다.
설치한 뒤 특정 작업에 사용할 만한 스킬이 있는지 물어보면, Claude가 이 스킬을 호출해서 npx skills find 명령으로 관련 스킬을 검색할 수 있습니다.
스킬의 지침은 skills.sh 순위를 먼저 확인하고, 검색 결과의 설치 수와 저장소 출처를 확인해서 추천한 뒤, 사용자가 원하면 설치 명령까지 실행하도록 구성되어 있습니다.

1
프론트엔드 화면을 디자인할 때 사용할 만한 스킬이 있는지 찾아 줘.

지침에 포함된 설치 명령은 개인 범위(-g)에 확인 절차 없이(-y) 설치하는 형태입니다.
현재 프로젝트에만 설치하려면 설치를 요청할 때 설치 범위를 함께 알려 줍니다.
스킬 없이 터미널에서 직접 검색할 수도 있습니다.

1
2
3
4
5
npx skills find frontend design
## anthropics/skills@frontend-design 882.1K installs
## leonxlnx/taste-skill@design-taste-frontend 473.8K installs
## pbakaus/impeccable@frontend-design 54.5K installs
## smithery.ai@frontend-design 6.2K installs

skill-creator는 Anthropic이 공개한 스킬로, 새 스킬을 만들고 기존 스킬을 개선하는 과정을 돕습니다.
만들고 싶은 스킬을 설명하면 Claude가 용도, 호출 시점, 출력 형식을 질문하고 SKILL.md 초안을 작성합니다.
방금 대화에서 진행한 작업을 스킬로 만들어 달라고 요청하면, 대화에서 사용한 도구와 작업 순서, 사용자가 수정한 내용을 바탕으로 초안을 작성합니다.

Claude Code에서는 공식 마켓플레이스의 플러그인으로 설치할 수 있습니다.

1
/plugin install skill-creator@claude-plugins-official

다른 에이전트에서도 함께 사용하려면 npx skills add anthropics/skills --skill skill-creator 명령으로 설치합니다.
플러그인으로 설치하면 /skill-creator:skill-creator, skills CLI로 설치하면 /skill-creator로 직접 호출하며, 스킬을 만들어 달라는 요청에서 자동으로 호출되기도 합니다.

1
skill-creator로 Git 변경 사항을 분석해서 Conventional Commits 형식의 커밋 메시지를 작성하는 스킬을 만들어 줘.

초안을 작성한 뒤에는 평가를 이어서 진행할 수 있습니다.
테스트 프롬프트를 스킬을 사용할 때와 사용하지 않을 때로 나누어 서브에이전트에서 실행하고, 통과율, 소요 시간, 토큰 사용량을 비교한 결과를 브라우저 화면으로 보여 줍니다.
테스트 케이스는 스킬 폴더의 evals/evals.json에 저장되며, 스킬이 필요한 요청에서 자동으로 호출되도록 description을 반복해서 다듬는 기능도 포함되어 있습니다.

1
skill-creator로 commit-helper 스킬을 평가해 줘.

# Agents

Claude Code가 한 번에 여러 작업을 처리하는 방식은 네 가지입니다.
넷을 가르는 기준은 누가 작업을 조율하느냐입니다.
Claude가 한 대화 안에서 곁가지 작업을 떼어 맡기고 결과를 모으면 Sub Agents, 그 조율을 Claude의 턴 단위 판단이 아니라 스크립트가 맡으면 Dynamic Workflows입니다.
Claude가 계획을 세우고 여러 세션에 일을 나눠 준 뒤 진행을 감독하면 Agent Teams, 사용자가 독립적인 작업을 넘겨 두고 나중에 상태를 확인하면 Agent View입니다.

여러 작업을 처리하는 네 가지 방식

# Sub Agents

Sub Agents는 특정 작업을 위한 전문화된 독립 AI 어시스턴트입니다.
메인 Claude 세션과 분리된 환경에서 실행되기 때문에, 복잡한 작업을 수행할 때 메인 컨텍스트가 불필요한 정보로 오염되는 것을 방지합니다.
예를 들어, 대규모 코드베이스를 탐색하거나 반복적인 테스트를 실행할 때, Sub Agent가 독립적으로 작업을 수행하고 핵심 결과만 메인 세션에 전달합니다.

서브에이전트는 메인 대화와 별개인 자기만의 컨텍스트 윈도우에서 작업합니다.
시작할 때 포함되는 것은 에이전트의 시스템 프롬프트, Claude가 작성한 작업 지시, CLAUDE.md(내장 Explore와 Plan은 제외)이며, 지금까지의 대화 기록이나 메인 대화에서 읽은 파일과 사용한 스킬은 포함되지 않습니다.
작업 중에 읽은 파일과 명령의 출력은 서브에이전트의 컨텍스트에만 쌓이고, 메인 대화에는 마지막 보고만 전달됩니다.

메인 대화와 서브에이전트의 컨텍스트

대화 기록까지 알아야 하는 곁가지 작업이라면 /subtask 작업 내용으로 지금까지의 대화를 이어받는 서브에이전트를 시작할 수 있으며, 이때도 메인 대화에는 마지막 결과만 전달됩니다.

메인 컨텍스트에 남지 않을 뿐 토큰을 사용하지 않는 것은 아닙니다.
메인 대화에서 이미 읽은 파일이라도 필요하면 다시 읽어야 하므로 작은 작업은 메인 대화에서 직접 처리하는 것이 효율적입니다.

주요 장점은 다음과 같습니다.

• Context 오염 방지: 독립 세션에서 실행되어 메인 대화에 영향 없음
• 반복 작업 위임: 코드 리뷰, 테스트 생성처럼 반복되는 작업을 맡김
• 병렬 처리: 여러 작업을 동시에 처리

내장 에이전트는 다음과 같습니다.

필요한 작업자를 직접 정의하는 방법은 Custom Agents에서 살펴봅니다.

# Dynamic Workflows

Dynamic Workflow는 서브에이전트를 대규모로 오케스트레이션하는 스크립트입니다.
작업을 설명하면 Claude가 그 작업에 맞는 오케스트레이션 스크립트를 직접 작성하고, 런타임이 백그라운드에서 실행합니다.
실행되는 동안에도 세션은 계속 사용할 수 있으며, 진행 상황은 /workflows 명령으로 확인합니다.

핵심은 루프, 분기, 중간 결과를 스크립트가 직접 들고 있다는 점입니다.
각 에이전트의 결과가 Claude의 컨텍스트에 쌓이지 않고 스크립트 변수에 저장되므로, Claude 컨텍스트에는 최종 결과만 들어옵니다.
이 구조 덕분에 한 번의 실행에서 수십~수백 개의 에이전트로 확장할 수 있습니다.

에이전트의 결과를 스크립트 변수에 모으는 구조

• 동시 실행은 min(16, CPU 코어 수 - 2)개로 제한됩니다.
• 한 번의 실행에서 최대 1,000개까지 에이전트를 생성할 수 있습니다.
• 워크플로우 안의 에이전트끼리는 서로 통신하지 않고, 각자 결과를 스크립트에만 보고합니다.
• 실행 구조는 시작 전에 코드로 고정되어, 실행 중에 대화로 방향을 바꿀 수 없습니다.

코드베이스 전체 버그 스윕, 수백 개 파일 마이그레이션, 여러 소스를 교차 검증하는 리서치처럼 규모가 큰 일괄 작업에 적합합니다.

프롬프트에 ultracode 키워드를 넣으면 그 프롬프트 하나만 워크플로우로 처리하며, 세션의 사고 깊이 설정은 건드리지 않습니다.
"워크플로우를 사용해 줘"처럼 자연어로 요청해도 똑같이 처리됩니다.

1
ultracode 모든 API 엔드포인트에서 입력 검증 누락을 찾아 줘

/effort ultracode는 워크플로우 자동 판단을 켜는 세션 설정입니다.
2.1.284 버전부터는 사고 깊이와 별개의 토글이 되어, 사고 깊이를 xhigh로 바꾸지 않고 현재 단계 그대로 켜집니다.
/effort 화면에서는 Tab으로 Ultracode 토글을 바꾸고 Enter로 적용합니다.
이후 모든 작업에서 Claude가 워크플로우를 쓸지 스스로 정하며, 요청 하나가 파악, 수정, 검증 워크플로우 여러 개로 이어지기도 해서 토큰 소비가 큽니다.
일상적인 작업으로 돌아갈 때는 /effort ultracode off로 끕니다.
claude --effort ultracode로 처음부터 켠 채 시작할 수도 있으며, 이때는 사고 깊이도 xhigh로 함께 지정됩니다.
모든 세션을 ultracode가 켜진 상태로 시작하려면 설정 파일에 "ultracode": true를 지정합니다.

/deep-research는 Claude Code에 내장된 워크플로우 스크립트로, 여러 시각으로 웹 검색 진행 및 교차 검증 후 통과한 내용만 인용과 함께 보고서로 정리합니다.
웹 리서치라는 특정 작업에 맞춰져 있습니다.

1
/deep-research 2026년 프론트엔드 상태 관리 라이브러리 동향

실행이 시작되면 /workflows에서 진행 상황을 확인하고 제어합니다.
실행 중인 워크플로우와 완료된 워크플로우를 모두 보여주며, 단계별 진행률과 에이전트별 상태를 확인할 수 있습니다.
상태는 Queued, Running, Completed, Failed, Skipped, Blocked, Stopped 일곱 가지입니다.

s로 저장하면 Claude가 작성한 스크립트를 이름과 범위를 정해 파일로 남깁니다.
프로젝트 범위는 .claude/workflows/이름.js, 사용자 범위는 ~/.claude/workflows/이름.js에 저장되며, 이후 세션에서 /이름 명령으로 바로 실행합니다.
자주 쓰는 작업을 /deep-research처럼 자신만의 워크플로우 명령으로 만들어 두는 방법입니다.

한 번에 몇 개의 에이전트를 만들지는 /config의 "Dynamic workflow size" 항목으로 조절합니다.
기본값 medium은 10개 미만(Pro 플랜의 기본값은 small), small은 5개 미만, large는 50개 미만을 목표로 하며, unrestricted는 Claude가 작업 규모에 맞게 정합니다.
다음과 같이 설정 파일에 지정할 수도 있습니다.

1
2
3
{
  "workflowSizeGuideline": "large"
}

# Agent Teams

Agent Teams는 여러 Claude Code 인스턴스가 하나의 팀으로 협업하는 기능입니다.
하나의 세션이 리드(Lead) 역할로 작업을 조율하고 태스크를 할당하며 결과를 종합합니다.
팀원(Teammate)은 각자 독립된 컨텍스트 윈도우에서 작업하고, 서로 직접 메시지를 주고받을 수 있습니다.

• 리드와 팀원이 공유 태스크 리스트로 작업을 관리합니다.
• 리드가 태스크를 직접 할당할 수도 있고, 팀원이 남은 태스크를 스스로 가져갈(Self-claim) 수도 있습니다.
• 대부분의 작업에는 3~5명 규모의 팀이 권장됩니다.
• 팀원은 기본적으로 같은 터미널 안에서 실행되며, 입력창 아래의 에이전트 패널에서 선택해서 대화합니다. teammateMode 설정을 auto로 지정하면 tmux나 iTerm2의 분할 창에 팀원을 하나씩 띄울 수 있습니다.

서로 다른 가설로 나누어 진행하는 디버깅, 프론트엔드와 백엔드처럼 레이어 간 조율이 필요한 기능 구현, 리서치와 리뷰 작업에 적합합니다.

공유 태스크로 일을 나누고 메시지를 주고받는 팀

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 설정해 활성화합니다.

1
2
3
4
5
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

별도 명령 없이 자연어로 팀 구성을 요청하면 됩니다.

1
팀원 3명을 만들어서 이 버그의 원인을 서로 다른 가설로 조사해 줘

Dynamic Workflows와 비교하면 두 기능 모두 여러 에이전트를 활용하지만, 계획을 누가 들고 있는지가 다릅니다.
Dynamic Workflow는 계획을 코드로 옮긴 것입니다.
스크립트가 루프, 분기, 중간 결과를 직접 들고 있어 Claude의 컨텍스트에는 최종 결과만 남습니다.
반면 Agent Teams는 리드 에이전트가 오케스트레이터로서 턴마다 다음에 무엇을 할지 결정하고, 진행 상황을 공유 태스크 리스트로 관리합니다.

# Agent View

Agent View는 여러 백그라운드 세션을 한 화면에서 시작하고 관리하는 인터페이스입니다.
각 세션이 무엇을 하고 있는지, 어떤 세션이 사용자 입력을 기다리는지 목록으로 보여줍니다.
세션은 터미널과 분리되어 실행되므로, Agent View를 종료해도 백그라운드에서 계속 동작합니다.

Agent View를 닫아도 계속 실행되는 백그라운드 세션

터미널에서 다음 명령으로 실행합니다.

1
claude agents

혹은 기본 세션에서 ← 키를 사용해 백그라운드 세션으로 전환하며, Agent View 인터페이스로 넘어갈 수 있습니다.
백그라운드 세션은 claude --bg "작업 내용"으로 터미널 밖에서 시작할 수도 있고, Agent View의 입력창에 작업을 설명해서 새 세션을 만들 수도 있습니다.

세션마다 상태와 진행 상황 요약이 표시되므로, 확인이 필요한 세션을 쉽게 찾을 수 있습니다.
다음은 두 개의 백그라운드 세션이 각각 셸 명령 승인을 기다리고 있는 화면입니다.

Agent View 화면

주요 단축키는 다음과 같습니다.

# Custom Agents

Sub Agents의 내장 에이전트 외에 필요한 작업자를 직접 정의할 수도 있습니다.
커스텀 에이전트는 .claude/agents/이름.md 파일 하나로 정의합니다.
파일은 Skills의 SKILL.md처럼 YAML frontmatter와 Markdown 본문으로 구성되지만 역할이 다릅니다.
스킬은 지금 진행 중인 대화에 지침을 불러오는 것이고, 에이전트는 자기만의 컨텍스트를 가진 별도의 작업자를 만드는 것입니다.
frontmatter에는 이 작업자가 무엇을 하고, 언제 호출되어야 하고, 어떤 도구를 사용할 수 있는지 작성합니다.
본문은 그 작업자에게 전달되는 시스템 프롬프트가 됩니다.

에이전트가 맡는 일이 코드 리뷰나 테스트 같은 개발 작업이어야 하는 것은 아닙니다.
공지문, 보고서, 기획서 같은 업무 문서를 작성하고 검토하는 과정을 예로 들어 보겠습니다.

먼저 팀의 문서 작성 규칙을 Skills에서 살펴본 방식으로 스킬로 만듭니다.

1
2
3
4
5
6
7
8
9
10
---
name: writing-guide
description: 팀의 업무 문서 작성 규칙입니다. 공지문, 보고서, 기획서 같은 업무 문서를 작성하거나 수정할 때 사용하세요. document, report, writing.
---

- 첫 문단에 결론과 읽는 사람이 해야 할 일을 먼저 작성합니다.
- 문장은 합쇼체(~합니다)로 작성하고, 한 문장에는 하나의 내용만 작성합니다.
- 날짜는 `9월 25일(금)`, 금액은 `1,200만 원` 형식으로 작성합니다.
- 영문 약어는 처음 나올 때 풀어서 작성합니다. 예: 핵심 성과 지표(KPI)
- '빠른 시일 내', '적극 검토' 같은 모호한 표현 대신 날짜와 담당자를 작성합니다.

이 스킬은 에이전트 없이 혼자 사용해도 유용합니다.
메인 대화에서 다음과 같이 요청하면 Claude가 스킬을 불러와서 규칙에 맞춰 초안을 작성하고, 사용자는 같은 대화에서 표현을 고치거나 내용을 추가하면서 문서를 완성합니다.
이렇게 사용자와 주고받으며 문서를 다듬는 작업은 앞선 대화 내용이 필요하므로 메인 대화에서 처리합니다.

1
회의_메모.md를 참고해서 하반기 워크숍 공지문 초안을 작성해 줘

문서가 완성되면 검토가 필요합니다.
그런데 초안을 함께 작성한 메인 대화는 작성 의도와 수정 과정을 모두 알고 있어서, 문서에 빠진 설명도 이미 아는 내용으로 채워서 읽을 수 있습니다.
Sub Agents에서 살펴본 것처럼 서브에이전트는 대화 기록 없이 문서와 작업 지시만 받으므로, 문서를 처음 받아 보는 사람과 같은 조건에서 검토합니다.
그래서 검토는 다음과 같이 별도의 에이전트로 정의합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
---
name: doc-reviewer
description: 보고서, 기획서, 이메일, 공지문 같은 업무 문서를 처음 읽는 사람의 입장에서 검토하고 수정 제안을 보고합니다. 문서의 검토, 리뷰, 피드백을 요청할 때 사용하세요. review, proofread, feedback.
model: sonnet
skills:
  - writing-guide
---

당신은 기획서, 보고서, 대외 공지문을 검토해 온 15년 차 기획 및 커뮤니케이션 전문가입니다.
작성자의 의도는 모른다고 가정하고, 문서를 처음 받아 보는 독자의 입장에서 문서에 작성된 내용만으로 판단합니다.

## 문서 파악
검토 전에 문서 유형(보고서, 기획서, 이메일, 공지문), 대상 독자, 목적(의사결정 요청, 정보 공유, 협조 요청)을 판단합니다.
판단하기 어려우면 추정한 근거를 함께 밝힙니다.

## 검토 기준
- writing-guide 스킬의 규칙에 어긋나는 곳
- 근거 없는 주장, 근거와 결론이 이어지지 않는 곳
- 같은 용어, 숫자, 날짜가 문서 안에서 다르게 작성된 곳
- 읽는 사람이 무엇을 언제까지 해야 하는지 알 수 없는 곳
- 외부에 공개되면 문제가 될 수 있는 표현
- 유형별 확인: 보고서는 수치의 출처와 비교 기준, 기획서는 문제 정의에서 기대 효과와 비용까지의 흐름, 이메일은 제목만으로 용건을 알 수 있는지, 공지문은 일시, 장소, 대상, 문의처

## 보고 형식
첫 줄에 문서 유형, 독자, 목적을 작성하고, 지금 상태로 보내도 되는지 두 문장 이내로 판단합니다.
문제는 '반드시 수정'(오해나 잘못된 결정으로 이어지는 문제)과 '수정 권장'(전달력을 떨어뜨리는 문제)으로 나눠서 보고합니다.
문제마다 원문, 문제, 수정 예시를 한 줄씩 작성합니다.

## 주의
- 문서를 수정하거나 전체를 다시 작성하지 않고, 지적한 부분의 수정 예시까지만 작성합니다.
- 해당하는 문제가 없는 구분은 "없음"으로 작성하고, 억지로 채우지 않습니다.
- 사실 여부를 확인할 수 없는 수치나 주장은 판단하지 않고 "확인 필요"로 표시합니다.

에이전트 파일의 각 부분은 실리는 곳과 시점이 다릅니다.

에이전트 파일의 각 부분이 실리는 곳

description은 스킬과 마찬가지로 Claude가 요청을 보고 이 에이전트에게 위임할지 판단하는 기준입니다.
모든 에이전트의 description은 세션이 시작될 때 항상 컨텍스트에 실리므로, 무엇을 하고 언제 사용하는지만 간결하게 작성합니다.

이 에이전트에는 사용할 도구의 목록인 tools 필드를 작성하지 않았습니다.
tools를 생략하면 메인 대화에서 사용할 수 있는 내장 도구와 MCP 도구를 모두 상속하므로, 커넥터로 Google Drive나 Notion을 연결했다면 별도의 설정 없이 Google Docs, Word, PDF 문서와 Notion 페이지도 검토할 수 있습니다.
반대로 tools를 작성하면 그 목록에 있는 도구만 사용할 수 있으므로, 커넥터 도구도 mcp__claude_ai_Notion처럼 서버 이름으로 함께 지정해야 합니다.
검토자가 문서를 고치지 않도록 하는 것은 본문의 '주의'에서 지시했으며, 도구 사용 자체를 막으려면 disallowedTools 필드에 Edit, Write처럼 제외할 도구를 작성합니다.
도구를 사용할 수 있더라도 실제로 실행할 때는 승인 모드와 권한 규칙에 따라 승인을 요청할 수 있습니다.

메인 대화에서는 사용하지 않고 이 에이전트에서만 사용할 MCP 서버라면, 세션에 등록하는 대신 mcpServers 필드에 .mcp.json과 같은 형식으로 정의할 수도 있습니다.
서버는 에이전트가 시작될 때 연결되고 작업이 끝나면 해제되며, 메인 대화에는 그 서버의 도구 설명이 실리지 않으므로 컨텍스트를 절약할 수 있습니다.

skills에 지정한 writing-guide는 앞에서 만든 스킬입니다.
서브에이전트는 대화 기록 없이 시작하므로 메인 대화에서 사용한 스킬도 전달되지 않지만, skills에 지정한 스킬은 에이전트가 시작될 때 SKILL.md 본문 전체가 컨텍스트에 함께 실립니다.
규칙을 스킬로 분리했기 때문에 메인 대화에서 문서를 작성할 때와 에이전트가 검토할 때 같은 규칙을 기준으로 삼을 수 있습니다.
규칙을 에이전트 본문에만 작성했다면 메인 대화에서 작성하는 초안에는 규칙이 적용되지 않고, 규칙이 바뀔 때마다 두 곳을 함께 고쳐야 합니다.

이 예제처럼 tools를 생략했거나 tools에 Skill 도구를 포함했다면, 지정하지 않은 스킬도 에이전트가 필요할 때 직접 호출할 수 있습니다.
disable-model-invocation: true로 자동 호출을 끈 스킬은 미리 지정할 수 없습니다.

본문은 에이전트의 시스템 프롬프트이므로, 무엇을 기준으로 판단하고 결과를 어떤 형태로 보고할지 구체적으로 작성합니다.
서브에이전트에는 AskUserQuestion 도구가 제공되지 않아서 작업 중에 사용자에게 질문할 수 없습니다.
그래서 예제의 '문서 파악'처럼 판단하기 어려운 상황에서 어떻게 진행할지도 본문에 미리 정합니다.
에이전트는 작업이 끝나면 마지막 보고만 메인 대화에 전달하므로, '보고 형식'처럼 보고할 내용과 순서도 본문에 작성합니다.

frontmatter의 주요 필드는 다음과 같습니다.

에이전트를 사용하는 방법은 스킬과 같습니다.
"워크숍 공지문을 검토해 줘"처럼 요청하면 Claude가 description을 보고 doc-reviewer에게 위임합니다.
특정 에이전트를 반드시 실행하려면 입력창에서 @를 입력해 목록에서 에이전트를 선택하거나, @agent-이름을 직접 작성합니다.

1
2
3
@agent-doc-reviewer 워크숍_공지문.md 파일을 검토해 줘
@agent-doc-reviewer Google Drive에 있는 '하반기 워크숍 안내' 문서를 검토해 줘
@agent-doc-reviewer Notion의 '3분기 마케팅 기획안' 페이지를 검토해 줘

문서 파일에 @를 붙이면 그 내용이 메인 대화에 먼저 실리므로, 경로만 전달해서 에이전트가 직접 읽게 합니다.

다음은 회신 기한이 없고 예산이 두 곳에서 다르게 작성된 공지문을 검토한 보고의 일부입니다.
보고의 내용과 형식은 실행할 때마다 달라질 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
문서 유형: 공지문(사내 워크숍 안내) / 독자: 전 직원(추정, 문서에 명시적 대상 표기 없음) / 목적: 하반기 워크숍 일정 공지 및 참석 여부 회신 요청(협조 요청)

판단: 워크숍 날짜와 예산 금액이 문서 안에서 서로 다르게 표기되어 있고 회신 기한, 방법, 문의처가 없어, 지금 상태로는 발송하면 안 됩니다. 위 내용을 정정하고 누락 정보를 채운 뒤 재검토가 필요합니다.

반드시 수정
...
3. 원문: "예산: 1인당 12만 원" / "식비를 포함한 1인당 예산은 15만 원이며, 초과 비용은 개인 부담입니다."
   문제: 같은 항목(1인당 예산)이 12만 원과 15만 원으로 다르게 표기되어 정확한 기준 금액을 알 수 없음.
   수정 예시: "예산: 1인당 15만 원(식비 포함)"으로 통일하고 뒤 문장의 "12만 원"은 삭제.

4. 원문: "참석 여부는 빠른 시일 내에 회신 부탁드립니다."
   문제: '빠른 시일 내'는 writing-guide에서 지양하도록 명시한 모호한 표현이며, 회신 기한, 방법, 담당자가 없어 언제까지 누구에게 회신해야 하는지 알 수 없음.
   수정 예시: "참석 여부는 9월 18일(금)까지 [담당자명, 이메일/연락처]로 회신 부탁드립니다."
...

수정 권장
...
3. 원문: "각 팀의 KPI 공유와 팀 빌딩 프로그램이 준비되어 있습니다."
   문제: 영문 약어 KPI가 처음 등장할 때 풀어서 작성되지 않음(writing-guide 규칙 위반).
   수정 예시: "각 팀의 핵심 성과 지표(KPI) 공유와 팀 빌딩 프로그램이 준비되어 있습니다."
...

검토 보고가 메인 대화에 전달되면, 초안을 작성하던 대화에서 그대로 수정을 요청합니다.
수정도 메인 대화에서 진행하므로, 초안을 작성할 때와 같이 writing-guide 스킬의 규칙을 기준으로 문서를 고칠 수 있습니다.

1
검토에서 지적한 회신 기한과 예산 불일치를 반영해서 공지문을 수정해 줘

파일을 직접 작성하는 대신 Claude에게 요청해서 만들어도 됩니다.
예전에 있던 /agents 마법사는 제거되었으므로, 지금은 이 두 가지 방법만 사용합니다.

1
2
3
.claude/agents/에 doc-reviewer 에이전트를 만들어 줘.
15년 차 기획 및 커뮤니케이션 전문가로서 완성된 업무 문서를 처음 읽는 사람의 입장에서 검토하고, 문제를 '반드시 수정'과 '수정 권장'으로 나눠서 원문, 문제, 수정 예시로 보고하는 역할이야.
writing-guide 스킬을 미리 로드하고, sonnet 모델을 사용해 줘.

# Remote Control

Remote Control은 내 컴퓨터에서 실행 중인 Claude Code 세션을 claude.ai/code나 Claude 모바일 앱(iOS, Android)에서 이어서 조작하는 기능입니다.
세션은 계속 내 컴퓨터에서 실행되므로 파일 시스템, MCP 서버, 프로젝트 설정을 그대로 사용하면서, 자리를 옮겨 휴대폰이나 다른 컴퓨터의 브라우저에서 대화를 이어갈 수 있습니다.
클라우드에서 실행되는 Claude Code on the web과 다른 점이 바로 이 실행 위치입니다.

사용하려면 다음 조건이 필요합니다.

• Pro, Max, Team, Enterprise 플랜 (Team과 Enterprise는 관리자가 Claude Code 관리 설정에서 Remote Control을 먼저 켜야 함)
• /login으로 연결한 구독 계정 (API 키나 claude setup-token으로 발급한 토큰으로는 동작하지 않음)
• api.anthropic.com에 직접 연결하는 환경 (Bedrock, Vertex AI, LLM 게이트웨이나 프록시는 지원하지 않음)
• 프로젝트 폴더에서 한 번 이상 claude를 실행해서 폴더 신뢰 확인을 마친 상태

대화형 세션 안에서 /remote-control을 실행하면 세션 주소와 QR 코드가 표시되고, 하단 상태줄에 /rc active 표시가 나타납니다.
주소를 브라우저에서 열거나 휴대폰으로 QR 코드를 스캔하면 같은 대화가 그대로 이어집니다.

/remote-control 화면

1
2
3
4
5
# 시작할 때부터 Remote Control 켜기
claude --remote-control

# 서버 모드로 실행하고 원격 연결을 기다림 (여러 세션 동시 서비스)
claude remote-control

모든 세션에서 자동으로 켜려면 /config의 Enable Remote Control for all sessions를 켜거나, 사용자 설정에 remoteControlAtStartup을 지정합니다.
이 설정은 사용자 설정(~/.claude/settings.json)에서만 true가 적용되며, 프로젝트 설정과 로컬 설정의 true는 무시되고 false만 적용됩니다.

1
2
3
{
  "remoteControlAtStartup": true
}

옵션을 항상 켜 두어도 토큰 사용량이나 응답 속도는 거의 달라지지 않습니다.
Remote Control은 단순히 대화를 다른 기기로 전달하는 것이므로, 모델에 전달하는 요청 내용은 같고 연결한 기기가 없는 동안에는 전달할 메시지가 있는지 확인하는 가벼운 통신만 주기적으로 발생합니다.
오히려 세션 도중에 Remote Control을 켜면 그 시점에 프롬프트 구성이 바뀌면서 프롬프트 캐싱이 한 번 새로 시작될 수 있으므로, 사용하려면 시작할 때 켜는 것이 좋습니다.

Remote Control을 사용했을 때:

• 대화 내용이 Anthropic 서버에 저장됩니다. 코드 실행과 파일 접근은 계속 내 컴퓨터에서만 이루어집니다. 보존 기간은 데이터 사용 정책을 따릅니다.
• Claude가 생성하는 커밋과 PR에 Claude-Session: 링크가 자동으로 추가되어 작업의 대화로 돌아갈 수 있게 됩니다. 링크는 내 계정에서만 확인 가능하며, 원치 않으면 설정 파일에 attribution.sessionUrl = false를 추가합니다. 커밋과 PR에 붙는 Claude 표기를 모두 숨기려면 "attribution": false로 지정합니다(2.1.281 이상).

연결한 기기에서는 대화와 서브에이전트의 진행 상황을 그대로 보면서 메시지를 보내고, 권한 요청에 답하고, 변경 사항의 diff를 확인하고, 모델과 사고 깊이를 바꿀 수 있습니다.
/plugin이나 /resume처럼 터미널 화면이 필요한 명령은 터미널에서만 동작하고, /compact, /clear, /context, /usage처럼 텍스트로 답하는 명령과 /model sonnet, /effort high처럼 값을 인수로 전달하는 명령은 기기에서도 동작합니다.

Remote Control 세션에서도 1M 컨텍스트를 사용할 수 있습니다.
세션이 내 컴퓨터에서 실행되므로 컨텍스트 윈도우도 터미널 세션의 모델 설정을 그대로 따릅니다.
claude.ai/code와 모바일 앱의 모델 선택 메뉴에는 [1m] 변형이 없지만, 버전 5 이상의 모델은 모델 자체가 1M 윈도우라서 기기의 메뉴에서 골라도 모든 플랜에서 1M으로 실행됩니다.

# Plugins

플러그인은 커스텀 명령어, 에이전트, Skills, Hooks, MCP 서버를 하나의 패키지로 묶어 Claude Code를 확장합니다.
팀이나 커뮤니티에서 공유하기 좋은 형태이며, 마켓플레이스를 통해 배포할 수 있습니다.

마켓플레이스에서 설치하는 플러그인의 구성

# Skills vs Plugins

플러그인의 본질은 "기능 추가"가 아니라 "번들링 + 배포 + 버전 관리"입니다.

# 플러그인 구조

플러그인은 다음과 같은 구성요소를 포함할 수 있습니다(이 외에 LSP 서버, Monitor, Mods 등도 지원합니다).

1. Agents: 복잡한 작업을 위임받는 Sub Agent
2. Skills: Claude가 자동으로 발견하여 사용하는 스킬 (슬래시 명령어 포함)
3. Hooks: 도구 호출 전/후에 실행되는 이벤트 핸들러
4. MCP Servers: 외부 도구/서비스 연동

1
2
3
4
5
6
7
8
9
10
11
12
13
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 플러그인 매니페스트
├── agents/                  # 선택: Sub Agent
│   └── code-reviewer.md
├── skills/                  # 선택: Skills (슬래시 명령어 포함)
│   └── log-analyzer/
│       └── SKILL.md
├── hooks/                   # 선택: Hooks
│   └── hooks.json
├── scripts/                 # 선택: 유틸리티 스크립트
│   └── notify-slack.sh
└── .mcp.json               # 선택: MCP 서버 설정

구성 요소 폴더는 모두 플러그인 루트에 두고, .claude-plugin/ 폴더에는 plugin.json 매니페스트만 둡니다.
매니페스트는 .claude-plugin/plugin.json 경로에 있어야 하며, 플러그인 루트에 둔 plugin.json은 읽지 않습니다.

plugin.json 매니페스트는 다음과 같이 작성합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "name": "my-plugin",
  "description": "Plugin 설명 (마켓플레이스 검색용)",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "homepage": "https://github.com/your/plugin",
  "repository": "https://github.com/your/plugin",
  "license": "MIT",
  "keywords": ["devops", "automation", "deployment"]
}

매니페스트는 선택 사항입니다.
구성 요소를 기본 위치에 두었다면 매니페스트가 없어도 플러그인이 로드되며, 플러그인 이름은 폴더 이름으로 정해집니다.
그래서 혼자 사용하는 플러그인은 로드하는 방법에 따라 매니페스트를 생략할 수 있습니다.

~/.claude/skills/ 안의 폴더는 .claude-plugin/plugin.json이 있어야 플러그인으로 인식되고, 없으면 일반 스킬 폴더로 취급됩니다.
claude plugin init my-plugin 명령을 실행하면 매니페스트와 SKILL.md가 포함된 플러그인 폴더가 ~/.claude/skills/my-plugin/에 생성됩니다.
로컬 마켓플레이스는 플러그인의 매니페스트 대신 마켓플레이스 폴더의 .claude-plugin/marketplace.json이 필요합니다.
다른 사람에게 배포할 플러그인은 이름, 버전, 설명을 명시하고 버전 단위로 업데이트를 관리할 수 있도록 매니페스트를 작성하는 것이 좋습니다.
완성한 플러그인은 GitHub 저장소를 마켓플레이스로 등록해 배포하거나, 유료 플랜 사용자라면 디렉터리 제출 포털에서 Anthropic의 Claude 디렉터리 등록을 신청할 수 있습니다.

# 플러그인 설치 및 관리

/plugin 명령을 실행하면 마켓플레이스의 플러그인을 검색해서 설치하고, 설치한 플러그인을 관리하는 화면이 열립니다.
Anthropic이 운영하는 공식 마켓플레이스(claude-plugins-official)는 기본으로 등록되어 있어서, 별도의 설정 없이 바로 검색할 수 있습니다.
Discover 탭에는 공식 마켓플레이스와 함께 Anthropic Directory에 등록된 수천 개의 플러그인도 표시되며, 검색창 아래 목록에서 Ctrl + S를 누르면 마켓플레이스별로 걸러 볼 수 있습니다.

/plugin 화면의 Discover 탭

명령으로 직접 설치하고 관리할 수도 있습니다.
공식 마켓플레이스 외의 플러그인은 GitHub 저장소나 URL, 로컬 경로를 마켓플레이스로 먼저 등록합니다.

1
2
3
4
5
6
7
8
9
10
11
12
# 마켓플레이스 등록 (GitHub 저장소, URL, 로컬 경로)
/plugin marketplace add jarrodwatts/claude-hud

# 플러그인 설치
/plugin install plugin-name@marketplace-name

# 활성화/비활성화
/plugin enable plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name

# 제거
/plugin uninstall plugin-name@marketplace-name

같은 작업을 터미널에서 claude plugin install plugin-name@marketplace-name처럼 서브 명령으로 실행할 수도 있습니다.
아직 등록하지 않은 마켓플레이스라면 /plugin install plugin-name --marketplace owner/repo처럼 --marketplace 옵션으로 등록과 설치를 한 번에 진행합니다.
프로젝트 설정에서 직접 활성화 상태를 관리할 수도 있습니다.

1
2
3
4
5
6
{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true
  }
}

# Claude 계정 플러그인 동기화

Claude 앱의 사용자 지정(Customize) > 플러그인에서 켠 플러그인도 스킬처럼 Claude Code에 동기화됩니다.
같은 계정으로 로그인한 Claude Code(2.1.273 이상)는 실행할 때마다 계정을 확인해서, 새 플러그인과 업데이트를 ~/.claude/plugins/synced/에 내려받고 계정에서 끈 플러그인은 제거합니다.
조직에서 구성원에게 켜 준 플러그인도 함께 내려받으며, 마켓플레이스에서 설치한 플러그인과 똑같이 스킬, 에이전트, Hooks, MCP 서버가 모두 로드됩니다.

동기화한 플러그인은 플러그인명@synced라는 이름으로 로드되고, claude plugin list의 Synced from claude.ai 항목과 /plugin의 Installed 탭에서 확인할 수 있습니다.
예를 들어 Cowork에서 설치한 engineering 플러그인은 터미널에서 다음과 같이 표시되고, 플러그인의 스킬은 /engineering:code-review처럼 호출합니다.

1
2
3
4
5
6
7
claude plugin list
## Synced from claude.ai:
##
##   engineering@synced
##     Version: 1.2.0
##     Path: ~/.claude/plugins/synced/.../engineering
##     Status: loaded

동기화 확인은 백그라운드에서 진행되므로, 세션 중에 변경 사항이 생기면 /reload-plugins 명령으로 바로 반영하거나 다음 실행 때 반영됩니다.
동기화한 플러그인은 claude plugin install, update, uninstall 명령으로 관리하지 않으며, 업데이트는 다음 동기화 때 자동으로 내려받고 제거하려면 claude.ai에서 끕니다.
이 컴퓨터에서만 끄려면 claude plugin disable engineering@synced처럼 비활성화하고, 동기화 자체를 끄려면 사용자 설정에서 syncClaudeAiPlugins를 false로 지정합니다.
조직에서 필수로 지정한 플러그인은 비활성화할 수 없습니다.

# 쓸 만한 플러그인

무엇부터 설치할지 모르겠다면 Discover 탭에 표시되는 설치 수가 기준이 됩니다.
다음은 설치 수가 많고 실제 작업에서 자주 사용하는 플러그인입니다.

이 중 claude-hud는 화면 하단의 상태줄을 바꿔 주는 플러그인입니다.
기본 상태줄은 승인 모드 정도만 보여 주지만, claude-hud를 설치하면 컨텍스트 사용량, 플랜 사용량과 갱신 시각, 이번 세션에서 사용한 도구, 실행 중인 에이전트를 항상 볼 수 있습니다.
작업 중에 컨텍스트가 얼마나 찼는지 확인하려고 /context를 실행할 필요가 없어집니다.

1
2
3
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud@claude-hud
/claude-hud:setup

/claude-hud:setup은 플러그인이 제공하는 스킬로, 상태줄 설정을 사용자 설정(~/.claude/settings.json)에 작성합니다.
설정 후 다음 메시지부터 상태줄이 바뀌며, 표시할 항목은 /claude-hud:configure로 조절합니다.

claude-hud가 적용된 상태줄

# Mods

Mod는 Claude Code의 동작과 화면을 바꾸는 JavaScript 또는 TypeScript 함수이며, 플러그인에 담아서 설치하고 공유합니다(2.1.287 이상).
Claude Code는 도구 호출, 프롬프트 제출, 화면 그리기 같은 일이 일어날 때마다 이벤트를 발생시키고, Mod는 그 이벤트를 지켜보거나 내용을 바꾸거나 직접 처리합니다.

Hooks와 비슷해 보이지만 실행되는 위치가 다릅니다.
Hooks는 설정 파일에 등록한 셸 명령이나 HTTP 요청을 Claude Code 밖에서 실행하고, Mod는 Claude Code 안에서 실행되는 함수라서 대화 옆에 패널을 그리거나 기존 화면 요소를 바꿀 수 있습니다.

다른 사람이 공개한 Mod를 설치해서 사용할 수도 있고, Claude에게 요청해서 나만의 Mod를 만들 수도 있습니다.

# Mod 설치

Mod도 플러그인이므로 플러그인 설치 및 관리에서 살펴본 방법 그대로 설치합니다.
예를 들어, Claude의 응답이 끝날 때마다 이어서 할 만한 요청을 버튼으로 제안하는 next-steps Mod를 설치해 보겠습니다.

1
/plugin install next-steps --marketplace pawandeepdhall/claude-mods

마켓플레이스를 추가할지 묻는 질문에 y를 누르면 플러그인 정보와 설치 범위를 고르는 화면이 표시됩니다.
나만 사용할 것이라면 Install for you (user scope)를 선택합니다.

Mod 설치 범위 선택

설치한 Mod는 세션을 다시 시작하지 않아도 바로 동작합니다.
회의록을 요약해 달라고 요청하면, 응답이 끝날 때 입력창 위에 다음에 할 만한 요청이 버튼으로 표시됩니다.
Ctrl+X와 Tab을 차례로 눌러서 입력창 위 영역으로 이동한 뒤, Tab으로 항목을 고르고 Enter로 선택합니다.
항목을 선택하고 Send를 누르면 Claude에게 요청이 전달되며, 여러 항목을 함께 선택할 수도 있습니다.

입력창 위에 표시된 다음 할 일 버튼

Send를 누르면 버튼의 짧은 문구 대신, 지금까지의 대화를 반영해서 구체적으로 작성한 요청이 전달됩니다.
응답이 끝나면 다음 할 일 버튼도 새 대화에 맞게 다시 표시됩니다.
다음 할 일을 고르고 요청을 작성하는 데 Haiku 모델을 사용하므로, 사용량이 조금 더 듭니다.

Mod가 작성해서 전달한 요청과 결과

Mod가 더 필요 없으면 /plugin의 Installed 탭이나 다음 명령으로 제거합니다.
@ 뒤에는 저장소 이름이 아니라 마켓플레이스 이름을 작성하며, 마켓플레이스 이름은 Installed 탭에서 확인할 수 있습니다.

1
/plugin uninstall next-steps@my-claude-mods

제거하면 메뉴를 닫는 즉시 입력창 위의 버튼이 사라지고 원래 화면으로 돌아갑니다.
다만 Mod가 대신 보낸 요청은 대화 기록에 남고, Mod가 파일을 만들거나 설정을 바꿨다면 그 내용도 그대로 남습니다.
함께 추가한 마켓플레이스도 남아 있으므로, 필요 없다면 /plugin marketplace remove my-claude-mods로 따로 제거합니다.

설치하기 전에 저장소를 내려받아 claude plugin validate ./plugins/next-steps처럼 검사하면, Mod가 다루는 이벤트(hooks)와 호출하는 기능(calls)을 확인할 수 있습니다.
Anthropic이 공개한 예제 Mod나 커뮤니티에서 모은 Mod 목록에서 다른 Mod를 찾아볼 수도 있습니다.

# Mod 만들기

Mod는 코드를 직접 작성하지 않고, Claude에게 원하는 기능을 설명해서 만들 수 있습니다.
화면을 공유하거나 녹화하다 보면 대화에 거래처의 이메일이나 전화번호, 금액이 그대로 보여서 곤란할 때가 있습니다.
그래서 이런 정보를 화면에서만 가려 주는 Mod를 만들어 보겠습니다.

1
화면을 공유하거나 녹화할 때 대화에 나오는 이메일 주소, 전화번호, 금액을 화면에서만 가려 주는 Mod를 만들어 줘. Claude는 원래 값으로 작업하고, /share-mode 명령으로 켜고 끌 수 있게 해 줘. 켜져 있을 때는 입력창 위에 공유 모드라고 표시해 줘.

Claude는 내장 스킬인 /plugin-authoring을 불러와서 사용 중인 Claude Code 버전에 맞게 Mod 파일을 작성합니다.
Mod 파일은 ~/.claude 폴더에 저장되는데, 이 폴더는 보호 경로라서 Manual 모드나 Accept Edits 모드에서는 파일을 만들 때마다 승인을 요청합니다.
첫 파일을 저장하면 이 세션에서 핫 리로드(Hot Reload)를 켤지 묻는데, Enable for this session을 선택합니다.

Mod 핫 리로드 켜기

핫 리로드를 켜면 응답이 끝나는 시점에 Mod를 불러오고, 이후 Claude가 Mod를 고칠 때마다 그 응답이 끝나는 시점에 다시 불러옵니다.
Not now를 선택하면 파일만 남고, 같은 세션을 다시 시작할 때 Mod를 불러옵니다.

Mod를 불러온 뒤 거래처 목록을 표로 정리해 달라고 요청하면, 아직은 이메일과 전화번호, 금액이 그대로 표시됩니다.

공유 모드를 켜기 전

/share-mode를 실행하면 이미 표시된 대화까지 이메일, 전화번호, 금액이 가려지고, 입력창 위에 공유 모드가 켜져 있다고 표시됩니다.
화면에 그리는 내용만 바꾸므로 Claude는 원래 값으로 계속 작업하며, /share-mode를 다시 실행하면 원래대로 표시됩니다.

공유 모드를 켠 후

가리는 방식이나 표시 문구가 마음에 들지 않으면 Claude에게 그대로 요청하면 되고, 응답이 끝나면 고친 Mod를 다시 불러옵니다.
실제로 굵은 글씨 안의 금액을 가렸을 때 ** 기호가 그대로 보이는 문제도 이렇게 요청해서 고쳤습니다.
정해진 패턴으로 값을 찾아서 가리는 것이라 형식이 특이한 값은 놓칠 수 있으므로, 녹화를 시작하기 전에 한 번 확인합니다.

Claude가 만든 Mod는 세션 전용 폴더(~/.claude/dev-mods/세션ID/)에 저장되어 이 세션에서만 로드되고, 설정한 보관 기간(cleanupPeriodDays)이 지나면 삭제됩니다.
다른 세션에서도 계속 사용하려면 Claude에게 요청합니다.

1
이 Mod를 다른 세션에서도 계속 쓸 수 있게 해 줘

Claude는 Mod를 보관용 폴더로 옮기고 설치까지 진행합니다.
예를 들어, 이번에는 Mod를 ~/claude-mods/share-mode 폴더로 옮긴 뒤, ~/claude-mods 폴더를 로컬 마켓플레이스로 등록해서 설치했습니다.
옮기는 위치와 방법은 요청할 때마다 달라질 수 있으므로 Claude의 응답에서 확인합니다.

새 세션에서 /plugin의 Installed 탭을 열면 로드된 Mod 수와 이름(mods active)이 위쪽에 표시됩니다.
설치한 Mod는 User 항목에, Claude Code에 내장된 Mod는 Built-in 항목에 표시되며, 여기서 끄거나 제거할 수 있습니다.

/plugin의 Installed 탭에 표시된 Mod

/diff 화면(cc-plugin-diff)이나 AGENTS.md 읽기(cc-plugin-agents-md)처럼 Claude Code의 일부 기능도 Mod로 제공됩니다.
작업을 지켜보다가 놓치기 쉬운 내용을 입력창 위에 알려 주는 cc-plugin-you-should-know는 기본으로 꺼져 있으며, /plugin enable cc-plugin-you-should-know@builtin으로 켭니다.

Mod가 그리는 화면은 터미널과 데스크톱 앱의 Code 탭에서만 표시되며, VS Code 확장의 채팅 패널이나 claude -p에서는 이벤트 처리만 동작합니다.

# GitHub PR 자동화

Claude에서 브랜치의 변경 사항을 요약하고 PR 생성 및 리뷰할 수 있습니다.

• 브랜치의 커밋 내역을 분석해 PR 제목과 설명을 자동 작성
• 코드 단위 리뷰(댓글), 리뷰어 지정, 라벨, 병합 등을 자연어로 처리 가능
• 내부적으로 gh(GitHub CLI) 명령을 실행하므로 GitHub CLI 설치 필요
• 리뷰 의견에 맞춰 PR 설명을 다시 다듬거나 댓글을 자동 작성

GitHub CLI 다운로드 설치: https://github.com/cli/cli/releases
GitHub CLI 터미널 설치:

1
2
3
4
5
6
7
8
# macOS
brew install gh

# Windows
winget install --id GitHub.cli --source winget

# GitHub CLI 설치 후 로그인!
gh auth login

1
현재 브랜치의 변경 사항을 분석해서 PR을 생성해 줘.

# CLI 플래그

자주 사용하는 CLI 플래그입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 이전 세션 이어가기
claude -c

# 특정 세션 재개 (ID 또는 이름으로)
claude -r "auth-refactor" "이 PR 마무리해 줘"

# 비대화형으로 질문하고 응답만 출력 (-p와 --print는 동일)
claude -p "이 프로젝트의 구조를 설명해 줘"

# Plan 모드로 시작
claude --permission-mode plan

# 파이프라인에서 사용
cat error.log | claude -p "이 에러를 분석해 줘"

# 최신 버전으로 업데이트
claude update

# 비대화형 모드

Claude Code는 대화형 모드뿐만 아니라 스크립트나 파이프라인에서 사용할 수 있는 비대화형 모드도 지원합니다.
-p 또는 --print 플래그로 대화형 모드 없이 응답을 출력합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 단일 질문에 응답 받기 (-p와 --print는 동일)
claude -p "이 프로젝트에서 사용하는 프레임워크는?"

# 파이프라인에서 사용
cat error.log | claude -p "이 에러 로그를 분석해 줘"

# JSON 형식으로 출력
claude -p "package.json의 의존성을 분석해 줘" --output-format json

# 이전 세션 이어가면서 비대화형으로 쿼리
claude -c -p "타입 에러 확인해 줘"

# 스크립트에서 사용
SUMMARY=$(claude -p "README.md를 한 문장으로 요약해 줘")
echo "프로젝트 요약: $SUMMARY"

비대화형 모드는 CI/CD 파이프라인, 자동화 스크립트, Git Hooks 등에서 유용합니다.

1
2
3
4
5
6
7
#!/bin/bash
# 커밋 전 코드 리뷰 자동화
REVIEW=$(claude -p "staged 파일들을 리뷰하고 문제점을 알려줘")
if echo "$REVIEW" | grep -q "심각한 문제"; then
  echo "$REVIEW"
  exit 1
fi