Claude Code Workshop - Chapter 1 Overview

AWS 최우형님의 GitHub Claude Code Deep Dive Workshop 을 보면서 스스로 공부한 내용을 작성했습니다.

포스팅 모든 자료는 해당 워크숍 커리큘럼에서 학습했습니다.

* 자료 출처

GitHub - whchoi98/claude-code-workshop: claude-code-workshop

claude-code-workshop. Contribute to whchoi98/claude-code-workshop development by creating an account on GitHub.

github.com

1. What is Claude Code

1.1. 사전 내용

학습 내용

- Claude Code 정체성, 모델, Agentic Coding 개념

- 공식 정의 및 Anthropic 배경, 최신 모델 라인업

- Agentic Loop 와 Code Completion 대비 차별점

- 실행 환경 스펙트럼과 주요 사용 사례

- 구독 모델과 데이터 사용 정책

학습 목표

- Claude Code 가 무엇이고 왜 다른지 설명할 수 있으며, 본인 환경에 설치와 인증을 마치고 첫 세션 운영 가능

1.2. Claude Code 공식 정의

터미널, IDE, 데스크톱, 브라우저에서 동작하는 Agentic Coding 도구

- Claude Code 는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며 개발 도구와 통합되는 Anthropic 의 Agentic Coding 도구

- 자연어 지시를 받아 멀티스텝 작업을 자율적으로 완수

3가지 정의

Agentic Tool자율적으로 도구를 호출하며 멀티스텝 작업을 완수하는 에이전트형 도구

Everywhere터미널, VS Code, JetBrains, Desktop, 웹, Slack 까지 동일 엔진으로 실행

By AnthropicClaude 모델을 만든 Anthropic 의 1차 도구로 모델 통합이 가장 깊음

1.3. Anthropic 회사 배경

AI Safety 중심의 프론티어 모델 개발사

- Claude 모델 패밀리와 Claude Code, Agent SDK 를 직접 개발

Anthropic 용어

AI Safety First
- Constitutional AI 등 안전 연구를 제품에 직접 반영하는 개발 철학
- 안전을 나중에 붙이는 게 아니라 먼저 설계하는 것
- 제품을 먼저 만들고 안전 장치를 추가하는 방식이 아닌, 모델 학습 단계부터 배포 방식, 사용자 인터페이스 설계까지 전 과정에 안전을 통합하는 철학
Constitutional AI
- 2022년 Anthropic 이 발표한 모델 훈련 방법
- 사람이 일일이 유해한 답변 예시를 골라주지 않아도, AI 가 스스로 헌법(Constitutional)을 기준으로 자기 답변을 평가하고 개선하게 만듦

Claude Family

- Fable, Opus, Sonnet, Haiku 로 이어지는 프론티어 모델 라인업

Fable
- 최상위 Mythos-class
- 장시간 자율 세션 특화
- 가장 어려운 대규모 작업 수행
Opus
- 깊은 추론, 복잡한 아키텍처 결정
- 복잡한 리팩토링, 설계
Sonnet
- 기본 모델, 네이티브 1M 컨텍스트
- 일상 코딩 작업 전반
Haiku
- 빠른 응답, 비용 효율
- 간단한 변화, 검색, 분류

1.4. Agentic AI

사용자의 목표를 받아 스스로 계획을 세우고, 도구를 사용하며, 결과를 관찰하면서 목표 달성까지 자율적으로 작동하는 AI 시스템

Agentic AI 4가지 특징

Goal-driven(목표지향)
단계별 명령이 아닌 최종 목표를 받아 스스로 경로를 결정
Tool-using(도구활용)
파일 읽기, 명령 실행, 웹 검색 등 외부 도구를 능동 호출
Observative(관찰)
도구 결과를 관찰하고 다음 행동을 결정하는 피드백 루프
Iterative(반복적)
실패하면 다른 접근을 시도하며 완료까지 반복, 자가 수정

Agentic Loop

- Claude 가 사용자에 의해 명령을 입력 받으면 3단계를 계속 반복해가면서 작업을 수행

Gather Context
코드이해 - 파일 검색, 읽기
Claude.md 및 메모리 로드
Take Action
파일 편집, 명령 실행, 커밋 등 실제 변경 수행
Verify Results
테스트 실행, 타입 검사, 결과 관찰 후 다음 판단
Loop (Repeat / Steer)
완료까지 반복, ESC 로 중단 혹은 지시 추가 가능

