터미널에 claude 한 줄만 치면, AI가 내 코드를 직접 읽고 고치고 테스트까지 돌린다. 이 글 하나로 설치, 첫 실행, 명령어, 실전 워크플로우, 자동화까지 전부 끝냅니다.

처음 클로드 코드를 켰을 때 가장 당황스러운 건 채팅창이 아니라 그냥 검은 터미널이라는 점입니다. 코드를 복사해서 붙여넣는 곳이 없습니다. 대신 "로그인 버그 고쳐줘"라고 치면 알아서 파일을 뒤지고, 원인을 찾고, 코드를 고치고, 테스트를 돌립니다.

이 차이를 이해하는 순간부터 생산성이 완전히 달라집니다. 아래 순서대로만 따라오시면 됩니다.

1. 클로드 코드란 무엇인가

클로드 코드는 Anthropic이 만든 에이전틱 코딩 도구(agentic coding tool) 입니다. 질문에 답만 하고 기다리는 챗봇이 아니라, 내 파일을 읽고, 명령을 실행하고, 코드를 수정하며 스스로 문제를 풀어나갑니다.

기존 AI 코딩 도구와의 차이는 한 문장으로 정리됩니다.

코드 전달

일반 AI 챗봇: 내가 복사해서 붙여넣음

클로드 코드: 알아서 파일을 찾아 읽음

수정 방식

일반 AI 챗봇: 답변을 내가 다시 붙여넣음

클로드 코드: 직접 파일을 편집

검증

일반 AI 챗봇: 내가 직접 실행

클로드 코드: 테스트·빌드를 스스로 돌림

반복

일반 AI 챗봇: 매번 내가 다시 요청

클로드 코드: 실패하면 스스로 재시도

핵심은 "검증 루프를 닫아주는 것" 입니다. 테스트나 빌드처럼 통과/실패가 명확한 기준을 쥐여주면, 클로드가 알아서 될 때까지 반복합니다. 이 기준이 없으면 클로드는 "다 된 것 같다"에서 멈추고, 검증은 결국 사람 몫이 됩니다.

어디서 쓸 수 있나

터미널 CLI가 기본이지만, 그것만 있는 게 아닙니다.

1. 터미널 CLI — 가장 기본이자 기능이 가장 완전한 형태
2. 데스크톱 앱 — 여러 세션을 시각적으로 병렬 관리
3. VS Code / JetBrains 확장 — 인라인 diff, @ 파일 참조
4. 웹 (claude.ai/code) — 로컬 설치 없이 GitHub 저장소 연결
5. 모바일 앱 — 이동 중에 작업 지시·모니터링
6. CI/CD — GitHub Actions, GitLab CI 연동

이 글은 터미널 CLI 기준으로 설명합니다. 여기서 배운 개념은 나머지 환경에도 그대로 적용됩니다.

2. 설치하기

방법 1. 네이티브 설치 (권장)

가장 간단하고, 백그라운드에서 자동 업데이트까지 됩니다. Node.js나 Docker 같은 사전 준비물이 필요 없습니다.

macOS / Linux / WSL — 터미널(bash, zsh)에서:

curl -fsSL https://claude.ai/install.sh | bash

Windows — PowerShell에서:

irm https://claude.ai/install.ps1 | iex

Windows — CMD(명령 프롬프트)에서:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

PowerShell과 CMD를 헷갈릴 때 구분법 프롬프트가 PS C:\ 로 시작하면 PowerShell, C:\ 로만 시작하면 CMD입니다.

1. The token '&&' is not a valid statement separator 오류 → 지금 PowerShell에 CMD용 명령을 넣은 것
2. 'irm' is not recognized... 오류 → 지금 CMD에 PowerShell용 명령을 넣은 것

방법 2. 패키지 매니저

macOS (Homebrew):

brew install --cask claude-code

claude-code는 안정 채널(약 1주 늦게 반영되고 큰 회귀가 있는 릴리스는 건너뜀), claude-code@latest는 최신 채널입니다. 다만 Homebrew 설치는 자동 업데이트가 안 되므로 주기적으로 직접 올려야 합니다.

brew upgrade claude-code

Windows (WinGet):

winget install Anthropic.ClaudeCode

WinGet도 자동 업데이트가 없습니다.

winget upgrade Anthropic.ClaudeCode

Linux 배포판 패키지 매니저: Debian/Ubuntu는 apt, Fedora/RHEL은 dnf, Alpine은 apk로도 설치할 수 있습니다.

설치 확인

모든 환경 공통:

claude --version

버전 번호 뒤에 (Claude Code)가 출력되면 성공입니다.

