Claude Code 활용 가이드

채팅형 AI와 다른 점

브라우저의 채팅형 AI는 대화창 안에 갇혀 있다. Claude Code는 내 컴퓨터에서 직접 일하는 에이전트라서, 도움을 청하는 상대가 아니라 실제로 실행하는 팀원에 가깝다.

동작 원리: 도구 사용

LLM 자체는 파일을 읽거나 명령을 실행할 수 없다. 「파일을 읽어 줘」라고만 하면 「읽을 수 없습니다」가 돌아온다. 코딩 어시스턴트는 그 사이에서 도구 사용(tool use) 루프를 돌린다.

flowchart TB
  task["작업 받기(#quot;이 에러를 고쳐 줘#quot;)"]
  ctx["맥락 모으기: 모델이 정해진 형식으로 #quot;이 파일을 읽어 달라#quot;고 요청<br/>→ 어시스턴트가 읽어서 내용을 돌려줌"]
  plan["계획 세우기"]
  run["실행: 파일 수정·명령 실행도 같은 방식으로 요청<br/>→ 어시스턴트가 수행하고 결과를 돌려줌"]
  next["결과를 보고 다음 행동 결정"]
  task --> ctx --> plan --> run --> next
  next -->|"반복"| ctx

Claude Code의 기본 도구는 파일 읽기·편집, 셸 명령, 검색 정도다. 모델이 이 도구들을 엮어 처음 보는 도구도 쓰고 복잡한 작업을 처리한다. 새 도구(MCP)를 붙이면 그것도 알아서 쓴다. 코드를 미리 색인해 외부 서버로 올리지 않고 그때그때 탐색하므로 코드베이스 전체를 보내지 않아도 된다.

설치와 준비물

터미널에서 네이티브 설치 스크립트를 실행한다. 네이티브 설치는 백그라운드에서 자동 업데이트된다.

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
 
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
 
# 패키지 관리자 (자동 업데이트 안 됨)
brew install --cask claude-code        # macOS
winget install Anthropic.ClaudeCode    # Windows
 
# 프로젝트 폴더로 이동해 실행, 처음 한 번 브라우저로 로그인
cd ~/your-project-folder
claude

• OS: macOS 13+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+. RAM 4GB 이상.
• Windows: PowerShell·CMD에서 바로 설치된다. Git for Windows가 있으면 Git Bash로 셸 명령을 돌리고, 없으면 PowerShell을 쓴다. 샌드박스가 필요하면 WSL 2에 설치한다.
• 계정: Pro·Max·Ultra·Team·Enterprise 구독 또는 Console(API) 계정. 무료 플랜에는 포함되지 않는다.
• 터미널이 낯설면 데스크톱 앱이나 VS Code·JetBrains 확장으로도 같은 에이전트를 쓴다.

처음 켰을 때 해 두면 편한 설정이 있다.

익숙해지는 순서

Claude Code는 빈 입력창 하나만 보여 주는 범용 도구라 무엇부터 할지 막막하기 쉽다. 정해진 워크플로를 강제하지 않기 때문이다. 다음 순서로 범위를 넓히면 무엇을 한 번에 맡길 수 있고 무엇은 옆에서 이끌어야 하는지 감이 생긴다.

flowchart LR
  a["코드베이스 질문"] --> b["코드 편집"] --> c["팀 도구 연결"] --> d["맥락 쌓기(CLAUDE.md)"] --> e["자동화·병렬 실행"]

1. 코드베이스에 질문하기

처음에는 코드를 고치게 하지 말고 질문만 한다. 새 코드베이스 온보딩에 특히 효과가 크다. 동료에게 묻고 코드를 뒤지던 시간이 크게 준다.

• 「이 클래스는 어디서 어떻게 생성되나」: 단순 텍스트 검색이 아니라 실제 사용 예를 찾아 문서처럼 답한다.
• 「이 함수는 왜 인자가 15개고 이름이 이상한가」: git 기록을 따라가 누가 어떤 이슈 때문에 넣었는지 요약한다. 시스템 프롬프트에 git 사용법이 있어서가 아니라 모델이 git을 알기 때문이다.
• 「이번 주에 내가 뭘 배포했지」: 로그에서 내 커밋을 모아 주간 회의 보고 초안을 만든다.

