Claude Code 공식문서 리뷰 - Outside of the terminal[1] : Claude Code on the web, Claude Code on desktop, Chrome extension

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

Claude Code Docs 공식 문서 >> Outside of the terminal 섹션의 내용 중 3가지를 살펴 보려고 합니다.

(Claude Code on the web, Claude Code on desktop, Chrome extension)

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

 

이 글의 구성

1. Claude Code on the web
2. Claude Code on desktop
3. Chrome extension
4. Visual Studio Code
5. JetBrains IDESs
6. Github Actions
7. Gitlab CI/CD
8. Claude Code in Slack

 

1. Claude Code on the web

원문 : https://code.claude.com/docs/en/claude-code-on-the-web

웹에서 Claude Code 사용하기

• 핵심 기능: 터미널 없이 클라우드에서 비동기 코딩 작업 실행
• 상태: 연구 프리뷰 (Research Preview)
• 지원 대상: Pro, Max, Team/Enterprise 프리미엄 시트
• 지원 플랫폼: GitHub (GitLab 미지원)

내가 예전에 리뷰헀었던 글도 참고

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

 

개요

Claude Code on the web은 Anthropic의 보안 클라우드 인프라에서 Claude Code 작업을 비동기적으로 시작할 수 있는 연구 프리뷰 기능이다.

주요 활용 사례

사용 사례	설명
코드 아키텍처 질문	코드 구조와 기능 구현에 대한 질문 답변
버그 수정 및 루틴 작업	자주 조정이 필요 없는 일상적인 작업
병렬 작업	여러 버그 수정을 동시에 진행
원격 저장소	로컬에 체크아웃하지 않은 코드 작업
백엔드 변경	테스트 주도 개발을 통한 백엔드 수정

사용 가능 대상

구독 유형	사용 가능
Pro 사용자	사용 가능
Max 사용자	사용 가능
Team 프리미엄 시트	사용 가능
Enterprise 프리미엄 시트	사용 가능

참고
Claude iOS 앱에서도 이동 중 작업 관리가 가능하다.

 

시작하기

설정 단계

1. claude.ai/code 방문
2. GitHub 계정 연결
3. 저장소에 Claude GitHub 앱 설치
4. 기본 환경 선택
5. 코딩 작업 제출
6. 변경 사항 검토 및 GitHub에서 풀 리퀘스트 생성

초보자 팁
처음 사용한다면 먼저 작은 저장소에서 간단한 버그 수정부터 시작해보자. 복잡한 작업보다 결과를 빠르게 확인할 수 있다.

 

작동 방식

작업 흐름

1. 저장소 클론 → Anthropic 관리 VM에 저장소 클론
    ↓
2. 환경 설정 → 보안 클라우드 환경 준비
    ↓
3. 네트워크 구성 → 설정에 따른 인터넷 접근 구성
    ↓
4. 작업 실행 → 코드 분석, 변경, 테스트 실행
    ↓
5. 완료 → 완료 시 알림
    ↓
6. 결과 → 브랜치에 변경 사항 푸시, PR 생성 준비

 

웹과 터미널 간 작업 이동

웹에서 터미널로 이동

웹에서 시작한 작업을 로컬 터미널에서 계속하려면:

1. "Open in CLI" 버튼 클릭

2. 터미널에 명령어 붙여넣기 후 실행

 

3. 로컬 변경 사항은 스태시되고 원격 세션 로드

 

4. 로컬에서 작업 계속

실전 팁
복잡한 디버깅이 필요하거나 IDE 통합이 필요할 때 웹에서 터미널로 이동하면 좋다. 로컬 개발 환경의 모든 도구를 활용할 수 있다.

 

클라우드 환경

기본 이미지

범용 이미지에는 다음이 포함되어 있다:

• 주요 프로그래밍 언어 및 런타임
• 일반적인 빌드 도구 및 패키지 관리자
• 테스팅 프레임워크 및 린터