Windows 네이티브 환경 팁 Git for Windows를 함께 설치하는 걸 권장합니다. 있으면 클로드가 Bash 툴을 쓰고, 없으면 PowerShell을 셸로 사용합니다. WSL 환경이라면 따로 설치할 필요 없습니다.

3. 로그인과 요금제

설치했다고 바로 쓸 수 있는 건 아닙니다. 계정이 필요합니다.

모든 환경 공통 — 아무 폴더에서나:

claude

처음 실행하면 브라우저가 열리면서 로그인을 요구합니다. 한 번 로그인하면 자격 증명이 저장되어 다시 묻지 않습니다.

세션 안에서 계정을 바꾸거나 재인증하려면:

/login

사용 가능한 계정 종류

Claude 구독 (Pro / Max / Team / Enterprise)

설명: 가장 무난한 선택. 정액제

Claude Console

설명: API 크레딧 선불 방식. 첫 로그인 시 "Claude Code" 워크스페이스가 자동 생성되어 비용 추적 가능

클라우드 제공자

설명: Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry

자체 게이트웨이

설명: 조직이 운영하는 경우 SSO로 로그인

⚠️ 무료 플랜으로는 클로드 코드를 쓸 수 없습니다. 유료 구독이나 Console 크레딧이 필요합니다.

4. 첫 세션 5분 실습

터미널에서 작업할 프로젝트 폴더로 이동한 뒤 실행합니다.

모든 환경 공통:

cd /경로/내프로젝트 claude

버전, 현재 모델, 작업 디렉터리가 표시되고 프롬프트가 뜹니다. 이제 영어로 안 써도 됩니다. 한국어로 그냥 말하듯이 치면 됩니다.

1단계 — 코드베이스 파악하기

이 프로젝트가 뭐 하는 프로젝트인지 설명해줘 이 프로젝트는 어떤 기술 스택을 쓰고 있어? 메인 진입점(entry point)이 어디야? 폴더 구조를 설명해줘

파일을 직접 첨부할 필요가 없습니다. 클로드가 필요한 파일을 알아서 찾아 읽습니다. 이게 일반 챗봇과의 가장 큰 차이입니다.

2단계 — 첫 코드 수정

메인 파일에 hello world 함수 하나 추가해줘

클로드가 적절한 파일을 찾아 변경 내용을 보여줍니다. 설치 후 첫 세션에서는 변경할 때마다 물어봅니다. Yes를 선택하면 적용됩니다.

3단계 — Git도 말로

내가 뭘 바꿨는지 보여줘 설명이 담긴 메시지로 커밋해줘 feature/quickstart 라는 새 브랜치 만들어줘 최근 커밋 5개 보여줘 머지 충돌 해결하는 것 좀 도와줘

4단계 — 실제 작업 시켜보기

회원가입 폼에 입력값 검증 로직 추가해줘 빈 폼도 제출되는 버그가 있어. 고쳐줘

이때 클로드는 관련 코드를 찾고 → 맥락을 파악하고 → 구현하고 → 테스트가 있으면 실행합니다.

5. 필수 명령어 정리

명령어는 두 종류입니다. 셸 명령어는 터미널에서 클로드를 시작할 때, 세션 명령어는 클로드 실행 중에 씁니다.

셸 명령어 (터미널에서 입력)

claude

하는 일: 대화형 모드 시작

claude "작업 내용"

하는 일: 첫 프롬프트를 넣은 채로 시작

claude -p "질문"

하는 일: 한 번만 실행하고 종료 (스크립트용)

claude -c

하는 일: 현재 폴더의 최근 대화 이어서 진행

claude -r

하는 일: 이전 대화 목록에서 골라 재개

claude --permission-mode plan

하는 일: 플랜 모드로 시작

세션 명령어 (클로드 실행 중 입력)

/help

하는 일: 사용 가능한 명령어 목록

/clear

하는 일: 대화 기록 초기화 (가장 자주 쓰게 됨)

/compact

하는 일: 대화를 요약해서 압축

/rewind

하는 일: 이전 시점으로 되돌리기

/init

하는 일: 프로젝트에 맞는 CLAUDE.md 초안 생성

/context

하는 일: 지금 컨텍스트에 뭐가 올라와 있는지 확인

/permissions

하는 일: 도구별 권한 설정

/mcp

하는 일: MCP 서버 연결 상태 확인

/hooks

하는 일: 등록된 훅 확인

/doctor

하는 일: 설정 전반 점검

/resume

하는 일: 이전 대화 이어서 하기

/exit

하는 일: 종료 (또는 Ctrl+D 두 번)

알아두면 편한 단축키

/

기능: 사용 가능한 명령어·스킬 목록 열기

Tab

기능: 명령어 자동완성

↑