코드는 색인하지 않는다. 원격 DB에 코드를 올리지 않고 로컬에서 그때그때 탐색하므로, 색인을 기다릴 필요 없이 설치하자마자 쓴다.

2. 코드 편집하기

Claude Code가 가진 도구는 파일 편집, 셸 명령, 파일 검색 정도로 적다. 「이걸 해 줘」라고만 하면 도구를 알아서 엮어 탐색 → 구상 → 편집한다.

• 큰 작업은 먼저 계획을 받는다. 거대한 기능을 한 번에 시키면 원하던 것과 다른 결과가 나오기 쉽다. 「코드를 쓰기 전에 계획을 세워서 승인을 받아라」 한마디면 된다. 계획 모드를 써도 되지만 말로 시켜도 충분하다.
• 「commit, push, PR」 한 줄이면 git log에서 커밋 형식을 읽고 브랜치·커밋·PR까지 만든다.

3. 결과를 확인할 수단을 준다

Claude가 스스로 결과를 볼 수 있으면 반복해서 고친다. 단위 테스트, 브라우저 스크린샷(Puppeteer·Playwright MCP), iOS 시뮬레이터 스크린샷이 그 수단이다. 시안 이미지를 주고 웹 UI를 만들게 하면 첫 결과는 꽤 비슷한 정도지만, 스크린샷을 보며 두세 번 반복하게 하면 거의 똑같아진다. 이미지는 드래그 앤 드롭, 붙여넣기, 파일 경로 중 무엇으로 줘도 된다.

4. 팀 도구를 알려 준다

팀이 쓰는 CLI는 「--help로 사용법을 보고 이 CLI로 해라」라고 알려 주면 쓴다. 자주 쓰면 CLAUDE.md에 적어 세션마다 기억하게 한다. MCP 도구도 같다. 새 코드베이스에서 팀의 도구를 전부 쥐여 주면 Claude가 대신 쓴다.

필수 명령어

긴 지시문 대신 명령 하나로 정확하게 제어한다. /만 입력하면 쓸 수 있는 명령과 스킬 목록이 뜬다.

슬래시 명령

설치 문제는 터미널에서 claude doctor로 진단한다.

파일 참조와 단축키

Esc는 언제 눌러도 세션을 망가뜨리지 않는다. 20줄 수정안 중 한 줄만 마음에 안 들면 Esc로 멈추고 그 한 줄만 말한 뒤 다시 하게 한다. 방향이 맞다고 확신이 서면 Shift+Tab으로 편집 자동 수락 모드에 두고, 셸 명령만 승인한다. !로 실행한 명령과 출력은 맥락에 들어가 Claude가 다음 턴에 본다.

MCP로 도구 연결하기

MCP(Model Context Protocol) 는 AI를 외부 도구와 잇는 개방형 표준이다. "AI용 USB-C"처럼 프로토콜 하나로 개발(GitHub, Sentry, Linear), 생산성(Notion, Slack, Jira·Confluence), 데이터(PostgreSQL, 웹 검색), 커뮤니케이션(Gmail, Google Calendar) 도구에 연결한다.

# 예: Notion을 HTTP MCP 서버로 추가
claude mcp add --transport http notion https://mcp.notion.com/mcp

추가한 뒤 /mcp로 연결 상태를 확인한다. MCP 도구는 처음 쓸 때마다 권한을 묻는다. 늘 허용할 서버는 설정 파일의 허용 목록에 mcp__서버이름 형식으로 넣는다(밑줄이 두 개다).

claude mcp add playwright npx @playwright/mcp@latest

// .claude/settings.local.json
{ "permissions": { "allow": ["mcp__playwright"] } }

브라우저 도구를 붙이면 확인 수단과 프롬프트 개선을 한 번에 엮을 수 있다. 「localhost:3000을 열어 컴포넌트를 하나 만들어 보고, 스타일을 검토한 뒤, 앞으로 더 나은 컴포넌트가 나오도록 @src/lib/prompts/generation.tsx의 생성 프롬프트를 고쳐라」.