Agentic Coding vs Code Completion

- 자동완성은 커서 위치에서 다음 코드를 제안하고, Agentic Coding 은 목표를 받아 저장소 전체에서 작업을 수행

Code Completion (기존)
- 현재 파일, 커서 주변 컨텍스트
- 다음 몇 줄을 제안
- 실행과 검증은 개발자 몫
- IDE 안에서만 동작
Agentic Coding (Claude Code)
- 저장소 전체 + 터미널 + Git 상태
- 여러 파일을 편집하고 명령 실행
- 테스트로 스스로 검증 후 수정
- 터미널, IDE, 웹 어디서든 동작

1.5. Claude Code 특징

Claude Code 4대 핵심 가치

깊은 코드 이해
- 단일 파일이 아닌 프로젝트 전체를 자율 탐색
실제 작업 완수
- 파일 수정, 테스트 실행, PR 생성까지 수행
안전한 권한 모델
- Allow, Ask, Deny 규칙과 체크포인트로 동작 범위 통제
확장 가능한 통합
- Skills, Subagents, MCP, Hooks, SDK 로 워크플로에 맞춰 확장

Claude Code 권한 모드

Plan
- 소스 수정 없이 탐색과 계획만 수행
- 승인 후 실행
Default
- 파일 편집과 셀 명령 전 매번 질문
Accept Edits
- 편집과 mkdir 등 파일 작업 자동, 그 외 질문
Auto
- 백그라운드 안전 검사로 전 행동 평가, 리서치 프리뷰

CI 등 비대화 환경은 --permission-mode 플래그와 사전 합의된 Allow 규칙으로 운영

1.6. Claude Code 사용 사례

디버깅
- 에러 메시지로부터 원인 추적 및 수정안 제시, 적용
리팩토링
- 대규모 코드베이스의 일관된 패턴 변경과 구조 개선
신기능 개발
- 요구사항으로부터 계획, 구현, 테스트까지 일괄 처리
코드베이스 학습
- 낯선 프로젝트 구조와 흐름을 자연어 대화로 학습
테스트 작성
- 커버리지 갭 분석과 자동 테스트 생성, 실패 수정
DevOps 자동화
- 셀 스크립트, IaC, CI/CD 파이프라인 작성과 점검

1.7. Claude Code 데이터 보안

Claude Code 데이터 보안 및 프라이버시

- 로컬 실행 시 코드는 사용자 머신에 있고, 모델 추론에 필요한 컨텍스트만 API 로 전송

- 전송 구간과 저장 구간 모두 암호화

Local
- 로컬 우선 실행
- 파일 접근과 명령 실행은 사용자 머신에서 권한 규칙으로 통제
Transit
- TLS 전송 암호화
- API 통신은 TLS 로 보호
- 사내 프록시와 커스텀 CA 도 지원
Cloud
- 클라우드 경로 선택
- Bedrock 사용 시 트래픽이 AWS 계정 경계 안에서 처리
Control
- 조직 통제 수단
- managed settings, 감사 로그, ZDR(Zero Data Retention) 옵션으로 정책 강제

Anthropic 데이터 사용 정책 핵심

학습 사용
- 상업용 계정 기본 미사용, 명시 동의 시만 사용
- Console(API), Bedrock 기본 미사용
보존 기간
- 안정성 검토 목적 제한적 보존
- ZDR 계약 시 보존 없음
인간 검토
- 약관 위반 의심 등 예외 상황에 한정
- 자동화 시스템 우선
제3자 공유
- 법적 의무 외 없음
- 소환장 등 법적 요구 한정 시 공유
암호화
- 전송 시 TLS 암호화
- 유휴시 AES-256 암호화

2. Architecture

2.1. 전체 아키텍처 / Agentic Harness

Agentic Harness
- 에이전트를 감싸는 하네스
- 모델 자체는 그대로 두고, 그 모델이 자율적으로 도구를 쓰고 반복 작업을 수행할 수 있게 만드는 주변 인프라 전체
언어 모델을 코딩 에이전트로 만드는 4계층
- Interface
  - Terminal CLI / VS Code / JetBrains / Desktop / Web / Slack / CI 등 동일 엔진 표면
- Harness
  - 도구 실행, 권한 검사 컨텍스트와 메모리 관리, 체크포인트, 세션 저장
- Model
  - Fable, Opus, Sonnet, Haiku 를 alias 로 선택하고 /model 로 전환