사용 가능한 도구 확인

check-tools

언어별 환경

언어	버전 및 도구
Python	Python 3.x, pip, poetry, 과학 라이브러리
Node.js	최신 LTS, npm, yarn, pnpm, bun
Ruby	3.1.6, 3.2.6, 3.3.6 (기본: 3.3.6)
PHP	8.4.14
Java	OpenJDK, Maven, Gradle
Go	최신 안정 버전, 모듈 지원
Rust	전체 툴체인, cargo
C++	GCC 및 Clang 컴파일러

데이터베이스

데이터베이스	버전
PostgreSQL	16
Redis	7.0

 

환경 설정

의존성 관리

SessionStart 훅을 사용하여 자동 설치를 구성할 수 있다.

.claude/settings.json 설정:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

scripts/install_pkgs.sh 스크립트 생성:

#!/bin/bash
npm install
pip install -r requirements.txt
exit 0

실행 권한 부여:

chmod +x scripts/install_pkgs.sh

로컬 vs 원격 실행 구분

CLAUDE_CODE_REMOTE 환경 변수를 확인하여 실행 환경을 구분할 수 있다:

#!/bin/bash
# 원격 환경에서만 실행
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

npm install
pip install -r requirements.txt

환경 변수

.env 형식의 키-값 쌍으로 설정한다:

API_KEY=your_api_key
DEBUG=true

 

네트워크 접근 및 보안

네트워크 정책

GitHub 프록시

기능	설명
인증 관리	GitHub 인증을 안전하게 관리
자격 증명 범위	샌드박스 내에서 범위가 지정된 자격 증명 사용
푸시 제한	현재 작업 브랜치로만 git push 제한
원활한 작업	클론, 페치, PR 작업 지원

보안 프록시

모든 아웃바운드 트래픽은 보안 프록시를 통과한다:

• 악의적인 요청으로부터 보호
• 속도 제한 및 남용 방지
• 향상된 보안을 위한 콘텐츠 필터링

기본 허용 도메인

버전 관리

플랫폼	도메인
GitHub	github.com, api.github.com, raw.githubusercontent.com
GitLab	gitlab.com, registry.gitlab.com
Bitbucket	bitbucket.org, api.bitbucket.org

패키지 관리자

언어	도메인
JavaScript	registry.npmjs.org, yarnpkg.com
Python	pypi.org, files.pythonhosted.org
Ruby	rubygems.org, api.rubygems.org
Rust	crates.io, rustup.rs
Go	proxy.golang.org, pkg.go.dev
JVM	maven.org, repo1.maven.org, gradle.org

 

보안 모범 사례

원칙	설명
최소 권한 원칙	필요한 최소한의 네트워크 접근만 활성화
정기적 감사	허용된 도메인을 주기적으로 검토
HTTPS 사용	HTTP보다 HTTPS 엔드포인트 선호

 

보안 및 격리

기능	설명
격리된 가상 머신	각 세션은 Anthropic이 관리하는 격리된 VM에서 실행
네트워크 접근 제어	기본적으로 제한됨, 비활성화 가능
자격 증명 보호	자격 증명이 샌드박스 내부에 없음, 보안 프록시로 처리
보안 분석	PR 생성 전 격리된 VM에서 코드 분석 및 수정

 

가격 및 속도 제한

• Claude Code on the web은 모든 Claude 사용량과 속도 제한을 공유한다
• 여러 작업을 병렬로 실행하면 비례적으로 더 많은 속도 제한을 소비한다

주의
병렬 작업 실행 시 속도 제한에 도달할 수 있으니 주의가 필요하다.

 

제한 사항

제한	설명
저장소 인증	웹에서 로컬로 세션을 이동하려면 동일한 계정으로 인증되어야 함
플랫폼 제한	GitHub만 지원, GitLab 및 기타 비GitHub 저장소는 미지원

 