프런트엔드 작업이라면 Chrome DevTools MCP를 붙여 Claude Code가 실제 브라우저를 열고 성능 트레이스·Lighthouse·콘솔로 결과를 직접 확인하게 할 수 있다. 설치와 플래그는 DevTools의 AI 지원과 에이전트용 DevTools(MCP)에 있다.

Skills와 CLAUDE.md

Skills: 재사용하는 자동화

스킬은 작업별 지시를 묶은 패키지로, 관련 작업이 오면 Claude가 알아서 불러 쓰고 /스킬이름으로 직접 부를 수도 있다. 폴더 하나에 SKILL.md 하나가 기본 단위이고, 예전의 커스텀 슬래시 명령(.claude/commands/)도 스킬로 합쳐졌다.

~/.claude/skills/          ← 내 모든 프로젝트
.claude/skills/            ← 이 저장소 (팀과 공유)
├── prd-generator/
│   └── SKILL.md
└── data-cleaner/
    ├── SKILL.md
    └── scripts/clean.py

스킬에 인자를 받으려면 본문에 $ARGUMENTS를 쓴다. 예를 들어 테스트 작성 규칙을 .claude/skills/write-tests/SKILL.md에 두면 /write-tests hooks 폴더의 use-auth.ts처럼 부른다. 새로 만든 스킬이 바로 안 보이면 세션을 다시 시작한다.

Write comprehensive tests for: $ARGUMENTS
 
Testing conventions:
- Use Vitest with React Testing Library
- Place test files in a __tests__ directory next to the source file
- Name test files as [filename].test.ts(x)
 
Coverage: happy paths, edge cases, error states

Claude Code에는 /loop(주기 실행), /batch(대규모 병렬 변경), /simplify, /code-review 같은 번들 스킬이 들어 있다. claude.ai와 API에서는 Anthropic이 만든 문서 스킬(Word docx, 스프레드시트 xlsx, 프레젠테이션 pptx, pdf)을 쓸 수 있다. 스킬을 직접 만드는 방법은 Claude 스킬 만들기 가이드에 따로 정리했다.

CLAUDE.md: 프로젝트 메모리

매 세션 처음에 읽히는 마크다운 파일이라, 한 번 적어 두면 같은 설명을 반복할 필요가 없다. /init으로 초안을 만들고, 200줄 안쪽으로 유지한다.

## Key Commands
- npm run build / npm test
 
## Style Guide
- Use TypeScript, follow existing patterns
 
## Important Context
- Deploy target: Vercel

CLAUDE.md에는 자주 쓰는 셸 명령, MCP 도구, 아키텍처 결정, 핵심 파일처럼 이 코드베이스에서 일하려면 알아야 할 것만 짧게 둔다. 길어지면 맥락만 차지하고 효과는 적다. 하위 폴더에 둔 CLAUDE.md는 Claude가 그 폴더에서 일할 때 필요할 때만 읽힌다. 어떤 메모리 파일이 읽히고 있는지는 /memory로 보고 고친다.

CLAUDE.md는 사람이 쓰는 지시이고, 자동 메모리는 Claude가 내 교정과 선호를 스스로 적어 두는 노트다(~/.claude/projects/<프로젝트>/memory/MEMORY.md). 저장소에 AGENTS.md만 있으면 그것을 대신 읽는다.

팀과 설정 공유하기

설정은 CLAUDE.md만이 아니라 권한, MCP 서버, 스킬까지 같은 계층으로 나뉜다.

무엇부터 할지 모르겠으면 프로젝트 공유 설정부터 만든다. 한 사람이 한 번 다듬으면 팀 전원이 덕을 보는 네트워크 효과가 생긴다. 예를 들어 브라우저 MCP 서버를 .mcp.json으로 커밋해 두면 누구든 따로 설치하지 않고 E2E 테스트와 스크린샷 반복을 쓴다. 맥락 문서는 누구를 위한 것인지(매번 읽힐지, 필요할 때만 읽힐지, 팀 공유인지 개인 선호인지)를 따져 배치하고, 시간을 들여 다듬을수록 성능이 크게 오른다.

자동화: claude -p

