Desktop 앱 핵심 기능
Claude Desktop 앱의 Code 탭은 터미널 없이 GUI 환경에서 Claude Code를 사용할 수 있게 해줍니다. 이 문서에서는 Desktop 앱이 표준 CLI 경험에 추가로 제공하는 핵심 기능을 상세히 설명합니다.
Desktop 앱 핵심 기능 맵
💬
Chat 모드
대화형 AI 어시스턴트
📄 파일·이미지 첨부 분석
🎯 프로젝트별 대화 관리
🧠 장기 메모리 활용
🔌 MCP 도구 연동
🤝
Cowork 모드
화면 공유 협업
🖥️ 화면 실시간 공유
👁️ 컨텍스트 자동 인식
🔁 비주얼 피드백 루프
🖱️ Computer Use 통합
⚡
Code 모드
자율 코딩 에이전트
🔍 비주얼 Diff 리뷰
🌐 라이브 프리뷰
⚡ 병렬 세션 실행
📅 스케줄 & 배경 작업
세 모드 모두 하나의 Desktop 앱에서 통합 제공 — 상황에 맞게 전환하여 사용
권한 모드 (Permission Modes)
Desktop 앱은 보내기 버튼 옆의 모드 선택기를 통해 Claude의 권한 수준을 조절할 수 있습니다.
| 모드 | 설명 | 적합한 상황 |
|---|---|---|
| Ask (기본값) | 모든 파일 수정, 명령 실행 전에 사용자 승인 요청 | 안전하게 작업하고 싶을 때, 새로운 프로젝트 |
| Auto accept edits | 파일 수정은 자동 승인, 명령 실행은 승인 필요 | 코드 작성에 집중, diff로 나중에 리뷰 |
| Plan | 코드를 수정하지 않고 계획만 수립 | 접근 방법을 먼저 검토하고 싶을 때 |
| Auto | 파일 수정과 허용된 명령 모두 자동 실행 | 신뢰할 수 있는 작업, 빠른 반복 |
| Bypass | 대부분의 권한 체크를 건너뜀 (--dangerously-skip-permissions와 동일) | 개인 개발 환경에서 빠른 프로토타이핑 |
Bypass 모드 주의
Bypass 모드는 대부분의 권한 프롬프트를 건너뜁니다. 단, .git, .claude, .vscode, .idea, .husky 디렉토리에 대한 쓰기는 여전히 확인을 요청합니다. 프로덕션 코드나 중요한 시스템에서는 사용하지 마세요. Settings > Claude Code > "Bypass permissions mode"에서 활성화해야 사용 가능합니다.
효율적인 모드 전환 워크플로우
- Plan 모드로 접근 방법 검토
- 계획이 마음에 들면 Auto accept edits로 전환하여 실행
- diff 리뷰 후 코멘트로 피드백
- 반복 작업이 안정화되면 Auto 모드로 전환
1. 비주얼 Diff 리뷰 (Visual Diff Review)
Claude가 코드를 수정한 뒤, 파일별로 변경 사항을 시각적으로 검토할 수 있습니다. CLI에서는 터미널 출력으로만 확인하지만, Desktop에서는 IDE 수준의 diff 뷰어를 제공합니다.
동작 방식
- Claude가 파일을 변경하면
+12 -1같은 diff 통계 표시기가 나타남 - 클릭하면 diff 뷰어가 열림 — 왼쪽에 파일 목록, 오른쪽에 변경 내용
- 각 라인을 클릭하여 인라인 코멘트 작성 가능
- 코멘트 작성 후 Cmd+Enter (macOS) 또는 Ctrl+Enter (Windows)로 일괄 제출
- Claude가 코멘트를 읽고 수정하면, 새로운 diff로 다시 확인
코드 리뷰 기능
diff 뷰 우측 상단의 Review code 버튼을 클릭하면 Claude가 변경 사항을 자동 평가합니다:
| 검토 대상 | 검토하지 않는 항목 |
|---|---|
| 컴파일 에러 | 스타일/포맷팅 |
| 확실한 로직 에러 | 기존에 있던 이슈 |
| 보안 취약점 | 린터가 잡을 수 있는 문제 |
| 명백한 버그 |
실전 예시: API 엔드포인트 리팩토링
💬 "users API의 GET /users/:id 엔드포인트에 캐싱 레이어를 추가해줘"
Claude가 3개 파일 수정 → diff 표시기 +45 -8 나타남 → 클릭하여 diff 뷰 열기
📁 파일 목록 📄 변경 내용
├─ src/routes/users.ts + import { cache } from '../lib/cache';
├─ src/lib/cache.ts +
└─ src/config/redis.ts + const CACHE_TTL = 300; // 5분
+
+ export async function getUser(id: string) {
+ const cached = await cache.get(`user:${id}`);
+ if (cached) return JSON.parse(cached);
...
인라인 코멘트 작성:
cache.ts15번째 줄 클릭 → "TTL을 환경변수로 빼주세요" 코멘트 추가users.ts28번째 줄 클릭 → "에러 시 캐시 무시하고 DB에서 직접 조회하도록 fallback 추가" 코멘트 추가- Cmd+Enter로 코멘트 일괄 제출 → Claude가 두 피드백을 반영하여 재수정
활용 팁
- 복잡한 작업은 Plan 모드로 먼저 접근 방법을 검토한 뒤, Auto accept edits로 전환하여 실행
- 커밋 전
/simplify를 실행하면 3개 리뷰 에이전트가 병렬로 품질 검토 - diff 뷰에서 여러 파일의 코멘트를 모아 한 번에 제출하면 효율적
- Review code 버튼으로 Claude 자체 리뷰 → 인라인 코멘트로 피드백 → 수정 반복
2. 라이브 앱 프리뷰 (Live App Preview)
Claude가 개발 서버를 시작하고 내장 브라우저에서 변경 사항을 실시간으로 확인합니다.
동작 방식
- 프론트엔드 웹 앱뿐만 아니라 백엔드 서버도 지원 (API 엔드포인트 테스트, 서버 로그 확인)
- Claude가 파일 수정 후 대부분 자동으로 서버 시작
- 기본적으로 Auto-verify 활성화 — 매 수정 후 Claude가 스크린샷 촬영, DOM 검사, 클릭, 폼 입력 등으로 자동 검증
실전 예시: React 대시보드 개발
💬 "대시보드 페이지에 실시간 차트 컴포넌트를 추가해줘. Recharts 사용하고,
API에서 5초마다 데이터를 가져와서 업데이트하도록 해줘."
Claude의 동작:
npm install recharts실행src/components/RealtimeChart.tsx생성src/pages/Dashboard.tsx에 차트 통합- 자동으로 개발 서버 시작 (
npm run dev) - 내장 브라우저에서 대시보드 열기
- 스크린샷 촬영 → 차트가 렌더링되는지 확인
- 5초 대기 → 데이터 업데이트 확인
- "차트가 정상적으로 실시간 업데이트됩니다" 보고
내장 브라우저에서 직접 상호작용 가능:
- 차트 위에 마우스 호버 → 툴팁 확인
- 필터 버튼 클릭 → 데이터 범위 변경
- Claude에게 "차트 색상을 파란색으로 바꿔줘" → 즉시 프리뷰에 반영
프리뷰 서버 설정 (launch.json)
Claude가 프로젝트를 자동 감지하여 .claude/launch.json에 설정을 저장합니다:
{
"version": "0.0.1",
"autoVerify": true,
"configurations": [
{
"name": "my-app",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 3000
}
]
}
설정 필드 레퍼런스
| 필드 | 타입 | 설명 |
|---|---|---|
name | string | 서버 고유 식별자 |
runtimeExecutable | string | 실행 명령어 (npm, yarn, node 등) |
runtimeArgs | string[] | 명령어에 전달할 인자 (예: ["run", "dev"]) |
port | number | 서버 포트 (기본값: 3000) |
cwd | string | 작업 디렉토리 (프로젝트 루트 기준 상대 경로) |
env | object | 추가 환경 변수 (예: { "NODE_ENV": "development" }) |
autoPort | boolean | 포트 충돌 시 자동 대체 여부 |
program | string | node로 직접 실행할 스크립트 |
args | string[] | program에 전달할 인자 |
프레임워크별 설정 예시
Next.js + Yarn:
{
"version": "0.0.1",
"configurations": [
{ "name": "web", "runtimeExecutable": "yarn", "runtimeArgs": ["dev"], "port": 3000 }
]
}
모노레포 (프론트엔드 + API):
{
"version": "0.0.1",
"configurations": [
{
"name": "frontend",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"cwd": "apps/web",
"port": 3000,
"autoPort": true
},
{
"name": "api",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "start"],
"cwd": "server",
"port": 8080,
"env": { "NODE_ENV": "development" },
"autoPort": false
}
]
}
Node.js 스크립트 직접 실행:
{
"version": "0.0.1",
"configurations": [
{ "name": "server", "program": "server.js", "args": ["--verbose"], "port": 4000 }
]
}
포트 충돌 처리
autoPort 값 | 동작 |
|---|---|
true | 자동으로 빈 포트 찾아 사용 (대부분의 개발 서버에 적합) |
false | 에러 발생 (OAuth 콜백, CORS 등 특정 포트 필수 시) |
| 미설정 (기본) | Claude가 해당 포트가 필수인지 질문 후 저장 |
프리뷰가 안 열릴 때
- Preview 드롭다운에서 서버 상태 확인
.claude/launch.json의port와 실제 서버 포트가 일치하는지 확인runtimeExecutable이 시스템에 설치되어 있는지 확인 (예:yarn이 없으면npm으로 변경)
3. 컴퓨터 사용 (Computer Use)
Claude가 앱을 열고, 화면을 제어하며, 여러분처럼 직접 컴퓨터를 조작합니다. macOS와 Windows에서 사용할 수 있습니다.
요구사항
- 리서치 프리뷰 단계이며 Pro 또는 Max 플랜 필요
- Team/Enterprise 플랜에서는 사용 불가
- Claude Desktop 앱이 실행 중이어야 함
활성화 방법
- Desktop 앱 업데이트 — claude.com/download에서 최신 버전 다운로드
- Settings > General > Computer use 토글 켜기
- macOS 권한 부여 (macOS만 해당):
- 접근성(Accessibility): 시스템 설정 → 개인 정보 보호 및 보안 → 손쉬운 사용 → Claude 토글 켜기
- 화면 녹화(Screen Recording): 시스템 설정 → 개인 정보 보호 및 보안 → 화면 기록 → Claude 토글 켜기
- 권한 변경 후 Claude Desktop 재시작 필요
Claude의 도구 선택 우선순위
Claude는 가장 정밀한 도구부터 시도합니다:
| 우선순위 | 도구 | 적용 상황 | 예시 |
|---|---|---|---|
| 1순위 | 커넥터 | 연결된 서비스 | "Slack에 메시지 보내줘" → Slack 커넥터 |
| 2순위 | Bash | 셸 명령어 | "npm test 실행해줘" → Bash 도구 |
| 3순위 | Claude in Chrome | 브라우저 작업 | "Google에서 검색해줘" → Chrome 확장 |
| 4순위 | Computer Use | 위 도구 불가 | "Figma에서 디자인 확인해줘" → 화면 제어 |
앱 권한 등급
| 등급 | Claude가 할 수 있는 것 | 해당 앱 | 이유 |
|---|---|---|---|
| View only (보기 전용) | 스크린샷에서 앱 확인만 | 브라우저, 트레이딩 플랫폼 | 브라우저는 Chrome 확장이 더 정확 |
| Click only (클릭 전용) | 클릭, 스크롤 (타이핑/단축키 불가) | 터미널, IDE | 터미널은 Bash 도구가 더 안전 |
| Full control (전체 제어) | 클릭, 타이핑, 드래그, 단축키 | 그 외 모든 앱 | 대체 도구가 없는 네이티브 앱 |
실전 예시 모음
예시 1: iOS 시뮬레이터 테스트
💬 "Xcode에서 프로젝트를 빌드하고 iOS 시뮬레이터에서 실행해줘.
로그인 화면에서 test@example.com으로 로그인한 뒤,
모든 탭을 눌러서 크래시가 없는지 확인해줘."
Claude의 동작:
- Xcode 앱 열기 → Full control 권한 요청 → 사용자 승인
- Cmd+B로 프로젝트 빌드
- Cmd+R로 시뮬레이터에서 실행
- 로그인 폼에 이메일/비밀번호 입력
- 각 탭을 순서대로 클릭하며 스크린샷 촬영
- 결과: "모든 탭 정상 동작. 프로필 탭에서 프로필 이미지가 로드되지 않는 시각적 문제 발견" → 코드 수정 제안
예시 2: Figma 디자인과 실제 구현 비교
💬 "Figma에서 디자인 파일을 열고, 실제 구현된 localhost:3000 페이지와
간격, 색상, 폰트 크기를 비교해줘."
Claude의 동작:
- Figma 앱 열기 → View only (브라우저 기반) or Full control
- 디자인 페이지 스크린샷 촬영
- 브라우저에서 localhost:3000 스크린샷 촬영
- 두 스크린샷 비교하여 차이점 목록 작성
- 결과: "헤더 패딩 24px→16px, 버튼 색상 #3B82F6→#2563EB, 본문 폰트 14px→15px 차이 발견"
예시 3: 스프레드시트 데이터 처리
💬 "Numbers에서 매출_데이터.xlsx를 열고,
3월 데이터로 월별 매출 차트를 만들어줘."
Claude의 동작:
- Numbers 앱에서 파일 열기 → Full control
- 3월 데이터 범위 선택
- 차트 삽입 메뉴에서 막대 차트 선택
- 축 레이블, 제목 설정
- 결과: 차트 스크린샷과 함께 완료 보고
Computer Use가 적합하지 않은 경우
- 웹 브라우저 작업 → Chrome 확장(Claude in Chrome) 사용이 더 빠르고 정확
- 터미널 명령어 → Bash 도구가 더 효율적
- 외부 API 호출 → 커넥터(Connector)나 MCP 서버 사용
- 금융 거래, 송금 → Claude가 실행하지 않으며, 사용자가 직접 수행해야 함
보안 주의
- 터미널, Finder/파일 탐색기, 시스템 설정 등 광범위한 접근 권한이 있는 앱은 추가 경고 표시
- 앱 승인은 현재 세션 동안만 유지 (Dispatch 세션은 30분)
- Settings > General에서 거부할 앱 목록 설정 가능
- 이메일/메시지의 링크를 함부로 클릭하지 않음 — 프롬프트 인젝션 방지
4. GitHub PR 모니터링 (PR Monitoring)
PR을 열면 CI 상태 바가 세션에 나타나고, Claude가 GitHub CLI를 통해 체크 결과를 자동으로 추적합니다.
핵심 기능
| 기능 | 설명 |
|---|---|
| Auto-fix | CI 체크 실패 시 Claude가 자동으로 실패 출력을 읽고 수정 시도 |
| Auto-merge | 모든 체크 통과 시 Claude가 자동으로 PR 병합 (squash 방식) |
| 데스크톱 알림 | CI 완료 시 데스크톱 알림 전송 |
요구사항
GitHub CLI (gh)가 설치되고 인증되어 있어야 합니다. 미설치 시 Desktop이 PR 생성 시점에 설치를 안내합니다.
실전 예시: 기능 개발부터 자동 병합까지
💬 "사용자 프로필에 아바타 업로드 기능을 추가하고,
테스트 작성한 다음, PR을 만들어줘."
전체 워크플로우:
1. Claude가 코드 작성 (3개 파일 수정, 2개 파일 생성)
↓
2. 테스트 로컬 실행 → 통과 확인
↓
3. git commit + git push + gh pr create
↓
4. CI 상태 바 자동 표시 → Auto-fix ON, Auto-merge ON 토글
↓
5. 다른 작업으로 전환 (새 세션 열기)
↓
6. CI 실행 중... (ESLint 에러 발견!)
↓
7. [Auto-fix] Claude가 ESLint 에러 자동 수정 → 재푸시
↓
8. CI 재실행... → 모든 체크 통과 ✅
↓
9. [Auto-merge] 자동 squash 병합 완료
↓
10. 데스크톱 알림: "PR #42가 병합되었습니다"
Auto-fix가 수정하는 것 vs 못하는 것
| 수정 가능 | 수정 어려움 |
|---|---|
| 린트(Lint) 에러 | 통합 테스트 실패 (외부 서비스 의존) |
| 타입 에러 | 환경 변수 미설정 |
| 단위 테스트 실패 | 플레이키(Flaky) 테스트 (간헐적 실패) |
| 빌드 에러 | 네트워크 타임아웃 |
| import 누락 | 인프라 문제 (DB 연결 등) |
Auto-merge 사전 설정
Auto-merge를 사용하려면 GitHub 저장소에서 먼저 설정해야 합니다:
- GitHub 저장소 → Settings → General
- "Pull Requests" 섹션에서 "Allow auto-merge" 체크박스 활성화
- Branch protection rules에서 required status checks 설정 권장
5. 병렬 세션 (Parallel Sessions)
사이드바에서 + New session을 클릭하면 여러 작업을 동시에 병렬로 진행할 수 있습니다.
Git 워크트리 자동 격리
Git 저장소에서는 각 세션이 **독립된 Git 워크트리(Worktree)**를 자동 생성하여 사용합니다. 한 세션의 변경이 다른 세션에 영향을 주지 않습니다.
| 항목 | 설명 |
|---|---|
| 워크트리 위치 | 기본: <프로젝트>/.claude/worktrees/, Settings에서 커스텀 경로 설정 가능 |
| 브랜치 접두사 | Settings에서 워크트리 브랜치에 접두사 설정 (예: claude/) |
| 워크트리 정리 | 세션 호버 → 아카이브 아이콘 클릭 |
| gitignore 파일 포함 | 프로젝트 루트에 .worktreeinclude 파일 생성하면 .env 등 포함 가능 |
실전 예시: 3개 작업 동시 진행
📂 세션 1: "로그인 버그 수정" → claude/fix-login-bug 브랜치
📂 세션 2: "대시보드 차트 추가" → claude/add-dashboard-chart 브랜치
📂 세션 3: "API 엔드포인트 리팩토링" → claude/refactor-api 브랜치
워크플로우:
- 세션 1 열기 → "로그인 시 세션 만료 처리가 안 되는 버그 수정해줘"
- Claude가 작업 중일 때 + New session 클릭
- 세션 2 열기 → "대시보드에 매출 차트를 추가해줘"
- Claude가 작업 중일 때 다시 + New session 클릭
- 세션 3 열기 → "GET /api/users 엔드포인트를 페이지네이션 지원하도록 리팩토링해줘"
- 각 세션이 독립된 워크트리에서 작업 → 서로 충돌 없음
- 완료된 세션부터 PR 생성 → Auto-fix + Auto-merge
.worktreeinclude로 환경 파일 공유
.env 파일은 .gitignore에 포함되어 워크트리에 복사되지 않습니다. 프로젝트 루트에 .worktreeinclude를 만들면 해결됩니다:
.env
.env.local
세션 관리
| 작업 | 방법 |
|---|---|
| 세션 필터링 | 사이드바 상단 필터 아이콘 (Active/Archived, Local/Cloud) |
| 세션 이름 변경 | 세션 상단 툴바의 제목 클릭 |
| 컨텍스트 사용량 확인 | 세션 제목 클릭 |
| 컨텍스트 압축 | 자동 요약 또는 /compact 입력 |
6. Dispatch 통합
Dispatch는 Claude Desktop의 Cowork 탭에 있는 지속적 대화 기능입니다. 핸드폰에서 Dispatch에 작업을 보내면, Claude가 판단하여 Code 세션을 자동 생성합니다.
실전 예시: 출퇴근 중 개발 관리
시나리오 1: 아침 출근 지하철에서
📱 (Dispatch에 메시지)
"어제 밤에 users API에서 null 에러가 발생했어.
에러 로그를 확인하고 수정한 다음, 테스트 실행하고 PR 만들어줘."
동작 과정:
- Dispatch가 **"코딩 작업"**으로 판단 → Desktop에 Code 세션 자동 생성
- Code 탭 사이드바에 Dispatch 뱃지가 표시된 세션 나타남
- Claude가 에러 분석 → 코드 수정 → 테스트 → PR 생성
- 📱 푸시 알림: "PR이 생성되었습니다 — Review 필요"
- 사무실 도착 후 Desktop에서 diff 리뷰
시나리오 2: 퇴근 후 간단한 작업 지시
📱 (Dispatch에 메시지)
"README.md를 업데이트하고 설치 가이드를 최신 버전에 맞게 수정해줘."
시나리오 3: 코딩이 아닌 작업 (Cowork에서 처리)
📱 (Dispatch에 메시지)
"이번 주 GitHub 이슈들을 정리하고 우선순위별로 요약해줘."
→ 리서치 작업이므로 Cowork에서 처리 (Code 세션 생성 안 됨)
Code 세션이 생성되는 기준
| Dispatch에게 보낸 메시지 | 결과 |
|---|---|
| "로그인 버그를 수정해줘" | 개발 작업 → Code 세션 생성 |
| "테스트를 실행하고 실패한 것 수정해줘" | 개발 작업 → Code 세션 생성 |
| "PR 만들어줘" | 개발 작업 → Code 세션 생성 |
| "Claude Code 세션을 열고 ~해줘" | 명시적 요청 → Code 세션 생성 |
| "이 문서를 요약해줘" | 리서치 → Cowork에서 처리 |
| "스프레드시트를 분석해줘" | 분석 → Cowork에서 처리 |
Dispatch 세션 특성
| 항목 | 일반 Code 세션 | Dispatch Code 세션 |
|---|---|---|
| 생성 방식 | 수동 | 자동 생성 |
| 표시 | 일반 탭 | Dispatch 뱃지 표시 |
| 앱 승인 유효기간 | 세션 전체 | 30분 후 만료 (재승인 필요) |
| 알림 | 없음 | 푸시 알림 |
| Computer Use | 세션 전체 | 30분 승인 후 재요청 |
요구사항
- Pro 또는 Max 플랜 필요 (Team/Enterprise 불가)
- Apple Silicon (M1 이상) Mac 또는 Windows 필요
- Intel Mac에서는 Cowork 탭 사용 불가
- Desktop 앱이 실행 중이고 컴퓨터가 깨어 있어야 함
문제 해결
| 문제 | 원인 | 해결 |
|---|---|---|
| 작업을 보냈는데 Code 세션이 안 생김 | Dispatch가 코딩 작업으로 인식 못 함 | "Claude Code 세션을 열고 ~해줘"로 명시 요청 |
| Code 세션이 파일을 찾지 못함 | 프로젝트 폴더 미설정 | Desktop에서 기본 프로젝트 폴더 설정 |
| 푸시 알림이 안 옴 | 모바일 알림 비활성화 | 핸드폰 설정 → Claude → 알림 허용 |
| 30분 후 앱 승인 만료 | Dispatch 세션 보안 정책 | Desktop에서 세션을 열어 일반 세션으로 작업 계속 |
| Desktop이 꺼져 있으면 동작 안 함 | 로컬 실행 필수 | 클라우드 세션 사용 |
7. 스케줄 작업 (Scheduled Tasks)
Claude를 정해진 시간에 자동으로 실행합니다. 매일 아침 코드 리뷰, 주간 의존성 감사, 커넥터를 활용한 모닝 브리핑 등에 활용합니다.
3가지 스케줄 방식 비교
| 클라우드 | Desktop | /loop | |
|---|---|---|---|
| 실행 환경 | Anthropic 클라우드 | 로컬 머신 | 로컬 머신 |
| 컴퓨터 필요 | ❌ | ✅ | ✅ |
| 세션 필요 | ❌ | ❌ | ✅ |
| 재시작 후 유지 | ✅ | ✅ | ❌ (세션 종료 시 중지) |
| 로컬 파일 접근 | ❌ (새 클론) | ✅ | ✅ |
| 최소 간격 | 1시간 | 1분 | 1분 |
실전 예시: 개발팀 자동화 시나리오
예시 1: 매일 아침 코드 리뷰
사이드바 Schedule → New task → New local task:
| 필드 | 설정 |
|---|---|
| Name | daily-code-review |
| Description | 매일 아침 전날 커밋 리뷰 |
| Frequency | Daily 09:00 |
| Prompt | 아래 참고 |
어제 main 브랜치에 머지된 커밋들을 리뷰하세요.
각 커밋에 대해:
1. 보안 이슈가 있는지 확인
2. 테스트가 누락되었는지 확인
3. 성능 문제가 있는지 확인
결과를 요약하고, 문제가 있으면 GitHub 이슈를 생성하세요.
예시 2: 주간 의존성 감사
| 필드 | 설정 |
|---|---|
| Name | weekly-deps-audit |
| Frequency | Weekly 월 10:00 |
| Prompt | npm audit를 실행하고, 심각도 high 이상의 취약점이 있으면 자동 수정하고 PR을 만들어줘. |
예시 3: 모닝 브리핑 (커넥터 활용)
| 필드 | 설정 |
|---|---|
| Name | morning-briefing |
| Frequency | Weekdays 08:30 |
| Prompt | GitHub에서 열린 PR과 이슈 현황을 확인하고, Slack #dev 채널에 오늘의 브리핑을 보내줘. |
한국 시간(KST) 기준 설정
| 설정 | 로컬 시간 (KST) | 활용 |
|---|---|---|
| Daily 09:00 | 오전 9시 | 출근 시 코드 리뷰 |
| Weekdays 18:00 | 오후 6시 | 퇴근 전 일일 요약 |
| Weekly 월 10:00 | 월요일 오전 10시 | 주간 의존성 감사 |
| Hourly | 매시 정각 | CI 상태 모니터링 |
시간대 자동 감지
Desktop 스케줄은 로컬 시간대를 사용합니다. 한국에서 사용하면 자동으로 KST(UTC+9) 기준으로 동작합니다. UTC 변환이 필요 없습니다.
놓친 실행 처리
컴퓨터가 슬립 상태였다면, 깨어날 때 최근 7일 내 놓친 실행을 1회만 보충 실행합니다.
프롬프트 가드레일
보충 실행이 의도치 않게 동작하지 않도록 조건을 추가하세요:
오늘의 커밋만 리뷰하세요. 오후 5시 이후라면 리뷰를 건너뛰고
놓친 항목 요약만 작성하세요.
권한 관리 팁
- 태스크 생성 후 Run now으로 테스트 실행
- 권한 프롬프트가 나타나면 "always allow" 선택
- 이후 자동 실행에서는 승인 없이 동작
- 저장된 권한은 태스크 상세 페이지의 Always allowed 패널에서 확인/취소
8. 커넥터 (Connectors)
외부 서비스를 Claude에 연결하여 캘린더 읽기, 메시지 전송, 이슈 생성 등을 수행합니다. 커넥터는 본질적으로 GUI로 설정하는 MCP 서버입니다.
실전 예시: 하루 업무 자동화
💬 "오늘 Google Calendar 일정을 확인하고,
오전에 예정된 코드 리뷰 미팅 관련 PR을 GitHub에서 찾아서
diff를 미리 분석해줘.
분석 결과를 Slack #code-review 채널에 올려줘."
Claude가 3개 커넥터를 순서대로 사용:
- Google Calendar → 오전 일정 확인 → "10:00 코드 리뷰 미팅 (PR #87)"
- GitHub → PR #87 diff 분석 → 보안/성능 이슈 정리
- Slack → #code-review 채널에 분석 결과 메시지 전송
커넥터별 설정 가이드
GitHub 커넥터
- 프롬프트 박스 + → Connectors → GitHub 선택
- GitHub OAuth 인증 진행
- 저장소 접근 권한 승인
- 활용 예시:
"최근 PR 목록을 보여줘"
"이슈 #42의 내용을 확인해줘"
"fix/login-bug 브랜치에 PR을 만들어줘"
"실패한 CI 로그를 분석해줘"
Slack 커넥터
- + → Connectors → Slack 선택
- Slack 워크스페이스 OAuth 인증
- 채널 접근 권한 설정
- 활용 예시:
"#dev 채널에 배포 완료 알림을 보내줘"
"#bugs 채널의 최근 메시지에서 보고된 버그를 정리해줘"
"@홍길동에게 DM으로 리뷰 요청을 보내줘"
Linear 커넥터
- + → Connectors → Linear 선택
- Linear API 인증
- 활용 예시:
"이 버그 수정 후 Linear 이슈를 Close 해줘"
"이번 스프린트의 미완료 태스크를 보여줘"
"새로운 버그 이슈를 만들고 우선순위 High로 설정해줘"
Google Calendar 커넥터
활용 예시:
"오늘 일정을 확인해줘"
"다음 주 수요일 오후 2시에 코드 리뷰 미팅을 잡아줘"
"이번 주 회의 일정과 관련된 PR을 정리해줘"
Notion 커넥터
활용 예시:
"API 문서 페이지를 업데이트해줘"
"이번 릴리스 노트를 Notion에 작성해줘"
"기술 설계 문서에서 인증 관련 내용을 찾아줘"
커넥터 vs MCP 서버
| 항목 | 커넥터 | MCP 서버 |
|---|---|---|
| 설정 방식 | GUI (Desktop 앱 내 + 버튼) | 설정 파일 (.mcp.json) |
| 인증 | OAuth (클릭 몇 번) | 수동 토큰/API 키 설정 |
| 적합한 경우 | 지원 서비스 빠른 연결 | 커스텀 통합, 지원 목록에 없는 서비스 |
| 사용 환경 | 로컬 + SSH 세션 | 모든 환경 (CLI, 원격 포함) |
커넥터 인증 만료
OAuth 토큰이 만료되면 Settings → Connectors에서 재인증할 수 있습니다. 세션 중간에 만료되면 Claude가 재인증을 안내합니다.
9. 로컬 / SSH / 클라우드 환경
세션 시작 시 3가지 실행 환경 중 선택할 수 있습니다.
환경 비교
| 환경 | 실행 위치 | 장점 | 한계 |
|---|---|---|---|
| Local | 내 컴퓨터 | 모든 파일 접근, 최대 기능 | 컴퓨터 켜야 함 |
| Remote | Anthropic 클라우드 | 앱 닫아도 실행, 멀티 레포 | Git 클론만 접근 |
| SSH | 원격 머신 | GPU/특수 환경 접근 | 머신에 Claude 설치 필요 |
실전 예시: 상황별 환경 선택
Local — 일상 개발
💬 "로컬 프로젝트에서 테스트를 수정하고 커밋해줘"
→ 로컬 파일에 직접 접근, .env 파일 사용, 모든 도구 활용 가능
Remote — 장시간 리팩토링
💬 "이 프로젝트의 모든 클래스 컴포넌트를 함수형 컴포넌트로 마이그레이션해줘"
→ 노트북 닫아도 계속 실행, claude.ai/code에서 진행 상황 확인
멀티 레포 지원: 레포 pill 옆 + 버튼으로 추가 레포 선택
💬 "shared-lib의 API를 변경하고, frontend와 backend 레포에서 호출하는 부분도 같이 수정해줘"
SSH — GPU 서버에서 모델 학습
💬 "GPU 서버에서 모델을 학습시키고, 결과 로그를 분석해줘"
SSH 연결 설정:
| 필드 | 예시 |
|---|---|
| Name | gpu-server |
| SSH Host | ubuntu@gpu.mycompany.com 또는 ~/.ssh/config의 gpu-server |
| SSH Port | 22 (기본값) |
| Identity File | ~/.ssh/id_ed25519 |
설정 방법: 환경 드롭다운 → + Add SSH connection → 정보 입력
세션 이동
작업 중 환경을 전환해야 할 때:
- Local → Remote: 세션 툴바의 VS Code 아이콘 → "Continue in" → "Claude Code on the Web" → 브랜치가 푸시되고 원격 세션으로 이동
- CLI → Desktop: 터미널에서
/desktop입력 → Desktop 앱에서 세션 이어서 작업
CLI와 Desktop 비교
CLI 플래그 대응표
| CLI | Desktop 대응 |
|---|---|
--model sonnet | 보내기 버튼 옆 모델 드롭다운 |
--resume, --continue | 사이드바에서 세션 클릭 |
--permission-mode | 보내기 버튼 옆 모드 선택기 |
--dangerously-skip-permissions | Settings → Claude Code → Bypass permissions mode |
--add-dir | 원격 세션에서 + 버튼으로 레포 추가 |
--worktree | 자동 워크트리 (병렬 세션) |
ANTHROPIC_MODEL 환경 변수 | 모델 드롭다운 |
기능 비교표
| 기능 | CLI | Desktop |
|---|---|---|
| 권한 모드 | 모든 모드 (dontAsk 포함) | Ask, Auto accept edits, Plan, Auto, Bypass |
| 서드파티 프로바이더 | Bedrock, Vertex, Foundry | ❌ (Anthropic API 직접 연결만) |
| MCP 서버 | 설정 파일 | 커넥터 UI + 설정 파일 |
| 플러그인 | /plugin 명령어 | 플러그인 매니저 UI |
| @mention 파일 | 텍스트 기반 | 자동완성 (로컬/SSH만) |
| 파일 첨부 | ❌ | 이미지, PDF 지원 |
| 세션 격리 | --worktree 플래그 | 자동 워크트리 |
| 병렬 세션 | 별도 터미널 | 사이드바 탭 |
| 반복 작업 | Cron, CI 파이프라인 | 스케줄 태스크 |
| Computer Use | macOS에서 /mcp로 활성화 | macOS + Windows GUI |
| Dispatch | ❌ | Dispatch 세션 |
| 스크립팅/자동화 | --print, Agent SDK | ❌ |
Desktop에서 사용할 수 없는 기능
| 기능 | 대안 |
|---|---|
| 서드파티 프로바이더 | CLI에서 Bedrock/Vertex/Foundry 사용 |
| Linux | Desktop은 macOS/Windows만 지원 |
| 인라인 코드 제안 | 대화형 프롬프트와 명시적 코드 변경으로 작동 |
| 에이전트 팀 | CLI 또는 Agent SDK 사용 |
Enterprise 설정
Team 또는 Enterprise 플랜에서는 관리자가 Admin Console을 통해 조직 전체의 Claude Desktop 설정을 관리할 수 있습니다.
관리자 제어 항목
| 설정 | 설명 |
|---|---|
| Permission Mode 제한 | 조직에서 사용 가능한 권한 모드 제한 (예: Bypass 금지) |
| MCP 서버 허용 목록 | 승인된 MCP 서버만 연결 가능 |
| Computer Use 비활성화 | 조직 전체에서 Computer Use 기능 차단 |
| 채널 플러그인 제한 | allowedChannelPlugins로 승인된 채널만 허용 |
| 원격 제어 활성화 | Remote Control 기능의 조직 수준 활성화/비활성화 |
| 모델 선택 제한 | 사용 가능한 모델 목록 제한 |
Managed Settings
관리자가 managed settings를 배포하면 개별 사용자의 settings.json보다 우선 적용됩니다:
{
"channelsEnabled": true,
"allowedChannelPlugins": [
{"marketplace": "claude-plugins-official", "plugin": "telegram"}
],
"permissions": {
"disableBypassPermissionsMode": "disable"
}
}
Enterprise 기능 활용
Enterprise 관리자는 Anthropic Admin Console에서 조직 정책을 설정합니다. 개별 사용자가 변경할 수 없는 보안 정책을 강제 적용할 수 있습니다.
연계 기능
Desktop 앱 각 모드의 전용 가이드
장점, 단점과 한계점
장점
- 시각적 Diff 리뷰: IDE 수준의 diff 뷰어로 변경 사항을 파일별로 검토하고 인라인 코멘트를 작성할 수 있어, CLI의 텍스트 출력보다 훨씬 직관적입니다
- 라이브 프리뷰: 코드 수정과 동시에 웹 앱의 변경 결과를 실시간으로 확인하여 빠른 피드백 루프를 구성할 수 있습니다
- 9가지 통합 기능: Diff 리뷰, 라이브 프리뷰, 병렬 세션, 배경 에이전트, Computer Use, 스케줄 등 9가지 핵심 기능을 하나의 앱에서 제공합니다
- GUI로 접근성 높음: 터미널에 익숙하지 않은 사용자도 모드 선택기, 토글, 사이드바 등 GUI 인터페이스로 Claude Code의 모든 기능을 활용할 수 있습니다
- 권한 모드 시각적 관리: Ask, Auto accept edits, Plan, Auto, Bypass 등 5가지 권한 모드를 보내기 버튼 옆에서 즉시 전환하여 안전성과 속도를 상황에 맞게 조절할 수 있습니다
단점과 한계점
- Desktop 앱 전용: CLI에서는 사용할 수 없는 기능이 많아, SSH 서버나 원격 리눅스 환경에서는 Desktop 기능을 활용하기 어렵습니다
- macOS/Windows만 지원: Linux Desktop 앱은 제공되지 않으며, Intel Mac에서는 Cowork 탭 등 일부 기능이 제한됩니다
- 리소스 사용량 높음: Electron 기반 앱으로 메모리와 CPU 사용량이 높으며, 병렬 세션을 여러 개 실행하면 시스템 부하가 증가합니다
- 일부 기능 연구 프리뷰: 라이브 프리뷰, Computer Use 등 일부 기능은 아직 연구 프리뷰 단계로, 동작이 불안정하거나 향후 변경될 수 있습니다
- CLI 대비 세밀한 제어 부족: 환경 변수, 파이프라인, 플래그 조합 등 CLI가 제공하는 세밀한 제어 옵션은 Desktop GUI에서 일부 지원되지 않습니다
활용 팁
Desktop의 GUI 편의성과 CLI의 세밀한 제어를 모두 활용하려면, Desktop에서 Code 탭으로 작업하면서 필요시 내장 터미널이나 별도 CLI 세션을 병행하세요. 리소스가 부족하면 병렬 세션 수를 줄이고, 사용하지 않는 배경 에이전트를 정리하세요.
문제 해결
| 문제 | 해결 방법 |
|---|---|
| 403 또는 인증 오류 | 로그아웃 → 재로그인, 유료 구독 확인, 앱 완전 종료 후 재실행 |
| 빈 화면 / 멈춤 | 앱 재시작, 업데이트 확인 |
| "Failed to load session" | 폴더 존재 확인, Git LFS 설치 확인, 다른 폴더 선택 |
| 도구를 찾지 못함 | 터미널에서 도구 동작 확인, 셸 프로필 PATH 확인, 앱 재시작 |
| Git/Git LFS 오류 | Windows: Git for Windows 설치, Git LFS: git lfs install 후 재시작 |
| MCP 서버 오작동 (Windows) | 설정 확인, 앱 재시작, 작업 관리자에서 프로세스 확인 |
| 앱이 종료되지 않음 | macOS: Cmd+Q 또는 Cmd+Option+Esc, Windows: Ctrl+Shift+Esc |
| Cowork 탭 사용 불가 (Intel Mac) | Apple Silicon (M1 이상) 필요, Chat/Code 탭은 정상 작동 |
| "Branch doesn't exist yet" | git fetch origin <브랜치> → git checkout <브랜치> |
| 프리뷰 서버가 안 열림 | .claude/launch.json 설정 확인, 포트 충돌 확인 |
| Computer Use 권한 오류 | macOS: 시스템 설정에서 접근성/화면 기록 허용 후 앱 재시작 |
| 커넥터 인증 만료 | Settings → Connectors에서 재인증 |
상세 문제 해결
인증 오류 (403, 401)
# 1. 현재 인증 상태 확인
claude auth status
# 2. 로그아웃 후 재로그인
claude auth logout
claude auth login
# → claude.ai 옵션 선택
# 3. 그래도 안 되면 앱 완전 종료 후 재시작
# macOS: Cmd+Q → 다시 열기
# Windows: 작업 관리자에서 Claude 프로세스 모두 종료 → 다시 열기
인증 오류 체크리스트
- 유료 구독(Pro/Max/Team/Enterprise)이 활성 상태인지 확인
- 조직 계정이라면 관리자가 Desktop 사용을 허용했는지 확인
- VPN이 Anthropic 도메인을 차단하지 않는지 확인
빈 화면 또는 앱 멈춤
# macOS: 캐시 초기화
rm -rf ~/Library/Application\ Support/Claude/Cache
rm -rf ~/Library/Application\ Support/Claude/GPUCache
# Windows: 캐시 초기화
# %APPDATA%\Claude\Cache 폴더 삭제
# 앱 재시작 후에도 문제가 지속되면 재설치
Git 관련 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
git: command not found | Git 미설치 | macOS: xcode-select --install, Windows: Git for Windows 설치 |
git lfs: command not found | Git LFS 미설치 | git lfs install 실행 후 앱 재시작 |
fatal: not a git repository | Git 저장소가 아닌 폴더 | git init으로 초기화하거나 Git 저장소 폴더 선택 |
Branch doesn't exist yet | 원격 브랜치 미동기화 | git fetch origin → git checkout <브랜치> |
Windows에서 MCP 서버 문제
Windows 환경에서 MCP 서버가 정상 동작하지 않을 때:
# 1. MCP 서버 프로세스 확인
# 작업 관리자(Ctrl+Shift+Esc) → 세부 정보 탭에서 MCP 관련 프로세스 확인
# 2. 설정 파일 확인
# %USERPROFILE%\.claude\settings.json 또는 프로젝트의 .mcp.json
# 3. Node.js 경로 확인
where node
# PATH에 Node.js가 포함되어 있는지 확인
# 4. 앱 재시작으로 MCP 서버 재초기화
Windows MCP 주의사항
- Windows에서는 MCP 서버의
command경로에 절대 경로를 사용하는 것이 안전합니다 npx를 사용하는 경우npx.cmd로 지정해야 할 수 있습니다- 방화벽이 로컬 MCP 서버의 포트를 차단할 수 있습니다