기능: 이전 명령 기록

Shift+Tab

기능: 권한 모드 순환 전환

Esc

기능: 클로드 작업 중단 (맥락은 유지)

Esc Esc

기능: 되돌리기 메뉴 열기

Ctrl+G

기능: 계획을 에디터에서 직접 수정

@

기능: 파일 참조 (예: @src/auth.js)

6. 결과가 달라지는 4단계 워크플로우

클로드 코드를 잘 쓰는 사람과 못 쓰는 사람의 차이는 딱 하나입니다. 바로 코딩을 시키느냐, 먼저 읽게 하느냐.

바로 코딩시키면 엉뚱한 문제를 정확하게 푸는 코드가 나옵니다.

1단계: 탐색 (Explore)

Shift+Tab을 눌러 상태 표시줄에 ⏸ plan mode on이 뜰 때까지 전환합니다. 플랜 모드에서는 읽기만 하고 파일을 수정하지 않습니다.

src/auth 폴더를 읽고 세션과 로그인을 어떻게 처리하는지 파악해줘. 환경변수로 시크릿을 어떻게 관리하는지도 같이 봐줘.

2단계: 계획 (Plan)

구글 OAuth를 추가하고 싶어. 어떤 파일들을 고쳐야 해? 세션 흐름은 어떻게 되고? 계획을 세워줘.

Ctrl+G를 누르면 계획을 텍스트 에디터에서 직접 열어 고칠 수 있습니다. 여기서 방향을 잡는 시간이 나중에 몇 배로 돌아옵니다.

3단계: 구현 (Implement)

계획을 승인하거나 Shift+Tab으로 플랜 모드를 빠져나옵니다.

네가 세운 계획대로 OAuth 흐름을 구현해줘. 콜백 핸들러 테스트도 작성하고, 테스트 스위트 돌려서 실패하는 건 고쳐줘.

4단계: 커밋 (Commit)

설명이 담긴 메시지로 커밋하고 PR 올려줘

플랜 모드를 건너뛰어야 할 때 오타 수정, 로그 한 줄 추가, 변수명 변경처럼 범위가 뻔한 일에는 오히려 방해가 됩니다. 판단 기준: diff를 한 문장으로 설명할 수 있으면 계획은 생략하세요.

7. 프롬프트 잘 쓰는 법

클로드는 의도를 추론할 수는 있어도 마음을 읽지는 못합니다. 아래 4가지 패턴만 익혀도 재작업이 확 줄어듭니다.

① 범위를 좁혀라

❌ foo.py 테스트 추가해줘

✅ foo.py에 대한 테스트를 작성해줘. 사용자가 로그아웃된 엣지 케이스를 커버하고, mock은 쓰지 마.

② 근거가 있는 곳을 알려줘라

❌ ExecutionFactory API가 왜 이렇게 이상해?

✅ ExecutionFactory의 git 히스토리를 훑어보고 이 API가 어떻게 이 모양이 됐는지 정리해줘

③ 기존 패턴을 가리켜라

❌ 달력 위젯 추가해줘

✅ 홈 화면의 기존 위젯 구현들을 먼저 보고 패턴을 파악해줘. HotDogWidget.php가 좋은 예시야. 같은 패턴으로 달력 위젯을 만들어줘. 이미 쓰고 있는 라이브러리 외에 새 라이브러리는 추가하지 마.

④ 증상 + 위치 + "고쳐진 상태"를 함께 줘라

❌ 로그인 버그 고쳐줘

✅ 세션 타임아웃 후에 로그인이 실패한다는 제보가 있어. src/auth/ 의 인증 흐름, 특히 토큰 갱신 부분을 확인해줘. 먼저 이 문제를 재현하는 실패 테스트를 작성한 다음에 고쳐줘.

검증 기준을 함께 주기

이게 가장 효과가 큽니다.

❌ 이메일 주소 검증 함수 구현해줘

✅ validateEmail 함수를 작성해줘. 테스트 케이스 예시: user@example.com은 true, invalid는 false, user@.com은 false. 구현 후 테스트를 실행해줘.

UI 작업이라면:

✅ [스크린샷 붙여넣기] 이 디자인대로 구현해줘. 결과를 스크린샷으로 찍어서 원본과 비교하고, 차이점을 나열한 다음 수정해줘.

자료를 풍부하게 주는 방법

1. @로 파일 참조 — @src/auth/token.js 처럼 쓰면 클로드가 먼저 읽고 답합니다
2. 이미지 붙여넣기 — 스크린샷을 프롬프트에 복사/드래그로 바로 넣을 수 있습니다
3. URL 제공 — 문서나 API 레퍼런스 주소를 그대로 주면 됩니다
4. 파이프로 데이터 전달 — cat error.log | claude
5. 클로드가 직접 가져오게 — "필요한 정보는 직접 찾아봐"라고 지시