모범 사례

1. Claude Code 훅 사용

SessionStart 훅을 구성하여 환경 설정을 자동화한다.

2. 요구 사항 문서화

CLAUDE.md에 의존성을 명확하게 지정한다.

3. AGENTS.md 활용

단일 정보 소스를 위해 CLAUDE.md에서 @AGENTS.md로 참조한다.

<!-- CLAUDE.md 예시 -->
# 프로젝트 정보

이 프로젝트는 React + Node.js 기반입니다.

## 에이전트 설정
@AGENTS.md

실전 팁
CLAUDE.md에 프로젝트의 빌드 명령어, 테스트 방법, 주요 디렉토리 구조를 명시해두면 Claude Code가 더 정확하게 작업을 수행한다.

 

2. Claude Code on desktop

원문 : https://code.claude.com/docs/en/desktop

데스크톱에서 Claude Code 사용하기
네이티브 데스크톱 애플리케이션으로, 여러 Claude Code 세션을 로컬에서 동시에 실행하고, 클라우드 세션과 원활하게 연동할 수 있다. Git worktree를 활용하여 각 세션을 격리된 환경에서 운영한다.

 

주요 기능

1. Git Worktree를 활용한 병렬 로컬 세션

기능	설명
동시 실행	같은 저장소에서 여러 Claude Code 세션을 동시에 실행
격리된 환경	각 세션은 자체 git worktree를 가짐
기본 위치	~/.claude-worktrees (설정 변경 가능)

Git Worktree란?
하나의 Git 저장소에서 여러 작업 디렉토리를 만들 수 있는 기능이다. 각 worktree는 다른 브랜치를 체크아웃할 수 있어, 동시에 여러 작업을 진행할 때 유용하다.

2. .gitignore 파일 포함

.worktreeinclude 파일을 사용하여 무시된 파일 중 어떤 것을 새 worktree에 복사할지 지정할 수 있다.

• .gitignore 스타일 패턴 사용
• .worktreeinclude와 .gitignore 모두에 매치되는 파일만 복사

3. 웹에서 Claude Code 시작

데스크톱 앱에서 직접 보안 클라우드 세션을 시작할 수 있다. 리소스 집약적인 작업에 유용하다.

팁: 로컬 리소스가 부족하거나 백그라운드에서 오래 실행되는 작업이 있다면 웹 세션으로 전환하는 것이 좋다.

 

설치

다운로드 링크: claude.ai/download

플랫폼	지원 여부
macOS	지원
Windows (x64)	지원
Windows (arm64)	미지원
Linux	지원

주의: Windows arm64 아키텍처에서는 로컬 세션을 사용할 수 없다.

 

설정

Git Worktree 사용

저장소 루트에 .worktreeinclude 파일을 생성한다.

.env
.env.local
.env.*
**/.claude/settings.local.json

worktree가 생성될 때 .gitignore에 있으면서 .worktreeinclude에도 매치되는 파일이 메인 저장소에서 worktree로 자동 복사된다.

.worktreeinclude 작동 방식

1. .worktreeinclude에 패턴 정의
        ↓
2. .gitignore와 교집합 확인
        ↓
3. 매치되는 파일만 worktree로 복사

커스텀 환경 변수

1. "Local" 환경 선택
2. 설정 버튼 클릭
3. .env 형식으로 키-값 쌍 지정

API_KEY=your_api_key
DEBUG=true

# 여러 줄 값 - 따옴표로 감싸기
CERT="-----BEGIN CERT-----
MIIE...
-----END CERT-----"

보안 참고: 환경 변수 값은 보안을 위해 UI에서 마스킹된다.

PATH 환경 설정

Claude Code on desktop은 셸 설정에서 $PATH 환경 변수를 자동으로 추출한다.

사용 가능한 도구:

• yarn, npm, node
• 터미널에서 사용 가능한 모든 개발 도구

