개발자가 쓰는 AI 일기

Foldernote — 개인정보 처리방침 / Privacy Policy

2026-05-21T08:30:00.653-07:00

Foldernote 개인정보 처리방침

최종 업데이트: 2026-05-25

Foldernote(이하 "본 앱")는 사용자의 노트를 로컬에 저장하는 노트 앱입니다. 본 앱은 사용자의 어떠한 개인정보도 서버로 전송하거나 외부와 공유하지 않습니다.

1. 수집하지 않는 정보

본 앱은 다음 정보를 수집·전송·저장하지 않습니다:

이름, 이메일, 전화번호 등 개인 식별 정보
위치, 연락처
광고 ID, 기기 ID, 사용 분석 데이터
충돌(crash) 보고서

본 앱은 광고 SDK, 분석 SDK, 충돌 보고 SDK, 푸시 알림 SDK 등 어떠한 제3자 서비스도 통합하지 않으며 자체 백엔드 서버도 운영하지 않습니다.

1-1. 네트워크 사용 범위

v1.3.0부터 본 앱은 android.permission.INTERNET 권한을 선언합니다. 네트워크는 오직 한 가지 경우에만 사용됩니다:

사용자가 노트 본문에 직접 입력한 마크다운 이미지 참조 (![alt](https://...)) 를 미리보기에서 렌더링할 때, 해당 URL로부터 이미지를 받아옵니다.

이 외의 네트워크 활동은 없습니다 — 광고/분석/원격 측정/자동 업데이트 확인/푸시/원격 설정 호출 등 어느 것도 발생하지 않습니다. 이미지 요청은 사용자가 적은 URL의 호스트 서버로 직접 전송되며, 해당 서버는 일반적인 HTTP 요청처럼 사용자의 IP 주소와 User-Agent를 볼 수 있습니다 (브라우저로 같은 URL을 열 때와 동일). 본 앱은 사용자를 식별하는 어떠한 헤더나 쿠키도 추가하지 않습니다.

2. 로컬 저장 정보

사용자가 작성한 노트, 폴더, 만다라트 그리드, 설정, 첨부된 날짜 정보는 모두 사용자 기기 내부 저장소에 SQLite 데이터베이스 형태로 저장됩니다. 이 데이터는 사용자의 명시적인 작업(공유, 백업, 앱 삭제 등) 외에는 기기 밖으로 나가지 않습니다.

3. 백업

사용자가 설정에서 백업을 활성화하면, 본 앱은 사용자가 직접 선택한 폴더(예: 기기 내 저장소의 임의 경로, SD 카드, 또는 Google Drive·Dropbox 등 사용자가 시스템에서 마운트한 위치)에 암호화된 백업 파일을 작성합니다.

본 앱은 어떤 클라우드 서비스에도 직접 접근하지 않습니다.
백업 파일의 위치, 빈도, 공유 여부는 전적으로 사용자가 통제합니다.
백업 파일을 외부 클라우드에 동기화하는 것은 사용자가 설치한 별도의 동기화 앱(Google Drive, Dropbox 등)의 동작이며, 본 앱과 무관합니다.

4. 권한 사용

본 앱이 요청하는 권한과 사용 목적:

INTERNET — 위 1-1 항목에 기술된 마크다운 이미지 URL 렌더링에만 사용. 다른 네트워크 호출은 없습니다.
USE_BIOMETRIC — 폴더 잠금 해제 복구 흐름에서 지문/생체 인증 또는 기기 자격 증명을 요청하기 위해 사용. 인증 결과는 본 앱 내부에서만 사용되며 외부로 전송되지 않습니다.
RECEIVE_BOOT_COMPLETED — 기기 재부팅 후 홈 화면 위젯이 자동으로 다시 그려지도록 사용. 노트 데이터에는 영향 없습니다.
CAMERA — 노트 편집 화면의 이미지 첨부 버튼에서 카메라로 촬영할 때 사용. 촬영된 이미지는 앱 내부 저장소에만 저장되며 외부로 전송되지 않습니다.

저장소 권한은 Android의 Storage Access Framework(SAF)를 통해 사용자가 선택한 폴더에 한정해 받습니다. 본 앱은 일반 저장소 권한(READ_EXTERNAL_STORAGE 등)을 요청하지 않습니다.

5. 제3자 서비스

본 앱은 광고 SDK, 분석 SDK, 충돌 보고 SDK, 푸시 알림 SDK 등 어떠한 제3자 서비스도 통합하지 않습니다. 마크다운 이미지 URL을 미리보기에서 렌더링할 때 해당 URL의 호스트 서버는 제3자에 해당하며, 그 처리는 해당 호스트의 정책을 따릅니다.

6. 어린이

본 앱은 만 13세 미만 어린이를 대상으로 하지 않으며, 어린이로부터 의도적으로 정보를 수집하지 않습니다.

7. 변경

본 방침은 향후 변경될 수 있으며, 변경 시 본 페이지의 "최종 업데이트" 날짜가 갱신됩니다.

8. 연락처

문의: j2oasis@gmail.com

Foldernote Privacy Policy

Last updated: 2026-05-25

Foldernote (the "app") is a local-first note-taking app that stores the user's notes locally on their device. The app does not transmit or share any personal information with any server or third party.

1. Information We Do Not Collect

The app does not collect, transmit, or store:

Personally identifiable information such as name, email, or phone number
Location or contacts
Advertising IDs, device IDs, or analytics data
Crash reports

The app integrates no third-party SDKs (advertising, analytics, crash reporting, push notifications, etc.) and operates no backend server of its own.

1-1. Scope of Network Use

Starting with v1.3.0 the app declares the android.permission.INTERNET permission. The network is used in exactly one situation:

When rendering a markdown image reference (![alt](https://...)) the user has typed into their own note, the app fetches the image from that URL for inline preview.

No other network activity occurs — no ads, no analytics, no telemetry, no auto-update checks, no push, no remote configuration calls. Image requests go directly to the host of the URL the user typed. That host receives the request and can observe the user's IP address and User-Agent — exactly as a browser opening the same URL would. The app does not attach any identifying headers or cookies of its own.

2. Locally Stored Data

Notes, folders, mandalart grids, settings, and attached due dates are all stored locally on the user's device as a SQLite database. This data does not leave the device except through explicit user actions such as sharing, backup, or app removal.

3. Backups

When the user enables backups in Settings, the app writes encrypted backup files to a folder of the user's choice — this can be local device storage, an SD card, or any location the user has mounted through the system (e.g., a Google Drive or Dropbox folder exposed via Android's Storage Access Framework).

The app does not connect to any cloud service directly.
The location, frequency, and sharing of backup files are entirely controlled by the user.
Syncing backup files to an external cloud is performed by whichever separate sync app (Google Drive, Dropbox, etc.) the user has installed; this is independent of Foldernote.

4. Permissions

The app requests the following permissions:

INTERNET — used only for the markdown image URL rendering described in section 1-1 above. No other network calls.
USE_BIOMETRIC — used for the folder unlock-recovery flow that asks for biometric or device credential authentication. The result stays within the app and is never transmitted.
RECEIVE_BOOT_COMPLETED — lets the home-screen widget redraw after a device reboot. It has no effect on note data.
CAMERA — used when the note editor's image-attach button captures a photo. The captured image is stored in app-private storage and never transmitted.

Storage access is granted only through Android's Storage Access Framework (SAF), limited to the folder the user picks. The app does not request blanket storage permissions such as READ_EXTERNAL_STORAGE.

5. Third Parties

The app does not integrate any third-party SDKs — no advertising, analytics, crash reporting, or push notification services. When the app renders a markdown image URL in preview, the host of that URL counts as a third party; its handling of the request is governed by that host's own policy.

6. Children

The app is not directed at children under 13 and does not knowingly collect information from children.

7. Changes

This policy may change in the future. Any updates will be reflected in the "Last updated" date at the top of this page.

8. Contact

For questions, contact j2oasis@gmail.com.

클로드 코드(Claude Code) MCP 완벽 가이드: 쉬운 예제로 배우는 외부 도구 연결법

2026-05-02T15:28:00.000-07:00

클로드 코드(Claude Code)를 사용하다 보면 한 가지 답답한 순간이 옵니다. AI가 제 코드는 술술 읽고 수정해 주는데, 정작 깃허브(GitHub) 이슈는 제가 직접 복사해서 붙여 넣어야 하고, 데이터베이스 결과도 제가 직접 쿼리해서 가져다줘야 한다는 점입니다. "이거 한 번에 처리할 수 없을까?"라는 생각이 든다면, 바로 그 답이 **MCP(Model Context Protocol)**입니다.

이번 글에서는 MCP가 정확히 무엇이고, 클로드 코드에서 어떻게 활용하는지를 아주 쉬운 예제와 함께 풀어드립니다. 공식 문서를 기반으로 작성했기 때문에 안심하고 따라 하실 수 있습니다.

1. MCP란 무엇인가요?

**MCP(Model Context Protocol)**는 앤트로픽(Anthropic)이 2024년 11월에 공개한 오픈 소스 표준입니다. 한 줄로 정리하면 "AI 애플리케이션이 외부 도구·데이터와 소통하기 위한 공통 규격"입니다. 공식 사이트는 modelcontextprotocol.io에서 확인하실 수 있습니다.

쉬운 비유: USB-C 같은 존재

MCP를 가장 쉽게 이해하는 방법은 USB-C 포트를 떠올리는 것입니다.

USB-C가 등장하기 전에는 휴대폰마다 충전 단자가 다 달랐습니다. 삼성용 케이블, 애플용 케이블, 구형 안드로이드용 케이블을 따로따로 들고 다녔어야 했지요. 그런데 USB-C가 표준이 된 이후에는 케이블 하나로 거의 모든 기기를 연결할 수 있게 되었습니다.

MCP도 똑같은 역할을 합니다. 예전에는 AI를 깃허브에 연결하려면 깃허브 전용 통합 코드를 짜고, 슬랙(Slack)에 연결하려면 슬랙 전용 통합 코드를 또 짜야 했습니다. MCP가 등장한 이후에는 "MCP 서버"라는 표준 규격만 만들어 두면 어떤 AI 도구에서도 그 서버를 가져다 쓸 수 있게 되었습니다.

MCP가 해결하는 핵심 문제: M×N에서 M+N으로

조금 더 기술적인 시각에서 보면, MCP는 "M×N 문제"를 "M+N 문제"로 바꿔 줍니다.

AI 애플리케이션이 M개, 외부 도구가 N개 있을 때
MCP가 없으면: 각 조합마다 통합을 만들어야 하므로 M×N개의 연결 코드가 필요합니다
MCP가 있으면: 도구 제공자는 N개의 MCP 서버만 만들면 되고, AI 애플리케이션 개발자는 M개의 MCP 클라이언트만 만들면 되므로 결과적으로 M+N개의 통합으로 충분합니다

2. MCP의 구조: 3가지 핵심 구성 요소

MCP는 다음 3가지 구성 요소로 이루어져 있습니다. 식당에 비유하면 이해가 쉽습니다.

구성 요소	역할	식당 비유
MCP 호스트(Host)	사용자가 직접 사용하는 AI 애플리케이션	손님(여러분)
MCP 클라이언트(Client)	호스트 안에서 서버와의 연결을 관리	주문을 전달하는 종업원
MCP 서버(Server)	외부 도구·데이터를 노출하는 프로그램	음식을 만드는 주방

클로드 코드는 이 중 호스트 역할을 합니다. 여러분이 "깃허브에서 이슈 가져와 줘"라고 명령하면, 클로드 코드 안의 클라이언트가 깃허브 MCP 서버에 요청을 보내고, 서버가 실제로 깃허브 API를 호출해서 결과를 가져오는 식입니다.

MCP 서버가 제공하는 3가지 기능

MCP 서버는 다음 3가지 종류의 기능을 클라이언트에게 노출합니다.

도구(Tools): AI가 호출해서 어떤 작업을 수행하는 함수입니다. 예: "이슈 만들기", "데이터베이스에 쿼리하기"
리소스(Resources): AI가 읽어 들이는 데이터입니다. 예: 파일, 문서, API 응답
프롬프트(Prompts): 미리 정의된 명령 템플릿입니다. 예: "PR 리뷰 템플릿"

3. 클로드 코드에서 MCP가 작동하는 방식

클로드 코드 공식 문서에 따르면, 클로드 코드는 수백 개의 외부 도구·데이터 소스와 MCP를 통해 연결될 수 있습니다.

연결 후에는 자연어로 다음과 같은 명령을 내릴 수 있습니다.

이슈 트래커 연동: "JIRA의 ENG-4521 이슈를 구현하고 깃허브에 PR 만들어 줘."
모니터링 데이터 분석: "센트리(Sentry)에서 최근 24시간 동안 가장 자주 발생한 오류를 확인해 줘."
데이터베이스 쿼리: "이번 달 총 매출이 얼마야?"
워크플로 자동화: "지메일(Gmail)에서 이 사용자 10명에게 피드백 세션 초대 메일 초안을 만들어 줘."

복사·붙여 넣기 없이 한 번의 자연어 명령으로 외부 시스템과 직접 상호 작용할 수 있게 되는 것이 핵심입니다.

4. MCP 서버를 클로드 코드에 추가하는 3가지 방법

공식 문서는 MCP 서버 연결 방법을 3가지로 분류하고 있습니다.

방법 1: HTTP 원격 서버 (권장)

클라우드 기반 서비스에 가장 많이 쓰이는 방식입니다. 공식 문서에서도 원격 MCP 서버 연결 시 가장 권장하는 옵션입니다.

# 기본 문법
claude mcp add --transport http <이름> <URL>

# 노션(Notion) 연결 예시
claude mcp add --transport http notion https://mcp.notion.com/mcp

방법 2: SSE 원격 서버 (사용 비권장)

SSE(Server-Sent Events) 방식은 공식 문서에 따르면 현재 사용이 권장되지 않습니다(deprecated). 가능하면 HTTP 방식을 사용하시는 것이 좋습니다.

# 아사나(Asana) 연결 예시
claude mcp add --transport sse asana https://mcp.asana.com/sse

방법 3: stdio 로컬 서버

내 컴퓨터에서 직접 실행되는 프로세스 형태입니다. 시스템 접근이나 커스텀 스크립트가 필요할 때 적합합니다.

# 에어테이블(Airtable) 연결 예시
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

중요한 주의사항: 모든 옵션(--transport, --env, --scope, --header)은 반드시 서버 이름 앞에 와야 합니다. 그리고 --(이중 대시)로 서버 이름과 실행할 명령을 구분합니다.

5. 쉬운 예제로 배우는 MCP 활용

이제 가장 흔하게 사용되는 예제 3가지를 살펴보겠습니다. 모두 공식 문서에 수록된 내용입니다.

예제 1: 센트리(Sentry)로 오류 모니터링하기

운영 환경에서 발생하는 오류를 클로드 코드로 분석하는 시나리오입니다.

연결 명령:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

인증: 클로드 코드 안에서 다음 명령을 실행하면 브라우저에서 센트리 로그인 화면이 뜹니다.

/mcp

활용 예시:

"최근 24시간 동안 가장 자주 발생한 오류는 뭐야?"
"오류 ID abc123의 스택 트레이스 보여 줘."
"어떤 배포에서 이 새 오류들이 시작된 거야?"

이렇게 하면 센트리 대시보드를 직접 열지 않고도 클로드 코드 터미널에서 바로 디버깅을 진행할 수 있습니다. 센트리에 대해 더 알고 싶으신 분은 센트리 공식 사이트를 참고하세요.

예제 2: 깃허브 연동으로 코드 리뷰하기

깃허브의 원격 MCP 서버는 개인 액세스 토큰(Personal Access Token)으로 인증합니다.

준비 단계:

깃허브 토큰 설정 페이지로 이동합니다.
클로드가 작업할 저장소에 접근 권한을 가진 fine-grained 토큰을 새로 발급받습니다.

연결 명령:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

활용 예시:

"PR #456을 리뷰하고 개선 사항을 제안해 줘."
"방금 발견한 버그에 대한 새 이슈를 만들어 줘."
"나에게 할당된 열린 PR을 모두 보여 줘."

예제 3: PostgreSQL 데이터베이스 쿼리하기

stdio 방식으로 로컬 데이터베이스에 연결하는 예시입니다.

연결 명령:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

활용 예시:

"이번 달 총 매출이 얼마야?"
"orders 테이블의 스키마를 보여 줘."
"최근 90일 동안 구매가 없는 고객을 찾아 줘."

자연어로 질문하면 클로드가 알아서 SQL을 짜서 실행하고 결과를 정리해 줍니다. 보안을 위해 읽기 전용(readonly) 계정을 쓰는 것이 권장됩니다.

6. MCP 설치 범위(Scope): 3가지 중 무엇을 골라야 할까?

MCP 서버는 3가지 범위(scope) 중에서 골라 설치할 수 있습니다. 어느 프로젝트에서 보일지, 팀원과 공유할지를 결정하는 설정입니다.

범위	적용 범위	팀과 공유	저장 위치
로컬(Local)	현재 프로젝트만	아니요	`~/.claude.json`
프로젝트(Project)	현재 프로젝트만	예 (버전 관리 통해)	프로젝트 루트의 `.mcp.json`
사용자(User)	모든 프로젝트	아니요	`~/.claude.json`

어떤 범위를 골라야 할까요?

개인 실험용 서버: 로컬(local) — 기본값입니다
팀과 공유해야 하는 서버: 프로젝트(project) — .mcp.json 파일이 만들어지고, 이걸 깃에 커밋하면 팀원 모두가 같은 설정을 공유합니다
여러 프로젝트에서 자주 쓰는 개인용 서버: 사용자(user)

예를 들어 깃허브 서버를 팀과 공유하고 싶다면 다음과 같이 입력합니다.

claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/

보안 팁: 프로젝트 범위로 설정된 .mcp.json 파일을 처음 사용할 때 클로드 코드는 사용자에게 승인 여부를 묻습니다. 신뢰할 수 있는 서버만 추가하시기 바랍니다.

7. 자주 쓰는 MCP 관리 명령

MCP 서버를 추가한 뒤에는 다음 명령으로 관리할 수 있습니다.

# 등록된 서버 목록 보기
claude mcp list

# 특정 서버 정보 확인
claude mcp get github

# 서버 제거
claude mcp remove github

클로드 코드 세션 안에서는 다음 명령으로 서버 상태를 실시간 확인할 수 있습니다.

/mcp

8. 클로드 코드를 MCP 서버로 사용하는 흥미로운 활용

공식 문서에는 잘 알려지지 않은 기능이 하나 더 있습니다. 클로드 코드 자체를 MCP 서버로 만들 수 있다는 점입니다.

claude mcp serve

이 명령을 실행하면 클로드 코드의 파일 편집·명령 실행 기능이 다른 MCP 클라이언트(예: 클로드 데스크톱, 커서, 윈드서프 등)에게 노출됩니다. 즉, 다른 AI 도구가 클로드 코드를 호출해서 작업을 위임할 수 있게 되는 것이지요. "AI가 AI를 부린다"는 흥미로운 구도입니다.

클로드 데스크톱에서는 다음과 같이 설정해서 사용할 수 있습니다.

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

9. 실무에서 꼭 알아 두면 좋은 추가 기능

도구 검색(Tool Search): 컨텍스트 절약 기능

MCP 서버를 많이 추가할수록 클로드의 컨텍스트가 부담을 받는 것 아닐까 걱정될 수 있습니다. 하지만 클로드 코드에는 도구 검색(Tool Search) 기능이 기본으로 켜져 있어, 도구 정의를 미리 통째로 불러오는 대신 필요할 때마다 검색해서 가져옵니다. 즉, 서버를 많이 등록해도 컨텍스트 부담이 거의 늘지 않습니다.

출력 토큰 한도 관리

MCP 도구의 출력이 너무 길어지면 컨텍스트가 빠르게 소진됩니다. 이를 방지하기 위해 클로드 코드는 다음과 같이 처리합니다.

경고 임계치: 도구 출력이 10,000 토큰을 넘으면 경고가 표시됩니다
기본 최대치: 25,000 토큰
조정 방법: MAX_MCP_OUTPUT_TOKENS 환경 변수로 변경 가능

export MAX_MCP_OUTPUT_TOKENS=50000
claude

자동 재연결

HTTP나 SSE 서버가 세션 중간에 끊겼을 때 클로드 코드는 지수 백오프 방식으로 자동 재연결을 시도합니다. 1초 간격으로 시작해서 최대 5회까지 재시도하며, 그 후에는 실패로 표시됩니다. stdio 로컬 서버는 자동 재연결되지 않으므로 수동으로 다시 연결해야 합니다.

MCP 리소스 참조 (@ 멘션)

연결된 서버의 리소스를 파일처럼 참조할 수 있습니다. 프롬프트에서 @를 입력하면 자동 완성 메뉴가 뜨고, 다음과 같이 사용할 수 있습니다.

@github:issue://123 을 분석하고 수정안을 제안해 줘.

10. 보안 측면에서 반드시 알아야 할 점

클로드 코드 공식 문서는 타사(third party) MCP 서버 사용에 대해 명확한 경고를 합니다.

앤트로픽은 모든 MCP 서버의 정확성과 보안을 검증하지 않았습니다. 신뢰할 수 있는 MCP 서버만 설치하시기 바랍니다. 특히 신뢰할 수 없는 콘텐츠를 가져올 가능성이 있는 MCP 서버를 사용할 때는 프롬프트 인젝션(prompt injection) 위험에 노출될 수 있으니 각별히 주의해야 합니다.

또한 위키피디아의 MCP 항목에 따르면, 2025년 4월에 보안 연구자들은 MCP에 다음과 같은 보안 이슈가 존재한다는 분석을 발표했습니다.

프롬프트 인젝션
도구 권한이 결합되어 데이터를 빼낼 가능성
신뢰받는 도구를 조용히 대체할 수 있는 유사 도구(lookalike tools)

따라서 다음 사항을 권장합니다.

자격 증명은 절대 평문으로 저장하지 말고, ${ENV_VAR} 형태의 환경 변수 문법을 사용합니다 (공식 문서 권장)
데이터베이스 연결은 가능한 한 읽기 전용 계정을 사용합니다
검증되지 않은 출처의 MCP 서버는 설치하지 않습니다
깃허브 토큰은 fine-grained 토큰으로 발급해서 필요한 저장소에만 권한을 줍니다

11. 어디서부터 시작하면 좋을까요?

처음 MCP를 시작하시는 분께 다음 순서를 권장합니다.

클로드 코드 공식 문서 정독: 먼저 1차 자료를 차분히 읽어 보시기 바랍니다.
MCP 공식 사이트에서 프로토콜 자체를 학습: MCP의 철학과 구조를 이해하면 응용이 쉬워집니다.
간단한 서버 1~2개부터 연결: 처음부터 욕심내지 말고 깃허브 1개, 데이터베이스 1개 정도로 시작하세요.
공식 MCP 서버 모음 저장소: 앤트로픽이 관리하는 공식·커뮤니티 서버 목록을 둘러볼 수 있습니다.

마무리

MCP는 단순히 "AI에 도구를 붙이는 또 하나의 방법"이 아닙니다. AI 에이전트가 외부 시스템과 표준화된 방식으로 대화할 수 있게 만드는 인프라입니다. 클로드 코드는 그중에서도 가장 적극적으로 MCP를 받아들인 도구이며, 호스트와 서버 양쪽 역할을 모두 수행할 수 있는 흥미로운 설계를 가지고 있습니다.

처음에는 명령이 길어 보이고 설정이 복잡해 보일 수 있지만, 한 번 연결한 서버는 두고두고 시간을 절약해 줍니다. "복사·붙여 넣기"의 굴레에서 벗어나 진짜 자동화된 개발 흐름을 경험해 보시기 바랍니다.

이 글이 도움이 되셨다면 주변 개발자분들에게도 공유해 주세요. 다음 글에서는 직접 MCP 서버를 만들어 보는 방법을 다뤄 보겠습니다.

클로드 코드(Claude Code) 후크(Hooks) 완전 정복 — 개념부터 실전 예제까지

2026-04-30T04:33:00.000-07:00

클로드 코드(Claude Code)를 사용하다 보면 "매번 같은 명령을 반복하라고 요청하는 게 번거롭다", "AI가 실수로 중요한 파일을 수정하면 어쩌지?"라는 생각이 들 때가 있습니다. 이런 고민을 한 방에 해결해 주는 기능이 바로 후크(Hooks) 입니다.

이번 글에서는 클로드 코드의 후크 기능이 무엇인지, 어떻게 작동하는지, 그리고 실제로 어떤 식으로 활용할 수 있는지를 공식 문서를 기반으로 쉬운 예제와 함께 자세히 설명해 드리겠습니다.

1. 후크(Hooks)란 무엇인가요?

후크는 클로드 코드의 특정 시점에 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, 또는 LLM 프롬프트입니다. 쉽게 말해, "클로드가 ~을 하기 전에 / ~을 한 후에 무조건 ~을 실행해라" 라는 규칙을 미리 설정해 두는 기능이라고 이해하시면 됩니다.

깃(Git)을 사용해 보신 분이라면 pre-commit이나 post-commit 훅을 떠올리시면 됩니다. 깃 훅이 커밋 전후에 자동으로 린터나 테스트를 실행하는 것처럼, 클로드 코드 훅은 AI가 작업하는 과정의 특정 시점에 자동으로 원하는 명령을 실행해 줍니다.

후크와 일반 프롬프트의 차이점

CLAUDE.md 파일에 "코드 수정 후에는 항상 prettier를 실행해줘"라고 적어두는 것과 후크를 설정하는 것에는 결정적인 차이가 있습니다.

프롬프트(지시문): AI에게 주는 "권장사항"입니다. 대화가 길어지면 컨텍스트 윈도우에서 밀려나거나 우선순위가 떨어져 무시될 수 있습니다.
후크: "강제 규칙"입니다. 해당 이벤트가 발생하면 100% 확정적으로 실행됩니다.

즉, 후크는 LLM의 판단에 의존하지 않고 결정론적(deterministic) 으로 동작한다는 점이 가장 큰 강점입니다.

📚 공식 문서 링크: Automate workflows with hooks

2. 후크의 생명주기(Lifecycle) - 언제 실행되나요?

후크는 클로드 코드의 동작 흐름 중 정해진 시점에 발화됩니다. 공식 문서에 따르면 후크 이벤트는 발화 빈도에 따라 크게 세 가지로 나뉩니다.

세션당 한 번 발생: SessionStart, SessionEnd
턴(turn)당 한 번 발생: UserPromptSubmit, Stop, StopFailure
에이전트 루프 안에서 도구 호출마다 발생: PreToolUse, PostToolUse

대표적인 후크 이벤트들을 표로 정리하면 다음과 같습니다.

이벤트 이름	발화 시점
`SessionStart`	세션을 새로 시작하거나 재개할 때
`UserPromptSubmit`	사용자가 프롬프트를 제출했을 때(클로드가 처리하기 전)
`PreToolUse`	도구(파일 수정, 셸 실행 등)를 사용하기 직전. 차단 가능
`PostToolUse`	도구가 성공적으로 실행된 직후
`PostToolUseFailure`	도구 실행이 실패했을 때
`Notification`	클로드가 알림을 보낼 때(권한 요청, 유휴 상태 등)
`Stop`	클로드가 응답을 마쳤을 때
`PreCompact` / `PostCompact`	컨텍스트 압축 전/후
`SessionEnd`	세션이 종료될 때

이 중에서 가장 많이 사용하는 것은 PreToolUse(도구 사용 전 차단)와 PostToolUse(도구 사용 후 후처리)입니다.

📚 전체 이벤트 목록: Hooks reference - Hook events

3. 후크 설정 파일은 어디에 두나요?

후크는 JSON 형식의 설정 파일에 정의합니다. 어디에 두느냐에 따라 적용 범위가 달라집니다.

위치	적용 범위	공유 가능 여부
`~/.claude/settings.json`	모든 프로젝트	❌ (내 컴퓨터에만 적용)
`.claude/settings.json`	현재 프로젝트	✅ (Git 저장소에 커밋 가능)
`.claude/settings.local.json`	현재 프로젝트	❌ (gitignore 처리됨)

팀원들과 동일한 후크 규칙을 공유하고 싶다면 프로젝트 폴더의 .claude/settings.json에 두고 Git에 커밋하시면 됩니다.

4. 후크 설정의 기본 구조

후크 설정은 세 단계로 중첩된 JSON 구조를 가집니다.

{
  "hooks": {
    "이벤트이름": [
      {
        "matcher": "필터조건",
        "hooks": [
          {
            "type": "command",
            "command": "실행할 명령"
          }
        ]
      }
    ]
  }
}

이를 풀어서 설명하면:

이벤트 이름: PreToolUse, PostToolUse 같은 어떤 시점에 실행할지 지정
matcher: 어떤 도구나 상황일 때만 실행할지 필터링 (예: "Bash", "Edit|Write")
hooks 배열: 실제로 실행할 명령(셸 명령, HTTP 요청 등)

5. 가장 쉬운 첫 번째 예제: 알림 후크 만들기

공식 문서의 첫 번째 튜토리얼을 따라가 보겠습니다. 클로드가 사용자 입력을 기다릴 때 데스크톱 알림을 받는 후크입니다.

macOS 사용자

~/.claude/settings.json 파일을 열고 아래 내용을 추가합니다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux 사용자

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Windows(PowerShell) 사용자

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

동작 확인 방법

클로드 코드 안에서 /hooks 명령을 입력하면 등록된 모든 후크를 확인할 수 있습니다.
클로드에게 권한 승인이 필요한 작업을 시키고 다른 창으로 전환해 봅니다.
데스크톱 알림이 뜨면 성공입니다.

Notification 이벤트는 클로드가 권한을 요청할 때뿐만 아니라, 응답이 끝나 사용자 입력을 기다리는 유휴(idle) 상태일 때도 발화됩니다. 따라서 다른 작업을 하다가도 클로드가 자신을 필요로 하는 시점을 즉시 알 수 있습니다.

💡 macOS 팁: 알림이 뜨지 않는다면, osascript가 Script Editor 앱을 통해 알림을 발송하는데 권한이 없는 경우입니다. 터미널에서 osascript -e 'display notification "test"'를 한 번 실행한 뒤, 시스템 설정 > 알림에서 Script Editor를 찾아 알림을 허용해 주세요.

6. 실전 예제 1: 코드 수정 후 자동 포맷팅

가장 유용하게 쓰이는 후크 중 하나입니다. 클로드가 파일을 수정할 때마다 자동으로 Prettier를 실행해 코드 스타일을 맞춰주는 후크입니다.

프로젝트 루트의 .claude/settings.json에 다음을 추가합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

코드 풀이

PostToolUse: 도구 실행이 끝난 직후에 발화되는 이벤트입니다.
"matcher": "Edit|Write": 파일 편집 도구(Edit)나 파일 쓰기 도구(Write)가 사용되었을 때만 실행됩니다. Bash, Read 같은 다른 도구에는 반응하지 않습니다.
jq -r '.tool_input.file_path': 후크에 stdin으로 들어온 JSON 데이터에서 file_path 값을 추출합니다.
xargs npx prettier --write: 추출한 파일 경로를 Prettier에 넘겨 포맷팅을 적용합니다.

💡 사전 준비: 이번 글의 여러 예제에서 jq라는 JSON 파싱 도구를 사용합니다. macOS에서는 brew install jq, Debian/Ubuntu에서는 apt-get install jq 명령으로 설치할 수 있습니다. 설치하지 않은 경우 Python이나 Node.js로 JSON을 파싱하셔도 됩니다.

7. 실전 예제 2: 보호된 파일 수정 차단하기

.env 파일이나 package-lock.json 같은 민감한 파일을 클로드가 실수로 수정하지 못하도록 막는 후크입니다.

1단계: 후크 스크립트 생성

.claude/hooks/protect-files.sh 파일을 만듭니다.

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

2단계: 스크립트에 실행 권한 부여 (macOS / Linux)

chmod +x .claude/hooks/protect-files.sh

3단계: 후크 등록

.claude/settings.json에 아래 내용을 추가합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

코드 풀이

PreToolUse: 도구가 실행되기 전에 발화되어 작업을 차단할 수 있습니다.
exit 2: 종료 코드 2는 "차단(blocking error)"을 의미합니다. 클로드 코드는 stderr로 출력된 메시지를 클로드에게 피드백으로 전달하고, 실제 도구 실행은 막아버립니다.
$CLAUDE_PROJECT_DIR: 프로젝트 루트 경로를 가리키는 환경 변수입니다. 작업 디렉터리와 무관하게 항상 같은 경로를 참조할 수 있습니다.

8. 종료 코드(Exit Code)의 의미

후크 스크립트는 셸의 종료 코드를 통해 클로드 코드와 소통합니다. 가장 중요한 두 가지 코드를 기억해 두세요.

종료 코드	의미
0	성공. 작업이 정상 진행됩니다.
2	차단 에러. 작업이 막히고 `stderr` 내용이 클로드에게 피드백으로 전달됩니다.
그 외	대부분의 경우 차단되지 않는 에러. 작업은 진행되지만 디버그 로그에 기록됩니다.

특히 주의할 점은, 일반적인 유닉스 관습과 달리 종료 코드 1은 차단되지 않는다는 점입니다. 정책을 강제하고 싶다면 반드시 exit 2를 사용해야 합니다.

단, 종료 코드 2의 효과는 이벤트마다 다릅니다. 대표적으로:

PreToolUse: 도구 호출을 차단합니다.
UserPromptSubmit: 프롬프트 처리를 차단하고 프롬프트를 지웁니다.
Stop: 클로드가 멈추지 못하게 막고 대화를 계속하게 합니다.
PostToolUse: 차단할 수 없습니다(이미 도구가 실행됨). stderr만 클로드에게 전달됩니다.

📚 이벤트별 상세 동작: Exit code 2 behavior per event

9. 후크에 전달되는 입력 데이터(JSON)

후크 스크립트는 stdin을 통해 JSON 형식의 데이터를 받습니다. 예를 들어, PreToolUse 이벤트에서 클로드가 npm test를 실행하려 할 때 다음과 같은 JSON이 전달됩니다.

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

이 데이터를 jq나 Python, Node.js 등으로 파싱해서 원하는 로직을 구현하시면 됩니다.

모든 이벤트에 공통으로 전달되는 필드

session_id: 현재 세션의 고유 식별자
transcript_path: 대화 기록 JSON 파일 경로
cwd: 후크가 호출된 시점의 작업 디렉터리
hook_event_name: 발화된 이벤트 이름

도구 관련 이벤트에는 추가로 tool_name(도구 이름)과 tool_input(도구 인자)이 전달됩니다.

10. 후크 종류 5가지

클로드 코드는 5가지 후크 핸들러 타입을 지원합니다.

Command 후크 (type: "command"): 셸 명령을 실행합니다. 가장 빠르고 유연합니다.
HTTP 후크 (type: "http"): JSON 데이터를 지정된 URL로 POST 요청을 보냅니다. 외부 서비스 연동에 유용합니다.
MCP Tool 후크 (type: "mcp_tool"): 이미 연결된 MCP 서버의 도구를 호출합니다.
Prompt 후크 (type: "prompt"): 클로드 모델(기본은 Haiku)에 프롬프트를 보내 단일 턴 평가를 받습니다. 모델은 {"ok": true/false} 형태로 yes/no 결정을 반환합니다.
Agent 후크 (type: "agent"): 도구를 사용할 수 있는 서브에이전트를 띄워 조건을 검증합니다. (실험적 기능)

대부분의 경우 Command 후크 하나만 알아도 충분합니다.

11. 실전 예제 3: 위험한 명령(rm -rf) 차단하기

공식 문서에서 소개하는 가장 대표적인 예제입니다. rm -rf 같은 파괴적인 셸 명령을 차단합니다.

후크 설정

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

후크 스크립트 (`.claude/hooks/block-rm.sh`)

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0
fi

동작 흐름

클로드가 Bash 도구로 명령을 실행하려 할 때 PreToolUse 이벤트가 발화됩니다.
matcher: "Bash"가 일치하므로 이 후크 그룹이 활성화됩니다.
if: "Bash(rm *)" 조건이 추가로 평가되어, rm으로 시작하는 명령에만 스크립트가 실행됩니다.
스크립트가 실제 명령을 검사해 rm -rf가 포함되어 있으면 JSON으로 거부 결정을 출력합니다.
npm test 같은 안전한 명령이었다면 if 조건에서 걸러져 스크립트 자체가 실행되지 않으므로 성능 오버헤드도 없습니다.

이 예제는 후크의 두 가지 핵심 패턴을 동시에 보여줍니다.

종료 코드만 사용하는 단순한 차단 방식 (앞선 보호 파일 예제)
JSON 출력으로 더 정교하게 결정 제어 (이번 예제의 permissionDecision)

12. 후크는 어떻게 디버깅하나요?

방법 1: `/hooks` 메뉴 활용

클로드 코드 세션 안에서 /hooks를 입력하면 현재 등록된 모든 후크를 이벤트별로 확인할 수 있습니다. 어떤 설정 파일에서 왔는지(User, Project, Local, Plugin 등)도 표시되어 매우 편리합니다.

방법 2: 수동 테스트

JSON 입력을 직접 만들어 후크 스크립트에 넘겨보면 클로드 코드를 거치지 않고도 동작을 확인할 수 있습니다.

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # 종료 코드 확인

방법 3: 디버그 로그

클로드 코드를 실행할 때 --debug-file 옵션을 사용하면 모든 후크 실행 내역이 기록됩니다.

claude --debug-file /tmp/claude.log

다른 터미널에서 다음 명령으로 실시간 모니터링이 가능합니다.

tail -f /tmp/claude.log

이미 세션이 시작된 상태라면 /debug 명령으로 도중에 디버그 로그를 켤 수도 있습니다.

13. 자주 겪는 문제와 해결법

공식 문서에서 안내하는 대표적인 트러블슈팅 케이스입니다.

"Stop 후크가 무한 루프에 빠져요"

Stop 이벤트로 클로드를 계속 작업시키는 후크를 만들 때, 종료 조건을 두지 않으면 영원히 멈추지 않습니다. 입력 JSON의 stop_hook_active 필드를 확인해서 일찍 종료하도록 만들어야 합니다.

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
# 이후 후크 로직

"JSON 파싱 에러가 나요"

클로드 코드가 후크를 실행할 때 셸 프로필(~/.zshrc, ~/.bashrc)을 함께 로드합니다. 만약 프로필에 무조건 실행되는 echo 문이 있다면 그 출력이 후크 JSON 앞에 붙어버려 파싱이 실패합니다. 다음과 같이 인터랙티브 셸에서만 실행되도록 감싸주세요.

if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

"후크가 아예 실행되지 않아요"

/hooks로 후크가 올바르게 등록되어 있는지 확인하세요.
matcher 패턴이 도구 이름과 정확히 일치하는지 확인하세요. 매처는 대소문자를 구분합니다.
스크립트 파일에 실행 권한(chmod +x)이 있는지 확인하세요.

📚 더 많은 트러블슈팅: Limitations and troubleshooting

14. 후크 사용 시 보안 주의사항

후크는 사용자의 시스템 권한 전체로 실행됩니다. 따라서 다음 사항을 꼭 지켜주세요.

신뢰할 수 없는 출처의 후크 설정을 그대로 가져다 쓰지 마세요.
후크 명령을 추가하기 전에 반드시 코드를 직접 검토하세요.
외부 입력 값을 그대로 셸 명령에 넘기는 일은 피하세요(쉘 인젝션 위험).
.env, 비밀 키 같은 민감 파일에 후크가 접근하지 않도록 주의하세요.

특히 후크 설정은 .claude/settings.json을 통해 Git 저장소에 공유될 수 있으므로, 팀에서 공유되는 후크는 코드 리뷰를 거치는 것이 안전합니다.

15. 후크 활용 아이디어 모음

공식 문서와 가이드에서 소개하는 활용 사례입니다.

자동 포맷팅: 파일 수정 후 Prettier, Black, Ruff 등 자동 실행
자동 린팅: 코드 작성 후 ESLint, Pylint 등으로 검사
자동 테스트: 변경된 파일에 대한 단위 테스트 자동 실행
민감 파일 보호: .env, secrets/ 등 수정 차단
위험 명령 차단: rm -rf, DROP TABLE 등 차단
Git 브랜치 보호: main, master 브랜치 직접 푸시 차단
세션 시작 시 컨텍스트 주입: 현재 브랜치, 진행 중인 이슈 등 자동 입력
알림: Slack, 데스크톱 알림으로 작업 완료 통보
감사 로그: 모든 도구 사용 내역을 파일에 기록
컨텍스트 압축 후 재주입: 압축으로 손실된 중요 정보 복구

16. 마무리

후크는 클로드 코드를 단순한 AI 도우미에서 신뢰할 수 있는 자동화된 개발 파트너로 진화시키는 핵심 기능입니다. 처음에는 설정이 복잡해 보일 수 있지만, 이 글에서 소개한 알림 후크나 자동 포맷팅 후크처럼 작은 것부터 시작해서 조금씩 늘려가시면 됩니다.

처음 시도해 볼 만한 후크 추천 순서는 다음과 같습니다.

데스크톱 알림 후크 (Notification): 가장 간단하고 즉시 효과를 체감할 수 있습니다.
자동 포맷팅 후크 (PostToolUse + Edit/Write): 코드 품질을 자동으로 유지할 수 있습니다.
민감 파일 보호 후크 (PreToolUse): 실수를 원천 차단해 안심하고 클로드를 사용할 수 있습니다.

후크의 진정한 가치는 단순히 작업을 자동화하는 것을 넘어, AI에게 더 많은 자율성을 안전하게 부여할 수 있게 해준다는 점에 있습니다. 자동 검증 레이어가 있으면 클로드를 더 적극적으로 활용해도 불안하지 않으니까요.

더 깊이 공부하고 싶다면

여러분의 클로드 코드 워크플로우가 더 안전하고 효율적이 되기를 바랍니다.

클로드 코드(Claude Code) 스킬(Skills) 기능 완벽 가이드 — 예제로 쉽게 이해하기

2026-04-29T18:09:14.210-07:00

클로드 코드(Claude Code)에서 **스킬(Skills)**은 가장 강력한 확장 기능 중 하나입니다. 같은 지시를 매번 반복해서 입력하는 것이 번거로우셨다면, 스킬 기능이 바로 그 문제를 해결해 줄 수 있습니다.

이 글에서는 클로드 코드 스킬이 무엇인지, 어떻게 동작하는지, 그리고 직접 만들어 사용하는 방법까지 쉬운 예제와 함께 차근차근 알려드리겠습니다.

📌 클로드 코드(Claude Code)란? Anthropic이 제공하는 에이전트형 코딩 도구로, 터미널, IDE, 데스크톱 앱, 브라우저 등 다양한 환경에서 클로드에게 코딩 작업을 맡길 수 있습니다. 이 글에서 다루는 스킬 기능은 Claude.ai와 Claude API에서도 동일한 형식으로 사용할 수 있습니다.

1. 스킬(Skills)이란 무엇인가요?

스킬은 클로드(Claude)에게 특정 작업을 수행하는 방법을 미리 알려주는 폴더입니다. 한 번 만들어두면 클로드가 관련 작업을 할 때마다 알아서 그 지침을 참고하기 때문에, 매번 같은 설명을 반복할 필요가 없습니다.

Anthropic의 공식 문서에 따르면, 스킬은 워크플로, 컨텍스트, 모범 사례를 담은 재사용 가능한 파일시스템 기반 리소스입니다. 일반적인 프롬프트가 한 번의 대화에서만 적용되는 일회성 지시라면, 스킬은 여러 대화에 걸쳐 동일한 지침을 반복하지 않아도 되도록 만들어줍니다.

핵심 특징을 정리하면 다음과 같습니다.

폴더 단위로 구성되며, 그 안에 SKILL.md 파일이 반드시 들어 있습니다.
클로드가 작업 내용에 맞춰 자동으로 관련 스킬을 불러옵니다.
필요한 시점에만 로드되기 때문에 컨텍스트(맥락) 창을 효율적으로 사용합니다.
공식 문서 작성용(PDF, Word, Excel, PowerPoint 등) 스킬은 Anthropic에서 미리 만들어 제공합니다.

💡 참고: 스킬은 클로드 코드뿐 아니라 Claude.ai, Claude API에서도 동일한 형식으로 동작하도록 설계된 Agent Skills 공개 표준을 따릅니다.

2. 스킬이 왜 필요한가요?

스킬 기능이 만들어진 배경에는 몇 가지 명확한 이유가 있습니다.

1) 반복되는 지시를 한 번에 정리할 수 있습니다

매번 새로운 대화를 시작할 때마다 "우리 회사 브랜드 컬러는 #FF6B35이고, 헤더는 Montserrat Bold를 써주세요"라고 입력하는 건 번거롭습니다. 스킬에 한 번만 적어두면 이후로는 자동으로 적용됩니다.

2) 컨텍스트 창을 효율적으로 씁니다

스킬은 점진적 공개(Progressive Disclosure) 방식으로 동작합니다. 처음에는 스킬의 이름과 설명(description)만 클로드의 시스템 프롬프트에 로드되고, 실제로 그 스킬이 필요한 순간이 오면 그제서야 본문 내용을 읽어 들입니다.

이 덕분에 수십 개의 스킬을 설치해두어도 평소에는 컨텍스트를 거의 잡아먹지 않습니다.

3) 팀과 공유하기 쉽습니다