큰 기능은 클로드가 나를 인터뷰하게 하기

기능이 클수록 이 방법이 잘 먹힙니다.

[기능 간단 설명]을 만들고 싶어. AskUserQuestion 툴을 써서 나를 자세히 인터뷰해줘.

기술 구현, UI/UX, 엣지 케이스, 우려되는 점, 트레이드오프에 대해 물어봐. 뻔한 질문 말고, 내가 미처 생각하지 못했을 어려운 부분을 파고들어줘.

전부 다룰 때까지 계속 인터뷰한 다음, 완성된 명세를 SPEC.md 파일로 작성해줘.

명세가 완성되면 새 세션을 열어서 실행하세요. 깨끗한 컨텍스트로 구현에만 집중할 수 있고, 참조할 문서도 손에 남습니다.

8. CLAUDE.md — 프로젝트 규칙 파일 만들기

CLAUDE.md는 매 대화 시작마다 클로드가 자동으로 읽는 특별한 파일입니다. 코드만 봐서는 알 수 없는 정보를 여기에 적어둡니다.

먼저 초안을 자동 생성합니다.

/init

그다음 다듬습니다. 형식은 자유지만 짧고 사람이 읽기 좋게 씁니다.

# 코드 스타일 - CommonJS(require) 말고 ES 모듈(import/export) 문법 사용 - import는 가능하면 구조분해 (예: import { foo } from 'bar')

# 워크플로우 - 코드 변경을 마치면 반드시 타입체크할 것 - 성능상 전체 테스트 말고 단일 테스트를 우선 실행할 것

무엇을 넣고 무엇을 빼야 하나

클로드가 추측할 수 없는 실행 명령어

❌ 빼야 할 것: 코드를 읽으면 알 수 있는 내용

기본값과 다른 코드 스타일 규칙

❌ 빼야 할 것: 언어의 표준 관례

테스트 방법, 선호하는 테스트 러너

❌ 빼야 할 것: 상세한 API 문서 (링크만 걸기)

브랜치 이름, PR 규칙

❌ 빼야 할 것: 자주 바뀌는 정보

프로젝트 고유의 아키텍처 결정

❌ 빼야 할 것: 긴 설명이나 튜토리얼

개발 환경 특이사항 (필수 환경변수 등)

❌ 빼야 할 것: 파일별 코드베이스 설명

자주 걸리는 함정, 직관에 반하는 동작

❌ 빼야 할 것: "깔끔하게 코드 짜기" 같은 뻔한 말

실전 관리 팁

길면 무시당합니다. 각 줄마다 이렇게 자문하세요. "이 줄을 지우면 클로드가 실수하게 되나?" 아니라면 지웁니다. CLAUDE.md가 비대해지면 정작 중요한 규칙이 소음에 묻힙니다.

1. 클로드가 규칙이 있는데도 계속 같은 실수를 한다면 → 파일이 너무 길어서 규칙이 묻힌 것
2. CLAUDE.md에 답이 있는데 클로드가 되묻는다면 → 표현이 모호한 것
3. 특정 지시 하나를 계속 건너뛴다면 → 그 줄에만 IMPORTANT 강조를 붙이기 (여러 줄에 붙이면 아무것도 강조되지 않음)
4. 200줄 이내를 목표로 유지하고, 넘치면 스킬이나 .claude/rules/로 분리
5. git에 커밋해서 팀 전체가 함께 다듬을 것

제대로 로드됐는지는 이렇게 확인합니다.

/context

체크인된 CLAUDE.md라면 /doctor를 실행하면 클로드가 "이 부분은 코드에서 알 수 있으니 지워도 된다"고 제안해줍니다.

9. 권한 모드 이해하기

Shift+Tab을 누를 때마다 권한 모드가 바뀝니다. 무슨 차이인지 알아둬야 합니다.

Auto (자동)

동작: 별도 분류 모델이 위험한 행동만 걸러내고, 나머지는 묻지 않고 진행

Manual (수동)

동작: 파일 쓰기, Bash 명령, MCP 툴 사용 전마다 승인 요청

Plan (플랜)

동작: 읽기만 하고 아무것도 수정하지 않음

Accept Edits

동작: 파일 편집은 자동 승인, 명령 실행은 확인

Pro·Max·Team 플랜의 대화형 터미널 세션은 첫 세션 이후 Auto 모드가 기본 시작 모드입니다. 그 외 플랜에서는 Manual이 기본입니다.

승인 지옥에서 벗어나기

