Claude Code Web(웹 버전) 실전 가이드

 

 

0. Claude Code Web이 뭐가 다른가?

일반적인 코딩 AI(자동완성/챗봇)와 달리 Claude Code는 에이전트처럼 움직입니다.

• 저장소 맥락 파악 → 수정 범위 결정
• 테스트/명령 실행 → 결과 반영
• 변경사항 정리 → PR 생성까지 이어서 처리 (Claude)

웹 버전은 여기서 한 단계 더 나가서, **“브라우저만 있으면 된다”**가 핵심입니다. (TechCrunch)

---

1. 가격/플랜(핵심만)

웹 버전은 현재 **Pro / Max 사용자 중심(연구 프리뷰/베타)**로 제공되고, 최근엔 **Team/Enterprise(프리미엄 시트)**에도 확대됐습니다. (Claude)

• Pro: $20/월
• Max: $100/월(5x), $200/월(20x) (support.claude.com)

📌 그리고 중요한 점: 웹 세션은 다른 Claude Code 사용량과 레이트리밋을 공유합니다(병렬로 돌리면 빨리 닳을 수 있음). (Claude)

---

2. 시작하기(진짜 3분 컷)

Step 1) claude.ai에서 Code 열기

• 로그인 → 상단 메뉴의 Code(또는 “Claude Code on the web” 진입) (Claude)

Step 2) GitHub 연결

• Connect GitHub → OAuth 승인 → 저장소 선택(퍼블릭/프라이빗) (Claude)

Step 3) 네트워크 모드 선택(보안/편의 밸런스)

웹 버전은 네트워크 접근을 제한할 수 있는데, 보통 아래처럼 생각하면 편합니다. (개념/흐름은 웹 소개/보안 글에서 반복해서 강조됩니다) (Anthropic)

• No Internet: 외부 접근 완전 차단(가장 안전, 가장 답답)
• Restricted(화이트리스트): 실무에서 가장 무난
• Full Internet: 편하지만 주의 필요

✅ 추천: 처음엔 Restricted로 시작 + npmjs/pypi 같은 필수 도메인만 허용

---

3. “첫 프롬프트” 템플릿 5개(복붙용)

아래 5개만 저장해두면, 웬만한 작업은 바로 시작됩니다.

(1) 저장소 구조 파악 + README 정비

이 저장소 구조를 분석하고 README.md를 업데이트해줘.
- 프로젝트 개요
- 설치 방법
- 실행/사용 예제
- 개발/배포 흐름(있다면)
변경은 PR로 올려줘.

(2) “잘 정의된” 버그 수정

이슈: 로그인 버튼 클릭 시 null reference error가 발생한다.
재현 방법을 먼저 정리하고, 원인 분석 후 최소 수정으로 해결해줘.
테스트가 있다면 업데이트하고, PR로 올려줘.

(3) 리팩토링(범위 제한 필수)

src/auth 경로 내부만 리팩토링해줘.
목표: 가독성 개선 + 중복 제거
제약: public API(함수 시그니처)는 변경하지 말 것.
PR로 올려줘.

(4) 테스트 추가(TDD 스타일)

현재 기능에 대한 회귀 테스트를 추가해줘.
- 핵심 happy path 2개
- edge case 2개
테스트 실행 방법도 README에 보강해줘.

(5) 작업이 커지기 시작하면 “계획 먼저”

작업 전에 Plan을 먼저 작성해줘.
- 변경 파일 목록 예상
- 위험요소(회귀/보안/성능)
- 검증 체크리스트
Plan 승인 후에 구현 진행해줘.

---

4. 결과 검증 체크리스트(이거 꼭 넣으세요)

Claude가 PR을 만들어줘도, 검증은 사람이 해야 마음이 편합니다.

✅ PR 확인 체크리스트(복붙용)

[ ] 변경 범위가 요청한 디렉터리/파일에만 한정됐는가?
[ ] 불필요한 포맷/의미 없는 리네이밍이 과도하지 않은가?
[ ] 테스트가 추가/수정됐다면 실제로 실행 가능한가?
[ ] 빌드/린트/타입체크가 통과하는가?
[ ] 보안: 시크릿/토큰/키가 코드/문서에 포함되지 않았는가?
[ ] 성능: O(N^2) 같은 퇴보가 없는가?
[ ] README/문서 변경이 실제 실행 방법과 일치하는가?

---

5. CLAUDE.md가 “진짜” 핵심인 이유

Anthropic이 공식적으로도 CLAUDE.md를 강력 추천합니다.
Claude Code가 시작할 때 자동으로 컨텍스트에 포함시키는 “프로젝트 규칙/맥락” 파일이라, 잘 써두면 결과물 일관성이 확 좋아져요. (Anthropic)

✅ CLAUDE.md 템플릿(실무용, 80~120줄 목표)

# Project Overview
- What this repo does (1~2 lines)
- Primary users / target

## Tech Stack
- Framework:
- Language:
- Build/Test:
- DB/Infra:

## Project Structure
- src/...
- docs/...

## Key Commands
- install:
- dev:
- test:
- lint:
- type-check:
- build:

## Code Style
- Preferred patterns:
- Naming rules:
- Formatting:

## Testing Guidelines
- Required tests when changing core logic:
- Coverage target (if any):

