Claude Code 기초 가이드: 설치·권한·모델·컨텍스트 관리
Claude Code의 설치와 첫 실행부터 권한 모드, 모델 선택, 컨텍스트 정리, CLAUDE.md 작성법까지 단계별로 설명한다. 원자료에서 단순화된 권한 체계와 비용 관련 내용도 공식 문서 기준으로 바로잡았다.
Claude Code는 프로젝트 디렉터리의 파일을 읽고 수정하며 터미널 도구를 실행할 수 있는 에이전트형 코딩 도구다.
VS Code는 편리한 선택지이지만 필수 조건은 아니며, 지원되는 터미널 환경에서도 Claude Code를 실행할 수 있다.
초보자는 Plan 모드로 작업 범위를 검토한 뒤 기본 모드나 Accept Edits 모드로 전환하는 편이 안전하다.
비용은 인증 방식과 선택한 모델, 입력 컨텍스트, 작업 반복 횟수에 따라 달라진다.
CLAUDE.md는 대화 기억 저장소가 아니라 프로젝트의 구조와 명령, 규칙을 반복해서 제공하는 지침 파일이다.
Claude Code는 Anthropic의 Claude를 터미널과 코드 저장소에서 사용하는 에이전트형 개발 도구다. 단순히 코드 조각을 답변하는 데 그치지 않고, 허용된 범위 안에서 파일 탐색·편집, 명령 실행, 테스트와 오류 분석을 수행한다.
이 가이드는 설치 절차뿐 아니라 권한을 안전하게 설정하는 방법, 작업에 맞는 모델을 고르는 기준, 컨텍스트와 프로젝트 지침을 관리하는 방법을 설명한다. 명령과 지원 환경은 업데이트될 수 있으므로 실제 설치 시에는 공식 설정 문서에 표시되는 최신 명령을 확인해야 한다.
Claude로 코딩하는 세 가지 방식
각 방식은 결과물보다 도구가 로컬 프로젝트와 상호작용하는 범위에서 차이가 난다.
방식 | 로컬 파일 접근 | 명령 실행 | 적합한 작업 | 주요 한계
Claude 웹 | 기본적으로 제한적 | 기본적으로 불가 | 질문, 코드 설명, 짧은 예제, 설계 검토 | 답변을 프로젝트에 직접 반영하려면 복사와 실행이 필요함
Claude 데스크톱 앱 | 기능·연동·사용자 승인에 따라 다름 | 기능·연동에 따라 다름 | 문서 작업, 대화 중심 업무, 지원되는 로컬 연동 | 모든 설치 환경에서 저장소와 셸을 자동 제어하는 것은 아님
Claude Code | 프로젝트 범위에서 가능 | 권한 정책에 따라 가능 | 실제 저장소 수정, 테스트, 리팩터링, 장기 프로젝트 | 셸과 파일 권한을 다루므로 검토와 보안 설정이 필요함
Claude Code가 전문 개발자만을 위한 것은 아니다. 다만 파일 삭제, 의존성 설치, 빌드 스크립트 실행처럼 시스템에 영향을 주는 작업이 가능하므로 초보자일수록 Plan 모드와 버전 관리를 함께 사용하는 것이 좋다.
설치 전 준비 사항
다음 항목을 먼저 준비한다.
· 공식 문서에서 현재 지원되는 운영체제와 셸 환경을 확인한다.
· Claude Code를 이용할 수 있는 Anthropic 계정 또는 지원되는 인증·결제 환경을 준비한다.
· 기존 프로젝트라면 Git 저장소를 만들고 변경 사항을 커밋하거나 백업한다.
· 프로젝트의 테스트, 빌드, 린트 명령을 파악한다.
· VS Code 같은 편집기를 사용할 수 있지만, VS Code 자체가 Claude Code의 필수 조건은 아니다.
Windows에서는 공식 문서가 안내하는 PowerShell, 명령 프롬프트 또는 WSL 조건을 확인해야 한다. 조직에서 관리하는 컴퓨터라면 설치 권한, 프록시, 방화벽, 데이터 처리 정책도 먼저 점검한다.
Claude Code 설치와 첫 실행
1. 공식 설치 명령 확인
Claude Code 공식 설정 문서에서 운영체제에 맞는 최신 설치 방법을 선택한다. 설치 방식과 명령은 변경될 수 있으므로 오래된 영상이나 블로그의 명령을 그대로 재사용하기보다 공식 문서를 기준으로 삼는다.
2. 프로젝트 폴더 열기
새 폴더를 만들거나 기존 저장소로 이동한다. VS Code를 사용한다면 File > Open Folder로 폴더를 연 다음 Terminal > New Terminal을 선택할 수 있다.
cd path/to/project
claude
claude를 실행하면 필요한 경우 브라우저 인증 절차가 표시된다. 로그인 후 Claude Code는 현재 작업 디렉터리를 기준으로 프로젝트를 파악한다. 따라서 홈 디렉터리나 지나치게 넓은 상위 폴더보다 실제 저장소의 루트에서 실행하는 편이 안전하다.
3. 첫 요청은 작게 시작
처음부터 전체 애플리케이션 제작을 맡기기보다 다음과 같이 범위를 나눈다.
· 프로젝트 구조를 읽고 요약하게 한다.
· 구현 계획과 변경 대상 파일을 제시하게 한다.
· 한 기능만 구현하게 한다.
· 테스트나 정적 분석을 실행하게 한다.
· 변경 내역과 남은 위험을 설명하게 한다.
예시 요청:
이 저장소를 읽고 구조와 실행 방법을 요약해 줘. 아직 파일은 수정하지 말고,
로그인 폼을 추가하기 위한 계획과 변경 대상 파일만 제안해 줘.
권한 모드와 안전한 설정
Claude Code의 권한 모드는 버전과 설정 화면에 따라 표시 문구가 달라질 수 있다. 공식 설정에서 사용하는 대표적인 모드 개념은 다음과 같다.
모드 | 동작 | 권장 상황
Default | 파일 수정이나 위험 가능성이 있는 도구 실행 시 필요에 따라 승인을 요청 | 일반적인 일상 작업
Accept Edits | 파일 편집은 자동으로 허용하되 다른 도구에는 별도 승인이 적용될 수 있음 | 변경 파일을 Git으로 추적하는 개발 작업
Plan | 파일을 수정하거나 명령을 실행하지 않고 분석과 계획에 집중 | 저장소 파악, 설계 검토, 초보자의 첫 단계
Don't Ask | 사전 허용되지 않은 작업을 질문하는 대신 거부하는 비대화형 정책 | 자동화 환경이나 엄격한 허용 목록을 사용할 때
Bypass Permissions | 권한 확인 절차를 우회 | 격리된 컨테이너 등 위험을 통제한 환경 외에는 지양
Shift+Tab은 대화형 화면에서 제공되는 일부 권한 상태를 전환하는 데 사용될 수 있다. 그러나 모든 설정이 반드시 이 단축키만으로 순환되는 것은 아니므로 현재 화면의 상태 표시와 공식 권한 문서를 확인해야 한다.
초보자에게 권장하는 흐름
· Plan 모드에서 구현 계획을 받는다.
· 변경 파일과 실행할 명령을 검토한다.
· Default 또는 Accept Edits 모드에서 구현한다.
· 패키지 설치, 데이터베이스 변경, 삭제 명령은 직접 확인한다.
· git diff와 테스트 결과를 검토한 뒤 커밋한다.
Bypass Permissions는 단순히 편리한 고속 모드가 아니다. 잘못된 명령, 과도한 파일 접근, 비밀정보 노출의 피해를 키울 수 있으므로 개인 컴퓨터나 중요한 저장소에서 기본값으로 사용하지 않는다.
모델 선택과 비용 관리
대화형 세션에서 /model을 사용하면 계정과 환경에서 선택 가능한 모델을 확인하거나 변경할 수 있다. 모델 이름과 별칭, 제공 여부는 시점과 인증 방식에 따라 달라질 수 있으므로 고정된 모델 목록을 전제로 자동화하지 않는 편이 좋다.
/model
일반적인 선택 원칙은 다음과 같다.
작업 유형 | 선택 기준
아키텍처 설계, 어려운 디버깅, 복잡한 추론 | 성능이 높은 모델을 우선 검토
일반 구현, 테스트 작성, 반복적인 개발 | 성능과 속도의 균형이 좋은 모델 검토
단순 검색, 형식 변환, 짧은 수정 | 계정에서 지원한다면 빠르고 경제적인 모델 검토
Opus, Sonnet, Haiku는 모델 계열을 구분하는 이름이지만, 각 계열의 정확한 버전과 Claude Code 지원 여부는 계속 바뀔 수 있다. /model sonnet처럼 별칭을 사용할 수 있는 환경도 있지만 현재 세션에서 표시되는 선택지를 확인하는 것이 가장 정확하다.
비용을 줄이는 실용적인 방법
· 필요한 하위 디렉터리에서 실행해 불필요한 파일 탐색을 줄인다.
· 요청에 목표, 제약, 완료 조건을 한 번에 명시해 재작업을 줄인다.
· 큰 로그 전체보다 오류 주변과 재현 절차를 제공한다.
· 생성 파일, 빌드 결과, 대형 데이터 등 불필요한 경로를 제외한다.
· 탐색과 설계가 끝나면 새 작업 단위로 세션을 정리한다.
· 간단한 작업은 사용 가능한 범위에서 더 빠르고 저렴한 모델로 처리한다.
· API 기반 이용이라면 비용 관련 명령과 Anthropic Console의 사용량 정보를 함께 확인한다.
비용 구조는 로그인 방식에 따라 다르다. Claude 구독 계정에는 플랜별 사용 한도가 적용될 수 있고, Anthropic API 또는 클라우드 제공업체를 통한 사용은 토큰 기반 청구가 적용될 수 있다. 따라서 특정 모델이 언제나 무료이거나 일정 금액만 든다고 가정해서는 안 된다.
컨텍스트 윈도우 관리
컨텍스트 윈도우는 현재 응답을 만들 때 모델이 참고할 수 있는 대화, 파일 내용, 도구 결과, 프로젝트 지침 등의 범위다. 이것은 영구 기억이나 단순한 대화 글자 수와 같지 않다.
주요 명령
명령 | 용도 | 주의점
/context | 컨텍스트 사용 구성을 확인 | 표시 방식은 버전에 따라 달라질 수 있음
/compact | 현재 대화를 요약해 컨텍스트 공간을 확보 | 세부 정보가 요약 과정에서 축약될 수 있음
/clear | 현재 대화 기록을 지우고 새 대화를 시작 | 필요한 결정과 작업 상태를 먼저 문서에 남겨야 함
컨텍스트가 특정 비율을 넘으면 반드시 답변 품질이 떨어진다는 보편적인 기준은 없다. Claude Code가 자동 압축을 수행할 수도 있고, 품질은 포함된 정보의 양뿐 아니라 관련성·중복·충돌 여부에도 영향을 받는다.
다음 신호가 보이면 정리를 고려한다.
· 이미 수정한 요구 사항을 반복해서 놓친다.
· 오래된 파일 상태를 현재 상태로 오인한다.
· 서로 다른 기능의 조건을 혼동한다.
· 같은 파일을 불필요하게 반복해서 읽는다.
· 대화와 도구 출력이 지나치게 길어졌다.
기능 하나가 끝날 때마다 무조건 /clear를 실행할 필요는 없다. 대신 완료된 결정, 미해결 항목, 테스트 결과를 프로젝트 문서나 작업 기록에 남긴 뒤 새 세션으로 넘어가면 정보 손실을 줄일 수 있다.
CLAUDE.md로 프로젝트 지침 관리
파일명은 일반적으로 대문자를 포함한 CLAUDE.md로 작성한다. 이 파일은 Claude의 영구 기억이 아니라, Claude Code가 프로젝트에서 참고하는 지속적인 지침 문서다. 저장소에 포함하면 팀원과 지침을 공유할 수 있지만, 민감한 정보는 기록하면 안 된다.
/init 명령으로 프로젝트를 분석해 초기 CLAUDE.md 작성을 시작할 수 있으며, 결과는 반드시 사람이 검토해야 한다.
포함하면 좋은 내용
· 프로젝트의 목적과 핵심 기능
· 사용 언어, 프레임워크, 런타임 버전
· 중요한 디렉터리와 모듈의 역할
· 설치, 개발 서버, 테스트, 린트, 빌드 명령
· 코드 스타일과 네이밍 규칙
· 수정하면 안 되는 파일이나 생성 코드
· 보안·개인정보 처리 원칙
· 작업 완료 조건과 검증 절차
예시:
# Project instructions
## Stack
- TypeScript와 Node.js를 사용한다.
- 패키지 관리자는 pnpm이다.
## Commands
- 테스트: `pnpm test`
- 린트: `pnpm lint`
- 빌드: `pnpm build`
## Rules
- `.env`와 실제 자격 증명을 읽거나 커밋하지 않는다.
- 공개 API의 응답 형식을 바꾸기 전에 먼저 계획을 제시한다.
- 기능 변경에는 관련 테스트를 추가한다.
CLAUDE.md에 공식적인 최대 200줄 제한이 있는 것은 아니다. 그러나 너무 긴 지침은 컨텍스트를 소비하고 규칙 간 충돌을 만들 수 있으므로 짧고 구체적으로 유지하는 것이 실용적이다. 상세한 설계 설명은 별도 문서로 분리하고 필요한 경로를 안내한다.
권장 작업 절차
안전성과 결과 품질을 함께 높이는 기본 절차는 다음과 같다.
· Git 상태가 깨끗한지 확인하고 백업 또는 커밋을 만든다.
· 저장소 루트에서 Claude Code를 실행한다.
· CLAUDE.md와 기존 문서를 점검한다.
· Plan 모드에서 목표, 수정 파일, 테스트 계획을 받는다.
· 큰 작업을 검토 가능한 작은 단위로 나눈다.
· Default 또는 Accept Edits 모드에서 한 단위씩 구현한다.
· 설치·삭제·배포·데이터 변경 명령은 직접 검토한다.
· 테스트, 린트, 타입 검사와 git diff를 확인한다.
· 완료 상태와 남은 문제를 문서화한다.
· 다음 작업이 이전 대화와 무관하면 /clear로 새 세션을 시작한다.
보안 체크리스트
· .env, API 키, 인증서, 고객 데이터가 프롬프트나 저장소에 노출되지 않게 한다.
· 프로덕션 서버와 데이터베이스에서 직접 실험하지 않는다.
· 출처를 모르는 셸 명령이나 설치 스크립트는 실행 전에 읽어 본다.
· Claude가 작성한 코드도 의존성, 라이선스, 보안 취약점과 테스트를 검토한다.
· 중요한 작업에서는 최소 권한 원칙과 격리된 개발 환경을 적용한다.
· 자동 생성된 변경은 Git diff로 확인하고 사람이 최종 책임을 진다.
Claude Code는 개발 과정을 크게 단축할 수 있지만 결과의 정확성과 안전성을 보장하는 자동 장치는 아니다. 가장 안정적인 사용법은 명확한 지침, 제한된 권한, 작은 변경 단위, 자동 테스트와 사람의 검토를 결합하는 것이다.
Injoys