- Provider
  - Claude API / Amazon Bedrock / Google Vertex AI / Microsoft foundry / Gateway

실행 환경 3종

Local
- 기본값
- 내 머신에서 실행
- 파일과 도구, 환경에 완전 접근
Cloud
- Anthropic 관리 VM 에서 실행
- 작업 오프로드
- 원격 저장소 작업
Remote Control
- 실행은 내 머신, 조작은 브라우저
- 로컬 유지 + 웹 UI
--teleport
- 웹 세션을 터미널로
--remote
- 터미널에서 클라우드로

Agent SDK 위치

- SDK 를 통해 Claude Code 하네스를 Python 과 TypeScript 라이브러리로 노출

- CLI 를 쓰는것과 동일하게 권한 체계를 앱에 내장 가능

Claude Code CLI
- 대화형 REPL 과 헤드리스 모드
- 사람 주도 워크플로
- settings.json 을 통한 설정
- 즉시 사용
Agent SDK
- query() 등의 프로그래밍 인터페이스
- 앱과 서비스에 에이전트 내장
- 도구, 권한, 훅을 코드로 제어

API 통신 경로

- 하네스는 설정된 Provider로 추론 요청 전송

- 환경변수 스위치로 경로 선택, 조직은 게이트웨이로 중앙 집중화(LLM Gateway)

Claude API
- 기본 경로
- api.anthropic.com
Bedrock / Vertex(Gemini Enterprise Agent Platform) / Foundry
- USE_BEDROCK 등 스위치
LLM Gateway
- ANTHROPIC_BASE_URL
- 조직 중앙 관문

2.2. 자격증명 인증 우선 순위 6단계

여러 자격증명이 공존할 때 선택 순서

Claude Provider

- 환경변수 CLAUDE_CODE_USE_BEDROCK 설정 시 최우선

AUTH_TOKEN

- 환경변수 ANTHROPIC_AUTH_TOKEN

- Bearer 헤더로 전송, 게이트웨이 인증용

API_KEY

- 환경변수 ANTHROPIC_API_KEY

- X-Api-Key 헤더, 대화형에서는 1회 승인 필요

apiKeyHelper

- settings.json 설정 파일 안 스크립트 경로/설정

- 설정 스크립트가 반환하는 동적 키

- 볼트 연동과 회전에 적합

OAUTH_TOKEN

- 환경변수 CLAUDE_CODE_OAUTH_TOKEN

- claude setup-token 으로 만든 1년 토큰

- CI 파이프라인용

/login OAuth

- 구독 사용자 기본값

2.3. Claude Code 의 5가지 Tool

Claude Code 가 코딩 에이전트로 동작하기 위해 필요한 5가지 도구

File Ops

- Read, Edit, Write, NotebookEdit

- 파일 읽기, 정밀 수정, 신규 생성

- Edit, Write 는 승인 필요

Search

- Glob, Grep, 코드베이스 탐색

- 패턴 파일 찾기, 내용 정규식 검색

- 승인 불필요

Execution

- Bash, PowerShell, git, 테스트

- 셀 명령 실행

- 승인 필요

Web

- WebSearch, WebFetch, 문서 조회

- 웹 검색, URL 콘텐츠 조회

Code Intel

- LSP: 타입 오류, 정의 이동

- 코드 인텔리전스, 로그 감시, 예약

2.4. MCP Tool Integration

MCP 는 AI 도구를 외부 데이터 소스에 연결하는 개방형 표준

- GitHub, Slack, 사내 시스템 기능 등록 목적

서버 연결 (Connect)

claude mcp add 로 stdio, http 서버를 등록하고 /mcp 로 상태 확인

Tool Search (Scale)

도구 사용 시점에 온디맨드 로드로 컨텍스트 절약

인증 (Auth)

claude mcp login 으로 셀에서 OAuth 인증

관리 (Govern)

managed 설정으로 서버 allowlist, denylist 를 조직 차원에서 강제

2.5. 권한 모델

권한: 도구별 규칙 + 세션 모드
도구별 규칙(Rules / settings.json) - 정적 정책
- allow: 묻지 않고 실행
- ask: 실행 전 확인
- deny: 무조건 차단
- Bash(npm test) 등 도구별 패턴
- 조직 managed 설정이 최우선

