Claude Code, 만든 사람이 알려주는 실용 가이드

앤트로픽 기술팀 멤버이자 Claude Code 개발자인 보리스가 30분짜리 실용 가이드를 공개했다. 만든 사람이 직접 말하는 사용법이라 결이 다르다. 기능 목록이 아니라 어떤 작업에 어떻게 쓰는가로 묶어 정리한다.

Claude Code가 무엇이길래

Claude Code는 코딩 작업을 위한 새로운 세대의 AI 어시스턴트다. 한 줄, 몇 줄 코드 완성을 넘어 기능을 완전히 자율적으로 구축하고, 함수나 파일 전체를 쓰고, 버그를 동시에 고친다.

가장 큰 장점은 기존 도구를 그대로 쓴다는 점이다. 워크플로를 바꿀 필요가 거의 없다. VS Code든 XCode든 JetBrains든, Vim이나 터미널만 있어도 된다. 로컬이든 원격 SSH든 tmux 같은 멀티플렉서 안이든 제약 없이 돈다.

설치와 초기 설정

Node.js만 있으면 시작할 수 있다. 몇 가지는 먼저 맞춰 두면 좋다.

터미널 설정 — Shift+Enter로 줄바꿈이 되게 해 두면 백슬래시 없이 여러 줄 프롬프트를 쓸 수 있다
테마 — /theme 로 라이트·다크를 고른다
GitHub 앱 설치 — 터미널에서 명령어 하나로 설치하면 이슈나 PR에서 직접 Claude를 부를 수 있다
도구 승인 맞춤 — 자주 쓰는 도구는 매번 승인하지 않도록 설정한다
받아쓰기 (macOS) — 접근성 설정에서 받아쓰기를 켜면 딕테이션 키를 두 번 눌러 프롬프트를 말로 입력할 수 있다

작업 1. 코드베이스를 파악할 때 — Q&A로 시작한다

처음 쓴다면 코드 기반 Q&A부터가 좋다. 앤트로픽이 신입사원 기술 온보딩에 쓰는 방식이기도 하다. 기존에 수 주가 걸리던 온보딩이 2~3일로 줄었다고 한다.

Claude Code는 코드베이스 질문에 답하기 위해 별도의 인덱싱을 하지 않고, 코드를 원격 데이터베이스에 올리지도 않는다. 모든 코드는 로컬에 남고 생성형 모델 훈련에도 쓰이지 않는다. 다운로드하고 바로 물어보면 된다.

특정 코드가 어떻게 쓰이는지 물으면 단순 텍스트 검색을 넘어 클래스가 어떻게 인스턴스화되는지까지 답한다
“이 함수는 왜 인자가 15개인가요?” 같은 질문을 하면 git 히스토리를 뒤져 언제, 누가, 왜 그 인자를 넣었는지 분석해 요약한다. “git 히스토리를 확인하라”는 짧은 지시만으로 스스로 git 사용법을 파악한다
GitHub 이슈를 물으면 웹에서 내용을 가져와 맥락을 잡는다
“이번 주에 내가 무엇을 배포했지?” 같은 질문에는 배포 로그를 분석해 정리해 준다

Q&A로 프롬프트 작성법을 익히고 능력 범위를 가늠한 다음 편집 단계로 넘어가는 순서가 좋다.

작업 2. 코드를 고칠 때 — 계획을 먼저 받는다

Claude Code는 파일 편집, 배시 명령 실행, 파일 검색 같은 기본 도구를 유기적으로 엮어 탐색·브레인스토밍·편집을 한다. 어떤 도구를 쓰라고 지시할 필요가 없다. “이것을 해줘”라고 하면 방법을 스스로 찾는다.