## Guardrails (Do Not)
- NEVER commit directly to main
- Do not touch: src/legacy/**
- Do not add secrets to code or markdown
- Avoid breaking public API

계층 구조(공식 문서 기준)

• ~/.claude/CLAUDE.md (전체 프로젝트 공통)
• project-root/CLAUDE.md (프로젝트 규칙)
• 디렉터리별 CLAUDE.md (세부 규칙)
• CLAUDE.local.md (gitignore 처리되는 개인 규칙/메모에 유용) (Claude Code)

---

6. Hooks(자동화) 템플릿: “프롬프트보다 확실한 생산성”

Claude Code는 설정 파일로 **특정 시점에 자동 실행되는 명령(Hooks)**을 둘 수 있습니다. 이건 공식 문서/설정 체계에서 “정식 메커니즘”으로 안내됩니다. (Claude Code)

(A) 웹/CLI 공통: TypeScript 저장 시 Prettier 자동 실행

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "if [[ $TOOL_OUTPUT_PATH =~ \\.ts$ ]]; then npx prettier --write \"$TOOL_OUTPUT_PATH\"; fi"
      }]
    }]
  }
}

(B) 웹 추천: 세션 시작 시 의존성 자동 설치

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "npm install && echo 'Dependencies installed'"
      }]
    }]
  }
}

⚠️ 보안 주의: Hook은 환경 권한으로 자동 실행됩니다. 외부에서 받은 Hook은 반드시 검토하세요. (샌드박스/권한 모델 관련해서 Anthropic이 보안 글에서 반복 강조합니다) (Anthropic)

---

7. 슬래시 커맨드(웹에서도 쓰는 “필수 6개”)

웹 UI에서 자동완성이 없어도(버전 따라 다름) 커맨드 자체는 유용합니다.

• /init : 프로젝트 분석 + 기본 파일/가이드 생성 시작점
• /memory : 로드된 메모리/규칙 확인
• /permissions : 도구 권한 관리
• /clear : 새 작업 시작(컨텍스트 정리)
• /compact : 대화 압축(토큰/맥락 관리)
• /cost : 사용량 확인(플랜/레이트리밋 체감에 도움)

(메모리/설정 구조는 공식 문서에서 자세히 다룹니다) (Claude Code)

---

8. 보안: “클라우드에서 코드 돌리면 불안한데요?”

Anthropic은 Claude Code를 위해 **샌드박싱 런타임(sandbox-runtime)**을 오픈소스로 공개했고, Claude Code에서 명령 실행을 더 안전하게 만들기 위한 설계를 설명했습니다. (macOS/리눅스 격리 기술 언급 포함) (GitHub)

✅ 실전 보안 체크(블로그에 꼭 넣기)

• 시크릿/API 키를 CLAUDE.md/README에 쓰지 말 것
• 네트워크는 **Restricted(화이트리스트)**부터 시작
• PR 생성 전후로 **유출 가능 파일(로그/설정)**을 한 번 더 확인

---

9. 병렬 작업(웹의 강점) 운영 팁

웹은 탭을 여러 개 띄우기 쉬워서 병렬 작업이 편합니다.
다만 레이트리밋을 공유하니(특히 Pro) 아래처럼 운영하면 덜 막힙니다. (Claude)

• “큰 작업 1개 + 작은 작업 1개” 정도로 시작
• 각 탭마다 프롬프트 범위를 아주 좁게
• 결과가 커지면 /compact로 압축 후 이어가기

---

10. 트러블슈팅(실제 자주 걸리는 것 위주)

1) Session expired / 중간 끊김

• 원인: 네트워크/레이트리밋
• 대응: 작업을 작게 쪼개고, /cost로 사용량 확인(자주) (TechCrunch)

2) npm/pip 설치 실패

• 원인: 네트워크 모드 Restricted에서 도메인 미허용
• 대응: 필수 도메인 허용 or SessionStart Hook으로 자동 설치

3) “파일을 못 찾겠다”

• 대응: 파일 경로를 프롬프트에 명시적으로 넣기
  예: @src/components/Button.tsx 이 파일만 수정해줘

4) PR이 너무 큼

• 대응: 범위 제한 문장을 반드시 넣기
  “src/auth/**만”, “README만”, “테스트만” 처럼

---

11. 마무리: 저는 이렇게 쓸 것 같습니다(현실적인 워크플로우)

• 출근길(모바일/웹): 명확한 이슈 1~2개 위임, Plan 받고 진행
• 점심: PR 초안 확인, 추가 지시(범위 제한)
• 퇴근 전: 로컬에서 최종 검증(필요하면 CLI로 이어가기)

웹은 **“시작/위임/감시/PR 생성”**이 압도적으로 편하고,
CLI/로컬은 **“세밀한 디버깅/로컬 환경 재현”**이 강점이라, 둘이 보완 관계로 느껴졌습니다. (Claude)

---

(부록) 글 끝에 붙이면 좋은 “요약 박스”

✅ Claude Code Web = 브라우저에서 에이전트에게 일을 맡기는 방식
✅ 핵심은 CLAUDE.md(규칙) + Hooks(자동화) + 범위 제한 프롬프트
⚠️ 병렬 작업은 레이트리밋 공유라서 “작게 쪼개기”가 정답
🔐 시크릿/키는 절대 문서에 넣지 말 것