// 예시
{
  "permissions": {
    "allow": [
      "Read",
      "Bash(npm test)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ],
    "defaultMode": "acceptEdits"
  }
}

세션 모드(Shift+Tab): 자율성
- Plan: 소스 수정 없이 계획
- Default: 편집과 명령마다 확인
- Accept Edits: 파일 작업 자동
- Auto: 백그라운드 안전 검사
- 비대화는 --permission-mode

2.6. Context

모델이 답변을 생성하는 순간에 눈으로 보고 있는 텍스트 전체

LLM 모델이 답변하기 위해 지금까지 주어진 텍스트

Context Windows 구성

- 컨텍스트는 크기 제한이 존재하며 이를 컨텍스트 윈도우라고 지칭

세션 컨텍스트 구성 내용
- - System instructions - 하네스 기본 지침
- CLAUDE.md (계층 병합) - 프로젝트, 사용자, 조직 지침
- Auto memory (MEMORY.md) - 첫 200줄 or 25KB
- Skills 설명부 - 본문은 사용 시점 로드
- MCP 도구 이름 - 정의는 온디맨드 로드
- 대화 이력 + 도구 출력 - 세션이 길수록 증가

/context : 사용량을 색상 그리드로 시각화

/mcp : 서버별 컨텍스트 비용 확인

/memory : 현재 로드된 CLAUDE.md 목록 확인 가능

Context Compaction (압축) 처리

컨텍스트 한계 도달 시 동작

한계 도달 시 오래된 도구 출력부터 정리, 필요 시 대화 요약

초반 세부 사항은 사라질 수 있어, 영속 규칙은 CLAUDE.md 에 보관

임계 감지 : 윈도우 사용량이 한계 접근
출력 정리 : 오래된 도구 출력부터 제거
대화 요약 : 요청 및 핵심 코드 보존
Thrashing 방지 : 반복 실패 시 오류 표기

Checkpointing

모든 파일 편집은 롤백 가능

Claude가 파일 편집 전 해당 파일의 현재 내용을 스냅샷으로 저장

ESC 두 번 or /rewind 로 이전 상태로 롤백 가능

파일 변경 한정

DB, API, 배포 등의 외부 작용은 미포함

2.7. 보안 아키텍처

4개 레이어 보안 구성

Permissions

allow, ask, deny 규칙과 4가지 모드

Sandboxing

샌드박스 Bash 로 파일시스템과 네트워크 격리

Checkpoints

편집 전 스냅샷으로 사후 복구 경로 확보

Audit

세션 기록, Hooks, OTel 로 행위 추적, 정책 검증

Logging & Telemetry

로컬: JSONL / 조직: OpenTelemetry

Local 기록
- ~/.claude/projects/세션 JSONL
- resume, fork, rewind의 기반
- claude --debug 상세 로그
- /export 로 대화 내보내기
OTel
- 토큰, 비용, 도구 사용 메트릭
- OTLP 로 CloudWatch, Datadog 연계
- 사용자, 팀 단위 대시보드

3. Installation

3.1. Claude Code 설치 방법

5가지 존재

Native

권장 방법

curl, irm 원라이너

자동 업데이트 가능

# macOS, Linux
curl -fsSL https://claude.ai/install.sh | bash

Homebrew : 맥 사용자

# Stable 버전
brew install --cask claude-code

# Latest 버전
brew install --cask claude-code@latest

# 업그레이드 (자동 업그레이드 없음)
brew upgrade claude-code
brew upgrade claude-code@latest

# 디스크 정리
brew cleanup

WinGet : 윈도우 사용자
apt / dnf / apk : 리눅스 사용자
npm : 레거시 설치법

설치 검증

# Version 확인
claude --version

# 종합 자가 진단
claude doctor

# 수동 업데이트
claude update

자동 업데이트와 릴리스 채널

settings.json 으로 채널과 하한 지정

/config 의 Auto-update channel 항목으로도 변경 가능

{
    "autoUpdatesChannel": "stable", // latest(기본)
    "minimumVersion": "2.1.100", // 이 버전 밑으로는 다운그레이드 금지
    "env": {
        "DISABLE_AUTOUPDATER": "0"
    }
}

4. Authentication

4.1. Claude Code 인증 방법

6가지 인증 경로

구독 OAuth

claude 실행 후 브라우저 로그인

Claude Console

Console 계정, API 종량 청구

Claude Console 전용 롤 지원

Amazon Bedrock

AWS 자격증명, IAM 통제

AWS 표준화 조직

Google Vertex AI (Gemini Enterprise Agent Platform)

GCP ADC 자격증명

GCP 표준화 조직

Microsoft Foundry

Azure 자격증명

Azure 표준화 조직

apps gateway

사내 IdP SSO, 게이트웨이 토큰

자체 호스팅 중앙 관문

구독 OAuth

claude

# 로그인 방법 확인
/status

Claude Console

API 종량 청구 조직 경로

Console 조직에 사용자 초대 및 Role 부여

API Key 환경변수

export ANTHROPIC_API_KEY='API_KEY'

API Key 보안 수칙

하드 코딩 금지

소스와 이미지에 하드코딩 금지

스캐너로 커밋 차단 (pre-commit)

볼트 관리

Secrets Manager, Vault 에서 발급

apiKeyHelper 로 동적 주입

최소 권한

Console 의 Claude Code Role 로 키 용도 자체 제한

회전과 폐기

주기적 회전

AWS Bedrock

AWS 자격증명으로 추론 경로 전환

# Bedrock 경로 활성화
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=ap-northeast-2

# 인증 확인
claude
/status

# 인증 해제
unset CLAUDE_CODE_USE_BEDROCK AWS_REGION

Bedrock IAM 정책 - 최소 권한

{
    "Version": "2012-10-17",
    "Statement": [{
        "Sid": "ClaudeCodeBedrock",
        "Effect": "Allow",
        "Action": [
            "bedrock:InvokeModel",
            "bedrock:InvokeModelWithResponseStream"
        ],
        "Resource": "arn:aws:bedrock:*::foundation-model/anthropic.*"
    }]
}

apps gateway

사내 SSO 로 로그인하는 자체 호스팅 관문

Self-hosted gateway
- 게이트웨이가 IdP 로 개발자 인증
- 추론을 설정된 클라우드로 라우팅

4.2. 자격 증명 위치

macOS
- 암호화된 macOS keychain
- OS 보안 저장소
Linux
- ~/.claude/.credentials.json
- 0600 권한
- 파일 권한 보호
Windows
- %USERPROFILE%.claude.credentials.json
- 프로파일 ACL 상속
관리 명령
- /login, /logout
커스텀 경로
- CLAUDE_CONFIG_DIR 로 위치 변경
- Linux, Windows

4.3. CI 용 장기 토큰

setup-token 으로 1년 OAuth 발급

claude setup-token

# 사용
export CLAUDE_CODE_OAUTH_TOKEN=<token>
claude -p "안녕하세요. 올해는 무슨 연도인가요?"

# 인증 해제
unset CLAUDE_CODE_OAUTH_TOKEN

5. Quick Start (첫 사용)

5.1. 대화형 REPL

claude                         # 대화형 REPL 시작
claude "질문 또는 작업"           # 초기 프롬프트와 함께 시작
claude -p "작업"                # 헤드리스, 결과만 출력 후 종료

claude --model opus            # 모델 지정 시작
claude --continue              # 최근 세션 이어서
claude --resume                # 세션 선택해 재개

cat data.csv | claude -p "요약" # 파이프 입력
claude --help                  # 전체 플래그

대화형 REPL

- 프롬프트에 자연어로 지시

- 도구 호출 과정이 실시간 표시

- 대화는 자동 저장, 재개 가능

- / 입력으로 명령 목록 필터

claude

> 이 프로젝트가 뭘 하는지 설명해줘

> src/api 의 에러 처리 방식을 알려줘

5.2. 프롬프트 작성 요령, 슬래시(/) 명령

공식 베스트 프랙티스 4원칙

Delegate, Don't dictate

유능한 동료에게 위임하듯 맥락과 방향을 주고 세부 경로는 맡김

어떤 파일을 읽을지까지 지시할 필요 없음

구체적으로

관련 경로, 제약, 참고 패턴을 처음부터 명시해 교정 횟수 절감

검증 기준 제공

테스트 케이스, 기대 출력 등 스스로 확인할 기준 제공

탐색과 분리

복잡한 문제는 Plan 모드로 조사 먼저, 코딩은 그 다음

대화로 교정

완벽한 첫 프롬프트보다 중간 개입과 반복 교정이 빠름

슬래시 명령

첫 세션, 프로젝트 셋업 단계
- /init : 프로젝트 초기화 (CLAUDE.md 자동생성)
- /help : 사용 가능한 명령 카탈로그
- /status : 인증, 모델 확인
- /doctor : 종합 진단
컨텍스트 관리
- /clear : 새 대화 시작, 컨텍스트 초기화, 이전 대화는 /resume 에 보존
- /compact : 요약해 지속, 같은 작업을 이어가며 공간 확보
- /btw : 곁가지 질문, 대화 이력에 남지 않는 사이드 질문, 컨텍스트 오염 방지
- /context : 컨텍스트 사용량을 색상 그리드로 표시
- /mcp : 서버별 컨텍스트 비용 개별 확인

5.3. 권한 모드 운용

Shift + Tab 으로 순환

Plan
- 아키텍처 변경
- 50+ 파일
- 의사결정
Default
- 일반 작업, 승인 흐름 학습
Accept Edits
- 소규모 반복 수정, 빠른 루프
Auto
- 신뢰 저장소, 분류기 안전 검사

Plan 모드

탐색과 실행의 분리

소스 파일을 수정하지 않고 탐색과 설계만 수행

계획 승인 시 실행 - opusplan 은 이 전환에 모델까지 변경

진입 방법
- Shift+Tab 두 번
- /plan 명령
허용 작업
- 읽기, 검색, 웹 조회 가능
- 소스 수정과 위험 명령 불가
계획 승인
- 산출 계획을 검토, 수정 요청 후 승인 시 실행
opusplan
- 계획은 opus, 실행은 sonnet

Auto 모드

승인 없이 안전 검사와 함께 수행

모든 행동을 백그라운드 안전 분류기가 평가

신뢰 저장소와 도메인을 조직이 설정

hard deny 규칙으로 차단

동작 방식
- 행동별 위험을 분류기가 평가
- 안전하면 진행, 위험하면 확인
신뢰 설정
- auto-mode 설정으로 신뢰 저장소, 버킷, 도메인 지정
Hard Deny
- 분류기와 무관하게 무조건 차단
가용 범위
- Pro 플랜, Sonnet 지원

5.4. 세션 관리

이전 대화(이전 세션)를 이어가는 방법

claude --continue      # 이 디렉토리의 최근 세션 재개
claude --resume        # 세션 목록에서 선택 재개
claude --from-pr 123   # PR을 만든 세션 찾아 재개

> /resume              # 세션 안에서 피커 열기
# 현재 워크트리 기준, 단축키로 범위 확장

> /clear 결제모듈-리팩토링 # 이전 대화에 이름 붙여 보관
# 세션은 ~/.claude/projects/ 에 JSONL로 저장

세션 분기 (branch, fork)

/branch
- 현 시점에서 대화 사본 생성하여 사본(브랜치)으로 전환 후 작업
- 원본은 /resume 으로 복귀 가능
/fork
- 전체 맥락을 물려받은 서브에이전트 생성
- 나는 원본에서 계속 진행
- 완료 시 결과가 내 대화로 회수
- 장시간 백그라운드 작업 위임에 적합

체크포인트 복구 (rewind)

코드와 대화를 시점 단위로 롤백

/rewind

- 체크포인트 목록에서 시점 선택

- 복구범위: 코드만 / 대화만 / 둘다

6. Core Capabilities

6.1. LSP(Language Server Protocol) / 코드 인텔리전스

Language Server Tool - 편집 직후 타입 오류와 경고 확인

동작

편집 후 진단

편집 직후 타입 오류 확인해 즉시 수정

정의 이동

심볼의 정의 위치로 이동해 정확한 컨텍스트 확보

참조 찾기

변경 영향 범위를 참조 목록으로 정량 파악

플러그인

언어별 Code Intelligence 플러그인 설치로 활성

6.2. Agent 도구 / Subagent

Agent 도구는 독립 컨텍스트를 가진 서브에이전트를 생성

컨텍스트 격리 : 탐색 작업의 대량 출력이 메인 대화창을 오염시키지 않음

자동, 명시적 호출: 작업 성격에 따라 작업 위임, 명시적으로 지정하여 호출 가능

병렬 실행 : 독립 작업 여러개를 동시에 진행, /batch 는 워크트리 격리까지 가능

6.3. AskUserQuestion / 스케쥴 도구

Interactive + Scheduled

AskUserQuestion
- 요구 사항이 모호할 경우 객관식 질문 제시
- 잘못된 가정으로 판단하는 것을 방지
- 선택지가 곧 설계 옵션
CronCreate / List / Delete
- 세션 내 반복, 일회성 프롬프트 예약
- /loop 로 풀링형 반복 실행

7. Interfaces

7.1. 상황별 인터페이스 선택

Remote Control - 휴대폰에서 로컬 세션 이어가기, 실행은 내 머신에서

Web / iOS + Teleport - 로컬 시작, 모바일에서 계속 진행, 클라우드 세션 이동

Routines / Desktop 예약 - 반복 일정, 머신이 꺼져도 Routines 수행

GitHub Actions / GitLab - PR 리뷰, 이슈 분류 자동화, CI 통합

Slack 통합 - Slack 버그 리포트를 PR 로, @Claude 멘션

Chrome 통합 - 라이브 웹앱 디버깅, 콘솔, DOM 접근

VS Code 확장 (Cursor)

# 확장 마켓플레이스에서 'Claude Code' 검색
# Cmd+Shift+X (macOS) / Ctrl+Shift+X

# 설치 후 실행
# Cmd+Shift+P -> 'Claude Code'
# 'Open in New Tab' 선택

# Cursor도 같은 확장 사용
# vscode:extension/anthropic.claude-code
# cursor:extension/anthropic.claude-code

- CLI 설정 및 CLAUDE.md 그대로 공유

- MCP 서버 구성도 동일 적용

- 터미널 세션과 자유롭게 병행

기능

인라인 Diff
- 제안 변경을 에디터 diff 로 검토, 부분 수락 가능

@-mentions
- @파일, @심볼로 컨텍스트 지목
Plan 검토
- Plan 모드 산출물을 패널에서 구조적으로 검토
대화 이력
- 세션 이력을 에디터 안에서 탐색하고 재개

Desktop 앱

IDE 와 터미널 밖 독립 앱

여러 세션을 git 격리로 나란히 돌리고, 시각적 diff 와 앱 프리뷰, PR 모니터링까지 제공

기능

병렬 세션
- 세션마다 git 격리
- 드래그 앤 드롭 패널 배치
시각 검토
- diff 검토, 앱 프리뷰
- 통합 터미널과 파일 에디터
Dispatch
- 휴대폰에서 작업을 보내면 데스크톱 세션으로 생성
클라우드 세션
- 로컬과 클라우드 세션을 한 화면에서 함께 운영

Web

브라우저에서 GitHub 저장소를 연결해 클라우드 세션 시작

장시간 작업을 걸어두고 나중에 확인하거나, 병렬 작업 가능

Teleport / Remote Control

세션을 환경 사이로 옮기기

GitHub 연동 필요

# 웹, iOS 에서 시작한 세션을 터미널로 가져오기
claude --teleport

# 터미널 세션을 클라우드로 보내기
claude --remote

# 로컬 세션을 폰, 브라우저에서 조종
/remote-control

Slack 통합

채널에서 @Claude 를 멘션해 작업 위임

대화 내용이 작업 배경으로 전달

PR 회신: 수정 결과를 PR 링크로 스레드에 회신

7.2. 예약 실행 2가지 방법

로컬 파일이 필요하면 Desktop 예약, 머신이 꺼져도 돌아야 하면 Routines

Desktop Scheduled Tasks
- 내 머신에서 실행
- 로컬 파일과 도구 직접 접근
- 머신이 켜져 있어야 동작
- 예) 아침 코드리뷰, 야간 감사 등
Routines(claude.ai)
- Anthropic 관리 인프라에서 실행
- 머신 꺼져도 스케쥴 유지
- /schedule 로 CLI 에서도 생성
- 예) API 호출과 GitHub 이벤트 트리거