Manual 모드는 안전하지만 열 번쯤 승인하다 보면 읽지 않고 누르게 됩니다. 두 가지로 줄일 수 있습니다.

① 신뢰하는 도구를 미리 허용:

/permissions

npm run lint, git commit 같은 안전한 명령을 화이트리스트에 등록합니다.

② 샌드박스 사용:

/sandbox

OS 수준에서 파일시스템·네트워크 접근을 제한한 안전한 울타리 안에서 클로드가 더 자유롭게 움직이게 합니다.

10. 컨텍스트 관리 — 가장 중요한 자원

이 섹션이 이 글에서 가장 실질적으로 도움이 되는 부분입니다.

클로드의 컨텍스트 윈도우에는 대화 전체가 들어갑니다. 모든 메시지, 읽은 모든 파일, 실행한 모든 명령의 출력까지. 디버깅 세션 한 번, 코드베이스 탐색 한 번이면 수만 토큰이 순식간에 찹니다.

문제는 컨텍스트가 찰수록 성능이 떨어진다는 것입니다. 앞서 준 지시를 "잊어버리고" 실수가 늘어납니다.

실전 관리법

① 작업이 바뀌면 무조건 /clear

/clear

서로 관계없는 작업을 한 세션에서 이어가지 마세요. 가장 흔하고 가장 치명적인 실수입니다.

② 두 번 고쳐줬는데도 안 되면 /clear 후 다시 시작

같은 문제로 세 번째 지적하고 있다면, 컨텍스트는 이미 실패한 시도들로 오염된 상태입니다. 깨끗한 세션 + 배운 걸 반영한 더 구체적인 프롬프트가 긴 세션보다 거의 항상 낫습니다.

③ 압축은 지시와 함께

/compact API 변경사항 위주로 정리해줘

④ 되돌리기 활용

Esc를 두 번 누르거나 /rewind로 이전 시점으로 돌아갑니다. 대화만, 코드만, 또는 둘 다 복원할 수 있습니다.

/rewind

덕분에 "일단 과감하게 시도해보고 아니면 되돌리는" 작업 방식이 가능해집니다. 체크포인트는 대화와 함께 저장되므로 터미널을 껐다 켜고 나중에 재개해도 되돌릴 수 있습니다.

⚠️ 체크포인트는 클로드의 파일 편집 도구를 통한 변경만 추적합니다. Bash 명령이나 외부 프로세스로 생긴 변경은 포함되지 않습니다. git을 대체하지 못합니다.

⑤ 조사는 서브에이전트에게 시키기

서브에이전트를 써서 우리 인증 시스템이 토큰 갱신을 어떻게 처리하는지, 재사용할 만한 기존 OAuth 유틸리티가 있는지 조사해줘

서브에이전트는 별도의 컨텍스트 윈도우에서 수십 개 파일을 읽고 요약만 돌려줍니다. 내 대화창은 깨끗하게 유지됩니다.

⑥ 잠깐 궁금한 건 /btw

/btw 이 라이브러리 최신 버전이 뭐야?

답변이 대화 기록에 남지 않아서 컨텍스트를 늘리지 않습니다.

⑦ 세션에 이름 붙이고 브랜치처럼 쓰기

/rename oauth-migration

나중에 이렇게 이어갑니다.

claude --continue # 최근 대화 이어서 claude --resume # 목록에서 골라서

11. 확장 기능

기본 기능만으로도 대부분의 작업이 됩니다. 확장은 필요해졌을 때 하나씩 붙이는 게 맞습니다.

언제 무엇을 추가하나

같은 컨벤션을 두 번 틀림

이걸 추가하세요: CLAUDE.md에 규칙 추가

같은 프롬프트를 반복해서 침

이걸 추가하세요: 스킬로 저장

같은 절차서를 세 번째 붙여넣음

이걸 추가하세요: 스킬로 정리

브라우저 탭에서 계속 데이터를 복사함

이걸 추가하세요: MCP 서버 연결

곁가지 작업 로그가 대화창을 뒤덮음

이걸 추가하세요: 서브에이전트로 분리

"묻지 말고 매번 해야 하는" 일이 생김

이걸 추가하세요: 훅 작성

두 번째 저장소에도 같은 세팅이 필요함

이걸 추가하세요: 플러그인으로 패키징

스킬 (Skills)

.claude/skills/ 폴더에 SKILL.md를 넣으면 됩니다. 클로드가 상황에 맞게 자동으로 불러오거나, /스킬이름으로 직접 호출합니다.

참조형 스킬 — 지식을 담는 용도:

--- name: api-conventions description: 우리 서비스 REST API 설계 규칙 --- # API 규칙 - URL 경로는 kebab-case - JSON 속성은 camelCase - 목록 엔드포인트는 항상 페이지네이션 포함 - API 버전은 URL 경로에 표기 (/v1/, /v2/)