스킬은 단순한 폴더이므로 Git으로 버전 관리가 가능하고, 팀원들과 동일한 작업 표준을 공유할 수 있습니다.

스킬 vs CLAUDE.md vs MCP — 무엇이 다른가요?

처음 클로드 코드를 접하면 비슷해 보이는 개념들이 많아 헷갈리실 수 있습니다. 간단히 정리하면 다음과 같습니다.

CLAUDE.md — 프로젝트의 영구적인 컨텍스트 파일로, 매 대화마다 항상 로드됩니다. 짧은 사실 정보(우리 회사는 무엇을 하는지, 사용하는 기술 스택은 무엇인지 등)에 적합합니다.
스킬(Skills) — 필요할 때만 로드되는 절차적 지침입니다. 본문이 길어도 사용하지 않는 동안에는 컨텍스트를 차지하지 않습니다.
MCP(Model Context Protocol) — 외부 도구와 시스템에 연결해서 새로운 기능을 추가합니다(예: Slack, Asana, 데이터베이스 등).

공식 문서에서는 CLAUDE.md의 한 섹션이 단순한 사실 정보가 아니라 점점 절차적인 내용으로 자라났다면, 그것이 스킬로 옮겨야 할 신호라고 설명합니다.

3. 스킬의 구조 — SKILL.md 파일 살펴보기

모든 스킬은 SKILL.md라는 마크다운 파일을 중심으로 구성됩니다. 이 파일은 두 부분으로 나뉩니다.

YAML 프론트매터(Frontmatter) — 스킬의 메타데이터(이름, 설명 등)
마크다운 본문 — 클로드가 따라야 할 실제 지침

가장 기본적인 SKILL.md 예시

Anthropic 공식 스킬 저장소에서 제공하는 템플릿은 다음과 같이 생겼습니다.

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[클로드가 이 스킬을 활성화했을 때 따를 지침을 여기에 작성합니다]

## Examples
- 사용 예시 1
- 사용 예시 2

## Guidelines
- 가이드라인 1
- 가이드라인 2

프론트매터의 필수 필드

공식 문서에 따르면, YAML 프론트매터에는 두 개의 필드가 필수입니다.

필드	설명	제한
`name`	스킬 이름. 슬래시 명령어로도 사용됩니다.	최대 64자, 소문자/숫자/하이픈만 허용
`description`	스킬이 무엇을 하고 언제 써야 하는지에 대한 설명	최대 1024자

description이 가장 중요합니다. 클로드는 이 설명만 보고 "지금 이 스킬을 써야 할까?"를 판단하기 때문입니다. 그래서 "무엇을 하는지 + 언제 써야 하는지"를 명확하게 적어야 합니다.

폴더 구조

스킬은 단순한 마크다운 파일이 아니라 폴더입니다. 필요하다면 보조 파일들을 함께 넣을 수 있습니다.

my-skill/
├── SKILL.md          (필수)
├── scripts/          (선택: 클로드가 실행할 수 있는 스크립트)
├── references/       (선택: 필요할 때 참고하는 추가 문서)
└── assets/           (선택: 템플릿, 아이콘, 폰트 등)

💡 팁: 공식 모범 사례 가이드에서는 SKILL.md 본문을 500줄 이내로 유지하라고 권장합니다. 그보다 길어지면 별도 파일로 쪼개는 것이 좋습니다.

4. 직접 만들어보는 간단한 스킬 예제

이론은 이쯤 하고, 실제로 동작하는 간단한 스킬 하나를 만들어보겠습니다.

예제: 코드 설명 스킬 만들기

Claude Code 공식 문서에서 소개하는 예제를 그대로 따라가 보겠습니다. 코드를 받았을 때 비유와 다이어그램을 사용해 설명하도록 가르치는 스킬입니다.

1단계: 폴더와 파일 만들기

홈 디렉터리 아래에 다음 경로로 파일을 만듭니다.

~/.claude/skills/explain-code/SKILL.md

2단계: 파일에 내용 작성하기

---
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

3단계: 사용해보기

이제 클로드 코드 안에서 코드 파일을 보여주며 "이 코드 어떻게 동작해?"라고 물어보면, 클로드가 자동으로 이 스킬을 불러와 비유와 다이어그램을 곁들인 설명을 해줍니다. 또는 명시적으로 /explain-code 명령어로 호출할 수도 있습니다.

폴더 위치 두 가지 — 개인용 vs 프로젝트용

스킬을 어디에 두느냐에 따라 적용 범위가 달라집니다.

개인용(User-level) — ~/.claude/skills/ 경로에 두면 모든 프로젝트에서 사용할 수 있습니다.
프로젝트용(Project-level) — 프로젝트 폴더 안의 .claude/skills/ 경로에 두면 해당 프로젝트에서만 적용되며, Git을 통해 팀원들과 공유할 수 있습니다.

5. 한 단계 더 — 좋은 description 쓰는 법

스킬을 만들어도 클로드가 알아서 써주지 않는다면 십중팔구 description이 모호하기 때문입니다. 공식 문서와 모범 사례에서 강조하는 좋은 description의 공식은 다음과 같습니다.

무엇을 하는지 + 언제 써야 하는지 + 핵심 기능

나쁜 예와 좋은 예 비교

❌ 나쁜 예시:

description: Helps with code

너무 광범위해서 클로드가 언제 호출해야 할지 판단할 수 없습니다.

✅ 좋은 예시:

description: Reviews pull requests for security vulnerabilities using OWASP Top 10. Use when reviewing PRs, auditing code for security issues, or when the user mentions security review.

이렇게 적으면 클로드는 "PR 리뷰", "보안 검토" 같은 키워드가 등장할 때 자동으로 이 스킬을 활성화합니다.

💡 공식 가이드의 팁: 클로드는 스킬을 "덜 호출하는" 경향이 있다고 알려져 있습니다. 그래서 description에 트리거 단어들을 명시적으로 적어주는 것이 활성화율을 높이는 데 도움이 됩니다.

6. 미리 만들어진 스킬 사용하기

직접 만들지 않아도 Anthropic이 제공하는 공식 스킬들을 바로 쓸 수 있습니다. 대표적으로는 다음과 같은 것들이 있습니다.

docx — Word 문서 생성, 편집, 분석
pdf — PDF 텍스트/표 추출, 폼 작성, 병합/분할
pptx — PowerPoint 슬라이드 생성 및 편집
xlsx — Excel 스프레드시트 작업
claude-api — Claude API 사용 시 최신 SDK 문서와 모범 사례 제공

이 스킬들은 Anthropic 공식 스킬 저장소에서 확인할 수 있고, 유료 플랜(Pro, Max, Team, Enterprise)의 Claude.ai에서는 이미 사용 가능하도록 준비되어 있습니다.

클로드 코드에서 플러그인으로 설치하기

클로드 코드에서는 Anthropic 공식 스킬 저장소를 플러그인 마켓플레이스로 등록해서 스킬을 설치할 수 있습니다. 클로드 코드 안에서 다음 명령을 입력하면 됩니다.

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

설치 후에는 "PDF 스킬을 써서 이 파일의 폼 필드를 추출해줘" 같이 자연스럽게 요청하면 클로드가 알아서 해당 스킬을 사용합니다.

7. 스킬 사용 가능 환경

공식 도움말 문서에 따르면, 커스텀 스킬은 다음 환경에서 사용할 수 있습니다.

Claude.ai — Pro, Max, Team, Enterprise 플랜에서 코드 실행이 활성화된 경우 사용 가능합니다. 설정(Settings) → 기능(Features)에서 zip 파일로 업로드합니다.
Claude API — Skills API를 통해 업로드하고 사용할 수 있습니다.
클로드 코드 — .claude/skills/ 디렉터리에 폴더로 두거나 플러그인 마켓플레이스로 설치합니다.

⚠️ 중요: 공식 문서에 따르면, 한 곳에 업로드한 스킬이 다른 환경으로 자동 동기화되지는 않습니다. 즉 Claude.ai에 업로드한 스킬은 API에 별도로 업로드해야 하고, 클로드 코드의 스킬은 파일시스템 기반이라 둘 모두와 별개로 관리됩니다.