실전 팁: .env.local 파일에 개발 환경별 설정을 저장하고, .worktreeinclude에 포함시켜 모든 worktree에서 동일한 환경을 사용하자.

 

번들된 Claude Code 버전

항목	설명
번들 버전	데스크톱에는 안정적인 번들 버전의 Claude Code 포함
다운로드 시점	첫 실행 시 필요한 버전 다운로드
버전 관리	데스크톱이 자동으로 업데이트 및 정리 관리
CLI 버전과 차이	안정성을 우선하여 최신 CLI 버전과 다를 수 있음

 

엔터프라이즈 설정

조직에서는 다음을 설정할 수 있다.

설정	방법
로컬 Claude Code 비활성화	isClaudeCodeForDesktopEnabled 엔터프라이즈 정책 옵션
웹 Claude Code 비활성화	관리자 설정에서 변경 (claude.ai/admin-settings/claude-code)

 

제한 사항

제한	설명
Windows arm64	이 아키텍처에서는 사용 불가
Git 필수	폴더에 Git이 초기화되어 있지 않으면 worktree를 생성하지 않음

 

사용 시나리오

시나리오 1: 여러 기능을 동시에 개발

# 메인 저장소에서 데스크톱 앱 실행
# 각 기능별로 별도의 세션 시작
# 각 세션은 자동으로 별도의 worktree에서 작업

시나리오 2: 버그 수정과 기능 개발 병행

1. 세션 1: 긴급 버그 수정 (hotfix 브랜치)
2. 세션 2: 새 기능 개발 (feature 브랜치)
3. 각 세션이 독립적으로 작업, 충돌 없음

시나리오 3: 리소스 집약적 작업은 웹으로

1. 로컬 세션에서 작업 시작
2. 리소스가 많이 필요한 작업 발견
3. 웹 세션으로 전환하여 클라우드에서 처리

실전 팁: 대규모 코드베이스 분석이나 전체 테스트 스위트 실행 같은 무거운 작업은 웹 세션을 활용하면 로컬 리소스를 절약할 수 있다.

참고 자료

• Claude Desktop 다운로드
• 웹에서 Claude Code - 웹 기반 사용법
• Claude Desktop 지원 문서
• 엔터프라이즈 설정 - 기업용 설정 가이드

 

3. Chrome extension

원문 : https://code.claude.com/docs/en/chrome

Claude Code와 Chrome 연동 (베타)
Claude Code는 Claude in Chrome 브라우저 확장 프로그램과 연동하여 터미널에서 직접 브라우저 자동화 기능을 제공한다. 터미널에서 코드를 작성하고, 브라우저에서 테스트와 디버깅을 컨텍스트 전환 없이 수행할 수 있다.

내가 리뷰 했던 글 참고 : Claude for Chrome(Claude Sonnet 4.5 브라우저 확장)출시 - AI가 웹 브라우저를 직접 조작하는 시대

 

연동으로 가능한 작업

Chrome과 연결하면 다음 작업들이 가능하다.

기능	설명
라이브 디버깅	Claude가 콘솔 에러와 DOM 상태를 직접 읽고 코드를 수정
디자인 검증	Figma 목업으로 UI를 만들고, 브라우저에서 열어 일치 여부 확인
웹 앱 테스트	폼 유효성 검사, 시각적 회귀, 사용자 플로우 검증
인증된 웹 앱 접근	Google Docs, Gmail, Notion 등 로그인된 앱에 API 없이 접근
데이터 추출	웹 페이지에서 구조화된 정보를 추출하여 로컬에 저장
작업 자동화	데이터 입력, 폼 작성, 멀티 사이트 워크플로우 자동화
세션 녹화	브라우저 상호작용을 GIF로 녹화

 

사전 요구사항

전제 조건:

• Google Chrome 브라우저
• Claude in Chrome 확장 프로그램 (버전 1.0.36 이상)
• Claude Code CLI (버전 2.0.73 이상)
• 유료 Claude 플랜 (Pro, Team, 또는 Enterprise)

중요 제한사항

제한	설명
Chrome만 지원	현재 Google Chrome에서만 작동
다른 브라우저 미지원	Brave, Arc 등 Chromium 기반 브라우저 미지원
WSL 미지원	Windows Subsystem for Linux 환경 미지원

 

연동 작동 방식

Claude Code는 Chrome의 Native Messaging API를 통해 Claude in Chrome 확장 프로그램과 통신한다.

┌─────────────────┐      Native Messaging API      ┌─────────────────┐
│   Claude Code   │ ←─────────────────────────────→│  Chrome 확장    │
│   (터미널)      │                                 │  프로그램       │
└─────────────────┘                                 └─────────────────┘
        │                                                   │
        │ 명령 전송                                         │ 브라우저 제어
        ▼                                                   ▼
   작업 계속 가능                                    ┌─────────────────┐
   (터미널에서)                                     │   Chrome 탭     │
                                                    └─────────────────┘

핵심 특징

• Claude Code가 브라우저 탭을 제어하고, 페이지 내용을 읽고, 액션을 수행
• 자동화가 진행되는 동안 터미널에서 계속 작업 가능
• 로그인 페이지, CAPTCHA, 차단 요소를 만나면 Claude가 일시 정지
• 브라우저의 로그인 상태에 접근 (로그인된 사이트는 재인증 불필요)

참고:

• Chrome은 브라우저 작업을 위해 새 탭을 열며, 기존 탭을 가져가지 않는다
• 보이는 브라우저 창이 필요하다 (헤드리스 모드 미지원)
• 차단 요소를 수동으로 처리하고 Claude에게 계속하라고 말할 수 있다

 

설정 방법

1단계: Claude Code 업데이트

claude update

Chrome 연동에는 최신 버전이 필요하다. 네이티브 설치 프로그램을 사용했다면 자동으로 업데이트된다.

2단계: Chrome 활성화로 Claude Code 시작

claude --chrome

3단계: 연결 확인

/chrome 명령으로 연결 상태를 확인하고 설정을 관리한다.

/chrome

확장 프로그램이 감지되지 않으면 설치 링크와 함께 경고가 표시된다.

기본값으로 활성화하기

/chrome
# "Enable by default" 선택

주의: 기본값으로 활성화하면 브라우저 도구가 항상 로드되어 컨텍스트 사용량이 증가한다.

버전 확인 방법:

# Claude Code 버전 확인
claude --version

# Chrome 확장 프로그램 버전 확인
# Chrome에서 chrome://extensions 접속 후 Claude in Chrome 확인

 

테스트해보기

연결이 완료되면 다음 명령으로 테스트해보자.

"code.claude.com/docs에 가서 검색 박스를 클릭하고, "hooks"를 입력한 다음 어떤 결과가 나오는지 알려줘"

Claude가 페이지로 이동하고, 검색 필드를 클릭하고, 쿼리를 입력한 후 결과를 보고한다.

 

ex)

 

예제 워크플로우

로컬 웹 애플리케이션 테스트

"방금 로그인 폼 유효성 검사를 업데이트했어. localhost:3000을 열고, 잘못된 데이터로 폼을 제출해보고 에러 메시지가 제대로 나타나는지 확인해줘"

콘솔 로그로 디버깅

"대시보드 페이지를 열고 페이지 로드 시 콘솔에 에러가 있는지 확인해줘"

폼 자동 입력

"contacts.csv에 고객 연락처 스프레드시트가 있어. 각 행에 대해 crm.example.com의 CRM에 가서 "Add Contact"를 클릭하고 이름, 이메일, 전화번호 필드를 채워줘"

Google Docs에 콘텐츠 작성

"최근 커밋을 기반으로 프로젝트 업데이트 초안을 작성하고 docs.google.com/document/d/abc123에 있는 내 Google Doc에 추가해줘"