8. Claude.md & Memory

8.1. 메모리 시스템

메모리는 내가 쓰는 것 + Claude 가 쓰는 것 2가지 존재

둘 다 매 세션 시작시 로드

지시와 규칙은 CLAUDE.md에 Claude 가 발견한 학습은 Auto Memory 에 적재

Claude.md
- 사용자 작성
- 코딩 표준, 워크플로, 아키텍처 지시
- 프로젝트, 사용자, 조직 스코프
- 버전 관리로 팀과 공유
- 지시가 반복될 경우 여기에 기록
Auto Memory
- Claude 작성
- 빌드 명령, 디버깅 인사이트 자동 축적
- 저장소 단위, 워크트리 간 공유
- 매 세션 첫 200줄 또는 25KB 로드
- 교정할수록 알아서 똑똑해짐

메모리 계층 구조

Managed : 조직 정책
User : 사용자 로컬 PC 전역에 설정, 모든 프로젝트에 적용 (~/.claude/CLAUDE.md)
Project : 프로젝트(레포)별 설정, 버전 관리로 팀 공유 (./CLAUDE.md 또는 ./.claude/CLAUDE.md)
Local : 프로젝트별 설정, 팀에 공유하지 않고 내가 작업하기 편하게 만든 규칙. .gitignore 등록 대상 (./CLAUDE.local.md)