계획을 먼저 — 복잡한 기능은 구현 전에 브레인스토밍과 계획을 요청한다. 계획을 검토하고 승인한 뒤 코드를 쓰게 하면 원하는 결과에 훨씬 가까워진다
commit, push, PR — “commit push PR” 같은 짧은 명령으로 커밋 메시지 형식, 브랜치 푸시, PR 생성까지 자동화된다. 코드와 히스토리, git 로그를 분석해 그 저장소에 맞는 커밋 형식을 알아낸다. 시스템 프롬프트에 명시되지 않은 동작인데 모델 자체의 능력으로 된다

작업 3. 팀 도구를 붙일 때

BASH 도구 — 팀에서 쓰는 CLI 도구가 있으면 help 명령으로 사용법을 배우게 한다. 자주 쓰는 도구는 Claude.md에 등록해 세션 사이에도 기억하게 한다
MCP 도구 — 마찬가지로 정보를 주면 사용법을 익혀 쓴다

일반적인 워크플로는 이렇다. 탐색과 계획을 먼저 하고, 코드를 쓴 뒤 확인을 요청하게 하고, 스스로 작업을 검증할 수단을 준다. 단위 테스트를 쓰게 하거나 Puppeteer, iOS 에뮬레이터 스크린샷으로 결과를 보게 하는 식이다. 목업 이미지를 주고 웹 UI를 만들게 한 뒤 2~3번 반복 검증을 거치면 거의 완성에 가까운 결과가 나온다.

작업 4. 컨텍스트를 심을 때 — Claude.md

컨텍스트를 많이 줄수록 더 나은 결정을 내린다. 가장 간단한 방법이 Claude.md라는 마크다운 파일이다.

프로젝트 루트 Claude.md — 시작할 때마다 첫 사용자 턴에 자동으로 포함된다. 소스 컨트롤에 체크인해 팀과 공유하는 것이 좋다
로컬 Claude.md — 체크인하지 않는 개인용
중첩 Claude.md — 하위 디렉토리에 두면 그 디렉토리에서 작업할 때 자동으로 딸려 온다
전사 Claude.md — 엔터프라이즈 루트에 두면 회사 전체 코드베이스에서 가져온다

담을 내용은 자주 쓰는 BASH 명령어, MCP 도구 정보, 아키텍처 결정 사항, 중요한 파일 목록 같은 것이다. 간결하게 유지하는 것이 중요하다. 너무 길면 컨텍스트만 차지하고 쓸모가 떨어진다.

컨텍스트를 넣는 경로는 셋이다. 자동 로드되는 Claude.md, 홈 디렉토리나 프로젝트에 .claudecommands 파일을 만들어 등록하는 사용자 정의 슬래시 명령어, 그리고 프롬프트에서 파일을 직접 언급하는 것. 컨텍스트를 다듬는 데 쓴 시간은 성능으로 돌아온다.

작업 5. 팀 전체에 깔 때 — 계층적 설정과 권한

설정도 계층적으로 가져온다.

프로젝트별 설정 — Git 저장소에 특화. 체크인하거나 개인용으로 둔다
글로벌 설정 — 모든 프로젝트에 적용
기업 정책 — 모든 직원과 팀원에게 자동 배포되는 전체 설정

예를 들어 모든 직원이 쓰는 테스트 명령어를 기업 정책 파일에 넣어 자동 승인되게 하거나, 특정 URL 접근을 막아 코드베이스 보안을 지킬 수 있다. MCP 서버 설정도 mcp.json 을 만들어 체크인하면 그 저장소에서 일하는 모든 엔지니어가 별도 설치 없이 쓴다.

무엇부터 할지 모르겠다면 공유 프로젝트 컨텍스트(Claude.md)부터 시작해 팀 전체가 이득을 보게 하는 편이 좋다.

memory 명령을 실행하면 현재 로드된 모든 메모리 파일—기업 정책, 사용자 메모리, 프로젝트 Claude.md, 중첩 파일—을 확인하고 직접 편집할 수 있다. 프롬프트에서 # 로 기억을 지시할 때 어느 파일에 저장할지도 고를 수 있다.

