Claude Code 시작

Claude Code는 터미널에서 동작하는 코딩 에이전트입니다. 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하는 작업을 대화로 맡길 수 있습니다. 이 문서는 설치부터 첫 커밋까지를 순서대로 짚습니다 — 설치 → 로그인 → 첫 실행 → /init → 파일 읽기·수정 → 커밋, 그리고 권한을 좁게 잡는 데까지. 에이전트가 무엇이고 개발자·비개발자 트랙이 왜 나뉘는지는 에이전트에서 다루므로, 이 문서는 이 제품을 어떻게 굴리는지에 집중합니다.

설치

설치 방식은 두 갈래입니다. native 설치는 한 줄이면 끝나고 백그라운드에서 자동 업데이트되므로 별도 조치가 필요 없습니다. 플랫폼별로 다음 한 줄을 실행하세요.

# macOS · Linux · WSL
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

패키지 매니저로도 설치할 수 있습니다. 이 경우 자동 업데이트가 없으므로 업그레이드는 수동입니다.

리눅스 배포판 패키지(apt·dnf·apk)도 별도로 제공됩니다. Windows에서는 Git for Windows 설치를 권장합니다(필수는 아닙니다) — 있으면 Bash 도구를 사용하고, 없으면 PowerShell로 대체 동작합니다. WSL 환경에서는 Git for Windows가 필요하지 않습니다.

인증과 로그인

설치 후 claude를 실행하면 첫 실행 시 브라우저 로그인이 열립니다. 한 번 로그인하면 자격증명이 저장되어 다시 로그인할 필요가 없습니다. 세션 안에서 다른 계정으로 바꾸려면 /login으로 재인증합니다.

로그인은 여러 계정 종류를 지원합니다. Claude Pro·Max·Team·Enterprise, API 크레딧 기반의 Claude Console(첫 로그인 시 'Claude Code' 워크스페이스가 자동 생성됩니다), 그리고 Amazon Bedrock·Google Vertex AI·Microsoft Foundry 같은 엔터프라이즈 클라우드 경유가 있습니다.

어느 좌석이 Claude Code를 포함하는지는 가격·정책에 따라 달라집니다. 내가 쓰는 구독·좌석에 Claude Code가 포함되는지는 계정에서 확인하세요.

첫 실행과 /init

저장소 루트에서 claude를 실행하면 현재 디렉토리를 대상으로 하는 대화 세션이 열리고, 버전·모델·작업 디렉토리가 표시됩니다. 세션 안에서 /help로 사용할 수 있는 명령을 확인합니다. 대화 세션 대신 일회성으로 실행하는 방식도 있습니다.

claude              # 현재 디렉토리에서 대화 세션 시작
claude "작업 설명"   # 일회성 작업 실행
claude -p "질의"     # 일회성 질의 후 종료
claude -c           # 현재 디렉토리의 최근 대화 이어가기
claude -r           # 이전 대화 목록에서 선택

처음 할 일은 /init입니다. 코드베이스를 분석해 빌드·테스트 명령과 발견한 규약을 담은 CLAUDE.md 초안을 만듭니다. 출력 위치는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md이며, 파일이 이미 있으면 덮어쓰지 않고 개선안을 제안합니다. 생성된 규약을 확인하고, 필요한 부분만 다듬어 커밋하세요.

참고 — CLAUDE_CODE_NEW_INIT=1로 대화형 멀티페이즈 /init 플로우를 켤 수 있습니다. 팀에서 이 플로우를 쓸지는 계정·설정에서 확인하세요.

파일 읽기·수정에서 첫 커밋까지

읽기와 수정은 권한 처리가 다릅니다. 파일 읽기는 필요할 때 권한 프롬프트 없이 자동으로 일어납니다. 반면 파일 수정(Edit·Write)은 매번 승인을 요청합니다 — 개별 승인하거나, 세션 동안 'Accept all'로 한 번에 허용할 수 있습니다. 수정·명령 실행에 승인 단계가 있는 이유(에이전트를 좁은 권한으로 다루는 원칙)는 에이전트에서 다룹니다.

모든 파일 편집은 되돌릴 수 있습니다. 편집 직전 스냅샷이 남으므로 Esc를 두 번 눌러 이전 상태로 되돌리거나, Claude에게 되돌려 달라고 요청하면 됩니다. 단 체크포인트는 세션 로컬이고 git과는 별개이며 파일 변경만 커버합니다. 원격에 영향을 주는 동작은 되돌릴 수 없으므로 Claude가 먼저 확인을 요청합니다.

변경을 확인하고 커밋하는 일도 대화로 맡깁니다.

내 변경 파일 보여줘
적절한 메시지로 커밋해줘

그러면 Claude가 git status와 git diff를 읽고 커밋을 제안하며, 사람이 승인합니다. Claude Code가 짠 코드도, 내가 리뷰하고 커밋하면 그건 내 코드이고 내 책임입니다(커밋 author = 책임 주체). 출력을 어디까지 신뢰할지의 근거는 출력 검증에서, 사람이 검증하는 표준 절차는 검증 워크플로에서 다룹니다.

여기까지가 이 문서의 Git 범위입니다. 브랜치 생성·머지·푸시, 그리고 git worktree 기반 병렬 작업 같은 공유 저장소 워크플로는 Claude Code 실무 가이드에서 다룹니다.

권한을 좁게 시작하기, 그리고 다음 걸음

권한은 좁게 시작하는 편이 안전합니다. Claude Code의 권한은 세 단계로 나뉩니다. 읽기 전용은 승인이 필요 없고, 파일 수정과 Bash 실행은 승인이 필요하며 한 번 허용하면 세션 동안 기억됩니다. 익숙해지기 전까지는 자동 승인을 넓히지 마세요.

승인 동작은 Shift+Tab으로 모드를 순환해 바꿉니다.

규칙으로 고정하려면 .claude/settings.json의 permissions에 allow·deny·ask 배열을 적습니다. Bash는 와일드카드(Bash(npm run *)·Bash(git *)), Read·Edit는 경로로 범위를 앵커합니다.

{
  "permissions": {
    "allow": ["Bash(npm run build)", "Bash(git commit *)", "Bash(npm test)"],
    "deny": ["Bash(git push *)", "Read(.env)", "Read(~/.ssh/*)"]
  }
}

세션 중에는 /permissions로 적용된 규칙과 그 출처를 확인합니다. 위 deny 항목(Read(.env)·Read(~/.ssh/*))은 '읽을 수 있는 범위'를 좁히는 메커닉을 보여줄 뿐입니다. 무엇을 Claude Code에 입력해도 되는지 — 자사 소스코드 포함 — 와 넣지 말아야 할 것은 안전하게 쓰는 법에 정리돼 있습니다.

여기까지가 시작 가이드입니다. 다음은 Claude Code 실무 가이드에서 브랜치·리뷰·공유 저장소 워크플로로 이어집니다. 함께 보면 좋은 문서는 아래와 같습니다.

• 에이전트 — 에이전트의 정의와 권한·승인 원칙의 배경.
• 안전하게 쓰는 법 — 자사 소스코드를 포함해 무엇을 입력해도 되는지의 기준.
• 출력 검증 · 검증 워크플로 — 출력을 신뢰하는 근거와 사람이 검증하는 절차.
• 용어집 — 낯선 용어 확인.