로딩 순서 및 병합

Project → User → Managed → Local

CLAUDE.md 작성 베스트 프랙티스

메모리는 강제 설정이 아닌 컨텍스트

짧게 - 사이즈 200줄 이하

구조적 - 헤더와 불릿을 통한 스캔 가능한 구조, 밀집 문단 지양

구체적 - 검증 가능. 2칸 들여쓰기처럼 확인 가능한 표현 사용

일관성 - 모순 제거, 상충 규칙은 임의 선택 유발

안티 패턴

- 소설 같은 장문 서사 → 명령과 규칙 중심의 간결한 목록

- 프로젝트와 무관한 일반 상식 → 이 저장소 고유의 사실만

- 비밀값과 자격증명 기록 → 비밀은 볼트, 경로만 언급

- 매 세션 불필요한 절차 문서 전체 → 다단계 절차는 Skill 로 분리

- 모순되는 규칙 방지 → 분기별 메모리 정리 루틴

모노레포 예시

루트는 얇게, 패키지별 온디맨드 로드

repo/
  CLAUDE.md       # 전역: 워크스페이스 명령, 공통 규칙
  .claude/rules/  # paths 스코프 규칙
  packages/
    web/CLAUDE.md # web 작업 시 온디맨드 로드
    api/CLAUDE.md # api 전용 컨벤션