실행형 스킬 — 반복 작업을 명령어로:

--- name: fix-issue description: GitHub 이슈 수정 disable-model-invocation: true --- GitHub 이슈를 분석하고 수정하세요: $ARGUMENTS

1. `gh issue view`로 이슈 상세 확인 2. 문제 파악 3. 관련 파일 검색 4. 수정 구현 5. 테스트 작성 및 실행 6. 린트·타입체크 통과 확인 7. 커밋 메시지 작성 8. 푸시 후 PR 생성

/fix-issue 1234 로 호출합니다. 부작용이 있는 작업은 disable-model-invocation: true를 넣어 내가 직접 호출할 때만 실행되게 하세요.

서브에이전트 (Subagents)

.claude/agents/에 정의합니다. 자기만의 컨텍스트와 허용 도구를 갖습니다.

--- name: security-reviewer description: 보안 취약점 관점에서 코드를 리뷰 tools: Read, Grep, Glob, Bash model: opus --- 당신은 시니어 보안 엔지니어입니다. 다음 관점으로 코드를 검토하세요: - 인젝션 취약점 (SQL, XSS, 커맨드 인젝션) - 인증·인가 결함 - 코드에 하드코딩된 비밀키나 자격 증명 - 안전하지 않은 데이터 처리

구체적인 라인 번호와 수정 제안을 함께 제시하세요.

호출은 이렇게:

서브에이전트를 써서 이 코드의 보안 이슈를 리뷰해줘

훅 (Hooks)

CLAUDE.md의 지시는 권고지만, 훅은 강제입니다. 특정 시점마다 무조건 실행됩니다.

클로드에게 직접 만들어달라고 하면 됩니다.

파일 편집할 때마다 eslint 실행하는 훅을 만들어줘 migrations 폴더에 쓰기를 차단하는 훅을 만들어줘

설정 확인은:

/hooks

핵심 구분: "절대 .env 파일 수정하지 마"를 CLAUDE.md에 적는 건 부탁입니다. PreToolUse 훅으로 막는 건 강제입니다. 반드시 지켜져야 하는 규칙은 훅으로 만드세요.

MCP — 외부 시스템 연결

MCP(Model Context Protocol)로 DB, Notion, Figma, Slack 같은 외부 시스템을 붙입니다.

터미널에서:

claude mcp add --transport http notion https://mcp.notion.com/mcp

연결 상태 확인:

/mcp

플러그인 (Plugins)

스킬·훅·서브에이전트·MCP 서버를 한 덩어리로 묶어 설치·배포하는 단위입니다.

/plugin

마켓플레이스를 탐색하고 설치할 수 있습니다. 타입 언어를 쓴다면 코드 인텔리전스 플러그인을 꼭 설치하세요. 심볼 단위 탐색이 가능해져서 파일을 통째로 읽는 낭비가 줄어듭니다.

CLI 도구를 활용하라

의외로 효과가 큰 팁입니다. CLI 도구는 외부 서비스를 다루는 가장 컨텍스트 효율적인 방법입니다. GitHub를 쓴다면 gh CLI를 설치하세요. 클로드가 이슈 생성, PR 열기, 코멘트 읽기에 알아서 활용합니다.

모르는 CLI 도구도 이렇게 가르치면 됩니다.

'foo-cli-tool --help'로 이 도구 사용법을 익힌 다음, A, B, C 작업을 해줘

12. 자동화와 병렬 작업

비대화형 모드 — 스크립트에 넣기

# 한 번만 물어보고 끝 claude -p "이 프로젝트가 뭐 하는지 설명해줘"

# 스크립트에서 파싱할 수 있는 JSON 출력 claude -p "모든 API 엔드포인트 목록 뽑아줘" --output-format json

# 실시간 스트리밍 claude -p "이 로그 파일 분석해줘" --output-format stream-json --verbose

CI 파이프라인, pre-commit 훅, 각종 자동화 스크립트에 이 방식으로 넣습니다.

파이프로 연결도 됩니다.

claude -p "<프롬프트>" --output-format json | your_command

대량 작업 팬아웃

수천 개 파일을 마이그레이션해야 한다면.

1단계 — 목록부터 만들게 합니다:

마이그레이션이 필요한 Python 파일 전부 나열해서 files.txt로 저장해줘

2단계 — 루프 스크립트 (Linux/macOS bash):

for file in $(cat files.txt); do claude -p "$file 을 Python 2에서 3으로 마이그레이션해줘. OK 또는 FAIL만 반환해." \ --allowedTools "Edit,Bash(git commit *)" done