작업 6. 자동화할 때 — Claude Code SDK

Claude Code 자체가 SDK 위에 만들어졌고, 사용자도 그 SDK로 자동화 도구를 만들 수 있다. CLI에서 claude -p(또는 claude --prompt)로 접근한다.

프롬프트, 허용된 도구, 배치 명령어, 출력 형식(JSON, 스트리밍 JSON)을 지정할 수 있어 CI/CD 파이프라인이나 사고 대응에 쓸 만하다. UNIX 유틸리티처럼 파이프로 엮이는 것이 재미있는 지점이다.

git status | claude -p "변경 사항 요약해줘" | jq .summary

매우 지능적인 UNIX 유틸리티라는 새로운 종류의 도구인 셈이다. GCP 버킷의 대용량 로그를 읽히거나 Sentry CLI에서 데이터를 가져와 분석시키는 것도 같은 방식이다.

작업 7. 여러 개를 동시에 돌릴 때

일반 사용자는 하나의 인스턴스와 터미널 탭 몇 개를 쓴다. 반면 파워 유저들은 SSH 세션과 TMUX 터널로 여러 인스턴스를 병렬로 돌리거나 git worktrees로 작업을 격리한다. 세션 수에 제한이 없어 병렬 작업에 쓸 만하다.

익혀 두면 좋은 단축키

Shift+Tab — 편집 승인·자동 승인 모드 전환. Bash 명령은 여전히 승인이 필요하지만 파일 편집은 자동 승인되고 나중에 되돌릴 수 있다
# — 특정 내용을 기억하도록 지시 (자동으로 Claude.md에 저장)
! — Bash 모드로 전환. 로컬에서 명령을 실행하고 그 결과를 컨텍스트에 넣는다
파일·폴더 언급 — 언제든 이름을 대면 컨텍스트에 추가된다
Esc — 현재 작업을 안전하게 중단한다. 세션에는 영향이 없어, 편집 제안 중 일부만 바꾸고 싶을 때 유용하다
Esc 두 번 — 기록으로 돌아가기
resume — 세션 종료 후 이전 작업 재개
Ctrl+R — Claude가 보고 있는 전체 출력 보기

멀티모달 입력

Claude Code는 처음부터 멀티모달이었다. 터미널이라 잘 드러나지 않을 뿐이다. 이미지 파일을 터미널로 드래그 앤 드롭하거나, 경로를 직접 입력하거나, 복사해 붙여넣으면 된다. 목업 이미지를 주고 UI를 구현하게 한 뒤 서버를 띄워 반복 검증하는 흐름이 여기서 나온다.

만든 사람의 이야기

가장 어려웠던 것은 BASH 명령어의 안전성이었다고 한다. BASH는 시스템을 예상치 못하게 바꿀 수 있는데, 그렇다고 모든 명령을 수동 승인하게 하면 생산성이 죽는다. 읽기 전용 명령어 분류와 정적 분석을 결합하고, 계층적 권한 시스템으로 레벨별 허용·차단을 관리하는 방식으로 풀었다.

CLI 도구로 만든 이유도 밝혔다. 앤트로픽 내부에서 VS Code, Vim, Emacs 등 제각각의 IDE를 쓰다 보니 공통분모인 터미널을 골랐다는 것. 그리고 모델의 발전 속도를 생각하면 특정 UI나 상위 레이어에 과하게 투자하기보다 핵심 모델 기능에 집중하는 것이 미래 지향적이라고 판단했다는 것이다.

앤트로픽의 엔지니어와 연구원 다수가 매일 Claude Code를 쓰고 있으며, 기술진의 약 80%가 일상적으로 활용한다. 연구원들은 노트북 도구로 주피터 노트북을 편집·실행하는 등 머신러닝과 모델링 작업에도 쓰고 있다.

영상 내용은 Gemini로 정리했다.