-p(print) 플래그를 붙이면 대화 없이 한 번 실행하고 끝나는 똑똑한 유닉스 유틸리티가 된다. Claude Code 자체가 쓰는 것과 같은 엔진(Agent SDK)이고, Python·TypeScript 패키지로도 쓸 수 있다.

# 빌드 로그를 파이프로 넣고 원인 설명을 파일로
cat build-error.txt | claude -p "이 빌드 오류의 근본 원인을 짧게 설명해" > output.txt
 
# 허용 도구를 지정해 무인 실행, JSON으로 받아 jq로 꺼내기
claude -p "테스트를 돌리고 실패를 고쳐" --allowedTools "Bash,Read,Edit" --output-format json | jq -r '.result'

CI, 장애 대응, 대용량 로그 분석(클라우드 버킷의 로그나 Sentry CLI 출력을 파이프로 넣기), 이슈 자동 분류(슬래시 명령 하나를 GitHub Actions에서 -p로 돌려 라벨 붙이기)에 쓴다. CI처럼 어디서 돌려도 같은 결과가 필요하면 --bare로 개인 훅·플러그인·CLAUDE.md를 읽지 않게 한다.

GitHub Actions 연동

/install-github-app을 실행하면 GitHub에 Claude 앱을 설치하고, API 키를 저장소 시크릿에 등록하고, 워크플로 파일을 담은 PR을 만든다.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "서버는 localhost:3000에서 이미 돌고 있고 로그는 logs.txt에 쌓인다. DB는 sqlite3 CLI로 조회한다. 필요하면 mcp__playwright 도구로 브라우저를 띄워 앱을 확인한다."
      --mcp-config .github/mcp.json
      --allowedTools "Bash(npm *),Bash(sqlite3 *),mcp__playwright__browser_snapshot,mcp__playwright__browser_click"

v1부터는 Claude Code CLI 인자를 claude_args 하나로 넘긴다. 베타 시절의 custom_instructions·mcp_config·allowed_tools 같은 개별 입력은 --append-system-prompt·--mcp-config·--allowedTools로 옮겨졌다. 전체 입력 목록은 GitHub Actions 문서에서 확인한다.

훅: 반드시 지킬 규칙

CLAUDE.md의 지시는 모델이 잊을 수 있다. 수정 후 포맷터·타입 검사, 민감 파일 차단처럼 반드시 실행돼야 하는 규칙은 도구 호출 앞뒤에 자동 실행되는 훅으로 건다. 이벤트·종료 코드·예제는 Claude Code 훅에 따로 정리했다.

프롬프트 기법

구체적인 지시, 예시, 단계 연결, 제약, 역할 부여 같은 일반 원칙은 어떤 모델에나 같다. 프롬프트 작성법 치트시트에 정리해 두었고, 여기서는 Claude Code에서만 통하는 것만 적는다.

계획 모드와 추론 강도: 넓이와 깊이

둘 다 토큰을 더 쓴다. 지금의 모델은 단계마다 생각할지 말지를 스스로 정하는 적응형 추론이라, 강도는 생각을 얼마나 자주·깊게 할지의 기준을 바꾼다.

• 과거에는 think < think hard < think harder < ultrathink처럼 프롬프트의 키워드로 생각 예산을 정했다. 지금은 ultrathink만 키워드로 인식하고, 나머지 표현은 그냥 프롬프트 문장으로 전달된다.

맥락이 흐트러졌을 때

작업 A를 하위 작업 a·b·c·d로 나눠 진행하는 중이라고 하자.

에이전트에게 맡길 때 결과를 일관되게 만드는 방법은 디자인 시스템을 아는 화면 생성 에이전트 설계하기, 반복 작업을 루프로 돌리는 방법은 루프 엔지니어링에서 더 깊이 다뤘다.

개발 팀장처럼 위임하기

Claude Code를 잘 쓰면 개발자의 자리는 코드를 치는 사람에서 결과를 정의하고 맡기는 엔지니어링 매니저·테크 리드로 옮겨 간다. 파일과 함수 단위로 생각하지 않고, 만들 기능의 스펙과 원하는 결과로 생각한다. 직접 세부를 챙기는 마이크로매니저 자리에서 물러나되, 코드 리뷰와 테스트라는 견제 장치는 유지한다.