8. 안전하게 사용하기 위한 주의사항

스킬은 강력한 만큼 사용에 주의가 필요합니다. Anthropic 공식 문서에서도 다음을 강조하고 있습니다.

신뢰할 수 있는 출처의 스킬만 사용하세요. 스킬은 클로드 환경에서 임의의 코드를 실행할 수 있습니다. 본인이 직접 만들었거나 Anthropic이 공식 제공하는 스킬을 우선적으로 사용할 것이 권장됩니다.
민감 정보를 하드코딩하지 마세요. API 키, 비밀번호, 토큰 같은 정보는 스킬 파일에 직접 적지 말아야 합니다.
외부에서 받은 스킬은 활성화 전에 내용을 검토하세요.

9. 정리

여기까지 클로드 코드 스킬 기능에 대해 알아보았습니다. 핵심을 다시 한번 정리하면 다음과 같습니다.

스킬은 클로드에게 특정 작업 방법을 알려주는 폴더입니다.
SKILL.md 파일 하나만 있으면 시작할 수 있고, 프론트매터의 name과 description이 핵심입니다.
점진적 공개 방식 덕분에 많이 설치해도 컨텍스트 창을 거의 차지하지 않습니다.
개인용은 ~/.claude/skills/, **프로젝트용은 프로젝트의 .claude/skills/**에 둡니다.
공식 스킬을 그대로 쓰거나, 직접 만들어서 팀과 공유하거나, 마켓플레이스에서 가져올 수 있습니다.

매일 같은 지시를 반복하고 있다면, 그것이 바로 스킬로 만들어야 한다는 신호입니다. 작은 스킬 하나부터 시작해보시면 워크플로가 한층 가벼워지는 것을 느끼실 수 있을 겁니다.

📚 참고 자료

클로드 코드(Claude Code) 서브에이전트(Subagents), 쉬운 예제로 완벽 이해하기

2026-04-29T17:51:00.000-07:00

클로드 코드(Claude Code)를 사용하다 보면 작업이 길어질수록 대화창이 무거워지고, 응답 속도가 느려지는 경험을 하게 됩니다. 이런 문제를 해결하기 위해 등장한 기능이 바로 서브에이전트(Subagents) 입니다. 이 글에서는 서브에이전트가 무엇인지, 왜 필요한지, 그리고 어떻게 사용하는지를 누구나 이해할 수 있는 쉬운 예제와 함께 정리해 드립니다.

참고로 이 글의 모든 내용은 Anthropic 공식 클로드 코드 문서를 기반으로 작성되었습니다.

1. 서브에이전트란 무엇인가요?

서브에이전트는 특정 작업을 전담하는 별도의 AI 보조 일꾼입니다. 메인 클로드(주 대화창)가 큰 프로젝트의 총괄 매니저라면, 서브에이전트는 매니저가 특정 업무를 맡기는 전문 직원이라고 생각하시면 됩니다.

핵심 특징은 다음과 같습니다.

독립된 대화창(컨텍스트 윈도우)에서 작업합니다. 즉, 서브에이전트가 처리한 내용은 메인 대화창을 어지럽히지 않습니다.
자체 시스템 프롬프트를 가지고 있어서, 특정 분야의 전문가처럼 행동하도록 설정할 수 있습니다.
사용 가능한 도구를 제한할 수 있어서, 보안과 안전성을 높일 수 있습니다.
작업이 끝나면 결과 요약만 메인 대화창으로 돌려보냅니다.

쉬운 비유: 회사의 팀장과 팀원

서브에이전트를 이해하는 가장 쉬운 방법은 회사를 떠올려 보시는 것입니다.

여러분이 팀장이라고 가정해 봅시다. 신규 기능을 개발해야 하는데, 그 전에 "기존 인증 시스템이 어떻게 동작하는지" 먼저 파악해야 합니다. 만약 팀장이 직접 100개의 코드 파일을 다 읽으면 머릿속이 너무 복잡해져서 정작 중요한 설계 작업에 집중할 수 없겠죠.

이때 팀장은 신입 사원에게 "기존 인증 시스템을 분석해서 핵심 내용만 한 페이지로 요약해 와" 라고 지시합니다. 신입 사원은 자기 자리에서 100개 파일을 모두 분석한 뒤, 핵심 요약만 들고 옵니다. 팀장은 100개 파일을 직접 보지 않고도 필요한 정보를 얻을 수 있습니다.

이 신입 사원이 바로 서브에이전트입니다.

2. 왜 서브에이전트가 필요한가요?

공식 문서에 따르면 서브에이전트는 다음과 같은 다섯 가지 이점을 제공합니다.

첫째, 컨텍스트 보존입니다. 탐색이나 조사 작업을 메인 대화창 밖에서 처리해서 메인 대화창을 깔끔하게 유지합니다.

둘째, 제약 조건 강제입니다. 서브에이전트가 사용할 수 있는 도구를 제한해서 의도하지 않은 작업을 방지합니다.

셋째, 설정 재사용입니다. 한 번 만든 서브에이전트를 여러 프로젝트에서 반복해서 사용할 수 있습니다.

넷째, 전문화된 행동입니다. 특정 도메인에 집중된 시스템 프롬프트로 해당 분야의 전문가처럼 동작합니다.

다섯째, 비용 절감입니다. 단순한 작업은 더 빠르고 저렴한 모델(예: Haiku)로 라우팅할 수 있습니다.

3. 클로드 코드에 기본 내장된 서브에이전트

클로드 코드를 설치하면 별도 설정 없이도 사용할 수 있는 내장 서브에이전트가 있습니다. 클로드가 상황에 맞게 자동으로 호출합니다.

Explore (탐색): 코드베이스를 검색하고 분석하는 데 최적화된 빠른 읽기 전용 에이전트입니다. Haiku 모델을 사용해서 속도가 빠르며, Write와 Edit 도구는 사용할 수 없습니다.

Plan (계획): 플랜 모드에서 코드베이스를 조사할 때 사용되는 에이전트입니다. 메인 대화의 모델을 그대로 상속받으며, 읽기 전용입니다.

General-purpose (범용): 탐색과 수정을 모두 필요로 하는 복잡한 다단계 작업에 사용됩니다. 모든 도구에 접근할 수 있습니다.

이 외에도 statusline-setup, Claude Code Guide 같은 보조 에이전트가 자동으로 호출되어 동작합니다.

4. 가장 쉬운 예제: 코드 리뷰 서브에이전트 만들기

이제 실제 예제를 살펴보겠습니다. 가장 흔하게 사용되는 코드 리뷰 서브에이전트입니다.

4-1. 서브에이전트 파일의 기본 구조

서브에이전트는 YAML 프론트매터(frontmatter) + 마크다운 본문 형태의 파일로 정의됩니다. 파일 확장자는 .md입니다.

---
name: code-reviewer
description: 코드 품질, 보안, 유지보수성을 검토하는 전문가. 코드 작성/수정 직후 적극적으로 사용할 것.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 높은 코드 품질과 보안 기준을 보장하는 시니어 코드 리뷰어입니다.

호출되었을 때:
1. git diff를 실행하여 최근 변경 사항을 확인합니다
2. 수정된 파일에 집중합니다
3. 즉시 리뷰를 시작합니다

리뷰 체크리스트:
- 코드가 명확하고 가독성이 좋은가
- 함수와 변수의 이름이 적절한가
- 중복된 코드는 없는가
- 적절한 에러 처리가 되어 있는가
- 노출된 비밀키나 API 키는 없는가

피드백은 우선순위별로 구성합니다:
- 치명적 문제 (반드시 수정)
- 경고 (수정 권장)
- 제안 (개선 고려)

4-2. 각 항목이 뜻하는 것

상단의 ---로 감싸진 부분이 프론트매터이고, 메타데이터를 담습니다.

name: 서브에이전트의 고유 이름입니다. 소문자와 하이픈만 사용 가능합니다. (필수)
description: 클로드가 "언제 이 서브에이전트를 호출해야 할지" 판단하는 기준입니다. (필수)
tools: 사용 가능한 도구 목록입니다. 여기서는 읽기 도구만 허용해서 안전하게 만들었습니다.
model: 사용할 모델입니다. sonnet, opus, haiku, inherit(메인과 동일) 중 선택할 수 있습니다.

--- 아래의 본문은 시스템 프롬프트입니다. 서브에이전트가 어떻게 행동해야 할지를 자세히 알려주는 부분입니다.

4-3. 어디에 저장하나요?

저장 위치에 따라 적용 범위가 달라집니다.

저장 위치	적용 범위
`.claude/agents/`	현재 프로젝트에서만 사용
`~/.claude/agents/`	내 컴퓨터의 모든 프로젝트에서 사용

팀과 공유하고 싶다면 .claude/agents/에 저장하고 git에 커밋하시면 됩니다.

5. 서브에이전트를 만드는 가장 쉬운 방법: `/agents` 명령어

직접 파일을 만드는 게 부담스러우시다면, 클로드 코드에서 제공하는 대화형 인터페이스를 사용하시면 됩니다.

클로드 코드 안에서 다음 명령어를 입력합니다.

/agents

그러면 탭 형태의 인터페이스가 열리고, 다음 단계로 서브에이전트를 만들 수 있습니다.

Library 탭으로 이동 후 Create new agent 선택
저장 범위 선택 (Personal 또는 Project)
Generate with Claude를 선택해서 클로드가 자동으로 식별자, 설명, 시스템 프롬프트를 생성하도록 합니다
사용할 도구 선택 (예: 읽기 전용 도구만 허용)
모델 선택
색상 선택 (UI에서 어떤 서브에이전트가 동작 중인지 식별하는 용도)
메모리 설정 (선택 사항)
저장 후 즉시 사용 가능

저장한 뒤에는 다음과 같이 자연어로 호출할 수 있습니다.

code-reviewer 에이전트를 사용해서 이 프로젝트의 개선점을 알려줘

6. 일상 업무로 보는 실제 활용 예제 3가지

이제 서브에이전트가 실제로 어떻게 도움이 되는지 세 가지 시나리오로 살펴보겠습니다.

예제 1: 테스트 실행 결과 정리

테스트 스위트를 돌리면 보통 수백, 수천 줄의 출력이 쏟아집니다. 메인 대화창에서 직접 돌리면 컨텍스트가 폭발적으로 차오릅니다.

이때는 다음과 같이 요청하면 됩니다.

서브에이전트를 사용해서 테스트 스위트를 실행하고, 실패한 테스트와 그 에러 메시지만 보고해줘

서브에이전트가 자기 대화창에서 모든 출력을 받아서 처리하고, 메인 대화창에는 실패 항목 요약만 돌아옵니다.

예제 2: 병렬로 여러 모듈 조사하기

큰 프로젝트에서 여러 모듈을 동시에 파악해야 할 때가 있습니다.

인증, 데이터베이스, API 모듈을 각각 별도의 서브에이전트로 병렬 조사해줘

세 서브에이전트가 동시에 자기 영역을 분석하고, 각자 요약된 결과를 가져옵니다. 한 번에 직렬로 조사하는 것보다 훨씬 빠릅니다.

예제 3: 다단계 워크플로우 체이닝

여러 단계로 이어지는 작업도 서브에이전트를 연결해서 처리할 수 있습니다.

code-reviewer 서브에이전트로 성능 이슈를 찾고, 그 다음 optimizer 서브에이전트로 그 이슈들을 수정해줘

각 서브에이전트가 자기 임무에만 집중하므로 결과의 품질이 높아집니다.

7. 서브에이전트를 명시적으로 호출하는 세 가지 방법

자동 위임에만 의존하기보다, 직접 호출하고 싶을 때가 있습니다. 공식 문서에서는 세 가지 방법을 제시합니다.

자연어 호출: 프롬프트에 서브에이전트 이름을 그냥 적어주시면 됩니다. 클로드가 위임 여부를 판단합니다.

code-reviewer 서브에이전트로 최근 변경 사항을 검토해줘

@-멘션: @를 입력하면 사용 가능한 서브에이전트 목록이 나타납니다. 이렇게 호출하면 반드시 그 서브에이전트가 실행됩니다.

@"code-reviewer (agent)" 인증 관련 변경 사항을 살펴봐줘

세션 전체에 적용: 클로드 코드를 시작할 때 --agent 플래그를 사용하면 세션 전체가 해당 서브에이전트의 시스템 프롬프트로 동작합니다.

claude --agent code-reviewer

8. 서브에이전트를 사용해야 할 때 vs 사용하지 말아야 할 때

서브에이전트가 만능은 아닙니다. 공식 문서는 명확한 가이드를 제공합니다.

메인 대화창을 사용해야 할 때:

잦은 상호작용과 반복적 다듬기가 필요할 때
여러 단계가 같은 컨텍스트를 공유할 때 (계획 → 구현 → 테스트)
빠르고 작은 변경을 할 때
응답 속도가 중요할 때 (서브에이전트는 컨텍스트를 새로 모으느라 시간이 걸립니다)

서브에이전트를 사용해야 할 때:

작업이 메인 컨텍스트에 굳이 필요 없는 장황한 출력을 만들 때
특정 도구 제한이나 권한을 강제하고 싶을 때
작업이 독립적이고 요약만 돌려받으면 될 때

또한, 서브에이전트는 다른 서브에이전트를 다시 호출할 수 없다는 제한이 있습니다. 중첩된 위임이 필요하다면 Skills 기능을 사용하거나, 메인 대화창에서 서브에이전트를 차례로 호출하는 방식을 써야 합니다.

9. 서브에이전트의 권한과 안전성

서브에이전트의 강력한 점 중 하나는 권한을 세밀하게 제어할 수 있다는 것입니다.

tools 필드로 사용 가능한 도구를 화이트리스트로 지정할 수도 있고, disallowedTools 필드로 특정 도구만 차단할 수도 있습니다. 예를 들어 다음과 같이 설정하면 파일 쓰기를 제외한 모든 도구를 사용할 수 있습니다.

---
name: no-writes
description: Write와 Edit를 제외한 모든 도구 상속
disallowedTools: Write, Edit
---

또한 permissionMode 필드로 권한 프롬프트 동작 방식도 제어할 수 있습니다. default(표준 확인), acceptEdits(편집 자동 승인), dontAsk(자동 거부), plan(읽기 전용 탐색) 등 다양한 모드가 있습니다.

10. 함께 알아두면 좋은 관련 기능

서브에이전트와 함께 보면 시너지가 큰 기능들입니다.

플러그인(Plugins): 서브에이전트를 패키지화해서 팀이나 프로젝트 간에 공유할 수 있습니다.

MCP 서버: 서브에이전트에 외부 도구나 데이터 접근 권한을 부여할 수 있습니다.

훅(Hooks): 서브에이전트의 도구 실행 전후에 자동으로 실행되는 스크립트를 설정할 수 있습니다.

스킬(Skills): 서브에이전트가 시작할 때 미리 도메인 지식을 주입할 수 있습니다.

에이전트 SDK: 클로드 코드를 프로그래밍 방식으로 사용할 때 서브에이전트를 정의하는 방법입니다.

마치며

서브에이전트는 클로드 코드를 단순한 AI 비서에서 체계적인 개발 시스템으로 끌어올리는 핵심 기능입니다. 처음에는 어렵게 느껴질 수 있지만, /agents 명령어로 대화형 생성을 한 번 해보시면 곧 익숙해지실 것입니다.

핵심 요약은 다음과 같습니다.

서브에이전트는 독립된 작업 공간을 가진 전문 일꾼입니다.
컨텍스트 절약, 권한 제어, 재사용성, 전문화, 비용 절감이라는 다섯 가지 이점이 있습니다.
마크다운 파일에 YAML 프론트매터를 넣어 정의합니다.
/agents 명령어로 손쉽게 만들 수 있습니다.
자동 위임, 자연어 호출, @-멘션, --agent 플래그 등 다양한 방법으로 호출할 수 있습니다.

더 자세한 정보는 Anthropic 공식 문서에서 확인하실 수 있습니다.

클로드 코드(Claude Code) Channels 기능으로 텔레그램 연동하는 방법 완벽 가이드

2026-04-28T05:37:00.000-07:00

클로드 코드(Claude Code)를 사용하다 보면 한 가지 불편한 점이 있습니다. 바로 터미널 앞에 계속 붙어 있어야 한다는 것입니다. 긴 작업을 시켜 놓고 외출하거나, 잠시 자리를 비울 때 작업 진행 상황을 확인하기 어렵습니다.

이 문제를 해결하기 위해 Anthropic은 Channels 기능을 리서치 프리뷰로 공개했습니다. Channels를 활용하면 텔레그램, 디스코드, iMessage 같은 메신저 앱에서 클로드 코드 세션과 직접 대화할 수 있습니다.

이 글에서는 그중에서도 가장 많이 사용되는 텔레그램 연동 방법을 처음부터 끝까지 자세히 다루겠습니다.

Channels 기능이란?

공식 문서에 따르면, Channels는 MCP(Model Context Protocol) 서버를 통해 외부 이벤트를 실행 중인 클로드 코드 세션으로 푸시하는 기능입니다.

핵심 특징을 정리하면 다음과 같습니다.

양방향 통신이 가능합니다. 클로드가 이벤트를 읽고 같은 채널을 통해 답장합니다.
이벤트는 세션이 열려 있을 때만 도착합니다. 따라서 항상 켜 두려면 백그라운드 프로세스나 영구 터미널에서 실행해야 합니다.
플러그인 형태로 설치합니다. 사용자가 직접 자신의 자격 증명으로 설정하는 구조입니다.

리서치 프리뷰에는 텔레그램, 디스코드, iMessage가 포함되어 있습니다.

다른 기능과의 차이점

클로드 코드에는 외부 시스템과 연결되는 여러 기능이 있는데, 각 기능의 역할이 다릅니다.

Claude Code on the web: GitHub에서 복제된 새로운 클라우드 샌드박스에서 작업을 실행합니다.
Claude in Slack: Slack 채널이나 스레드에서 @Claude 멘션으로 웹 세션을 생성합니다.
표준 MCP 서버: 클로드가 작업 중에 쿼리하는 방식이며, 세션으로 무엇이 푸시되지는 않습니다.
Remote Control: claude.ai나 모바일 앱에서 로컬 세션을 조작합니다.

Channels는 외부 소스에서 발생한 이벤트를 이미 실행 중인 로컬 세션으로 푸시한다는 점에서 위 기능들과 차이가 있습니다.

알아두면 좋은 동작 방식

공식 문서에 따르면, 클로드가 채널을 통해 답장할 때 터미널에서는 인바운드 메시지는 볼 수 있지만 답장 텍스트는 보이지 않습니다. 터미널에는 도구 호출과 확인 메시지(예: "sent")만 표시되고, 실제 답장 내용은 텔레그램 같은 외부 플랫폼에서 확인할 수 있습니다.

또한 실제 메신저를 연동하기 전에 플로우를 먼저 체험해 보고 싶다면, 공식적으로 제공되는 fakechat 데모 채널이 있습니다. 이 데모는 localhost에서 채팅 UI를 실행해 외부 서비스 없이 채널 흐름을 체험할 수 있게 해 줍니다.

텔레그램 연동을 위한 사전 준비물

본격적인 연동에 앞서 다음 사항들이 필요합니다.

1. 클로드 코드 v2.1.80 이상

Channels 기능은 클로드 코드 v2.1.80 이상에서만 동작합니다. 터미널에서 다음 명령어로 버전을 확인할 수 있습니다.

claude --version

2. claude.ai 로그인 계정

Channels 기능은 claude.ai 계정 로그인이 필수입니다. 공식 문서에 따르면 콘솔이나 API 키 인증 방식은 지원되지 않습니다.

3. Bun 런타임

텔레그램 플러그인의 MCP 서버는 Bun 런타임에서 실행됩니다. 다음 명령어로 설치할 수 있습니다.

curl -fsSL https://bun.sh/install | bash

Bun 공식 사이트에서도 자세한 설치 방법을 확인할 수 있습니다. 설치 후 bun --version 명령어로 정상 설치 여부를 점검하시기 바랍니다.

4. 텔레그램 앱과 BotFather 접근

텔레그램 앱이 설치되어 있어야 하고, BotFather로 봇을 생성해야 합니다.

5. Team/Enterprise 사용자의 경우

Team 또는 Enterprise 조직 사용자라면 관리자가 Channels 기능을 명시적으로 활성화해야 합니다. 관리자는 claude.ai → Admin settings → Claude Code → Channels 메뉴에서 설정할 수 있습니다.

Pro와 Max 사용자는 별도의 조직 설정 없이 바로 사용할 수 있습니다.

텔레그램 연동 단계별 설정 방법

이제 본격적으로 연동을 시작하겠습니다. 총 6단계로 진행됩니다.

1단계: BotFather로 텔레그램 봇 생성

먼저 텔레그램에서 @BotFather를 검색하여 채팅을 엽니다. BotFather는 텔레그램 공식 봇 관리 봇입니다.

채팅창에 다음 명령어를 입력합니다.

/newbot

BotFather가 두 가지 정보를 요청합니다.

이름(Name): 채팅 헤더에 표시되는 이름이며, 공백을 포함할 수 있습니다.
사용자명(Username): bot으로 끝나는 고유 핸들이어야 합니다 (예: my_assistant_bot). 이 값이 봇의 링크가 됩니다 (예: t.me/my_assistant_bot).

설정을 완료하면 BotFather가 다음과 같은 형식의 토큰을 반환합니다.

123456789:AAHfiqksKZ8...

주의사항: 토큰은 앞의 숫자와 콜론(:)을 포함한 전체 문자열을 복사해야 합니다. 이 토큰은 봇에 대한 모든 권한을 가지므로 절대 외부에 노출되어서는 안 됩니다.

2단계: 클로드 코드에 플러그인 설치

터미널에서 claude 명령어로 클로드 코드 세션을 시작합니다. 그다음 세션 안에서 다음 명령어를 입력합니다.

/plugin install telegram@claude-plugins-official

만약 "플러그인을 마켓플레이스에서 찾을 수 없다"는 메시지가 나타나면, 마켓플레이스가 누락되었거나 오래된 것일 수 있습니다. 다음 명령어로 새로 고치거나 추가합니다.

/plugin marketplace update claude-plugins-official

또는 처음 추가하는 경우라면 다음 명령어를 사용합니다.

/plugin marketplace add anthropics/claude-plugins-official

설치 후에는 /reload-plugins 명령어로 플러그인의 configure 명령어를 활성화해야 합니다.

3단계: 봇 토큰 설정

1단계에서 BotFather로부터 받은 토큰을 다음 명령어로 등록합니다.

/telegram:configure 123456789:AAHfiqksKZ8...

이 명령어를 실행하면 토큰이 ~/.claude/channels/telegram/.env 파일에 저장됩니다. 직접 파일을 편집하거나, 셸 환경변수에 TELEGRAM_BOT_TOKEN을 설정해도 됩니다. 두 곳 모두 설정된 경우 셸 환경변수가 우선 적용됩니다.

참고: 한 컴퓨터에서 여러 봇을 운영하려면(다른 토큰, 별도 허용 목록) TELEGRAM_STATE_DIR 환경변수를 인스턴스마다 다른 디렉토리로 지정하면 됩니다.

4단계: Channels 플래그로 클로드 코드 재시작

기존 세션을 종료하고 다음 명령어로 클로드 코드를 다시 실행합니다.

claude --channels plugin:telegram@claude-plugins-official

이 플래그가 있어야 텔레그램 플러그인이 활성화되어 봇 메시지를 폴링하기 시작합니다. 이 플래그 없이는 채널이 연결되지 않습니다.

5단계: 계정 페어링

이제 텔레그램 앱에서 본인이 만든 봇을 찾아 아무 메시지나 전송합니다. 봇이 6자리 페어링 코드로 응답합니다.

만약 봇이 응답하지 않는다면, 클로드 코드가 --channels 플래그와 함께 실행 중인지 확인하시기 바랍니다.

클로드 코드 세션으로 돌아와서 다음 명령어를 입력합니다.

/telegram:access pair <받은_6자리_코드>

이 단계가 완료되면 다음 메시지부터 봇이 클로드 코드 어시스턴트로 연결됩니다.

6단계: 접근 제한 설정

페어링은 사용자 ID를 캡처하기 위한 단계입니다. 한 번 페어링된 후에는 보안을 위해 허용 목록(allowlist) 모드로 전환하는 것이 좋습니다. 그렇지 않으면 모르는 사람이 봇에 메시지를 보냈을 때 페어링 코드를 받을 수 있습니다.

다음 명령어로 정책을 변경합니다.

/telegram:access policy allowlist

이로써 본인 계정에서만 메시지를 보낼 수 있게 됩니다.

텔레그램 봇이 사용할 수 있는 기능

공식 GitHub 저장소에 따르면, 어시스턴트에게 노출되는 도구는 세 가지입니다.

reply: 채팅에 메시지를 전송합니다. chat_id와 text를 받으며, reply_to(메시지 ID)로 네이티브 스레딩이 가능하고 files(절대 경로)로 첨부 파일을 보낼 수 있습니다. 이미지(.jpg/.png/.gif/.webp)는 인라인 미리보기와 함께 사진으로 전송되고, 그 외 파일 형식은 문서로 전송됩니다. 파일당 최대 50MB이며, 텍스트는 자동으로 분할됩니다.
react: 메시지 ID에 이모지 반응을 추가합니다. 텔레그램이 정한 고정 이모지 화이트리스트만 허용됩니다 (👍 👎 ❤ 🔥 👀 등).
edit_message: 봇이 이전에 보낸 메시지를 편집합니다. "작업 중…"에서 결과로 진행 상황을 업데이트할 때 유용합니다. 봇이 직접 보낸 메시지에만 적용됩니다.

수신된 메시지에는 자동으로 입력 표시기가 켜집니다. 어시스턴트가 응답을 작성하는 동안 텔레그램에서 "봇이름이 입력 중…" 표시가 나타납니다.

사진과 파일 처리 방식

수신된 사진은 ~/.claude/channels/telegram/inbox/ 경로에 다운로드되며, 로컬 경로가 <channel> 알림에 포함되어 어시스턴트가 Read 도구로 읽을 수 있습니다.

주의할 점: 텔레그램은 사진을 압축합니다. 원본 파일이 필요하다면 사진 대신 문서로 전송해야 합니다 (길게 누르기 → 파일로 보내기).

알아두면 좋은 제한사항

1. 메시지 히스토리 API 부재

텔레그램의 Bot API는 메시지 히스토리와 검색 기능을 모두 제공하지 않습니다. 봇은 메시지가 도착하는 시점에만 볼 수 있으며, fetch_messages 도구는 존재하지 않습니다. 어시스턴트가 이전 컨텍스트가 필요한 경우 사용자에게 붙여넣기나 요약을 요청합니다.

이는 과거 메시지의 첨부 파일도 마찬가지여서, 사진은 도착하는 즉시 다운로드됩니다.

2. 세션이 켜져 있어야 동작

세션이 종료되면 채널도 오프라인이 됩니다. 봇이 오프라인일 때 보낸 메시지는 텔레그램에서는 그대로 유실됩니다 (디스코드는 fetch_messages로 봇이 다시 온라인이 될 때까지 큐에 보관됩니다).

3. 권한 프롬프트 처리

작업 중 클로드가 권한 승인을 요청하면 세션은 사용자가 터미널에서 승인할 때까지 일시 중지됩니다. 외부에서 작업을 처리하려면 --dangerously-skip-permissions 플래그를 사용할 수 있지만, 본인이 신뢰하는 환경에서만 사용해야 합니다.

claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions

이 플래그는 보안상 위험을 감수하고 모든 권한 프롬프트를 건너뜁니다.

보안 고려사항

공식 보안 문서에서 강조하는 핵심은 다음과 같습니다.

모든 승인된 채널 플러그인은 발신자 허용 목록을 유지합니다. 추가된 ID만 메시지를 푸시할 수 있고, 그 외에는 자동으로 무시됩니다.
--channels 플래그로 세션마다 활성화할 서버를 제어합니다.
.mcp.json에 등록된 것만으로는 부족하며, --channels에 명시적으로 지정되어야 합니다.

봇 토큰은 봇에 대한 전체 권한을 부여하는 자격 증명이므로, 절대 GitHub 등 공개 저장소에 올리거나 타인과 공유해서는 안 됩니다.

활용 사례

공식 문서에서 소개하는 Channels의 주요 활용 패턴은 두 가지입니다.

채팅 브릿지(Chat bridge): 폰에서 텔레그램으로 클로드에게 질문을 보내면, 작업은 사용자 컴퓨터에서 실제 파일을 대상으로 실행되고 답변은 같은 텔레그램 채팅으로 돌아옵니다.
웹훅 수신기(Webhook receiver): CI, 에러 트래커, 배포 파이프라인 등 외부 서비스의 웹훅을 클로드가 이미 파일을 열어 두고 디버깅 중인 세션으로 전달할 수 있습니다.

핵심은 모바일 환경에서도 AI를 통해 데스크톱의 파일과 도구에 접근할 수 있다는 점입니다.

자주 발생하는 문제와 해결법

봇이 응답하지 않는 경우

가장 흔한 원인은 클로드 코드 세션이 --channels 플래그 없이 실행 중이거나, 아예 종료되어 있는 경우입니다. 세션 상태를 다시 확인하시기 바랍니다.

플러그인을 찾을 수 없다는 메시지

마켓플레이스가 추가되지 않았거나 오래된 경우입니다. 위에서 안내한 /plugin marketplace update 또는 /plugin marketplace add 명령어로 해결할 수 있습니다.

권한 프롬프트로 세션이 멈추는 경우

장시간 자리를 비울 때 흔히 겪는 문제입니다. 신뢰할 수 있는 환경이라면 --dangerously-skip-permissions 플래그 사용을 검토해 볼 수 있습니다.

마치며

클로드 코드의 Channels 기능은 아직 리서치 프리뷰 단계이므로 공식 문서에 따르면 --channels 플래그 문법과 프로토콜이 사용자 피드백에 따라 변경될 수 있습니다. 문제나 의견은 Claude Code GitHub 저장소로 보고할 수 있습니다.

이 기능을 활용하면 책상 앞에 앉아 있을 때만 가능했던 개발 작업을, 외출 중이나 이동 중에도 텔레그램 채팅으로 처리할 수 있습니다. 모바일 환경에서 AI를 통해 데스크톱 도구와 파일에 접근할 수 있다는 점이 가장 큰 장점입니다.

다음 단계로 아래 기능들을 함께 살펴보면 더 강력한 워크플로우를 구성할 수 있습니다.

채널 직접 만들기(Build your own channel): 플러그인이 없는 시스템을 위해 직접 채널을 구현합니다.
Remote Control: 폰에서 로컬 세션을 직접 조작합니다.
Scheduled tasks: 푸시 이벤트 대신 타이머 기반으로 폴링합니다.

클로드 코드(Claude Code) vs OpenAI 코덱스 vs 제미나이 CLI: 2026년 터미널 AI 코딩 에이전트 완벽 비교

2026-04-28T05:14:19.775-07:00

2026년 현재 AI 코딩 도구의 가장 뜨거운 경쟁은 터미널 기반 에이전트 영역에서 일어나고 있습니다. 그중에서도 클로드 코드(Claude Code), OpenAI 코덱스(Codex), 제미나이 CLI(Gemini CLI) 세 가지는 미국 3대 AI 회사인 앤트로픽(Anthropic), OpenAI, 구글(Google)이 각각 내놓은 대표 제품입니다. 이 글에서는 세 도구의 성능, 가격, 특징을 공식 자료와 객관적인 데이터를 바탕으로 비교해 드리겠습니다.

터미널 AI 코딩 에이전트란 무엇인가요?

본격적인 비교에 앞서, 터미널 기반 AI 코딩 에이전트가 일반적인 코드 자동완성 도구와 어떻게 다른지 짚고 가겠습니다. 깃허브 코파일럿 같은 자동완성 도구는 개발자가 코드를 입력하는 순간 다음에 올 코드를 제안합니다. 반면 터미널 AI 에이전트는 자연어로 작업을 지시하면, 코드베이스 전체를 읽고 여러 파일을 동시에 수정하며, 테스트를 실행하고 깃 커밋까지 자율적으로 수행합니다. 단순한 보조 도구가 아니라 위임 가능한 협업 파트너에 가깝다고 볼 수 있습니다.

한눈에 보는 비교

항목	클로드 코드	OpenAI 코덱스	제미나이 CLI
개발사	앤트로픽(Anthropic)	OpenAI	구글(Google)
형태	터미널 + IDE 확장 + 클라우드	터미널 + IDE 확장 + 클라우드	터미널 (오픈소스)
무료 플랜	없음	ChatGPT Free에 일부 포함	있음 (관대한 한도)
가장 저렴한 유료 플랜	Claude Pro 월 $20	ChatGPT Plus 월 $20	무료 사용 가능
핵심 모델	클로드 오퍼스 4.7	GPT-5.5, GPT-5.3-Codex	제미나이 3.1 프로
SWE-bench Verified 최고 점수	87.6%	85.0%	80.6%
컨텍스트 윈도우	최대 1M 토큰	모델에 따라 다름	1M 토큰
오픈소스 여부	비공개	비공개	오픈소스

세 가지 도구의 근본적인 차이점

세 도구는 모두 터미널에서 작동하는 AI 에이전트라는 공통점이 있지만, 회사의 전략과 가격 정책에서 큰 차이를 보입니다.

클로드 코드는 앤트로픽(Anthropic)이 개발한 터미널 기반의 에이전트형 코딩 도구입니다. 2025년 2월 리서치 프리뷰로 시작해 2025년 5월 정식 출시되었습니다. 명령줄에서 작동하며, 코드베이스 전체를 이해하고 자율적으로 파일을 편집하며 셸 명령어를 실행할 수 있습니다. 터미널뿐 아니라 IDE 확장 프로그램(VS Code, JetBrains), 데스크톱 앱, 브라우저에서도 사용할 수 있습니다.

OpenAI 코덱스는 OpenAI가 제공하는 AI 코딩 에이전트입니다. ChatGPT 계정과 연동되어 작동하며, 터미널 CLI, IDE 확장, 클라우드 환경, 깃허브 통합 등 다양한 형태로 제공됩니다. ChatGPT의 유료 플랜에 코덱스가 포함되어 있어 별도의 구독이 필요하지 않다는 점이 특징입니다.

제미나이 CLI는 구글(Google)이 발표한 오픈소스 터미널 AI 에이전트입니다. 가장 큰 특징은 무료 사용 한도가 매우 관대하다는 점입니다. 구글 공식 발표에 따르면 개인 구글 계정으로 로그인하면 분당 60회, 일일 1,000회의 요청을 무료로 사용할 수 있으며, 제미나이 2.5 프로 모델과 1M 토큰 컨텍스트 윈도우를 활용할 수 있습니다.

성능 벤치마크: SWE-bench Verified 결과

AI 코딩 도구의 실력을 객관적으로 측정하는 가장 권위 있는 벤치마크는 SWE-bench Verified입니다. 이 벤치마크는 실제 깃허브에 등록된 500개의 이슈를 AI가 해결하는 능력을 평가합니다. 각 이슈는 격리된 도커 컨테이너에서 실행되며, 모델이 생성한 패치가 단위 테스트를 통과해야 성공으로 인정됩니다.

2026년 4월 기준 각 도구의 핵심 모델 점수는 다음과 같습니다.

클로드 오퍼스 4.7(Claude Opus 4.7): 87.6%
GPT-5.3 Codex: 85.0%
클로드 오퍼스 4.6: 80.8%
제미나이 3.1 프로(Gemini 3.1 Pro): 80.6%
클로드 소넷 4.6: 79.6%

클로드 오퍼스 4.7은 2026년 4월 16일에 출시된 앤트로픽의 최신 모델로 현재 1위를 기록하고 있습니다. 더 어려운 벤치마크인 SWE-bench Pro에서도 클로드 오퍼스 4.7이 64.3%로 1위를 기록했으며, GPT-5.4(57.7%)와 제미나이 3.1 프로(54.2%)를 앞섰습니다.

다만 한 가지 주의할 점이 있습니다. SWE-bench 점수는 사용하는 에이전트 스캐폴드(scaffold, 모델을 감싸는 도구)에 따라 달라질 수 있습니다. 따라서 같은 모델이라도 도구마다 실제 사용 성능이 다를 수 있습니다.

가격 비교

각 도구의 가격은 사용 방식과 결합된 구독 형태에 따라 크게 달라집니다. 모든 가격은 2026년 4월 기준이며, USD(미국 달러) 기준입니다.

클로드 코드 가격

클로드 공식 가격 페이지에 따르면 다음과 같습니다.

Pro: 월 $20 (연간 결제 시 월 $17 상당)
Max 5x: 월 $100 (Pro의 5배 사용량)
Max 20x: 월 $200 (Pro의 20배 사용량)
Team Premium: 사용자당 월 $100 (최소 5명)
API 종량제: 클로드 오퍼스 4.7 기준 입력 100만 토큰당 $5, 출력 100만 토큰당 $25

클로드 코드는 별도의 무료 플랜이 없으며, 최소 Pro 구독 또는 API 크레딧이 필요합니다.

OpenAI 코덱스 가격

ChatGPT 공식 가격 페이지에 따르면, 코덱스는 별도의 구독이 아닌 ChatGPT 플랜에 포함되어 제공됩니다.

ChatGPT Free: 무료 (제한된 코덱스 체험)
ChatGPT Plus: 월 $20 (집중 코딩 세션용)
ChatGPT Pro $100: 월 $100 (Plus의 5배 사용량, 2026년 4월 9일 출시)
ChatGPT Pro $200: 월 $200 (Plus의 20배 사용량)
ChatGPT Business: 사용자당 월 $25(연간) 또는 월 $30(월간), 최소 2명
ChatGPT Enterprise: 별도 문의

또한 OpenAI 공식 안내에 따르면, 2026년 4월 2일부터 코덱스의 가격 체계가 메시지 단위에서 API 토큰 단위로 변경되었습니다. 이로 인해 입력, 캐시 입력, 출력 토큰별로 크레딧이 차감됩니다. OpenAI는 일반적으로 개발자당 월 $100~$200 수준의 사용량이 발생한다고 안내하고 있습니다.

제미나이 CLI 가격

제미나이 CLI는 사용자가 어떤 구글 계정으로 인증하느냐에 따라 사용 한도가 달라집니다. 제미나이 CLI 공식 안내에 따르면 다음과 같습니다.

무료 (개인 구글 계정 로그인): 분당 60회, 일 1,000회 요청, 제미나이 2.5 프로 모델 사용 가능
Gemini Code Assist Standard: 사용자당 월 $19 (연간 약정)
Gemini Code Assist Enterprise: 사용자당 월 $45 (연간 약정)
API 종량제: 제미나이 API 키로 토큰 단위 종량제 가능

제미나이 CLI는 세 도구 중 무료 사용 한도가 가장 넓다는 큰 장점이 있습니다.

컨텍스트 윈도우 비교

컨텍스트 윈도우는 AI가 한 번에 처리할 수 있는 텍스트의 양을 의미합니다. 큰 코드베이스를 다룰 때 매우 중요한 요소입니다.

클로드 코드 공식 문서에 따르면, 클로드 오퍼스 4.7, 오퍼스 4.6, 소넷 4.6 모델은 1M 토큰(약 100만 토큰) 컨텍스트 윈도우를 지원합니다. Max, Team Premium, Enterprise 플랜에서는 1M 컨텍스트가 추가 비용 없이 자동으로 활성화됩니다.

제미나이 CLI는 무료 플랜에서도 제미나이 2.5 프로 모델의 1M 토큰 컨텍스트 윈도우를 사용할 수 있다는 장점이 있습니다.

OpenAI 코덱스의 컨텍스트 윈도우는 사용하는 모델에 따라 다르며, GPT-5 계열 모델을 사용합니다.

기능별 비교

자율성과 에이전트 능력

앤트로픽 공식 설명에 따르면, 클로드 코드는 코드베이스 전체를 읽고, 여러 파일을 동시에 편집하며, 셸 명령어를 실행하고, 풀 리퀘스트를 생성하는 작업을 자율적으로 수행할 수 있습니다. 다만 기본 설정은 신중하게 동작하도록 되어 있어, 파일 변경이나 명령어 실행 전에 사용자의 확인을 요청합니다.

OpenAI 코덱스 공식 페이지에 따르면 코덱스는 내장된 워크트리(worktree)와 클라우드 환경을 통해 여러 에이전트가 병렬로 작업할 수 있습니다. Skills 기능을 통해 코드 이해, 프로토타이핑, 문서화 작업을 팀의 표준에 맞게 수행할 수 있고, Automations 기능으로 이슈 분류, 알림 모니터링, CI/CD 같은 일상적이지만 중요한 작업을 자동화할 수 있습니다.

제미나이 CLI 공식 안내에 따르면 제미나이 CLI는 ReAct(Reason and Act) 루프를 사용하여 코드 이해, 파일 조작, 명령 실행, 동적 트러블슈팅을 수행합니다. 또한 구글 검색과 통합되어 실시간 외부 컨텍스트를 받아올 수 있다는 점이 다른 두 도구와 차별화되는 특징입니다.

MCP(Model Context Protocol) 지원

MCP는 앤트로픽이 개발한, AI 에이전트가 외부 도구와 데이터에 접근할 수 있게 해 주는 표준 프로토콜입니다. 2025년 12월 에이전틱 AI 재단(Agentic AI Foundation)에 기증되어 산업 표준이 되었습니다.

세 도구 모두 MCP를 지원합니다. 클로드 코드는 MCP를 자체적으로 개발한 앤트로픽이 제공하는 만큼 기본적으로 깊이 통합되어 있습니다. OpenAI 코덱스는 AGENTS.md 파일과 MCP 서버를 통해 컨텍스트를 확장합니다. 제미나이 CLI도 내장된 MCP 지원을 통해 다양한 외부 도구와 연결할 수 있습니다.

오픈소스 여부

세 도구 중 제미나이 CLI만 오픈소스입니다. 제미나이 CLI 깃허브 저장소에서 누구나 코드를 검토하고 기여할 수 있으며, 자체 호스팅도 가능합니다.

클로드 코드와 OpenAI 코덱스는 비공개 소프트웨어입니다.

설치 방법 간단 안내

클로드 코드 설치: 공식 설치 가이드에 따라 운영체제별 네이티브 인스톨러로 설치할 수 있습니다. macOS에서는 Homebrew, Linux에서는 apt/dnf/apk, Windows에서는 WinGet으로 설치할 수 있습니다. 첫 실행 시 로그인이 요구됩니다.

OpenAI 코덱스 설치: 코덱스 공식 사이트에서 안내하는 대로 CLI를 설치한 후, ChatGPT 계정으로 로그인하여 사용합니다.

제미나이 CLI 설치: npm을 통해 npm install -g @google/gemini-cli 명령으로 설치할 수 있습니다. 설치 후 개인 구글 계정으로 로그인하면 무료 한도 내에서 바로 사용할 수 있습니다.

어떤 도구를 선택해야 할까요?

각 도구의 강점이 다르므로 사용 목적에 따라 선택을 달리하는 것이 좋습니다.

클로드 코드가 적합한 경우: 대규모 코드베이스를 다루거나, 복잡한 멀티 파일 리팩토링을 자주 하거나, 자율적인 에이전트 작업이 필요하며 최고 수준의 코딩 성능이 필요한 개발자에게 적합합니다. SWE-bench Verified와 SWE-bench Pro 모두에서 1위를 기록하고 있습니다.

OpenAI 코덱스가 적합한 경우: 이미 ChatGPT 유료 구독을 사용 중이고 추가 비용 없이 코딩 에이전트를 사용하고 싶거나, ChatGPT의 다른 기능들(Sora, Deep Research, Agent Mode 등)과 통합된 워크플로우를 원하는 개발자에게 적합합니다. 클라우드 환경에서 병렬 에이전트를 실행하는 기능이 강점입니다.

제미나이 CLI가 적합한 경우: 비용 부담 없이 시작하고 싶거나(무료 한도가 가장 넓음), 오픈소스 도구를 선호하거나, 구글 클라우드 생태계와 통합이 필요하거나, AI 코딩 에이전트를 처음 경험해 보는 개발자에게 적합합니다.

마무리

세 도구는 모두 터미널 기반 AI 에이전트라는 공통점이 있지만, 각각 다른 강점을 가지고 있습니다. 클로드 코드는 SWE-bench 87.6%로 코딩 성능 1위를 기록하며, OpenAI 코덱스는 ChatGPT 구독에 포함된다는 통합 편의성이 있고, 제미나이 CLI는 가장 관대한 무료 한도와 오픈소스라는 강점이 있습니다.

가장 큰 결정 요소는 이미 사용 중인 AI 서비스가 무엇인지일 수 있습니다. ChatGPT를 이미 사용 중이라면 코덱스가 추가 비용 없이 사용 가능하고, 부담 없이 시작하고 싶다면 제미나이 CLI의 무료 한도가 매력적이며, 최고 수준의 코딩 성능과 자율성이 필요하다면 클로드 코드가 좋은 선택입니다.

제미나이 CLI와 OpenAI 코덱스는 무료로 시작하거나 체험할 수 있으므로, 먼저 무료 한도 안에서 직접 사용해 보시고 자신에게 맞는 도구를 찾으시는 것이 가장 좋은 방법입니다.

참고 자료

본 글에 기재된 가격과 사양은 2026년 4월 기준이며, 추후 변경될 수 있습니다. 가입 전 반드시 각 서비스의 공식 페이지에서 최신 정보를 확인하시기 바랍니다.

클로드 코드(Claude Code) 모든 기능 총정리 — 한눈에 보는 전체 지도

2026-04-27T20:29:00.000-07:00

클로드 코드(Claude Code)는 Anthropic이 만든 에이전트형 코딩 도구입니다. 코드베이스를 직접 읽고, 파일을 편집하고, 명령을 실행하며, 개발 도구들과 통합됩니다. 터미널, IDE, 데스크톱 앱, 웹 브라우저 어디서든 사용할 수 있습니다.

이 글은 클로드 코드가 제공하는 모든 핵심 기능을 한 페이지에 모아 간단히 설명하는 것이 목표입니다. 각 항목의 자세한 사용법·예제·설정 방법은 추후 항목별 별도 글에서 다룰 예정입니다.

본 글의 모든 정보는 Anthropic 공식 문서와 확장 기능 개요 문서를 기반으로 작성되었습니다.

1. 클로드 코드를 사용할 수 있는 환경 (Surfaces)

클로드 코드는 어디서나 동일한 엔진으로 동작하며, CLAUDE.md, 설정, MCP 서버가 모든 환경에서 공유됩니다.

터미널 CLI — 가장 본격적인 환경입니다. 터미널에서 직접 파일을 편집하고 명령을 실행합니다.
VS Code 확장 — 인라인 diff, @-멘션, 플랜 리뷰, 대화 기록을 에디터에서 바로 사용할 수 있습니다. Cursor에서도 설치 가능합니다.
JetBrains 플러그인 — IntelliJ IDEA, PyCharm, WebStorm 등에서 인터랙티브 diff 뷰와 선택 영역 컨텍스트 공유를 제공합니다.
데스크톱 앱 — IDE나 터미널 밖에서 독립 실행됩니다. diff 시각 검토, 여러 세션 병렬 실행, 작업 예약, 클라우드 세션 시작이 가능합니다. (macOS, Windows x64, Windows ARM64 지원)
웹 브라우저 (claude.ai/code) — 로컬 설정 없이 브라우저에서 실행됩니다. 장시간 작업을 원격으로 돌리거나, 로컬에 없는 레포에서 작업할 수 있습니다. iOS 앱에서도 사용 가능합니다.
Chrome 확장 (베타) — 브라우저에서 직접 웹 애플리케이션을 디버깅합니다.
Slack 통합 — Slack에서 @Claude를 멘션해 버그 리포트를 PR로 받을 수 있습니다.

2. 핵심 확장 기능 (Extensions)

확장 기능들은 클로드 코드의 에이전트 루프 곳곳에 끼어들어 동작을 커스터마이즈합니다. 공식 문서는 다음 7가지를 핵심 확장으로 분류하고 있습니다.

2-1. CLAUDE.md — 프로젝트 영구 컨텍스트

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일입니다. 세션이 시작될 때마다 자동으로 클로드 컨텍스트에 로드됩니다. 코딩 표준, 아키텍처 결정, 선호 라이브러리, 리뷰 체크리스트 등 "항상 알고 있어야 할 규칙"을 적습니다.

사용자(user), 프로젝트(project), 관리자(managed) 등 여러 레벨에서 정의 가능하며, 모두 누적적으로 컨텍스트에 들어갑니다.
공식 문서는 CLAUDE.md를 200줄 이하로 유지할 것을 권장합니다. 내용이 늘어나면 참고 자료는 스킬로, 경로별 규칙은 .claude/rules/로 분리하는 것이 좋습니다.
클로드가 작업 도중 학습한 빌드 명령이나 디버깅 인사이트는 auto memory 기능을 통해 사용자가 직접 적지 않아도 세션 간에 저장됩니다.

2-2. Skills — 재사용 가능한 지식과 워크플로우

Skills는 마크다운 파일 형태의 재사용 가능한 지식·워크플로우 묶음입니다. 공식 문서가 "확장 기능 중 가장 유연하다"고 표현하는 핵심 기능입니다.

두 가지 유형: 클로드가 세션 내내 활용하는 참고형(reference) 스킬(예: API 스타일 가이드)과 사용자가 명령으로 실행하는 액션형(action) 스킬(예: /deploy 배포 워크플로우)이 있습니다.
호출 방식: /<이름> 형태의 슬래시 명령으로 직접 실행하거나, 클로드가 상황에 맞다고 판단해 자동으로 로드합니다.
컨텍스트 비용: 기본적으로 세션 시작 시에는 스킬의 설명만 로드되고, 실제 사용될 때 전체 내용이 로드됩니다. disable-model-invocation: true로 설정하면 사용자가 직접 호출하기 전까지 컨텍스트를 0으로 유지할 수 있습니다.
클로드 코드에는 /simplify, /batch, /debug 같은 번들 스킬이 기본 탑재되어 있습니다.

2-3. Subagents — 격리된 컨텍스트의 작업자

Subagents(서브에이전트)는 별도의 컨텍스트 윈도우에서 작업을 수행하고 요약 결과만 메인 대화에 반환하는 작업자입니다.

메인 대화 컨텍스트가 가득 차거나, 수십 개 파일을 읽는 작업처럼 중간 산출물이 보일 필요가 없을 때 적합합니다.
메인 세션의 대화 기록이나 이미 호출한 스킬을 자동으로 상속받지 않습니다. 필요한 스킬은 skills: 필드에 명시해야 합니다.
커스텀 서브에이전트는 .claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)에 마크다운 파일로 정의합니다.

2-4. Agent Teams — 다중 세션 협업 (실험적)

Agent teams(에이전트 팀)는 여러 개의 독립적인 클로드 코드 세션이 서로 메시지를 주고받으며 협업하는 기능입니다.

서브에이전트가 메인에게만 결과를 보고하는 것과 달리, 팀원끼리 직접 통신하고 공유 작업 목록을 통해 자율적으로 조율합니다.
경쟁 가설이 있는 리서치, 보안·성능·테스트를 동시에 검토하는 병렬 코드 리뷰, 각자 다른 부분을 담당하는 신기능 개발에 적합합니다.
현재 실험적(experimental) 기능이며 기본적으로 비활성화되어 있습니다. 토큰 비용도 서브에이전트보다 높습니다(각 팀원이 별도의 클로드 인스턴스).

2-5. MCP (Model Context Protocol) — 외부 서비스 연결

MCP는 AI 도구를 외부 데이터 소스에 연결하기 위한 개방 표준 프로토콜입니다. MCP를 통해 클로드 코드는 데이터베이스 쿼리, Slack 게시, Jira 티켓 업데이트, Google Drive 디자인 문서 읽기 같은 작업을 수행할 수 있습니다.

세션 시작 시에는 도구 이름만 로드되고, 실제 호출될 때 JSON 스키마가 로드됩니다(컨텍스트 효율).
/mcp 명령으로 연결 상태와 서버별 토큰 사용량을 확인할 수 있습니다.
공식 MCP 서버 레지스트리는 github.com/modelcontextprotocol/servers에서 볼 수 있습니다.

2-6. Hooks — 이벤트 기반 자동화 스크립트

Hooks(훅)는 클로드 코드의 특정 라이프사이클 이벤트에서 자동 실행되는 결정론적 셸 스크립트입니다. LLM이 개입하지 않으므로 동작이 예측 가능합니다.

대표적인 사용 예: 파일 편집 후 자동 포매팅, 커밋 전 린트 실행, MCP를 통한 Slack 알림 전송 등이 있습니다.
주요 이벤트로는 PreToolUse(도구 실행 전), PostToolUse(도구 실행 후), PreCompact/PostCompact(컨텍스트 압축 전후), PermissionRequest(권한 다이얼로그 표시 시), InstructionsLoaded(CLAUDE.md 로드 시) 등이 있습니다.
컨텍스트 비용이 0이며(외부 스크립트), .claude/settings.json에 정의합니다.

2-7. Plugins & Marketplaces — 패키징과 배포

Plugins(플러그인)는 스킬, 훅, 서브에이전트, MCP 서버를 하나의 설치 가능한 단위로 묶는 패키징 계층입니다. 동일한 설정을 여러 레포에서 재사용하거나 다른 사람에게 배포할 때 사용합니다.

플러그인 스킬은 /my-plugin:review 형태로 네임스페이스가 지정되어 다른 플러그인과 충돌하지 않습니다.
Marketplaces(마켓플레이스)는 플러그인 컬렉션을 호스팅·배포하는 채널입니다.

3. 권한 모드 (Permission Modes)

권한 모드는 클로드가 액션을 실행하기 전에 사용자에게 얼마나 자주 묻는지를 결정합니다. 터미널에서는 Shift+Tab으로 모드를 순환할 수 있습니다.

모드	묻지 않고 가능한 작업	적합한 상황
`default`	파일 읽기	시작할 때, 민감한 작업
`acceptEdits`	파일 읽기·편집	리뷰하면서 코드 반복 작성
`plan`	파일 읽기	코드베이스 탐색, 리팩터링 계획
`auto`	모든 액션(백그라운드 분류기 검사)	장시간 작업, 프롬프트 피로 감소
`dontAsk`	사전 승인된 도구만	잠긴 환경, CI 파이프라인
`bypassPermissions`	모든 액션, 검사 없음	격리된 컨테이너·VM 전용

auto 모드는 Team, Enterprise, API 플랜에서만 제공되며, 별도의 분류기 모델이 각 액션을 검토해 작업 범위를 벗어나거나 프롬프트 인젝션으로 보이는 동작을 차단합니다. bypassPermissions는 안전 장치가 없으므로 격리 환경에서만 사용해야 합니다.

4. 슬래시 명령 (Slash Commands)

슬래시 명령은 세션 안에서 클로드 코드를 제어하는 명령입니다. /를 입력하면 사용 가능한 모든 명령 목록이 표시됩니다. 명령은 두 종류로 나뉩니다.

번들 스킬: /simplify, /batch, /debug 같은 기본 탑재 스킬입니다. 사용자가 만든 스킬과 동일한 메커니즘으로 동작합니다.
빌트인 명령: CLI에 직접 코딩된 명령입니다. /clear(대화 초기화), /model(모델 변경), /mcp(MCP 상태 확인), /permissions(권한 확인), /help(도움말), /plan(플랜 모드 단발 실행), /schedule(루틴 생성) 등이 있습니다.

명령 가용성은 플랫폼·플랜·환경에 따라 다릅니다. 예를 들어 /desktop은 macOS와 Windows에서만 표시되고, /upgrade는 Pro·Max 플랜에서만 표시됩니다.

5. 자동화·스케줄링·원격 작업 기능

5-1. Routines — 클라우드 스케줄링

Routines(루틴)은 Anthropic이 관리하는 인프라에서 정해진 일정에 따라 실행되는 작업입니다. 컴퓨터를 꺼도 동작합니다. 아침 PR 리뷰, 야간 CI 실패 분석, 주간 의존성 감사 같은 반복 작업에 적합합니다. API 호출이나 GitHub 이벤트로도 트리거할 수 있습니다. 웹·데스크톱·CLI(/schedule)에서 생성할 수 있습니다.

5-2. Desktop scheduled tasks — 로컬 스케줄링

데스크톱 예약 작업은 사용자 컴퓨터에서 직접 실행되어 로컬 파일과 도구에 접근할 수 있습니다.

5-3. /loop (번들 스킬)

/loop은 번들 스킬 형태로 제공되며, CLI 세션 내에서 동일한 프롬프트를 반복 실행해 빠르게 폴링할 때 사용합니다(예: /loop 5m check if the deploy finished).

5-4. Remote Control

Remote Control(원격 제어)을 사용하면 휴대폰이나 다른 브라우저에서 로컬 세션을 이어서 작업할 수 있습니다.

5-5. Channels

Channels(채널)은 Telegram, Discord, iMessage, 또는 자체 웹훅에서 발생한 이벤트를 클로드 코드 세션에 전달합니다.

5-6. Computer use (프리뷰)

Computer use는 클로드가 사용자 컴퓨터의 화면을 보고 마우스·키보드를 직접 조작할 수 있게 해주는 프리뷰 기능입니다.

6. CI/CD 및 코드 리뷰 통합

GitHub Actions — 코드 리뷰와 이슈 분류를 자동화합니다.
GitLab CI/CD — GitLab 환경에서 동일한 자동화를 제공합니다.
GitHub Code Review — 모든 PR에 자동 코드 리뷰를 적용합니다.

CLI는 Unix 철학을 따라 다른 도구와 파이프·체이닝이 자유롭습니다. 예를 들어 tail -200 app.log | claude -p "Slack me if you see any anomalies"처럼 로그를 파이프로 넘겨 분석시킬 수 있습니다.

7. 안전·세션 관리 기능

7-1. Sandboxing — OS 레벨 격리

Sandboxing(샌드박싱)은 Bash 명령과 그 자식 프로세스가 정의된 경계를 넘어가지 못하도록 OS 레벨에서 강제하는 기능입니다. macOS는 Seatbelt를 사용해 별도 설치 없이 작동하며, Linux와 WSL2에서는 bubblewrap과 socat을 먼저 설치해야 합니다. /sandbox 명령으로 활성화합니다. 권한 시스템과 함께 **다층 방어(defense-in-depth)**를 구성합니다.

7-2. Checkpointing — 대화·코드 되돌리기

Checkpointing(체크포인팅)은 /rewind 명령으로 대화나 코드를 이전 시점으로 되돌릴 수 있게 해줍니다. 클로드가 잘못된 방향으로 갔을 때 빠르게 복구할 수 있습니다.

7-3. Background tasks — 백그라운드 작업 관리

/tasks 명령(별칭 /bashes)으로 백그라운드에서 실행 중인 작업들을 나열하고 관리할 수 있습니다.

7-4. Output styles — 응답 스타일 커스터마이즈

Output styles(출력 스타일)을 통해 클로드의 응답 형식을 사용자 취향에 맞게 조정할 수 있습니다. /config에서 변경합니다.

7-5. Fast mode — 빠른 응답 모드

/fast 명령으로 Fast mode를 토글할 수 있습니다. 응답 속도를 우선시합니다.

7-6. Voice dictation — 음성 입력

/voice 명령으로 푸시-투-토크 음성 받아쓰기 기능을 켤 수 있습니다(Claude.ai 계정 필요).

8. Agent SDK — 커스텀 에이전트 빌드

Agent SDK는 클로드 코드의 도구와 기능을 활용한 자체 에이전트를 직접 만들 수 있게 해주는 SDK입니다. 오케스트레이션, 도구 접근, 권한을 완전히 제어할 수 있습니다. 특정 도메인에 특화된 워크플로우를 구축할 때 사용합니다.

9. .claude 디렉토리 — 모든 설정의 중심

.claude 디렉토리는 프로젝트별 클로드 코드 설정이 저장되는 곳입니다. 주요 하위 항목은 다음과 같습니다.

.claude/settings.json — 모델, 권한, 환경변수, 훅, MCP 서버 설정
.claude/commands/ — 커스텀 슬래시 명령 (레거시 형식)
.claude/skills/<이름>/SKILL.md — 커스텀 스킬 (권장 형식)
.claude/agents/ — 커스텀 서브에이전트
.claude/rules/ — 경로별 규칙

전역 설정은 ~/.claude/ 아래에 동일한 구조로 저장되며, 프로젝트 설정이 충돌 시 우선합니다.

10. 기능별 컨텍스트 비용 요약

공식 문서가 정리한 컨텍스트 로딩 전략입니다.

기능	로드 시점	로드되는 내용	컨텍스트 비용
CLAUDE.md	세션 시작	전체 내용	매 요청마다
Skills	세션 시작 + 사용 시	시작 시 설명만, 사용 시 전체	낮음 (설명만 매 요청)
MCP 서버	세션 시작	도구 이름만, 스키마는 필요 시	도구 사용 전까지 낮음
Subagents	스폰 시	지정된 스킬과 함께 새 컨텍스트	메인 세션과 격리
Hooks	트리거 시	없음 (외부 실행)	0 (출력 반환 시 제외)

11. 기능을 언제 추가해야 할까

공식 문서가 권장하는 트리거 기반 도입 순서입니다.

트리거	추가할 기능
클로드가 같은 컨벤션·명령을 두 번 틀립니다	CLAUDE.md에 추가
작업 시작 시 같은 프롬프트를 반복 입력합니다	사용자 호출 스킬로 저장
같은 절차서·플레이북을 세 번째 붙여넣고 있습니다	스킬로 캡처
클로드가 못 보는 브라우저 탭에서 데이터를 계속 복사합니다	MCP 서버로 연결
사이드 작업이 주 대화를 출력으로 가득 채웁니다	서브에이전트로 분리
매번 자동으로 일어났으면 하는 일이 있습니다	훅 작성
두 번째 레포에 동일한 설정이 필요합니다	플러그인으로 패키징

마치며

클로드 코드는 단일 도구가 아니라 여러 환경(Surfaces)에서 동작하는 7가지 핵심 확장(CLAUDE.md, Skills, Subagents, Agent teams, MCP, Hooks, Plugins) + 권한 모드 + 자동화·스케줄링 + 안전·세션 관리 + Agent SDK가 결합된 플랫폼입니다. 공식 문서가 강조하듯, 처음부터 모든 것을 설정할 필요는 없습니다. 트리거가 생기면 그때 도입하시면 됩니다.

이 글에서는 각 기능의 정체와 역할만 빠르게 훑어보았습니다. 다음 글들에서는 항목별로 실제 설치·설정 방법, 예제 코드, 실수하기 쉬운 부분을 자세히 다룰 예정입니다.

참고 링크

클로드 코드(Claude Code) 터미널에서 실행 후 메뉴 완전 분석 (2026년 최신판)

2026-04-27T02:18:00.000-07:00

Anthropic의 공식 문서 기준으로 정리한 Claude Code 메뉴, 슬래시 명령어, 키보드 단축키, CLI 플래그 완벽 가이드입니다. 이 글의 모든 정보는 Claude Code 공식 문서를 직접 확인하여 작성했습니다.

📌 글을 시작하기 전에

Claude Code는 Anthropic이 개발한 터미널 기반 AI 코딩 도구입니다. 일반 채팅 인터페이스(claude.ai)와 달리 명령줄(CLI)에서 직접 실행되며, 프로젝트 파일을 읽고 수정하고 명령어를 실행할 수 있는 에이전트형 도구입니다.

이 글에서는 터미널에서 claude 명령으로 Claude Code를 실행한 직후 사용할 수 있는 모든 메뉴(슬래시 명령어), 키보드 단축키, CLI 플래그를 공식 문서 기준으로 빠짐없이 정리합니다.

⚠️ 참고: Claude Code는 매우 빠르게 업데이트되고 있어, 일부 명령어는 향후 변경되거나 추가될 수 있습니다. 가장 정확한 최신 정보는 항상 Claude Code 공식 명령어 문서에서 확인하시기 바랍니다.

🎯 바쁘신 분을 위한 핵심 5가지

이 글이 길어 보일 수 있지만, 실제로 처음 사용 시 외워야 할 것은 다섯 가지뿐입니다:

/help — 사용 가능한 모든 명령어 목록 보기
/clear — 대화 기록을 지우고 컨텍스트 비우기
/compact — 컨텍스트가 차오를 때 대화를 압축해 토큰 절약
Ctrl+C — 현재 입력이나 생성 취소 (Ctrl+D는 세션 자체 종료)
Shift+Tab — 권한 모드 빠른 전환 (default ↔ acceptEdits ↔ plan ↔ auto)

1. Claude Code 시작하기

1-1. 설치

Claude Code는 다음 두 가지 방법으로 설치할 수 있습니다 (공식 설치 가이드):

# 방법 1: 공식 설치 스크립트 (macOS / Linux / WSL)
curl -fsSL https://claude.ai/install.sh | sh

# 방법 2: npm으로 설치 (모든 OS)
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

💰 요금제 안내: Claude Code는 Anthropic의 Claude Pro / Max 구독 또는 Anthropic API 키로 사용할 수 있습니다. 일부 기능(예: auto 권한 모드)은 Team, Enterprise, API 요금제에서만 사용 가능하므로 자세한 사항은 공식 문서를 참고하세요.

1-2. 실행

프로젝트 폴더로 이동한 뒤 claude 명령어를 입력하면 인터랙티브 세션이 시작됩니다.

cd your-project
claude

세션이 시작되면 프롬프트 입력창이 나타나며, 여기서 자연어로 명령을 내리거나 슬래시 명령어(/) 를 입력해 메뉴를 사용할 수 있습니다.

2. 슬래시 명령어(/) 완전 정리

세션에서 / 키를 누르면 사용 가능한 모든 명령어 목록이 나타납니다. 알파벳을 추가로 입력하면 필터링됩니다 (예: /co 입력 시 /compact, /config, /copy, /cost, /context 등이 표시됨).

ℹ️ 모든 명령어가 모든 사용자에게 보이는 것은 아닙니다. 플랫폼, 요금제, 환경에 따라 표시 여부가 결정됩니다. 예를 들어 /desktop은 macOS와 Windows에서만, /upgrade는 Pro/Max 요금제에서만 표시됩니다.

표 안에서 <arg>는 필수 인수, [arg]는 선택 인수입니다.

2-1. 세션 관리 명령어

명령어	설명
`/clear`	대화 기록 삭제 및 컨텍스트 비우기 (별칭: `/reset`, `/new`)
`/compact [instructions]`	대화를 압축하여 컨텍스트 절약 (선택적으로 집중할 주제 지정 가능)
`/context`	현재 컨텍스트 사용량을 컬러 그리드로 시각화
`/resume [session]`	이전 세션을 ID나 이름으로 재개 (별칭: `/continue`)
`/rename [name]`	현재 세션 이름 변경 (없으면 자동 생성)
`/branch [name]`	현재 시점에서 대화의 새 분기를 생성 (별칭: `/fork`)
`/rewind`	코드/대화를 이전 시점으로 되돌리기 (별칭: `/checkpoint`) - 자세한 내용은 체크포인팅 문서 참조
`/export [filename]`	현재 대화를 일반 텍스트로 내보내기
`/copy [N]`	마지막 어시스턴트 응답을 클립보드에 복사 (N은 N번째 이전 응답 지정)
`/exit`	CLI 종료 (별칭: `/quit`)

2-2. 모델 및 모드 관련 명령어

명령어	설명
`/model [model]`	AI 모델 선택 또는 변경 (좌우 화살표로 추론 강도 조정 가능)
`/effort [low\|medium\|high\|max\|auto]`	모델 추론 강도 설정. `low`/`medium`/`high`는 세션 간 유지, `max`는 현재 세션 한정(Opus 4.6 이상 필요)
`/fast [on\|off]`	Fast 모드 토글
`/permissions`	도구 권한의 허용/요청/거부 규칙 관리 (별칭: `/allowed-tools`)
`/plan [description]`	프롬프트에서 직접 Plan 모드 진입
`/sandbox`	Sandbox 모드 토글 (지원 플랫폼 한정)

2-3. 정보 조회 명령어

명령어	설명
`/help`	도움말 및 사용 가능한 명령어 목록 표시
`/cost`	토큰 사용량 통계 표시 (비용 추적 가이드 참조)
`/usage`	요금제 사용량 한도 및 Rate limit 상태 표시
`/stats`	일별 사용량, 세션 기록, 연속 사용 일수, 모델 선호도 시각화
`/insights`	Claude Code 세션을 분석하는 보고서 생성 (프로젝트 영역, 상호작용 패턴, 마찰 지점 등)
`/status`	Settings 인터페이스의 Status 탭 열기 (버전, 모델, 계정, 연결 상태)
`/doctor`	Claude Code 설치 및 설정 진단 (`f` 키로 자동 수정)
`/release-notes`	변경 로그를 인터랙티브 버전 선택기에서 보기

2-4. 설정 및 환경 관련 명령어

명령어	설명
`/config`	Settings 인터페이스 열기 (별칭: `/settings`)
`/theme`	색상 테마 변경 (라이트/다크/색맹 친화/ANSI 테마 포함)
`/color [color\|default]`	프롬프트 바 색상 설정 (red, blue, green, yellow, purple, orange, pink, cyan)
`/keybindings`	키바인딩 설정 파일 열기/생성
`/terminal-setup`	터미널 키바인딩 설정 (Shift+Enter 등) - VS Code, Alacritty, Warp 등에서만 표시
`/statusline`	Claude Code의 상태줄 설정
`/memory`	`CLAUDE.md` 메모리 파일 편집 및 자동 메모리 활성화/비활성화
`/init`	프로젝트에 `CLAUDE.md` 가이드 초기화
`/add-dir <path>`	현재 세션에서 파일 접근을 위한 작업 디렉토리 추가

2-5. 확장 기능 관련 명령어

명령어	설명
`/agents`	서브에이전트(Agent) 설정 관리
`/skills`	사용 가능한 스킬 목록 표시
`/plugin`	Claude Code 플러그인 관리
`/reload-plugins`	활성 플러그인 재로드 (재시작 없이 변경사항 적용)
`/mcp`	MCP 서버 연결 및 OAuth 인증 관리
`/hooks`	도구 이벤트에 대한 후크(Hook) 설정 보기
`/ide`	IDE 통합 관리 및 상태 표시
`/chrome`	Chrome용 Claude 설정

2-6. 작업 흐름 관련 명령어

명령어	설명
`/diff`	인터랙티브 diff 뷰어 열기 (커밋되지 않은 변경 + 턴별 diff)
`/btw <question>`	대화 기록에 추가하지 않고 빠른 사이드 질문 하기
`/loop [interval] [prompt]`	세션이 열린 동안 프롬프트를 반복 실행 (스킬, 별칭: `/proactive`) - 예약 작업 참조
`/schedule [description]`	루틴(Routines) 생성/수정/실행
`/tasks`	백그라운드 작업 목록/관리 (`/bashes`로도 사용 가능)
`/debug [description]`	현재 세션에서 디버그 로깅 활성화 (스킬)

2-7. 깃허브 / 협업 관련 명령어

명령어	설명
`/install-github-app`	Claude GitHub Actions 앱 설정
`/install-slack-app`	Claude Slack 앱 설치 (브라우저에서 OAuth 진행)
`/autofix-pr [prompt]`	Claude Code on the Web 세션을 생성해 PR을 모니터링하고 CI 실패/리뷰 코멘트에 대응 (`gh` CLI 필요)
`/security-review`	현재 브랜치의 변경사항을 보안 취약점 측면에서 분석 (인젝션, 인증 문제, 데이터 노출 등)
`/team-onboarding`	지난 30일간의 사용 기록을 기반으로 팀 온보딩 가이드 생성

2-8. 스킬(Skill) 명령어

위 명령어 표에서 "스킬"로 표기된 항목들(/batch, /claude-api, /debug, /loop, /simplify)은 번들 스킬(Bundled Skill)입니다. 스킬은 사용자가 직접 호출할 수도 있고, 상황에 따라 Claude가 자동으로 호출할 수도 있는 프롬프트 기반 가이드입니다. 사용자가 직접 만들 수 있는 스킬과 동일한 메커니즘을 사용합니다.

대표적인 스킬 명령어를 다시 정리하면:

명령어	설명
`/batch <instruction>`	코드베이스 전반의 대규모 변경을 병렬로 조율 (5~30개 단위로 분해 후 git worktree에서 각 단위별로 에이전트를 띄워 PR 생성)
`/claude-api`	Claude API 레퍼런스 자료 로드 (Python, TypeScript, Java, Go, Ruby, C#, PHP, cURL 지원). `anthropic` 또는 `@anthropic-ai/sdk`를 import하면 자동 활성화됨
`/simplify [focus]`	최근 변경 파일을 검토하여 코드 재사용성/품질/효율성 개선 (3개 리뷰 에이전트 병렬 실행)
`/debug [description]`	현재 세션에서 디버그 로깅을 활성화하고 디버그 로그를 분석하여 문제 해결
`/loop [interval] [prompt]`	세션이 열린 동안 프롬프트를 반복 실행 (별칭: `/proactive`)

2-9. 계정 / 인증 관련 명령어

명령어	설명
`/login`	Anthropic 계정 로그인
`/logout`	Anthropic 계정 로그아웃
`/upgrade`	더 높은 요금제로 업그레이드 페이지 열기
`/privacy-settings`	개인정보 설정 보기/업데이트 (Pro/Max 한정)
`/extra-usage`	Rate limit 도달 시에도 작업을 계속할 수 있도록 추가 사용량 설정
`/passes`	Claude Code 무료 1주일 친구에게 공유 (자격 있는 계정만 표시)

2-10. 원격 / 모바일 / 데스크톱 연동

명령어	설명
`/desktop`	현재 세션을 Claude Code Desktop 앱에서 계속 (macOS, Windows 한정, 별칭: `/app`)
`/mobile`	Claude 모바일 앱 다운로드 QR 코드 표시 (별칭: `/ios`, `/android`)
`/remote-control`	claude.ai에서 원격 제어할 수 있도록 세션 공개 (별칭: `/rc`)
`/remote-env`	`--remote`로 시작된 웹 세션의 기본 원격 환경 설정
`/teleport`	Claude Code on the Web 세션을 현재 터미널로 가져오기 (별칭: `/tp`)
`/ultraplan <prompt>`	Ultraplan 세션에서 계획 작성 후 브라우저에서 검토
`/web-setup`	로컬 `gh` CLI 자격 증명을 사용해 GitHub 계정을 Claude Code on the Web에 연결
`/voice`	음성 받아쓰기 토글 (Claude.ai 계정 필요)

2-11. 클라우드 제공자 설정

명령어	설명
`/setup-bedrock`	Amazon Bedrock 인증/리전/모델 설정 (`CLAUDE_CODE_USE_BEDROCK=1` 필요)
`/setup-vertex`	Google Vertex AI 인증/프로젝트/리전/모델 설정 (`CLAUDE_CODE_USE_VERTEX=1` 필요)

2-12. 기타 명령어

명령어	설명
`/feedback [report]`	Claude Code에 대한 피드백 제출 (별칭: `/bug`)
`/powerup`	애니메이션 데모와 함께 Claude Code 기능을 학습
`/stickers`	Claude Code 스티커 주문

2-13. 제거되거나 변경된 명령어 (참고)

이전 버전에서 사용했던 명령어 중 변경된 항목들입니다. 검색 시 혼란을 줄이기 위해 정리합니다:

명령어	상태
`/vim`	v2.1.92에서 제거됨. Vim/Normal 편집 모드 전환은 `/config` → Editor mode에서 설정
`/pr-comments`	v2.1.91에서 제거됨. 이전 버전에서는 GitHub PR 댓글을 가져오는 기능이었으나, 현재는 Claude에게 직접 PR 댓글을 보라고 요청하면 됩니다
`/review`	Deprecated. 대신 `code-review` 플러그인을 설치 (`claude plugin install code-review@claude-plugins-official`)
`--enable-auto-mode`	v2.1.111에서 제거됨. Auto 모드는 이제 `Shift+Tab` 순환에 기본 포함되며, 시작부터 사용하려면 `--permission-mode auto` 사용

3. 키보드 단축키 완전 정리

세션 안에서 ? 키를 누르면 현재 환경에서 사용 가능한 단축키를 볼 수 있습니다 (공식 인터랙티브 모드 문서).

💡 macOS 사용자 주의: Alt+B, Alt+F, Alt+Y, Alt+M, Alt+P, Alt+T 같은 Option/Alt 키 단축키를 사용하려면 터미널에서 Option 키를 Meta로 설정해야 합니다.

iTerm2: Settings → Profiles → Keys → General → Left/Right Option key를 "Esc+"로 설정

Apple Terminal: Settings → Profiles → Keyboard → "Use Option as Meta Key" 체크

VS Code: 설정에서 "terminal.integrated.macOptionIsMeta": true 추가

자세한 내용은 터미널 설정 문서 참조

3-1. 일반 컨트롤

단축키	동작
`Ctrl+C`	현재 입력 또는 생성 취소
`Ctrl+X Ctrl+K`	모든 백그라운드 에이전트 종료 (3초 안에 두 번 누르면 확정)
`Ctrl+D`	Claude Code 세션 종료 (EOF 신호)
`Ctrl+G` 또는 `Ctrl+X Ctrl+E`	기본 텍스트 에디터에서 열기
`Ctrl+L`	프롬프트 입력 비우고 화면 다시 그리기 (대화 기록은 유지)
`Ctrl+O`	트랜스크립트 뷰어 토글 (도구 사용 및 실행 상세 표시)
`Ctrl+R`	명령 기록 역방향 검색
`Ctrl+V` (또는 `Cmd+V` iTerm2 / `Alt+V` Windows)	클립보드에서 이미지 붙여넣기
`Ctrl+B`	실행 중인 작업을 백그라운드로 (tmux 사용자는 두 번 누름)
`Ctrl+T`	작업 목록 토글
`Left/Right 화살표`	다이얼로그 탭 순환
`Up/Down 화살표` 또는 `Ctrl+P`/`Ctrl+N`	커서 이동 또는 명령 기록 탐색
`Esc + Esc`	되감기 또는 요약 (이전 시점으로 코드/대화 복원)
`Shift+Tab` 또는 `Alt+M`	권한 모드 순환 (`default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions` 등)
`Option+P` (Mac) / `Alt+P` (Win/Linux)	모델 전환 (입력한 프롬프트 보존)
`Option+T` / `Alt+T`	확장 사고(extended thinking) 모드 토글
`Option+O` / `Alt+O`	Fast 모드 토글

3-2. 텍스트 편집 단축키

단축키	동작
`Ctrl+A`	현재 줄 시작으로 커서 이동
`Ctrl+E`	현재 줄 끝으로 커서 이동
`Ctrl+K`	줄 끝까지 삭제 (붙여넣기 가능)
`Ctrl+U`	커서부터 줄 시작까지 삭제 (macOS의 `Cmd+Backspace`와 동일)
`Ctrl+W`	이전 단어 삭제 (Windows에서는 `Ctrl+Backspace`도 가능)
`Ctrl+Y`	삭제한 텍스트 붙여넣기
`Alt+Y` (Ctrl+Y 다음)	붙여넣기 기록 순환
`Alt+B`	단어 단위로 뒤로 이동
`Alt+F`	단어 단위로 앞으로 이동

3-3. 멀티라인 입력

여러 줄 입력을 하려면 다음 방법을 사용합니다:

방법	사용 환경
`\` + `Enter`	모든 터미널에서 작동
`Option+Enter`	macOS에서 Option as Meta 활성화 후
`Shift+Enter`	iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal에서 기본 작동
`Ctrl+J`	모든 터미널에서 설정 없이 작동
직접 붙여넣기	코드 블록, 로그 등

📝 VS Code, Cursor, Windsurf, Alacritty, Zed 사용자는 /terminal-setup을 한 번 실행하면 Shift+Enter 바인딩이 설치됩니다.

3-4. 빠른 명령어 진입

단축키	동작
시작에 `/`	명령어 또는 스킬 호출
시작에 `!`	Bash 모드 진입 (명령어를 직접 실행하고 출력을 컨텍스트에 추가)
`@`	파일 경로 자동완성 트리거

4. CLI 플래그 (실행 시 옵션)

claude 명령어 뒤에 붙이는 플래그로, 실행 시점부터 동작을 제어합니다 (공식 CLI 레퍼런스).

ℹ️ claude --help가 모든 플래그를 보여주지는 않으므로, 도움말에 없다고 해서 사용 불가한 것은 아닙니다.

4-1. 자주 쓰는 CLI 명령어

명령어	설명	예시
`claude`	인터랙티브 세션 시작	`claude`
`claude "query"`	초기 프롬프트와 함께 시작	`claude "explain this project"`
`claude -p "query"`	SDK 방식으로 한 번 실행 후 종료	`claude -p "explain this function"`
`claude -c`	현재 디렉토리의 가장 최근 대화 이어가기	`claude -c`
`claude -r "<session>" "query"`	세션 ID나 이름으로 재개	`claude -r "auth-refactor" "Finish this PR"`
`claude update`	최신 버전으로 업데이트	`claude update`
`claude install [version]`	특정 버전 설치 (예: `2.1.118`, `stable`, `latest`)	`claude install stable`
`claude auth login`	Anthropic 계정 로그인	`claude auth login --console`
`claude auth logout`	로그아웃	`claude auth logout`
`claude auth status`	인증 상태 확인 (JSON 또는 `--text`)	`claude auth status`
`claude mcp`	MCP 서버 설정	MCP 문서 참조
`claude plugin`	플러그인 관리 (별칭: `claude plugins`)	`claude plugin install code-review@claude-plugins-official`
`claude setup-token`	CI/스크립트용 장기 OAuth 토큰 생성	`claude setup-token`

4-2. 주요 CLI 플래그

플래그	설명
`--add-dir`	추가 작업 디렉토리 등록 (예: `claude --add-dir ../apps ../lib`)
`--model`	모델 지정 (예: `claude --model claude-sonnet-4-6`, 별칭 `sonnet`/`opus` 가능)
`--effort`	추론 강도 설정 (`low`, `medium`, `high`, `xhigh`, `max`)
`--permission-mode`	권한 모드로 시작 (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`)
`--allowedTools`	권한 프롬프트 없이 실행할 도구 지정
`--disallowedTools`	사용 불가 도구 지정
`--tools`	사용 가능한 내장 도구 제한 (예: `"Bash,Edit,Read"`)
`--print`, `-p`	인터랙티브 모드 없이 응답 출력
`--continue`, `-c`	가장 최근 대화 로드
`--resume`, `-r`	특정 세션 재개
`--name`, `-n`	세션 표시 이름 지정
`--worktree`, `-w`	격리된 git worktree에서 시작
`--tmux`	worktree용 tmux 세션 생성 (`--worktree` 필요)
`--verbose`	상세 로깅 활성화
`--debug`	디버그 모드 (카테고리 필터링 가능, 예: `"api,mcp"`)
`--debug-file <path>`	디버그 로그를 특정 파일로 기록
`--mcp-config`	JSON 파일/문자열에서 MCP 서버 로드
`--strict-mcp-config`	`--mcp-config`의 MCP 서버만 사용
`--bare`	최소 모드 (훅, 스킬, 플러그인, MCP, 자동 메모리, CLAUDE.md 자동 발견 생략)
`--ide`	유효한 IDE가 정확히 하나일 때 자동 연결
`--init`	초기화 훅 실행 후 인터랙티브 모드 시작
`--init-only`	초기화 훅만 실행 후 종료
`--max-turns`	에이전트 턴 수 제한 (print 모드 한정)
`--max-budget-usd`	최대 지출액 제한 (print 모드 한정)
`--output-format`	출력 형식 (`text`, `json`, `stream-json`)
`--input-format`	입력 형식 (`text`, `stream-json`)
`--fallback-model`	기본 모델 과부하 시 폴백 모델 (print 모드 한정)
`--fork-session`	재개 시 새 세션 ID 생성 (`--resume`/`--continue`와 함께)
`--from-pr`	특정 PR과 연결된 세션 재개
`--remote`	claude.ai에 새 웹 세션 생성
`--teleport`	웹 세션을 로컬 터미널로 가져오기
`--remote-control`, `--rc`	원격 제어 활성화 상태로 시작
`--chrome` / `--no-chrome`	Chrome 통합 활성화/비활성화
`--agent`	에이전트 지정
`--agents`	JSON으로 커스텀 서브에이전트 동적 정의
`--plugin-dir`	디렉토리에서 플러그인 로드
`--settings`	Settings JSON 파일/문자열 로드
`--setting-sources`	로드할 설정 소스 (`user`, `project`, `local`)
`--session-id`	특정 UUID로 세션 시작
`--no-session-persistence`	세션을 디스크에 저장하지 않음 (print 모드 한정)
`--dangerously-skip-permissions`	권한 프롬프트 모두 건너뛰기 (`--permission-mode bypassPermissions`와 동일)
`--allow-dangerously-skip-permissions`	`bypassPermissions`를 `Shift+Tab` 모드 순환에 추가 (시작은 다른 모드로)
`--version`, `-v`	버전 출력

4-3. 시스템 프롬프트 플래그

Claude Code는 시스템 프롬프트를 커스터마이징하는 4가지 플래그를 제공합니다.

플래그	동작
`--system-prompt`	기본 프롬프트를 통째로 교체
`--system-prompt-file`	파일 내용으로 교체
`--append-system-prompt`	기본 프롬프트 뒤에 추가
`--append-system-prompt-file`	파일 내용을 기본 프롬프트 뒤에 추가

📌 추천: 대부분의 경우 --append-system-prompt 계열 플래그를 사용하세요. Claude Code의 내장 기능을 보존하면서 요구사항만 추가할 수 있습니다.

5. Bash 모드와 파일 멘션 활용

5-1. `!` 접두사로 Bash 명령 직접 실행

프롬프트 시작에 !을 붙이면 Claude를 거치지 않고 명령어를 즉시 실행하고, 출력을 대화 컨텍스트에 추가합니다.

! npm test
! git status
! ls -la

특징:

명령어와 출력을 대화 컨텍스트에 추가
실시간 진행 상황 및 출력 표시
Ctrl+B로 백그라운드 전환 가능
Tab 키로 이전 ! 명령어 자동완성
Escape, Backspace, Ctrl+U로 종료

5-2. `@`로 파일 경로 자동완성

@ 키를 누르면 파일 경로 자동완성이 트리거됩니다. 예: @src/components/Header.tsx 이 파일의 반응형 레이아웃을 고쳐줘

이 방법은 Claude에게 파일 위치를 설명하거나 검색을 기다리는 것보다 훨씬 빠릅니다.

6. 백그라운드 작업

Claude Code는 긴 시간이 걸리는 명령어를 백그라운드에서 실행할 수 있습니다.

백그라운드로 보내는 두 가지 방법:

Claude에게 백그라운드 실행을 요청
일반 Bash 도구 실행 중 Ctrl+B 누르기 (tmux 사용자는 두 번)

주요 특징:

출력은 파일에 기록되며 Claude가 Read 도구로 가져올 수 있음
각 작업에 고유 ID 부여
Claude Code 종료 시 자동 정리
출력이 5GB를 초과하면 자동 종료
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 환경변수로 비활성화 가능

자주 백그라운드에서 실행되는 명령어: 빌드 도구(webpack, vite, make), 패키지 매니저(npm, yarn, pnpm), 테스트 러너(jest, pytest), 개발 서버, 장시간 프로세스(docker, terraform).

7. Vim 에디터 모드

/config → Editor mode에서 Vim 스타일 편집을 활성화할 수 있습니다.

7-1. 모드 전환

명령	동작
`Esc`	NORMAL 모드 진입
`i` / `I`	커서 앞 / 줄 시작에서 삽입
`a` / `A`	커서 뒤 / 줄 끝에서 삽입
`o` / `O`	아래 / 위에 새 줄 열기
`v` / `V`	문자 단위 / 줄 단위 비주얼 선택

7-2. NORMAL 모드 이동

명령	동작
`h`/`j`/`k`/`l`	좌/하/상/우 이동
`w` / `e` / `b`	다음 단어 / 단어 끝 / 이전 단어
`0` / `$` / `^`	줄 시작 / 줄 끝 / 첫 비공백 문자
`gg` / `G`	입력 시작 / 끝
`f{char}` / `F{char}`	다음 / 이전 문자로 점프
`t{char}` / `T{char}`	다음 / 이전 문자 직전으로 점프
`;` / `,`	마지막 f/F/t/T 동작 반복 / 역방향 반복

7-3. NORMAL 모드 편집

명령	동작
`x`	문자 삭제
`dd` / `D`	줄 삭제 / 줄 끝까지 삭제
`dw`/`de`/`db`	단어 / 단어 끝까지 / 뒤로 단어 삭제
`cc` / `C`	줄 변경 / 줄 끝까지 변경
`yy` / `Y`	줄 복사
`p` / `P`	커서 뒤 / 앞에 붙여넣기
`>>` / `<<`	들여쓰기 / 내어쓰기
`J`	줄 합치기
`u` / `.`	실행 취소 / 마지막 변경 반복

7-4. 텍스트 객체 (NORMAL 모드)

d, c, y 같은 연산자와 함께 사용:

명령	동작
`iw` / `aw`	안쪽 / 바깥쪽 단어
`iW` / `aW`	안쪽 / 바깥쪽 WORD (공백 구분)
`i"` / `a"`	안쪽 / 바깥쪽 큰따옴표
`i'` / `a'`	안쪽 / 바깥쪽 작은따옴표
`i(` / `a(`	안쪽 / 바깥쪽 괄호
`i[` / `a[`	안쪽 / 바깥쪽 대괄호
`i{` / `a{`	안쪽 / 바깥쪽 중괄호

⚠️ Block-wise 비주얼 모드(Ctrl+V)는 지원되지 않습니다.

8. 알아두면 유용한 부가 기능

8-0. 권한 모드(Permission Modes) 한눈에 보기

/permissions, --permission-mode, Shift+Tab 등에서 자주 등장하는 권한 모드는 Claude가 도구를 사용할 때 어떤 방식으로 사용자에게 확인을 받을지 결정합니다. 공식 문서에 명시된 모드는 다음과 같습니다:

모드	동작	추천 사용 상황
`default`	파일 읽기는 자동 허용, 편집/명령은 사용자 확인	시작 단계, 민감한 작업
`acceptEdits`	파일 읽기 + 편집 자동 허용, 명령만 확인	검토하면서 코드 반복 작업
`plan`	읽기만 가능, 코드 수정 없이 계획만 작성	코드베이스 탐색, 리팩토링 계획
`auto`	모든 작업을 백그라운드 분류기가 검토 후 자동 처리 (Team/Enterprise/API 요금제 + Sonnet 4.6 또는 Opus 4.6 필요)	장시간 작업, 프롬프트 피로 감소
`dontAsk`	사전 승인된 도구만 허용 (그 외는 자동 거부)	잠긴 환경, CI 파이프라인
`bypassPermissions`	모든 권한 확인 건너뜀 (`.git`, `.vscode`, `.idea` 등 일부 예외)	격리된 컨테이너/VM 환경에서만

세션 안에서는 Shift+Tab으로 default → acceptEdits → plan → auto 순으로 모드를 순환할 수 있습니다 (auto는 활성화 조건이 충족된 경우에만, bypassPermissions는 시작 시 명시적으로 활성화한 경우에만 순환에 등장). 시작할 때부터 특정 모드로 시작하려면 claude --permission-mode plan처럼 사용합니다.

⚠️ 주의: bypassPermissions 모드는 프롬프트 인젝션이나 의도하지 않은 작업에 대한 보호가 전혀 없으므로 격리된 환경에서만 사용하세요. 백그라운드 안전성 검사는 유지하면서 자동화 수준을 높이고 싶다면 auto 모드를 사용하는 것이 더 안전합니다.

8-1. 자주 쓰이는 환경 변수

본문에서 언급된 환경 변수들을 한 곳에 정리합니다. 모든 환경 변수의 전체 목록은 공식 환경 변수 문서에서 확인할 수 있습니다:

환경 변수	용도
`CLAUDE_CODE_USE_BEDROCK=1`	Amazon Bedrock 사용 모드 활성화 (`/setup-bedrock`이 표시됨)
`CLAUDE_CODE_USE_VERTEX=1`	Google Vertex AI 사용 모드 활성화 (`/setup-vertex`가 표시됨)
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`	백그라운드 작업 기능 전체 비활성화
`CLAUDE_CODE_TASK_LIST_ID`	세션 간 작업 목록 공유 (예: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`)
`CLAUDE_CODE_NEW_INIT=1`	`/init` 실행 시 스킬, 훅, 개인 메모리 파일까지 안내하는 인터랙티브 흐름 사용
`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false`	프롬프트 자동 제안 기능 비활성화
`CLAUDE_CODE_SIMPLE`	`--bare` 플래그 사용 시 자동 설정됨

8-2. 트랜스크립트 뷰어 (Ctrl+O)

Ctrl+O로 토글되는 트랜스크립트 뷰어 안에서:

단축키	동작
`Ctrl+E`	모든 콘텐츠 표시 토글
`[`	전체 대화를 터미널 스크롤백에 기록 (풀스크린 렌더링 필요)
`v`	대화를 임시 파일에 기록하고 `$VISUAL`/`$EDITOR`로 열기
`q`, `Ctrl+C`, `Esc`	트랜스크립트 뷰 종료

8-3. 명령 기록 검색 (Ctrl+R)

Ctrl+R을 누르면 이전에 입력한 명령을 인터랙티브하게 검색할 수 있습니다:

Ctrl+R로 검색 시작
검색어 입력
Ctrl+R을 다시 눌러 더 오래된 매치 순환
Tab 또는 Esc로 매치 수락 후 편집, Enter로 즉시 실행
Ctrl+C 또는 빈 검색에서 Backspace로 취소

8-4. 음성 입력

음성 받아쓰기 기능이 활성화되어 있으면 Space를 눌러 사용할 수 있습니다. 길게 누르면 녹음, /voice tap으로 탭 토글 모드 가능. Claude.ai 계정이 필요합니다.

8-5. 세션 요약 (Session recap)

자리를 비웠다가 터미널로 돌아오면 Claude Code가 지금까지의 세션 진행 상황을 한 줄로 요약해 보여줍니다. 마지막 턴 이후 3분 이상 경과하고 터미널이 비포커스 상태일 때 백그라운드에서 생성됩니다. /recap 명령으로도 즉시 생성 가능하며, /config에서 자동 요약을 비활성화할 수 있습니다.

8-6. PR 리뷰 상태

오픈 PR이 있는 브랜치에서 작업 중이면 푸터에 클릭 가능한 PR 링크(예: "PR #446")가 표시됩니다. 색상으로 리뷰 상태를 나타냅니다:

🟢 녹색: 승인됨
🟡 노란색: 리뷰 대기 중
🔴 빨간색: 변경 요청됨
⚪ 회색: 초안
🟣 보라색: 머지됨

Cmd+click(Mac) / Ctrl+click(Win/Linux)으로 브라우저에서 PR 열기. gh CLI 설치 및 인증(gh auth login)이 필요합니다.

9. MCP 프롬프트

MCP 서버는 명령어로 표시되는 프롬프트를 노출할 수 있습니다. 형식은 /mcp__<server>__<prompt>이며, 연결된 서버에서 동적으로 발견됩니다. 자세한 내용은 MCP 프롬프트를 명령어로 사용하기 문서 참조.

10. 한눈에 보는 추천 워크플로우

처음 Claude Code를 사용하는 분들을 위한 추천 순서입니다:

claude 명령으로 세션 시작
/init 으로 프로젝트에 CLAUDE.md 생성 (프로젝트 컨텍스트 자동 학습)
/help 로 사용 가능한 명령어 확인
/terminal-setup 으로 Shift+Enter 멀티라인 입력 활성화 (필요한 터미널의 경우)
/permissions 로 도구 권한 사전 설정
/model 로 작업에 맞는 모델 선택
세션 길어지면 /context 로 사용량 확인, /compact 으로 압축
작업 종료 후 /cost 또는 /stats 로 사용량 점검
다음 날 claude -c 로 이어서 작업

마무리

Claude Code는 단순한 AI 챗봇이 아니라 터미널에 상주하는 코딩 에이전트입니다. 이 글에서 다룬 슬래시 명령어, 키보드 단축키, CLI 플래그를 충분히 활용하면 일반 IDE 환경에서는 어려운 자동화와 워크플로우를 구축할 수 있습니다.

다만 Claude Code는 매우 빠르게 업데이트되고 있어 일부 명령어는 시간이 지나면서 변경되거나 새로 추가될 수 있습니다. 가장 정확하고 최신인 정보는 항상 다음 공식 문서에서 확인하시기 바랍니다:

세션 안에서는 언제든지 /help 를 입력하면 현재 환경에서 사용 가능한 모든 명령어를 즉시 확인할 수 있다는 점도 잊지 마세요.

이 글의 모든 명령어 및 단축키 정보는 2026년 4월 기준 Anthropic 공식 Claude Code 문서에서 직접 확인한 내용입니다.

클로드 코드(Claude Code) 맥(Mac)에서 실행하는 모든 방법 — 터미널부터 IDE, 데스크톱 앱, 웹까지

2026-04-26T08:39:12.215-07:00

요즘 개발자들 사이에서 가장 뜨거운 도구 중 하나가 바로 Claude Code입니다. Anthropic이 만든 에이전트형 코딩 도구로, 코드베이스를 이해하고, 파일을 직접 수정하며, 명령어를 실행하고, git 작업까지 자연어로 처리해줍니다.

저도 최근에 본격적으로 써보면서 깨달은 게 있습니다. "맥에서 Claude Code를 써보자"라고 결심하고 검색해 보면 정보가 너무 분산되어 있다는 겁니다. 어떤 글은 터미널 설치만 다루고, 어떤 글은 VS Code 확장만 다루고, 데스크톱 앱이 있다는 사실조차 모르는 사람도 많더라고요. "그래서 뭘로 시작해야 하지?"라는 질문에 한 번에 답해주는 글이 잘 안 보였습니다.

그래서 이번 글에서는 맥에서 Claude Code를 실행할 수 있는 모든 공식 방법을 한자리에 정리해 봤습니다. 모든 내용은 Anthropic 공식 문서와 Claude.com을 기준으로 작성했고, 추측이 아닌 직접 확인된 사실만 담았습니다.

📌 이 글이 다루는 것: 맥에서 Claude Code에 접근할 수 있는 공식 진입점 10가지를 4가지 카테고리(터미널, 다른 설치 방식, IDE, GUI/웹/협업 도구)로 정리했습니다.

시작하기 전: 꼭 알아둘 사항

시스템 요구사항

Claude Code 공식 setup 페이지에 따르면, 맥에서 Claude Code를 실행하려면:

macOS 13.0 이상 (Ventura 이상)
4GB 이상의 RAM, x64 또는 ARM64 프로세서 (M1/M2/M3 모두 지원)
인터넷 연결
Bash 또는 Zsh 셸 (맥은 기본으로 Zsh 사용)

유료 플랜이 필요합니다

Claude Code는 무료 플랜에서는 사용할 수 없습니다. Claude 공식 가격 페이지에 따르면:

Pro 플랜: 월 $20 (연간 결제 시 $17/월)
Max 플랜: 월 $100 (5x) 또는 $200 (20x)
Team 플랜: 시트당 월 $20부터
Enterprise 플랜: 영업 문의

또는 Anthropic Console에서 API 키를 발급받아 사용량 기반으로 결제할 수도 있습니다.

💡 참고: 가격과 플랜 정책은 자주 변경됩니다. 최신 정보는 반드시 공식 가격 페이지에서 확인하세요.

카테고리 1. 터미널에서 사용하기

가장 기본적이고 강력한 방법입니다. Claude Code의 모든 기능을 활용할 수 있습니다.

방법 1. macOS 기본 터미널 (Terminal.app)

가장 단순한 방법입니다. 맥에 기본 내장된 터미널 앱을 사용합니다.

터미널 열기

Cmd + Space로 Spotlight를 띄우고 "터미널" 또는 "Terminal"을 입력해서 실행합니다.

Native Installer로 설치 (공식 권장)

Claude Code 공식 setup 가이드가 가장 권장하는 방법은 네이티브 설치 프로그램입니다. Node.js가 필요 없고, 백그라운드에서 자동으로 업데이트됩니다.

터미널에 다음 명령어를 입력합니다:

curl -fsSL https://claude.ai/install.sh | bash

설치가 끝나면 새 터미널 창을 열고 다음 명령으로 확인합니다:

claude --version

실행하기

프로젝트 폴더로 이동한 후 claude만 입력하면 됩니다:

cd ~/projects/my-app
claude

처음 실행하면 브라우저가 열리면서 로그인 화면이 뜹니다. Claude 계정으로 로그인하면 됩니다.

방법 2. iTerm2

iTerm2는 맥 개발자들이 가장 많이 쓰는 서드파티 터미널입니다. 분할 창, 검색, 자동완성 등 기본 터미널보다 훨씬 풍부한 기능을 제공합니다.

설치 방법은 동일합니다. iTerm2에서 위와 같은 curl 명령어를 실행하면 됩니다.

iTerm2 사용 시 추가 팁

Claude Code 터미널 설정 공식 문서에 따르면, iTerm2에서는:

Shift+Enter로 줄바꿈이 별도 설정 없이 작동합니다.
데스크톱 알림을 받으려면 iTerm2 설정 → Profiles → Terminal에서 "Notification Center Alerts"를 활성화하고, "Filter Alerts" → "Send escape sequence-generated alerts"를 켜야 합니다.
Option 키 단축키(예: Option+P로 모델 전환)를 사용하려면 Settings → Profiles → Keys → General에서 Left/Right Option key를 "Esc+"로 설정합니다.

방법 3. Ghostty

Ghostty는 비교적 최근에 등장한 GPU 가속 터미널입니다. Claude Code 공식 문서에 따르면, Ghostty, Kitty, iTerm2 세 가지 터미널만이 데스크톱 알림을 별도 설정 없이 자동 지원합니다.

공식 터미널 설정 문서에 따르면 Ghostty에서는 Shift+Enter 줄바꿈이 기본 동작하고, OS 알림 센터로 알림이 자동 전달됩니다.

카테고리 2. 다른 설치 방식 (터미널 사용은 동일)

Native Installer 외에 익숙한 패키지 매니저로 설치하고 싶다면 아래 방법을 선택할 수 있습니다. 설치 후 터미널에서 claude 명령으로 실행하는 것은 동일합니다.

방법 4. Homebrew로 설치하기

Homebrew를 이미 사용 중이라면 더 익숙한 방법일 수 있습니다.

Homebrew 공식 cask 페이지에서 확인할 수 있듯이, Claude Code는 Homebrew 캐스크로 제공됩니다:

brew install --cask claude-code

공식 setup 문서에 따르면 두 가지 cask가 있습니다:

claude-code: 안정 버전 (보통 최신보다 약 1주일 늦게 배포되며, 큰 회귀 버그가 있는 릴리스는 건너뜀)
claude-code@latest: 최신 버전 즉시 반영

업데이트는 다음 명령으로 수동 실행해야 합니다 (네이티브 인스톨러와 달리 자동 업데이트되지 않음):

brew upgrade claude-code

방법 5. npm으로 설치하기

Node.js를 이미 사용하고 있다면 npm으로도 설치할 수 있습니다. 공식 문서에 따르면 Node.js 18 이상이 필요합니다.

npm install -g @anthropic-ai/claude-code

⚠️ 주의: 공식 문서는 sudo npm install -g를 사용하지 말라고 명시합니다. 권한 문제와 보안 리스크가 발생할 수 있습니다. 권한 에러가 난다면 공식 트러블슈팅 문서를 참고하세요.

npm 패키지 페이지에서 패키지 자체도 확인할 수 있습니다.

카테고리 3. IDE에서 사용하기

코드 에디터/IDE 안에서 Claude Code를 시각적으로 다루고 싶다면 아래 방법들이 있습니다. 시각적 diff 리뷰, 진단 자동 공유 등 IDE 통합 기능을 활용할 수 있습니다.

방법 6. VS Code 확장 프로그램

터미널이 부담스럽다면 Visual Studio Code에서 직접 사용할 수 있습니다.

Anthropic이 발표한 공식 블로그에서 소개한 대로, Claude Code 네이티브 VS Code 확장(베타)이 출시되었습니다. 사이드바 패널에서 인라인 diff를 실시간으로 보여주는 그래픽 인터페이스를 제공합니다.

설치 방법

VS Code를 실행합니다.
Cmd + Shift + X로 확장 프로그램 패널을 엽니다.
"Claude Code"를 검색합니다.
publisher가 Anthropic인지 반드시 확인한 뒤 설치합니다.

또는 Visual Studio Marketplace에서 직접 설치할 수도 있습니다.

공식 VS Code 문서에 따르면 VS Code 1.98.0 이상이 필요합니다.

주요 기능

공식 문서에 명시된 기능들입니다:

인라인 diff 리뷰: 변경 사항을 사이드바에서 바로 확인하고 승인/거부
@-mention 파일 참조: @filename으로 파일을 컨텍스트에 추가
Plan 리뷰: Plan Mode에서 Claude의 계획을 마크다운 문서로 열고 인라인 코멘트
다중 탭/창 세션: 여러 대화를 병렬로 진행
세션 히스토리: 키워드 검색으로 과거 세션 찾기
자동 진단 공유: TypeScript 에러, ESLint 경고 등을 Claude가 자동으로 인식
체크포인트: Claude가 편집한 파일을 추적해 이전 상태로 되돌릴 수 있음

Cursor에서도 사용 가능

공식 VS Code 문서는 Cursor용 별도 설치 버튼("Install for Cursor")도 제공합니다. Cursor가 VS Code 기반이기 때문에 동일한 확장이 동작합니다. Cursor 사용자는 자체 AI 에이전트와 Claude Code를 같은 창에서 함께 쓸 수 있다는 점이 흥미롭습니다.

방법 7. JetBrains IDE 플러그인 (IntelliJ, WebStorm, PyCharm 등)

JetBrains 제품군을 사용한다면 전용 플러그인이 있습니다.

설치 방법

공식 JetBrains 통합 문서에 따르면:

JetBrains IDE를 실행합니다.
Settings → Plugins로 이동합니다.
Marketplace에서 "Claude Code"를 검색합니다.
설치 후 IDE를 재시작합니다.

JetBrains Marketplace에서 직접 확인할 수도 있습니다. 단, 이 플러그인을 사용하려면 Claude Code CLI가 별도로 설치되어 있어야 합니다.

지원 IDE

공식 문서에 명시된 지원 IDE는 다음과 같습니다 — IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, GoLand.

사용 방법

공식 문서에 따르면 두 가지 방식으로 사용할 수 있습니다:

IDE의 통합 터미널에서 직접: 통합 터미널에서 claude를 실행하면 모든 통합 기능이 활성화됩니다.
외부 터미널에서 연결: 외부 터미널에서 claude를 실행한 후 /ide 명령을 입력하면 JetBrains IDE에 연결됩니다.

주요 기능

빠른 실행: macOS에서는 Cmd+Esc로 IDE에서 바로 Claude Code 실행
diff 뷰어: 변경 사항을 IDE의 diff 뷰어로 보기
선택 컨텍스트 자동 공유: 현재 선택한 코드/탭이 자동으로 Claude에 전달
파일 참조 단축키: macOS에서 Cmd+Option+K로 파일 참조 삽입 (예: @File#L1-99)
진단 자동 공유: IDE의 lint, syntax 에러를 Claude가 자동 인식

카테고리 4. GUI 앱과 웹/협업 도구

터미널이나 IDE 없이도 Claude Code를 사용할 수 있습니다. 비개발자나 가벼운 작업, 이동 중 작업에 적합합니다.

방법 8. Claude 데스크톱 앱

터미널 없이 GUI만으로 사용하고 싶다면 Claude 데스크톱 앱이 가장 편한 선택입니다.

설치

Claude 다운로드 페이지에서 macOS용 설치 파일을 받습니다. 일반 사용자는 DMG 파일을 다운로드해 Applications 폴더로 드래그해서 설치하면 됩니다 (기업 배포용으로는 PKG 인스톨러가 별도로 제공됩니다 — 기업 배포 가이드 참고).

설치 후 Applications 폴더에서 Claude를 실행하고 계정으로 로그인합니다.

Claude Code 사용

데스크톱 quickstart 공식 문서에 따르면, 앱 상단의 Code 탭을 클릭하면 Claude Code 인터페이스로 진입합니다.

데스크톱 앱은 CLI와 동일한 엔진을 사용하며, 같은 프로젝트에서 동시에 실행할 수도 있습니다. 설정도 공유됩니다 (CLAUDE.md 파일, MCP 서버, hooks, skills, settings 등). 공식 desktop 가이드에 따르면, CLI에서 진행하던 세션을 터미널에서 /desktop 명령으로 데스크톱 앱으로 그대로 옮길 수도 있습니다.

💡 데스크톱 앱은 Code 탭에서 Local 세션 외에도 Remote(Anthropic 클라우드 인프라에서 실행, 앱을 닫아도 계속 작동), SSH(원격 머신에 접속) 옵션도 제공합니다. 환경 선택, 프로젝트 폴더 지정, 모델 선택, 권한 모드 설정을 프롬프트 영역에서 직접 할 수 있습니다.

방법 9. Claude Code on the Web (브라우저)

claude.ai/code에 접속하면 브라우저에서 Claude Code를 사용할 수 있습니다.

Claude Code 제품 페이지의 설명에 따르면, 웹 버전은 GitHub 리포지토리와 연결해 사용하는 형태입니다. 브라우저에서 빠르게 접근할 수 있어서 병렬 작업이나 이동 중 코딩에 적합합니다. 클라우드 인프라에서 실행되기 때문에 노트북을 닫아도 작업이 계속 진행됩니다.

💡 로컬 파일 작업이 필요하다면 데스크톱 앱이나 CLI를 쓰는 게 낫습니다. 웹 버전은 GitHub 리포지토리 기반 작업에 최적화되어 있습니다.

방법 10. Slack 통합

팀과 Slack에서 협업한다면, Slack에서 직접 Claude Code 작업을 시작할 수 있습니다.

공식 Slack 통합 문서에 따르면:

Slack에서 @Claude로 멘션하고 코딩 작업을 요청합니다.
Claude가 자동으로 코딩 작업인지 감지하고, claude.ai/code에서 새 세션을 생성합니다.
진행 상황이 Slack 스레드에 업데이트됩니다.
완료되면 PR 생성 버튼이 제공됩니다.

Claude for Slack 페이지에서 더 자세한 내용을 확인할 수 있습니다. 단, Claude Code on the web 접근 권한이 필요하며, 현재는 GitHub 리포지토리만 지원합니다.

어떤 방법을 선택해야 할까?

각 사용자 유형별 추천을 정리하면 다음과 같습니다:

터미널이 익숙한 개발자: 기본 터미널 또는 iTerm2/Ghostty + 네이티브 인스톨러 조합이 가장 빠르고 가볍습니다.
VS Code를 주력으로 쓰는 개발자: VS Code 확장이 시각적인 diff 리뷰 측면에서 가장 편합니다.
JetBrains IDE 사용자: 전용 플러그인 + CLI 조합으로 IDE 컨텍스트를 그대로 활용할 수 있습니다.
터미널이 부담스러운 분: Claude 데스크톱 앱이 가장 진입 장벽이 낮습니다.
이동 중에도 코딩하고 싶다면: 웹 버전이나 Slack 통합을 활용하세요.
Homebrew를 이미 쓰는 분: brew install --cask claude-code가 익숙한 방식이라 편합니다.

공식 문서에서는 네이티브 인스톨러를 가장 권장합니다. Node.js 같은 의존성이 필요 없고, 백그라운드 자동 업데이트가 되기 때문입니다.

설치 후 확인 명령어

어떤 방법으로 설치했든, 설치가 잘 되었는지 확인할 때 유용한 명령어입니다:

# 버전 확인
claude --version

# 설치/설정 진단 (Node 버전, 인증 상태, 파일 권한 등을 자동 점검)
claude doctor

claude doctor는 공식 트러블슈팅 문서에서 자주 언급되는 진단 도구입니다. 뭔가 이상한데 원인을 모르겠을 때 가장 먼저 실행해보면 됩니다.

마치며

이렇게 맥에서 Claude Code를 사용할 수 있는 공식 방법들을 모두 정리해 봤습니다. 처음에는 "터미널에서 claude만 치면 되는 도구"라고 생각했는데, 정리해보니 IDE, 데스크톱 앱, 웹, Slack까지 정말 다양한 진입점이 있어서 저도 정리하면서 새로 알게 된 것들이 꽤 있었습니다. 특히 CLI 세션을 /desktop 명령으로 데스크톱 앱으로 옮길 수 있다는 부분은 처음 알았네요.

저는 개인적으로 iTerm2 + 네이티브 인스톨러 조합으로 시작해서, 시각적인 리뷰가 필요할 때 VS Code 확장을 쓰는 패턴을 선호합니다. 같은 계정이라면 공식 문서에서 설명하듯이 설정과 세션이 공유되기 때문에 자유롭게 오갈 수 있다는 게 큰 장점입니다.

이 글이 처음 Claude Code에 입문하는 분들께 작은 길잡이가 되었으면 좋겠습니다. 자주 변경되는 정보(가격, 새 기능, 지원 플랫폼)는 반드시 다음 공식 자료에서 다시 한번 확인하세요:

다음 글에서는 실제로 Claude Code를 사용하면서 느낀 점과 워크플로우 팁을 정리해보겠습니다. 즐거운 바이브 코딩 되세요! 🚀

클로드 코드(Claude Code) 실행 방법과 실행 옵션 완벽 정리

2026-04-26T07:46:00.000-07:00

터미널에서 자연어로 코드를 다루는 Claude Code는 단순한 자동완성 도구가 아니라, 코드베이스 전체를 이해하고 작업을 대신 수행하는 에이전트형(agentic) 코딩 도구입니다. 이 글에서는 설치 방법부터 실행 옵션, 권한 모드까지 공식 문서를 근거로 정확하게 정리했습니다.

본문에 등장하는 모든 옵션과 명령어는 Claude Code 공식 문서 기준이며, 이 글의 작성 시점은 2026년 4월입니다.

1. Claude Code란?

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. 자연어로 명령하면 파일을 읽고, 수정하고, 테스트를 돌리고, Git 작업까지 처리합니다.

용어 참고

에이전트형(agentic) 도구: 사람이 한 줄씩 시키지 않아도 목표를 받고 스스로 단계를 나누어 실행하는 도구를 말합니다. Claude Code는 "버그를 고쳐줘"라고만 말해도 관련 파일을 찾고, 수정안을 만들고, 사용자에게 승인을 요청하는 식으로 동작합니다.
REPL: Read-Eval-Print Loop의 줄임말로, 명령을 입력하면 즉시 평가해 결과를 보여주는 대화형 인터페이스입니다. claude 명령으로 실행되는 화면이 바로 REPL입니다.

2. 시스템 요구사항

공식 문서(Advanced setup)에 따른 요구사항입니다.

운영체제
- macOS 13.0 이상
- Windows 10 1809 이상 또는 Windows Server 2019 이상
- Ubuntu 20.04 이상
- Debian 10 이상
- Alpine Linux 3.19 이상
하드웨어: RAM 4GB 이상, x64 또는 ARM64 프로세서
네트워크: 인터넷 연결 필수
셸: Bash, Zsh, PowerShell, CMD
위치: Anthropic 지원 국가에서만 사용 가능
계정: Claude Pro, Max, Team, Enterprise 구독 또는 Anthropic Console 계정

참고: Windows에서 네이티브로 실행할 경우 Git for Windows가 필요하며, WSL을 쓰면 별도로 필요하지 않습니다.

3. 설치 방법

Claude Code 설치는 크게 다섯 가지 방법이 있습니다 (네이티브, Homebrew, WinGet, npm, Linux 패키지 매니저). 네이티브 설치(native installer)가 공식 권장 방법이며, Node.js 등 외부 의존성이 없습니다.

3-1. 네이티브 설치 (권장)

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

네이티브 설치는 백그라운드에서 자동으로 최신 버전으로 업데이트됩니다.

3-2. Homebrew (macOS)

brew install --cask claude-code

Homebrew는 두 가지 cask를 제공합니다.

claude-code: 안정(stable) 채널을 따라가며, 일반적으로 약 1주일 정도 늦지만 큰 회귀(regression)가 있는 릴리스는 건너뜁니다.
claude-code@latest: 최신(latest) 채널을 따라가며 새 버전이 나오는 즉시 받아옵니다.

Homebrew는 자동 업데이트가 되지 않으므로, 직접 brew upgrade claude-code(또는 brew upgrade claude-code@latest)를 실행해야 합니다.

3-3. WinGet (Windows)

winget install Anthropic.ClaudeCode

WinGet도 자동 업데이트가 되지 않으므로 주기적으로 winget upgrade Anthropic.ClaudeCode를 실행해야 합니다.

3-4. npm (레거시)

Node.js 18 이상 환경이 있다면 npm으로도 설치할 수 있습니다.

npm install -g @anthropic-ai/claude-code

주의: sudo npm install -g는 권한 문제와 보안 위험을 일으킬 수 있어 공식적으로 비권장됩니다. 권한 오류가 발생하면 트러블슈팅 문서를 참고하세요.

npm 패키지는 네이티브 설치와 동일한 바이너리를 가져오며, 설치된 claude 바이너리 자체는 Node를 호출하지 않습니다. 지원되는 npm 플랫폼은 darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64입니다.

3-5. Linux 패키지 매니저 (apt / dnf / apk)

Debian/Ubuntu, Fedora/RHEL, Alpine에서는 서명된 저장소를 통해 설치할 수 있습니다. 자세한 명령어와 GPG 키 검증 방법은 공식 Advanced setup 문서를 참고하세요.

3-6. 설치 확인

claude --version

좀 더 상세한 진단을 원한다면 claude doctor를 실행하세요. 인증 상태, MCP 서버 상태, 파일 권한 등을 점검해줍니다.

4. 로그인과 인증

설치 후 처음 claude 명령을 실행하면 로그인 프로세스가 시작됩니다.

claude
# 첫 실행 시 로그인 안내가 나타남

세션 안에서는 /login 슬래시 명령으로 로그인할 수 있습니다.

지원되는 계정 종류는 다음과 같습니다.

Claude Pro, Max, Team, Enterprise 구독 (권장)
Anthropic Console 계정 (선결제 크레딧 기반 API 사용)
Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등 엔터프라이즈 클라우드 제공자

참고: 무료 Claude.ai 계정으로는 Claude Code를 사용할 수 없습니다.

CI/CD 등 스크립트 환경에서 쓸 장기 OAuth 토큰이 필요하다면 다음 명령으로 발급받을 수 있습니다.

claude setup-token

5. 기본 실행 명령어

5-1. 대화형 세션 시작

cd /path/to/your/project
claude

프로젝트 디렉터리에서 실행하면 환영 화면과 함께 세션이 시작됩니다. /help로 명령어 목록을, /resume으로 이전 대화를 이어갈 수 있습니다.

5-2. 초기 프롬프트와 함께 시작

claude "이 프로젝트가 무엇을 하는지 설명해줘"

5-3. 일회성 쿼리(print 모드)

대화형 세션을 띄우지 않고 한 번만 답변을 받고 종료하려면 -p 또는 --print 옵션을 씁니다.

claude -p "이 함수를 설명해줘"

5-4. 파이프 입력

표준 입력으로 들어온 내용을 그대로 분석시킬 수 있습니다.

cat logs.txt | claude -p "이 로그에서 에러를 찾아줘"

5-5. 이전 대화 이어가기

claude -c: 현재 디렉터리에서 가장 최근 대화를 이어갑니다.
claude -r "<세션이름 또는 ID>" "추가 질문": 특정 세션을 재개합니다.
claude -r: 인터랙티브 picker로 세션을 고를 수 있습니다.

5-6. 업데이트와 설치 관리

claude update             # 즉시 최신 버전으로 업데이트
claude install stable     # stable 채널 바이너리 설치
claude install 2.1.118    # 특정 버전 설치

5-7. 인증 관련

claude auth login          # 로그인
claude auth logout         # 로그아웃
claude auth status         # 인증 상태(JSON)
claude auth status --text  # 사람이 읽기 쉬운 형식

claude auth status는 로그인되어 있으면 종료 코드 0, 아니면 1을 반환하므로 스크립트에서 활용하기 좋습니다.

5-8. 기타 자주 쓰는 명령

명령	설명
`claude agents`	설정된 서브에이전트(subagent) 목록 보기
`claude mcp`	MCP 서버 설정
`claude plugin`	플러그인 관리
`claude remote-control`	Remote Control 서버 시작
`claude setup-token`	장기 OAuth 토큰 발급 (CI 용)

6. 핵심 실행 옵션(플래그) 정리

여기서부터는 claude 실행 시 함께 쓰는 옵션입니다. 공식 문서의 CLI reference를 기준으로 자주 쓰이는 것 위주로 정리했습니다.

참고: claude --help가 모든 플래그를 보여주지는 않습니다. --help에 없다고 해서 그 옵션이 없는 것은 아니므로, 정확한 목록은 항상 공식 CLI reference를 확인하는 것이 좋습니다.

6-1. 모델·세션 관련

옵션	설명	예시
`--model`	사용할 모델 지정 (`sonnet`, `opus` 같은 alias 또는 정식 이름)	`claude --model claude-sonnet-4-6`
`--effort`	추론 노력 수준 (`low`, `medium`, `high`, `xhigh`, `max`). 모델에 따라 가능한 값이 다릅니다	`claude --effort high`
`--fallback-model`	기본 모델이 과부하일 때 대체할 모델 (print 모드 전용)	`claude -p --fallback-model sonnet "..."`
`--name`, `-n`	세션 표시 이름 지정 (`/resume`에서 보임)	`claude -n "auth-refactor"`
`--session-id`	특정 세션 ID(UUID) 사용	`claude --session-id "550e8400-..."`
`--continue`, `-c`	현재 디렉터리의 최근 대화 이어가기	`claude --continue`
`--resume`, `-r`	특정 세션 재개	`claude --resume auth-refactor`
`--fork-session`	재개 시 새 세션 ID로 분기	`claude --resume abc --fork-session`

6-2. 작업 디렉터리·파일

옵션	설명
`--add-dir`	Claude가 읽고 수정할 수 있는 추가 디렉터리 지정
`--worktree`, `-w`	격리된 git worktree 안에서 시작
`--tmux`	worktree 세션을 tmux로 실행 (`--worktree` 필요)

6-3. 시스템 프롬프트 커스터마이징

Claude Code는 기본 시스템 프롬프트를 갖고 있고, 이를 추가(append) 또는 대체(replace) 할 수 있습니다.

옵션	동작
`--system-prompt`	기본 시스템 프롬프트를 통째로 대체
`--system-prompt-file`	파일 내용으로 시스템 프롬프트 대체
`--append-system-prompt`	기본 프롬프트 뒤에 텍스트 추가
`--append-system-prompt-file`	기본 프롬프트 뒤에 파일 내용 추가

--system-prompt와 --system-prompt-file은 함께 쓸 수 없습니다. 대부분의 경우 append 계열을 쓰는 것이 안전합니다. Claude Code의 기본 능력을 유지하면서 추가 규칙만 얹을 수 있기 때문입니다.

claude --append-system-prompt "항상 TypeScript를 사용해."

6-4. 도구 제어

옵션	설명
`--tools`	Claude가 쓸 수 있는 빌트인 도구 제한 (`""`은 전부 비활성, `"default"`은 전부 허용)
`--allowedTools`	권한 묻지 않고 바로 실행할 도구 지정
`--disallowedTools`	모델 컨텍스트에서 제거할 도구 지정
`--disable-slash-commands`	모든 슬래시 명령과 skill 비활성화

# Bash, Edit, Read만 허용
claude --tools "Bash,Edit,Read"

# git log, git diff는 권한 안 묻고 실행
claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"

6-5. 권한 모드 (실행 시 옵션)

권한 모드는 --permission-mode 플래그로 시작 시점에 지정할 수 있습니다. (자세한 내용은 7장 참고)

claude --permission-mode plan
claude --permission-mode acceptEdits
claude --permission-mode auto
claude --permission-mode dontAsk
claude --permission-mode bypassPermissions

# bypassPermissions와 동일한 단축 플래그
claude --dangerously-skip-permissions

# bypassPermissions를 cycle에는 추가하지만 시작 모드는 다른 것으로 지정
claude --permission-mode plan --allow-dangerously-skip-permissions

6-6. Print 모드 전용 옵션

-p(print) 모드와 함께 쓰는 옵션들입니다. 자동화·CI 환경에서 주로 사용됩니다.

옵션	설명
`--output-format`	출력 형식 (`text`, `json`, `stream-json`)
`--input-format`	입력 형식 (`text`, `stream-json`)
`--max-turns`	에이전트 턴 수 제한
`--max-budget-usd`	최대 비용(USD) 제한
`--no-session-persistence`	세션을 디스크에 저장하지 않음
`--json-schema`	결과를 지정한 JSON Schema에 맞춰 검증된 JSON으로 반환
`--include-partial-messages`	스트리밍 중 부분 메시지도 포함

claude -p "테스트 실행하고 실패한 것만 리포트해줘" \
  --output-format json \
  --max-turns 5 \
  --max-budget-usd 1.00

6-7. 빠른 실행을 위한 `--bare`

스크립트에서 빠르게 호출하기 위한 최소 모드입니다. hooks, skills, plugins, MCP 서버, 자동 메모리, CLAUDE.md 등의 자동 탐색을 모두 건너뜁니다. 이 모드에서도 Bash, 파일 읽기/쓰기 도구는 사용 가능합니다.

claude --bare -p "이 함수의 시간 복잡도는?"

6-8. 디버깅·통합 관련

옵션	설명
`--debug`	디버그 모드 활성화. 카테고리 필터링 가능 (예: `"api,mcp"`)
`--debug-file <path>`	디버그 로그를 특정 파일에 기록
`--verbose`	상세 로깅
`--ide`	시작 시 IDE에 자동 연결 (단일 IDE만 감지될 때)
`--chrome` / `--no-chrome`	Chrome 통합 켜기/끄기
`--mcp-config`	JSON 파일/문자열에서 MCP 서버 로드
`--strict-mcp-config`	`--mcp-config`로 지정한 MCP만 사용
`--settings`	settings JSON 파일/문자열 로드
`--setting-sources`	로드할 설정 소스 (`user`, `project`, `local`)

7. 권한 모드(permission mode) 자세히 보기

Claude Code는 사용자가 매번 승인할지, 아니면 자율적으로 실행할지 선택할 수 있도록 권한 모드를 제공합니다. 공식 문서 Choose a permission mode 기준입니다.

세션 중에는 Shift+Tab 으로 모드를 순환할 수 있습니다 (default → acceptEdits → plan → auto). 단, auto는 Team/Enterprise/API 플랜과 Claude Sonnet 4.6 또는 Opus 4.6 모델이 필요하므로, 플랜이나 모델이 맞지 않으면 cycle에 나타나지 않을 수 있습니다. bypassPermissions는 --permission-mode bypassPermissions, --dangerously-skip-permissions, 또는 --allow-dangerously-skip-permissions 플래그로 시작했을 때만 cycle에 포함됩니다.

참고: CLI reference에 따르면 과거 사용되던 --enable-auto-mode 플래그는 v2.1.111에서 제거되었으며, 이제는 시작부터 auto 모드를 쓰려면 --permission-mode auto를 사용합니다.

모드	묻지 않고 가능한 동작	적합한 상황
`default`	파일 읽기	처음 시작, 민감한 작업
`acceptEdits`	파일 읽기 + 수정	코드 수정 반복 작업
`plan`	파일 읽기 (수정 불가)	코드베이스 탐색, 리팩터링 계획
`auto`	모든 동작(분류기로 백그라운드 검사)	장시간 작업, 프롬프트 피로 감소
`dontAsk`	사전 허용된 도구만	CI 등 잠긴 환경
`bypassPermissions`	모든 동작 (검사 없음)	격리된 컨테이너/VM에서만

7-1. plan 모드

Claude가 파일을 읽고 셸 명령으로 탐색하지만 소스 코드는 수정하지 않습니다. 대신 계획 파일을 작성하고 사용자의 승인을 기다립니다. 한 번의 요청에만 적용하려면 프롬프트 앞에 /plan을 붙이면 됩니다.

7-2. auto 모드 (연구 프리뷰)

별도의 분류기 모델이 각 동작을 검토해 작업 범위를 벗어나는 escalation, 의심스러운 인프라 접근, 프롬프트 인젝션 의심 동작을 차단합니다. 공식 문서는 이 모드를 research preview로 분류하며, 프롬프트 부담을 줄여주지만 안전을 보장하지는 않는다고 명시합니다.

이용 가능 플랜: Team, Enterprise, API 플랜에서만 사용 가능
모델 제한: Claude Sonnet 4.6 또는 Claude Opus 4.6 필요. Haiku, claude-3 모델, 서드파티 제공자(Bedrock, Vertex, Foundry)에서는 동작하지 않음
비용: 분류기 호출도 토큰 사용량에 포함됨

기본 차단 항목 예시:

curl | bash 같이 외부 코드 다운로드 후 실행
외부 엔드포인트로 민감 데이터 전송
프로덕션 배포 및 마이그레이션
클라우드 스토리지 대량 삭제
IAM/저장소 권한 부여
main 브랜치 직접 푸시, force push 같은 파괴적 소스 제어 동작

기본 허용 항목 예시:

작업 디렉터리 내 로컬 파일 작업
락 파일/매니페스트에 이미 선언된 의존성 설치
.env 읽고 일치하는 API에만 자격증명 전송
읽기 전용 HTTP 요청

7-3. dontAsk 모드

명시적으로 허용된 도구가 아니면 모두 자동 거부합니다. 완전 비대화형이라 CI 파이프라인에 적합합니다.

claude --permission-mode dontAsk

7-4. bypassPermissions 모드

모든 권한 검사를 건너뜁니다. 다만 .git, .vscode, .idea 디렉터리 쓰기는 여전히 확인을 거치고, .claude 디렉터리도 .claude/commands, .claude/agents, .claude/skills를 제외하면 확인을 거칩니다.

claude --permission-mode bypassPermissions
# 또는 동일한 의미의 단축 플래그
claude --dangerously-skip-permissions

⚠️ 주의: 이 모드는 프롬프트 인젝션이나 의도치 않은 동작에 대한 보호가 전혀 없습니다. 격리된 컨테이너, VM, 인터넷이 차단된 devcontainer에서만 사용해야 합니다. 더 안전한 자동화가 필요하면 auto 모드를 검토하세요.

8. 자동 업데이트 제어

네이티브 설치본은 백그라운드에서 자동 업데이트되지만, 채널과 동작을 세밀하게 제어할 수 있습니다. 설정 파일은 settings.json이며, 자세한 키 목록은 Settings 문서를 참고하세요.

8-1. 릴리스 채널 변경

{
  "autoUpdatesChannel": "stable"
}

"latest" (기본값): 새 기능 즉시 반영
"stable": 약 1주일 늦지만 큰 회귀가 있는 릴리스는 건너뜀

세션 안에서 /config → Auto-update channel 메뉴로도 바꿀 수 있습니다.

8-2. 최소 버전 고정

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

minimumVersion 아래로는 자동 업데이트나 claude update로도 다운그레이드되지 않습니다.

8-3. 자동 업데이트 비활성화

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER는 백그라운드 체크만 끕니다. claude update나 claude install 같은 수동 명령까지 막으려면 DISABLE_UPDATES를 설정해야 합니다. 자세한 환경변수 목록은 Environment variables 문서를 참고하세요.

9. 실전 시나리오별 추천 실행 명령

공식 문서의 옵션을 조합해 실제 상황에 어떻게 쓰면 좋은지 예시를 정리했습니다. 상황 설명은 공식 문서에 명시된 옵션 의미를 기반으로 한 활용 예시입니다.

9-1. 처음 프로젝트 탐색

cd my-project
claude --permission-mode plan

plan 모드로 시작하면 코드베이스만 읽고 수정하지 않으므로, 안전하게 구조를 파악할 수 있습니다.

9-2. 코드 리팩터링

claude -n "auth-refactor" --permission-mode acceptEdits

세션 이름을 붙여두면 나중에 claude --resume auth-refactor로 곧장 이어갈 수 있고, acceptEdits 모드로 파일 수정은 자동 승인하되 셸 명령은 매번 확인할 수 있습니다.

9-3. CI에서 자동 검토

claude -p "이 PR의 코드 변경사항을 리뷰하고 개선점을 제안해줘" \
  --output-format json \
  --max-turns 5 \
  --permission-mode dontAsk

dontAsk 모드로 사전 허용된 동작만 실행하고, JSON 출력으로 후속 파이프라인이 결과를 파싱할 수 있게 합니다.

9-4. 격리 환경에서 자유롭게 실행

docker run -it my-claude-image claude --dangerously-skip-permissions

컨테이너처럼 호스트가 보호되는 환경에서만 권한 우회를 허용합니다.

9-5. 병렬 작업

claude -w feature-auth

-w로 git worktree를 만들어 여러 Claude 세션을 격리해서 병렬로 돌릴 수 있습니다.

10. 자주 막히는 부분과 해결 팁

10-1. PowerShell vs CMD 헷갈림

설치 명령에서 &&가 PowerShell에서 안 먹히거나, irm이 CMD에서 안 먹힐 수 있습니다. 프롬프트가 PS C:\로 시작하면 PowerShell, 그냥 C:\이면 CMD입니다.

10-2. `command not found: claude`

PATH가 제대로 잡히지 않은 경우입니다. 네이티브 설치본은 보통 ~/.local/bin/claude나 ~/.claude/bin/claude에 위치하므로, 셸 설정 파일에 PATH를 추가해야 합니다. 자세한 진단은 claude doctor로 확인할 수 있습니다.

10-3. npm 설치 시 권한 오류

sudo npm install -g는 사용하지 마세요. 대신 사용자 디렉터리(~/.npm-global 등)를 npm prefix로 지정하는 방식이 공식 문서에서 권장됩니다.

10-4. 무료 계정으로 안 됨

Claude Code는 유료 계정(Pro, Max, Team, Enterprise) 또는 Console 계정이 필요합니다. 무료 Claude.ai 계정으로는 사용할 수 없습니다.

11. 마치며

Claude Code는 단순한 CLI 도구처럼 보이지만, 권한 모드와 실행 옵션을 어떻게 조합하느냐에 따라 개인 개발 보조부터 CI 자동화까지 활용 폭이 크게 달라집니다.

처음에는 default 모드로 안전하게 시작해 익숙해지면 acceptEdits, plan을 적극적으로 쓰고, 자동화가 필요한 상황에서는 -p와 dontAsk를 결합해 통제 가능한 자동 실행을 구성하는 것이 한 가지 자연스러운 흐름입니다.

새 기능과 옵션은 공식 What's New와 Changelog에서 자주 확인하시고, 막히는 부분이 있다면 세션 안에서 /help나 /bug 명령을 활용해보세요.

📚 참고 자료

클로드 코드(Claude Code) 업데이트 완벽 가이드 — 설치 방법별 최신 버전 유지하기

2026-04-25T21:11:02.000-07:00

클로드 코드는 거의 매일 새 버전이 나올 정도로 빠르게 발전하고 있습니다. 글 작성 시점 기준 npm에 올라온 @anthropic-ai/claude-code 패키지의 최신 버전은 **2.1.119**이며, 며칠 단위로 새 릴리스가 푸시되고 있죠. 새 모델 지원, 버그 수정, 토큰 한도 확장 같은 굵직한 변경사항이 자주 들어오기 때문에 버전을 최신으로 유지하는 것이 곧 생산성과 직결됩니다.

이번 글에서는 설치 방법별로 클로드 코드를 업데이트하는 방법을 정리하고, 자동 업데이트 채널 설정과 자주 마주치는 오류 해결법까지 한 번에 다뤄봅니다.

0. 먼저 내 설치 방식이 무엇인지 확인하기

업데이트 명령어는 어떻게 설치했느냐에 따라 완전히 달라집니다. 터미널을 열고 다음 명령으로 현재 버전과 설치 위치부터 확인하세요.

claude --version
which claude        # macOS / Linux / WSL
where claude        # Windows CMD
Get-Command claude  # Windows PowerShell

경로를 보면 설치 방식을 가늠할 수 있습니다.

경로 패턴	설치 방식
`~/.local/bin/claude` 또는 `~/.local/share/claude/...`	네이티브 인스톨러 (공식 권장)
`/opt/homebrew/...` 또는 `/usr/local/Cellar/...`	Homebrew
`~/.npm-global/...`, `~/.nvm/versions/node/...`	npm 글로벌
`C:\Program Files\WinGet\...`	WinGet
`/usr/bin/claude` (apt/dnf/apk 패키지)	리눅스 패키지 매니저

설치 환경 전반을 점검하려면 claude doctor 명령이 더 친절합니다. 누락된 의존성이나 권한 문제까지 함께 짚어주거든요. 이미 클로드 코드 세션에 들어와 있다면 슬래시 명령 /doctor로도 동일한 진단을 돌릴 수 있습니다.

1. 네이티브 인스톨러 — 백그라운드에서 알아서 업데이트

curl ... | bash 또는 irm ... | iex로 설치한 경우입니다. 가장 신경 쓸 일이 적은 방식으로, 클로드 코드가 시작할 때와 실행 중 주기적으로 알아서 최신 버전을 확인하고 백그라운드에서 다운로드합니다. 다음번 실행 시 새 버전이 적용되죠.

즉시 업데이트하고 싶다면

백그라운드 체크를 기다릴 수 없을 때는 직접 명령을 내립니다.

claude update

릴리스 채널 선택하기

네이티브 설치는 두 가지 채널 중 하나를 따릅니다.

latest (기본값): 새 기능이 출시되는 즉시 받습니다. 새것 좋아하는 분, 최신 모델을 빨리 써보고 싶은 분에게 적합합니다.
stable: 보통 1주 정도 늦게 도착하지만, 큰 회귀(regression)가 발견된 릴리스는 건너뜁니다. 안정성이 중요한 환경에 추천합니다.

채널은 클로드 코드 안에서 /config를 실행하고 Auto-update channel 항목에서 바꾸거나, ~/.claude/settings.json에 직접 적어줄 수 있습니다.

{
  "autoUpdatesChannel": "stable"
}

다운그레이드 방지 — `minimumVersion` 설정

latest로 잘 쓰다가 stable로 옮길 때, 현재 버전이 stable 채널 최신보다 더 높다면 의도치 않게 다운그레이드될 수 있습니다. 이를 막기 위해 최소 버전을 못 박을 수 있어요.

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

이렇게 해두면 백그라운드 업데이트와 claude update가 이 버전 미만으로는 절대 내려가지 않습니다. 기업 환경에서는 관리자 정책(managed settings)으로 조직 전체에 강제할 수도 있습니다.

자동 업데이트 끄기

자동 업데이트가 거슬린다면 환경 변수로 끌 수 있습니다.

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER는 백그라운드 체크만 막을 뿐, claude update를 직접 실행하면 여전히 동작합니다. 모든 업데이트 경로를 차단하려면 DISABLE_UPDATES를 사용하세요. 사내 배포 채널을 통해 특정 버전을 강제로 유지해야 하는 경우에 쓰입니다.

2. Homebrew (macOS / Linux) — 자동 업데이트 안 됨

Homebrew는 자동 업데이트되지 않습니다. 직접 명령을 실행해야 합니다.

# stable 채널로 설치한 경우
brew upgrade claude-code

# latest 채널로 설치한 경우
brew upgrade claude-code@latest

Homebrew는 두 개의 cask를 제공하며, cask 이름 자체가 채널을 결정합니다. autoUpdatesChannel 설정이 아니라 어떤 cask를 깔았는지가 중요해요. 헷갈리면 brew list --cask | grep claude로 확인할 수 있습니다.

또 한 가지 — Homebrew는 업그레이드 후에도 옛 버전을 디스크에 남겨둡니다. 디스크 공간이 아쉬우면 가끔 정리해주세요.

brew cleanup

⚠️ Homebrew 사용자가 주의할 함정

claude-code (stable) cask로 설치했는데 autoUpdatesChannel이 "latest"로 되어 있으면 순환 데드락이 생깁니다. 그런데 이 채널 설정의 **기본값이 "latest"**라서 별도로 만진 적이 없어도 이 함정에 빠질 수 있다는 게 문제예요. 인앱에서는 "업데이트 가능: 2.1.x → 2.1.y"라고 친절하게 알려주지만, 정작 brew upgrade claude-code를 실행하면 stable 채널의 더 낮은 버전만 받을 수 있어서 알림 속 버전을 영영 받지 못하는 상황이 생기죠.

해결책은 둘 중 하나입니다.

채널을 stable로 통일: ~/.claude/settings.json에서 autoUpdatesChannel을 "stable"로 두거나 아예 설정을 지웁니다. 그러면 인앱 알림도 stable 채널 기준으로 뜹니다.
latest cask로 갈아타기: 최신 버전을 빨리 받고 싶다면 brew uninstall claude-code && brew install --cask claude-code@latest로 옮긴 뒤 autoUpdatesChannel을 "latest"로 두세요.

요지는 **"설치한 cask와 autoUpdatesChannel의 채널을 맞추라"**는 것입니다.

3. WinGet (Windows) — 정기적인 수동 업그레이드

WinGet 역시 자동 업데이트가 없습니다. PowerShell에서 주기적으로 실행해주세요.

winget upgrade Anthropic.ClaudeCode

설치된 모든 패키지를 한꺼번에 올리고 싶다면 winget upgrade --all도 가능합니다.

4. 리눅스 패키지 매니저 (apt / dnf / apk)

apt, dnf, apk로 설치했다면 시스템 업그레이드 워크플로의 일부로 함께 올라갑니다.

# Debian / Ubuntu
sudo apt update && sudo apt upgrade claude-code

# Fedora / RHEL
sudo dnf upgrade claude-code

# Alpine
apk update && apk upgrade claude-code

이 방식의 장점은 시스템 전체 업데이트와 동일한 사이클로 관리된다는 점입니다. CI/CD 빌드 이미지나 서버 환경에서 특히 깔끔하죠.

5. npm 글로벌 패키지

npm install -g @anthropic-ai/claude-code

이 명령은 설치할 때도, 업데이트할 때도 동일하게 사용합니다. 같은 명령어를 다시 실행하면 npm이 최신 버전으로 갱신해줍니다. 특정 버전을 고정해서 깔고 싶다면 @ 뒤에 버전을 붙이세요.

npm install -g @anthropic-ai/claude-code@2.1.100

주의: sudo npm install -g는 사용하지 마세요. 권한 꼬임과 보안 이슈의 주범입니다. 권한 에러가 난다면 npm 글로벌 prefix를 홈 디렉토리(~/.npm-global 등)로 바꾸거나 nvm을 쓰는 쪽으로 정비하는 게 정답입니다.

pnpm 사용자라면 동일한 의미로 pnpm add -g @anthropic-ai/claude-code를 실행합니다.

6. 업데이트 후 확인

업데이트가 끝났으면 새 버전이 잘 잡혔는지 점검합니다.

claude --version

새로 들어온 변경사항이 궁금하다면 클로드 코드 안에서 슬래시 명령을 써보세요.

/release-notes

최근 릴리스의 주요 변경점을 바로 띄워줍니다. 전체 변경 이력은 GitHub의 CHANGELOG에서 확인할 수 있습니다.

7. 자주 마주치는 업데이트 오류와 해결

"Another Claude process is currently running" / "another process is currently installing"

설치나 업데이트 도중 프로세스가 비정상 종료되면, 인스톨러가 만들어둔 PID 락 파일이 남아 다음 시도를 막습니다. 헷갈리기 쉬운 점은 이 락 파일이 ~/.claude가 아니라 **XDG 표준 경로인 ~/.local/state/claude/locks/**에 있다는 것입니다. ~/.claude를 아무리 뒤져도 못 찾는 이유가 여기에 있죠.

# 어떤 락 파일이 있는지 확인
ls ~/.local/state/claude/locks/

# 해당 PID가 실제로 살아있는지 확인 (없으면 stale 락)
ps -p <PID>

# stale이라고 판단되면 삭제
rm ~/.local/state/claude/locks/*.lock

락 파일을 비운 뒤에도 시스템 프로세스 목록에 떠 있는 claude 프로세스가 있다면 함께 정리하고 재시도하세요.

macOS의 `ENOTEMPTY` npm 에러

macOS(Sonoma 이상)에서 npm으로 클로드 코드를 업데이트할 때 자주 발생하는 문제입니다. 클로드 코드 자체의 버그가 아니라 APFS 파일 잠금 때문에 npm이 폴더 이름을 바꾸지 못해 일어납니다. 해결 절차는 다음과 같습니다.

# 1) 기존 설치 제거
rm -rf $(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code

# 2) 숨겨진 임시 폴더 제거 (이 단계가 핵심)
rm -rf $(npm config get prefix)/lib/node_modules/@anthropic-ai/.claude-code-*

# 3) 캐시 정리
npm cache clean --force

# 4) 재설치
npm install -g @anthropic-ai/claude-code

2번 단계에서 지우는 .claude-code-* 형태의 숨김 폴더가 바로 ENOTEMPTY 에러의 원인이라 빠뜨리면 안 됩니다.

네이티브 설치인데 `claude update`가 npm-global로 인식하는 경우

PATH에서 nvm의 bin 디렉토리가 ~/.local/bin보다 우선순위가 높을 때 발생할 수 있는 알려진 이슈입니다. 이 경우 claude update가 네이티브 심링크를 지우고 npm 패키지로 덮어써버리니, npm 글로벌 패키지가 깔려 있다면 먼저 제거한 뒤 네이티브 인스톨러를 다시 실행하는 것이 안전합니다.

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

권한 에러

EACCES: permission denied

처음에 sudo로 npm 글로벌 설치를 했을 때 자주 나옵니다. npm 글로벌 디렉토리의 소유권을 본인 계정으로 되돌리거나, ~/.npm-global 같은 사용자 영역으로 prefix를 옮기는 것이 근본 해법입니다.

마무리 — 어떤 방식을 추천하나?

개인 개발 환경이라면 네이티브 인스톨러 + latest 채널 조합이 가장 손이 덜 갑니다. 백그라운드에서 알아서 갱신되고, 새 모델이 풀리면 가장 빨리 써볼 수 있습니다.

팀이나 회사에서 여러 명이 함께 쓴다면 stable 채널 + minimumVersion 고정 또는 리눅스 패키지 매니저 기반 배포가 안정적입니다. 회귀 이슈가 있는 릴리스를 자동으로 피해 가면서, 조직 전체가 같은 버전대를 유지할 수 있거든요.

CI/CD 환경이라면 npm으로 버전을 명시적으로 고정하고(@2.1.100처럼), 업데이트는 PR을 통해 의도적으로 올리는 방식이 재현성 측면에서 가장 깔끔합니다.

참고 자료

공식 문서 (Advanced setup): https://code.claude.com/docs/en/setup
npm 패키지: https://www.npmjs.com/package/@anthropic-ai/claude-code
GitHub CHANGELOG: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

클로드 코드(Claude Code), 코딩 초보자를 위한 친절한 입문 가이드

2026-04-25T08:25:00.000-07:00

"코드 한 줄도 못 짜는데, 정말 제가 써도 될까요?" 네, 됩니다. 오히려 그런 분들에게 가장 큰 변화를 가져다 줄 수 있는 도구입니다.

1. 클로드 코드가 뭔가요?

클로드 코드(Claude Code)는 Anthropic이 만든 AI 코딩 도우미입니다. 흔히 "터미널에서 작동하는 AI 개발자"라고 부릅니다.

기존에 우리가 알던 AI 코딩 도구들(예: GitHub Copilot)은 한 줄 한 줄 자동완성을 도와주는 정도였다면, 클로드 코드는 한 단계 더 나아갑니다. 여러분이 평범한 한국어로 "이 웹사이트에 로그인 기능을 추가해줘"라고 말하면, 코드 전체를 읽고, 어떤 파일들을 수정해야 할지 계획을 세우고, 실제로 코드를 작성하고, 테스트까지 돌려본 뒤 결과를 보여줍니다.

쉽게 비유하자면 이렇습니다.

GitHub Copilot = 옆에서 다음 단어를 알려주는 친구
ChatGPT/Claude 채팅 = 코드를 물어보면 답해주는 상담사
클로드 코드 = 프로젝트를 통째로 맡기면 알아서 일하는 신입 개발자

2. 왜 요즘 이렇게 화제인가요?

실제 기업 사례를 보면 감이 옵니다.

Wiz라는 회사는 5만 줄짜리 Python 코드를 Go 언어로 옮기는 작업을 했는데, 원래 2~3개월짜리 일을 약 20시간 만에 끝냈습니다.
Rakuten은 새 기능 출시까지 평균 24일 걸리던 것을 5일로 줄였습니다.
Anthropic 자체에서도 이제 회사 코드의 대부분을 클로드 코드가 작성한다고 밝혔습니다.

더 흥미로운 건, 개발자가 아닌 사람들도 쓰기 시작했다는 점입니다. 영업팀, 재무팀, 운영팀 직원들이 SQL이나 Python을 모르는 상태에서 "지난달 매출을 지역별로 정리해줘" 같은 자연어 요청만으로 데이터를 다루고 있습니다.

3. 초보자가 알아야 할 핵심 개념 3가지

(1) 에이전트(Agent) 방식

클로드 코드는 에이전트형 AI입니다. 한 번 질문하면 한 번 답하고 끝나는 게 아니라, 목표를 받으면 스스로 단계를 나누고, 도구를 사용하고, 결과를 확인하면서 계속 일을 진행합니다. 마치 신입 직원에게 일을 맡기는 것과 비슷합니다.

(2) 사용자의 환경에서 직접 작동

클라우드에 코드를 올리는 게 아니라, 여러분의 컴퓨터에서 직접 파일을 읽고 수정합니다. 따라서 보안에 민감한 회사 코드도 비교적 안전하게 다룰 수 있습니다.

(3) 권한 시스템

클로드 코드는 파일을 수정하거나 명령어를 실행할 때 기본적으로 여러분에게 허락을 구합니다. "이 파일을 이렇게 바꿔도 될까요?"라고 물어보고, 여러분이 승인해야만 진행합니다. 안전장치가 마련된 셈이죠.

4. 어떻게 설치하나요?

필수 준비물:

Node.js (자바스크립트 실행 환경)가 설치되어 있어야 합니다.
macOS, Windows, Linux 모두 지원합니다.
Anthropic 계정 (Claude Pro 또는 Max 플랜 권장)

설치 방법은 크게 세 가지입니다.

가장 보편적인 방법은 npm으로 설치하는 것입니다. 터미널을 열고 다음 명령어를 입력합니다.

npm install -g @anthropic-ai/claude-code

macOS 사용자라면 Homebrew로도 가능합니다.

brew install claude-code

Windows 사용자는 WinGet을 쓸 수도 있습니다.

winget install Anthropic.ClaudeCode

설치가 끝나면 작업하고 싶은 폴더로 이동해서 claude 명령어를 입력하면 됩니다. 처음 실행 시 로그인 안내가 나오니, 그대로 따라가면 됩니다.

VS Code, Cursor, JetBrains IDE 사용자라면 익스텐션(확장 프로그램) 형태로도 설치할 수 있습니다. 코드 변경사항을 IDE 안에서 시각적으로 확인할 수 있어 초보자에게 더 친숙할 수 있습니다.

5. 처음 써볼 때 좋은 작업들

설치하고 나서 막막하다면, 다음과 같은 작업부터 시작해 보세요.

기존 코드 이해하기: "이 폴더에 있는 코드가 무슨 일을 하는지 설명해줘"라고 물어보세요. 클로드 코드가 파일들을 읽고 정리해줍니다. GitHub에서 받은 오픈소스 프로젝트를 이해할 때 특히 유용합니다.

작은 버그 고치기: "로그인 버튼을 눌러도 반응이 없어. 뭐가 문제일까?"처럼 증상을 설명하면, 클로드가 관련 파일을 찾아서 원인을 짚어주고 수정해 줍니다.

테스트 작성: "이 함수에 대한 테스트 코드를 만들어줘"라고 부탁하면 자동으로 만들어줍니다. 코드 품질을 높이는 좋은 습관입니다.

Git 작업 도움받기: "지금까지 작업한 내용을 적당한 메시지로 커밋해줘" 같은 부탁도 됩니다. Git 명령어를 외우지 않아도 됩니다.

6. 초보자가 자주 하는 실수와 팁

한 번에 너무 많은 걸 시키지 마세요. "쇼핑몰 사이트 만들어줘"보다는 "사용자 회원가입 기능을 추가해줘"처럼 작은 단위로 부탁하는 게 결과가 훨씬 좋습니다.

결과를 그대로 믿지 마세요. AI도 실수합니다. 특히 중요한 코드라면 직접 읽어보거나 테스트를 돌려봐야 합니다. 클로드 코드는 도우미이지 대리인이 아닙니다.

CLAUDE.md 파일을 활용하세요. 프로젝트 폴더에 이 파일을 만들고 "이 프로젝트의 규칙은 이렇습니다", "이 폴더는 이런 용도입니다" 같은 메모를 적어두면, 클로드가 매번 그 내용을 참고합니다. 같은 설명을 반복할 필요가 없어집니다.

단계별로 검토하세요. 클로드가 "이 파일을 수정할게요"라고 물어보면 무심코 Yes를 누르지 말고, 어떤 변경인지 한 번 확인하는 습관을 들이세요.

7. 마무리: 한 줄 요약

클로드 코드는 "한국어로 부탁하면 코드를 짜고 실행해주는 AI 동료"입니다. 개발자에겐 생산성을 몇 배로 올려주는 도구이고, 비개발자에겐 코딩 세계로 들어가는 가장 부드러운 입구가 됩니다.

처음부터 모든 기능을 마스터할 필요는 없습니다. 작은 작업 하나로 시작해서, 익숙해지면 점점 더 큰 일을 맡겨보세요. 한 달 뒤에 여러분이 만든 결과물을 보면 스스로 놀라게 될 겁니다.

더 알아보기:

공식 문서: https://docs.claude.com/en/docs/claude-code/overview
빠른 시작 가이드: 공식 문서의 Quickstart 섹션 참고
공식 GitHub: https://github.com/anthropics/claude-code

Privacy Policy

2020-02-01T09:45:00.001-08:00

[FolderNote] Privacy Policy

1. Purpose of Processing Personal Information

This app processes personal information for the following purposes only and does not use it for any other purposes.

Used solely for the operation of app features.

2. Outsourcing of Personal Information Processing

This app does not outsource the processing of personal information to any third party.

3. Rights and Obligations of Data Subjects and How to Exercise Them

As the subject of personal information, users may exercise their rights related to personal information protection at any time. However, this app does not collect or retain any personal information of its users.

4. Items of Personal Information Processed

The following personal information items are processed:

"android.permission.CAMERA": This permission is required when using the camera feature within the app to take photos.

5. Destruction of Personal Information

This app does not collect or retain any personal information from users. Therefore, there is no personal information that needs to be destroyed.

6. Measures to Ensure the Security of Personal Information

This app does not collect or retain any usage information from app users.

개발자가 쓰는 AI 일기

Foldernote — 개인정보 처리방침 / Privacy Policy

Foldernote 개인정보 처리방침

1. 수집하지 않는 정보

1-1. 네트워크 사용 범위

2. 로컬 저장 정보

3. 백업

4. 권한 사용

5. 제3자 서비스

6. 어린이

7. 변경

8. 연락처

Foldernote Privacy Policy

1. Information We Do Not Collect

1-1. Scope of Network Use

2. Locally Stored Data

3. Backups

4. Permissions

5. Third Parties

6. Children

7. Changes

8. Contact

클로드 코드(Claude Code) MCP 완벽 가이드: 쉬운 예제로 배우는 외부 도구 연결법

1. MCP란 무엇인가요?

쉬운 비유: USB-C 같은 존재

MCP가 해결하는 핵심 문제: M×N에서 M+N으로

2. MCP의 구조: 3가지 핵심 구성 요소

MCP 서버가 제공하는 3가지 기능

3. 클로드 코드에서 MCP가 작동하는 방식

4. MCP 서버를 클로드 코드에 추가하는 3가지 방법

방법 1: HTTP 원격 서버 (권장)

방법 2: SSE 원격 서버 (사용 비권장)

방법 3: stdio 로컬 서버

5. 쉬운 예제로 배우는 MCP 활용

예제 1: 센트리(Sentry)로 오류 모니터링하기

예제 2: 깃허브 연동으로 코드 리뷰하기

예제 3: PostgreSQL 데이터베이스 쿼리하기

6. MCP 설치 범위(Scope): 3가지 중 무엇을 골라야 할까?

어떤 범위를 골라야 할까요?

7. 자주 쓰는 MCP 관리 명령

8. 클로드 코드를 MCP 서버로 사용하는 흥미로운 활용

9. 실무에서 꼭 알아 두면 좋은 추가 기능

도구 검색(Tool Search): 컨텍스트 절약 기능

출력 토큰 한도 관리

자동 재연결

MCP 리소스 참조 (@ 멘션)

10. 보안 측면에서 반드시 알아야 할 점

11. 어디서부터 시작하면 좋을까요?

마무리

클로드 코드(Claude Code) 후크(Hooks) 완전 정복 — 개념부터 실전 예제까지

1. 후크(Hooks)란 무엇인가요?

후크와 일반 프롬프트의 차이점

2. 후크의 생명주기(Lifecycle) - 언제 실행되나요?

3. 후크 설정 파일은 어디에 두나요?

4. 후크 설정의 기본 구조

5. 가장 쉬운 첫 번째 예제: 알림 후크 만들기

macOS 사용자

Linux 사용자

Windows(PowerShell) 사용자

동작 확인 방법

6. 실전 예제 1: 코드 수정 후 자동 포맷팅

코드 풀이

7. 실전 예제 2: 보호된 파일 수정 차단하기

1단계: 후크 스크립트 생성

2단계: 스크립트에 실행 권한 부여 (macOS / Linux)

3단계: 후크 등록

코드 풀이

8. 종료 코드(Exit Code)의 의미

9. 후크에 전달되는 입력 데이터(JSON)

모든 이벤트에 공통으로 전달되는 필드

10. 후크 종류 5가지

11. 실전 예제 3: 위험한 명령(rm -rf) 차단하기

후크 설정

후크 스크립트 (.claude/hooks/block-rm.sh)

동작 흐름

12. 후크는 어떻게 디버깅하나요?

방법 1: /hooks 메뉴 활용

방법 2: 수동 테스트

방법 3: 디버그 로그

13. 자주 겪는 문제와 해결법

후크 스크립트 (`.claude/hooks/block-rm.sh`)

방법 1: `/hooks` 메뉴 활용

5. 서브에이전트를 만드는 가장 쉬운 방법: `/agents` 명령어