웹 페이지에서 데이터 추출

"제품 목록 페이지에 가서 각 항목의 이름, 가격, 재고 상태를 추출해줘. 결과를 CSV 파일로 저장해"

데모 GIF 녹화

"장바구니에 상품을 추가하는 것부터 확인 페이지까지 결제 플로우를 완료하는 방법을 보여주는 GIF를 녹화해줘"

실전 팁 - 효과적인 프롬프트 작성:

• 구체적인 URL과 요소를 명시한다
• 단계별로 명확하게 지시한다
• 예상 결과를 함께 설명하면 검증이 쉽다

 

모범 사례

브라우저 자동화 시 다음 가이드라인을 참고한다.

상황	권장 사항
모달 대화상자	JavaScript alert, confirm, prompt는 브라우저 이벤트를 차단한다. 수동으로 닫고 Claude에게 계속하라고 말한다
새 탭 사용	Claude는 각 세션마다 새 탭을 생성한다. 탭이 응답하지 않으면 새 탭을 만들도록 요청한다
콘솔 출력 필터링	콘솔 로그는 장황할 수 있다. 모든 출력 대신 찾을 패턴을 지정한다

 

사용 가능한 도구

/mcp를 실행하고 claude-in-chrome을 클릭하면 사용 가능한 브라우저 도구 전체 목록을 볼 수 있다.

Claude가 수행할 수 있는 작업:

• 페이지 이동
• 클릭 및 입력
• 폼 작성
• 스크롤
• 콘솔 로그 및 네트워크 요청 읽기
• 탭 관리
• 창 크기 조절
• GIF 녹화

 

문제 해결

확장 프로그램이 감지되지 않음

Claude Code에서 "Chrome extension not detected" 메시지가 표시되면:

1. Chrome 확장 프로그램 (버전 1.0.36 이상) 설치 확인
2. Claude Code 버전 확인 (2.0.73 이상):

   claude --version

3. Chrome이 실행 중인지 확인
4. /chrome 실행 후 "Reconnect extension" 선택
5. 문제가 지속되면 Claude Code와 Chrome 모두 재시작

브라우저가 응답하지 않음

Claude의 브라우저 명령이 작동하지 않으면:

1. 모달 대화상자(alert, confirm, prompt)가 페이지를 차단하고 있는지 확인
2. Claude에게 새 탭을 만들고 다시 시도하도록 요청
3. 확장 프로그램을 비활성화했다가 다시 활성화하여 재시작

최초 설정

연동을 처음 사용할 때 Claude Code가 네이티브 메시징 호스트를 설치한다. 권한 오류가 발생하면 Chrome을 재시작하여 설치를 완료한다.

 

권한 관리

사이트별 권한은 Chrome 확장 프로그램에서 상속된다. Chrome 확장 프로그램 설정에서 권한을 관리하여 Claude가 어떤 사이트를 탐색하고, 클릭하고, 입력할 수 있는지 제어한다.

/chrome

위 명령으로 현재 권한 설정을 확인할 수 있다.

보안 팁:

• 민감한 사이트(은행, 결제 등)에 대한 권한은 신중하게 설정한다
• 필요한 사이트에만 권한을 부여한다
• 정기적으로 권한 설정을 검토한다

 

요약

항목	내용
기능	터미널에서 브라우저 자동화
필수 조건	Chrome, 확장 프로그램 v1.0.36+, Claude Code v2.0.73+
시작 명령	claude --chrome
상태 확인	/chrome
제한	Chrome만 지원, WSL 미지원, 헤드리스 미지원

참고 자료

• CLI 레퍼런스 - --chrome 플래그를 포함한 명령줄 옵션
• 일반적인 워크플로우 - Claude Code 활용 방법
• Claude for Chrome 시작하기 - 전체 확장 프로그램 문서