자주 보이는 실패와 대처는 이렇다.

주니어 개발자에게는 지치지 않는 멘토로도 쓸 수 있다. 내 코드 리뷰, 언어·방식 간 비교, 흔한 함정 설명을 부탁한다. 처음 쓸 때는 연습용이 아니라 실제 프로젝트에 적용해 보는 편이 빨리 감을 잡는다. 이 위임 방식을 실무 팀에 적용한 예는 AI 네이티브 프론트엔드 개발에 있다.

왜 터미널인가

터미널은 편집기가 제각각인 사람들의 공통분모이고, 모델이 빠르게 좋아지는 동안 곧 낡을 UI 계층에 묶이지 않는다. 그래서 어떤 IDE, 원격 SSH, tmux 안에서도 같은 방식으로 돌아간다. 같은 에이전트를 IDE 확장과 데스크톱·웹 앱으로도 쓴다.

터미널 에이전트의 핵심 난제는 셸 명령의 안전성이다. 명령마다 승인을 받으면 일이 안 되므로, 읽기 전용 명령을 구분하고, 정적 분석으로 안전하게 조합되는 명령을 가려내고, 여러 계층에서 허용·차단 목록을 두는 권한 체계로 푼다.

권한 모드

권한 모드는 무엇을 묻지 않고 실행할지를 정한다. Shift+Tab으로 돌아가며 바꾸고, 시작할 때는 --permission-mode <값>으로 고른다. 허용·거부 규칙(/permissions)은 어느 모드 위에나 겹쳐 적용되고, 거부 규칙은 모든 모드에서 이긴다.

자동 모드(auto mode) 는 「매번 승인」과 「전부 허용」 사이의 절충이다. 별도의 분류기 모델이 도구 호출을 실행 전에 보고, 요청 범위를 넘어서는 행동, 모르는 인프라를 건드리는 행동, 읽은 파일·웹 페이지의 적대적 내용에 끌려간 듯한 행동을 막는다.

• 분류기는 사용자 메시지, 읽기 전용이 아닌 도구 호출, CLAUDE.md만 본다. 도구 결과는 빼고 보므로 파일이나 웹 페이지에 심은 지시가 분류기를 직접 속이기 어렵다.
• 자동 모드에 들어가면 Bash(*)처럼 임의 코드 실행을 통째로 허용하는 넓은 규칙은 잠시 꺼지고, Bash(npm test) 같은 좁은 규칙만 남는다.
• 막히면 Claude는 이유를 받고 다른 방법을 찾는다. 연속 3번 또는 누적 20번 막히면 자동 모드를 멈추고 다시 사람에게 묻는다.
• 대화에서 「푸시하지 마」, 「내 리뷰 기다려」처럼 경계를 말하면 그 경계를 지킨다. 「force push 해도 돼」 같은 모호한 허락보다 브랜치 이름까지 짚은 구체적 승인만 차단을 푼다.
• 분류기도 틀린다. 의도가 모호하거나 환경 맥락이 부족하면 위험한 행동을 통과시키거나 무해한 행동을 막을 수 있고, 검사만큼 토큰·지연이 더 든다. 중요한 환경에서는 격리된 곳에서 돌린다.
• 조직 관리자는 관리 설정의 permissions.disableAutoMode: "disable"로 끌 수 있다.

요금제

구독(Pro·Max·Ultra·Team·Enterprise)으로 쓰거나, CI/CD·파이프라인처럼 자동화 용도면 API 사용량 과금으로 쓴다. Amazon Bedrock·Google Cloud Gemini Enterprise Agent Platform(구 Vertex AI)·Microsoft Foundry를 통해서도 쓸 수 있다. 플랜별 요금과 한도는 자주 바뀌므로 공식 요금 안내에서 확인하고, 세션 안에서는 /usage로 사용량을 본다.

관련 노트: Claude Code 훅, AI 코딩 실무 가드레일, 프롬프트 작성법 치트시트, Claude 스킬 만들기 가이드, AI로 개발 가속하기: 규칙을 키우는 개발, AI에게 일 맡기기: 권한·정보·도구