3단계 — 2~3개로 먼저 테스트한 뒤 전체 실행. --allowedTools로 권한을 좁혀두는 게 무인 실행에서는 필수입니다.

git 저장소라면 내장 명령도 있습니다.

/batch 모든 컴포넌트를 새 디자인 토큰으로 마이그레이션

클로드가 작업을 5~30개 서브에이전트로 쪼개고, 각각 별도 worktree에서 작업한 뒤 PR을 올립니다.

병렬 세션 — 작성자/리뷰어 패턴

새 컨텍스트에서 리뷰하면 자기가 방금 쓴 코드에 대한 편향이 없어서 리뷰 품질이 올라갑니다.

API 엔드포인트에 레이트 리미터 구현해줘

세션 B (리뷰어): @src/middleware/rateLimiter.ts 의 레이트 리미터 구현을 리뷰해줘. 엣지 케이스, 경쟁 상태, 기존 미들웨어 패턴과의 일관성을 봐줘.

리뷰 피드백이야: [세션 B 출력]. 이 이슈들을 해결해줘

테스트로도 같은 방식이 됩니다. 한쪽에서 테스트를 짜고, 다른 쪽에서 그 테스트를 통과시키는 코드를 짜게 하는 식입니다.

병렬 작업 방식은 여러 가지가 있습니다.

1. worktrees — 격리된 git 체크아웃에서 각 세션 실행
2. 데스크톱 앱 — 여러 로컬 세션을 시각적으로 관리
3. 웹 세션 — 클라우드 인프라에서 실행
4. claude agents — 백그라운드 세션들을 한 화면에서 감시

적대적 리뷰 단계 추가하기

작업을 "완료"로 넘기기 전에 한 단계 더 두면 품질이 확 올라갑니다.

서브에이전트를 써서 레이트 리미터 diff를 PLAN.md와 대조해서 리뷰해줘. 모든 요구사항이 구현됐는지, 명시된 엣지 케이스에 테스트가 있는지, 작업 범위 밖이 변경되지 않았는지 확인해줘. 스타일 취향 말고 누락된 것만 보고해줘.

⚠️ 주의: 문제를 찾으라고 시킨 리뷰어는 문제가 없어도 뭔가를 찾아냅니다. 모든 지적을 다 반영하면 불필요한 추상화 계층, 방어 코드, 일어나지 않을 케이스의 테스트로 코드가 비대해집니다. **"정확성이나 명시된 요구사항에 영향을 주는 것만 지적하라"**고 못 박아 두세요.

내장 명령도 있습니다.

/code-review

13. 초보자가 가장 많이 하는 실수 5가지

① 하나의 세션에 모든 걸 담기

한 작업을 하다가 무관한 걸 물어보고, 다시 원래 작업으로 돌아옵니다. 컨텍스트가 쓰레기로 가득 찹니다. → 작업이 바뀌면 /clear

② 계속 고쳐주기

틀렸다고 지적하고, 또 틀리고, 또 지적합니다. 실패한 접근법들이 컨텍스트를 오염시킵니다. → 두 번 실패하면 /clear 후 배운 걸 반영한 새 프롬프트로 다시 시작

③ CLAUDE.md 과잉 작성

너무 길면 클로드가 절반을 무시합니다. 중요한 규칙이 소음에 묻히기 때문입니다. → 가차 없이 쳐내기. 지시가 없어도 잘하는 건 지우고, 반드시 지켜야 하는 건 훅으로 전환

④ 검증 없이 믿기

그럴싸해 보이는 구현이 엣지 케이스를 처리 못 합니다. → 항상 검증 수단(테스트·스크립트·스크린샷)을 함께 줄 것. 검증할 수 없으면 배포하지 말 것

⑤ 범위 없는 무한 탐색

"이거 좀 조사해줘"라고만 하면 수백 개 파일을 읽으며 컨텍스트를 다 씁니다. → 범위를 좁게 지정하거나, 서브에이전트에게 시켜서 메인 컨텍스트를 보호할 것

14. 트러블슈팅

claude: command not found

PATH에 등록이 안 된 경우입니다. 터미널을 완전히 껐다 켜보세요. 그래도 안 되면:

claude doctor

설치 중 syntax error near unexpected token '<' 또는 403 오류

네트워크나 프록시 문제일 가능성이 높습니다. 사내망이라면 프록시 설정이 필요합니다. 대안으로 Homebrew나 WinGet 설치를 시도해보세요.

설정이 적용 안 되는 것 같을 때

무엇이 실제로 로드됐는지 직접 확인합니다.

/context # 컨텍스트에 뭐가 올라왔는지 /doctor # 전체 설정 점검 /hooks # 등록된 훅 확인 /mcp # MCP 서버 연결 상태