# 다른 팀 파일 제외 (settings.json)
{ "claudeMdExcludes": ["packages/legacy/**"] }
# 루트는 얇게, 상세는 패키지와 rules로

9. Workflow Patterns

9.1. 반복 가능한 실무 패턴

Explore-Plan-Code(EPC)

탐색으로 이해 → 계획으로 방향 합의 → 코드 실행

Explore
- 관련 코드 읽기
- 흐름 추적
Plan
- 접근 설계
- 계획 협상 및 승인
Code
- 승인된 계획대로 구현
- 테스트 검증

TDD Workflow

실패하는 테스트가 곧 명세

최소 구현 원칙 - 과설계 방지

Code Review

/code-review            # 현재 diff 리뷰
/code-review high       # 노력 수준 지정
/code-review --fix      # 발견 사항 자동 수정
/code-review --comment  # PR 인라인 코멘트 게시
/code-review ultra      # 클라우드 멀티에이전트 심층

/simplify               # 버그 탐색 없이 정리만
/security-review        # 보안 관점 읽기 전용 검사

# 머지 전 로컬 게이트로 습관화

Multi-Agent

큰 변경을 병렬 단위 실행

/batch 분할 실행

Visual Workflow

스크린샷이 곧 명세

코드 결과와 디자인 시안 대조하여 수정