응답이 느려지거나 자꾸 압축될 때

컨텍스트가 가득 찬 상태입니다. /clear로 초기화하거나, /compact로 요약하세요. CLAUDE.md가 너무 길지 않은지도 점검하세요.

사내 프록시 / 사설 CA 환경

기업 환경에서는 프록시 서버, 사설 인증기관(CA), mTLS 설정이 필요할 수 있습니다. 이 경우 공식 문서의 네트워크 설정 문서를 참고하세요.

15. 자주 묻는 질문 (FAQ)

Q. 클로드 코드는 무료인가요? A. 아닙니다. Claude Pro, Max, Team, Enterprise 구독이나 Claude Console 크레딧이 필요합니다. 무료 플랜에는 포함되지 않습니다.

Q. 한국어로 지시해도 되나요? A. 됩니다. 한국어로 자연스럽게 지시하면 됩니다. 다만 코드 주석이나 커밋 메시지를 어떤 언어로 쓸지는 CLAUDE.md에 명시해두는 게 좋습니다.

Q. Node.js를 미리 설치해야 하나요? A. 네이티브 설치(install.sh / install.ps1)를 쓰면 필요 없습니다. Node.js, Docker 등 별도 런타임 없이 동작합니다.

Q. Windows에서 WSL 없이 쓸 수 있나요? A. 쓸 수 있습니다. 다만 Git for Windows를 함께 설치하면 클로드가 Bash 툴을 쓸 수 있어서 더 편합니다. 없으면 PowerShell을 셸로 사용합니다.

Q. 내 코드가 학습에 쓰이나요? A. 데이터 처리 정책은 계정 종류(개인/Team/Enterprise)와 설정에 따라 다릅니다. 엔터프라이즈 계정에는 ZDR(Zero Data Retention) 옵션도 있습니다. 공식 데이터 사용 정책 문서를 확인하세요.

Q. Cursor나 GitHub Copilot과 뭐가 다른가요? A. 자동완성이나 에디터 내 채팅이 아니라, 터미널에서 스스로 파일을 읽고 명령을 실행하며 작업을 완수하는 에이전트라는 점이 다릅니다. 물론 VS Code·JetBrains 확장도 제공되므로 병행해서 쓸 수 있습니다.

Q. 실수로 코드를 망가뜨리면요? A. Esc를 두 번 누르거나 /rewind로 이전 시점의 대화와 코드를 복원할 수 있습니다. 다만 Bash 명령으로 생긴 변경은 추적되지 않으므로 git 커밋을 자주 하는 습관은 여전히 필수입니다.

Q. 팀에서 같이 쓰려면요? A. CLAUDE.md를 git에 커밋하는 것부터 시작하세요. 팀 전체가 함께 다듬으면 시간이 지날수록 가치가 누적됩니다. 여러 저장소에 같은 세팅이 필요해지면 플러그인으로 패키징하면 됩니다.

마무리 — 이것만 기억하세요

긴 글이었지만, 실전에서 통하는 건 결국 다섯 가지입니다.

1. 검증 수단을 쥐여줘라. 테스트, 빌드, 스크린샷. 통과/실패가 명확하면 클로드가 알아서 반복한다.
2. 바로 코딩시키지 마라. 읽게 하고(탐색) → 계획 세우게 하고 → 그다음 시켜라.
3. 구체적으로 말해라. "로그인 버그 고쳐줘"와 "세션 타임아웃 후 토큰 갱신이 실패한다, src/auth/를 봐라"는 하늘과 땅 차이다.
4. 컨텍스트를 아껴라. 작업이 바뀌면 /clear. 두 번 고쳐줬는데 안 되면 새 세션.
5. CLAUDE.md는 짧게. 길면 무시당한다.

나머지는 쓰면서 감이 잡힙니다. 오늘 당장은 설치하고, 본인 프로젝트에서 이 프로젝트 설명해줘 한 줄만 쳐보세요. 그 다음은 자연스럽게 이어집니다.

참고 자료 (공식 문서)

1. 클로드 코드 공식 문서: https://code.claude.com/docs/en/overview
2. 빠른 시작 가이드: https://code.claude.com/docs/en/quickstart
3. 베스트 프랙티스: https://code.claude.com/docs/en/best-practices
4. 확장 기능 가이드: https://code.claude.com/docs/en/features-overview
5. 한국어 문서 색인: https://code.claude.com/docs/_llms/ko.md

이 글이 도움이 되셨다면 북마크해두고 필요할 때 찾아보세요. 명령어 표와 프롬프트 예시는 실무에서 계속 꺼내 쓰게 됩니다.