Chrome 을 통한 검증

Headless 자동화

-p 플래그로 스크립트 편입

Pipeline 과 JSON

구조화 출력으로 후처리

CI 통합

키는 시크릿으로 주입

읽기 위주 작업

Routines 예약 실행

머신이 꺼져도 실행되는 자동화

/goal 지속 실행

조건이 참이 될 때까지 지속적 실행

9.2. 비용 관리 전략

모델, 컨텍스트, 캐시 3축 (/usage 분해 뷰로 소비처를 찾고 조정)

모델
- 작업별 모델 분리
- 난제: opus
- 일상: sonnet
- 배치: haiku
컨텍스트
- 최대한 가볍게 유지
- clear, compact, 경로 스코프 rule 을 통한 윈도우 최소화
캐시
- 잦은 모델 전환과 세션 중 CLAUDE.md 수정은 캐시 미스 유발

컨텍스트 관리 전략

작업 경계마다 정리하는 습관이 긴 세션의 품질 향상

/clear - 작업 전환

/compact - 같은 작업 지속

/btw - 곁가지 질문

서브에이전트 - 탐색 위임

/context - 상태 점검

토큰 효율 베스트 프랙티스

경로 지목
- 저장소 전체 탐색 대신 관련 경로를 직접 지목
출력 형식 지정
- 표로, 다섯 줄로 등 출력 길이를 명시적으로 통제
MCP 다이어트
- 안쓰는 서버 해제
메모리 다이어트
- CLAUDE.md 200 줄 유지
rules 경로 스코프 분리