Claude Code 입문: 설치, 안전 권한, 첫 30분 실전 가이드

Claude Code는 터미널에서 사용하는 AI 코딩 에이전트입니다. 단순히 코드 조각을 질문하는 채팅 도구가 아니라, 프로젝트 파일을 읽고, 검색하고, 수정안을 만들고, 허용된 범위에서 파일을 편집하며, 테스트나 빌드 명령까지 실행할 수 있습니다.

초보자가 처음에 실패하는 이유는 대부분 설치가 아니라 첫 작업이 너무 큰 데 있습니다. “앱 전체를 고쳐줘”라고 시작하면 변경 범위가 커지고, 무엇이 맞는지 판단하기 어려워집니다. 첫날의 목표는 자동 개발이 아니라, 안전하게 한 번 성공하는 것입니다.

이 글은 공식 setup, common workflows, CLI usage를 기준으로 다시 정리했습니다. 다음 단계로는 CLAUDE.md 작성 가이드와 컨텍스트 관리 가이드를 함께 읽으면 좋습니다.

Claude Code를 어떻게 봐야 하나

Claude Code는 “작업을 전부 맡기는 도구”라기보다, 작은 개발 작업을 함께 진행하는 도구입니다. 특히 기존 코드 이해, 작은 버그 수정, 테스트 추가, README 정리, PR 요약처럼 범위가 분명한 일에 강합니다.

처음에는 이 순서가 안전합니다.

단계	할 일	목적
1	설치와 로그인	실행 가능 상태 확인
2	읽기 전용으로 코드 이해	수정 전 맥락 확보
3	작은 작업 하나 선택	위험 축소
4	diff와 테스트 확인	결과 검증
5	규칙을 문서화	다음 세션 안정화

빠르게 보이진 않지만, 이 흐름이 결과적으로 가장 빠릅니다.

설치 전 준비

먼저 실수해도 괜찮은 저장소나 브랜치를 준비하세요. 운영 브랜치에서 바로 시작하지 않는 것이 좋습니다.

git status
git switch -c try-claude-code

구버전 Git이라면 다음을 사용합니다.

git checkout -b try-claude-code

확인할 항목은 다음과 같습니다.

• Claude Code를 사용할 수 있는 Claude 계정
• 인터넷 연결
• 작업할 프로젝트 루트 폴더
• Git으로 diff를 볼 수 있는 상태
• 테스트나 빌드 명령을 실행할 수 있는 환경
• .env, 비밀키, 고객 데이터는 보호한다는 원칙

Windows에서는 PowerShell과 CMD 명령이 다릅니다. 프롬프트가 PS C:\로 시작하면 PowerShell입니다.

설치와 진단

macOS, Linux, WSL에서는 공식 네이티브 설치를 사용합니다.

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

Windows PowerShell에서는 다음을 실행합니다.

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

설치 후 바로 확인합니다.

claude --version
claude doctor

claude doctor는 설치와 설정 문제를 조기에 발견하는 데 유용합니다. 첫 세션에서 막히기 전에 실행해두는 편이 좋습니다.

npm 설치도 가능합니다.

npm install -g @anthropic-ai/claude-code

다만 특별한 이유가 없다면 공식 네이티브 설치를 먼저 권장합니다. 권한 문제를 만들 수 있는 sudo npm install -g는 피하세요.

첫 30분 운영법

프로젝트 루트에서 시작합니다.

cd my-project
claude

처음에는 브라우저 로그인이 진행됩니다. 로그인 후 바로 기능 구현을 요청하지 말고, 먼저 읽기 전용으로 지도를 만들게 하세요.

이 프로젝트를 처음 봅니다.
아직 파일을 수정하지 말고, 읽기만 해서 정리해주세요.

- 프로젝트가 하는 일
- 주요 디렉터리와 역할
- dev, test, build 명령 후보
- 변경하면 위험해 보이는 파일
- 먼저 읽을 파일 5개

근거가 된 파일 경로를 함께 적고, 불확실한 내용은 단정하지 마세요.

다음으로 작은 작업 후보를 요청합니다.

이 저장소에서 초보자가 처음 하기 좋은 개선 작업 5개를 제안해주세요.

조건:
- 30분 안에 끝날 크기
- 수정 파일은 최대 2개
- 테스트 또는 수동 확인 방법이 있음
- 인증, 결제, 비밀값, 운영 데이터는 건드리지 않음

각 작업에 난이도, 위험도, 확인 방법을 붙여주세요.

이제 Claude Code는 코드를 무작정 쓰는 도구가 아니라, 온보딩을 도와주는 파트너가 됩니다.

위험한 권한 피하기

Claude Code는 명령 실행과 파일 수정을 할 수 있으므로 권한을 신중히 다뤄야 합니다. 초보자는 기본 승인 흐름이나 계획 중심 모드에서 시작하세요.

claude --permission-mode plan

세션 안에서는 권한을 확인할 수 있습니다.

/permissions

bypassPermissions 또는 --dangerously-skip-permissions는 대부분의 확인을 건너뛰므로 조심해야 합니다. 격리된 컨테이너나 VM처럼 망가져도 되는 환경이 아니라면 첫 주에는 쓰지 않는 편이 좋습니다.

보수적인 권한 예시는 다음과 같습니다.

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm run test *)",
      "Bash(npm run build *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)"
    ]
  }
}

핵심은 낮은 위험의 확인 작업은 쉽게 하고, 삭제, push, 비밀값 접근은 자동화하지 않는 것입니다.

예시1: README 개선

README 개선은 첫 작업으로 좋습니다. 앱 동작을 바꾸지 않으면서 프로젝트 이해를 높일 수 있기 때문입니다.

README.md를 개선하고 싶습니다.
먼저 README.md와 package.json을 읽고 부족한 정보를 목록으로 정리해주세요.
아직 편집하지 말고, 제가 승인한 뒤 README.md만 수정해주세요.

승인 후에는 범위를 줄입니다.

README.md에 "로컬 개발"과 "테스트 실행" 섹션만 추가해주세요.
package.json에서 확인 가능한 명령만 사용하고, 배포 절차는 새로 만들지 마세요.

이 방식은 결과를 검토하기 쉽습니다.

예시2: 작은 버그 수정

버그 수정은 재현 조건이 중요합니다.

다음 버그를 조사해주세요.

현상:
- 검색창에 공백만 입력하면 전체 결과가 표시됩니다.

기대:
- 공백만 입력한 경우 검색하지 않은 상태처럼 처리합니다.

제약:
- 먼저 원인 후보를 설명하세요.
- 최대 1개 파일만 수정하세요.
- 수정 후 실행할 테스트 또는 수동 확인을 알려주세요.

수정 후 diff를 확인합니다.

git diff

그리고 리뷰를 요청합니다.

현재 git diff를 리뷰해주세요.
의도하지 않은 변경, 과한 추상화, 테스트 부족, 엣지 케이스 누락을 봐주세요.
문제가 없으면 수동 확인 절차 3가지를 정리해주세요.

예시3: 학습 자료나 상담 CTA 추가

콘텐츠 사이트나 문서 사이트라면 Claude Code로 자연스러운 다음 행동을 만들 수 있습니다.

이 글을 읽고 초보자용 CTA 3개를 제안해주세요.

목표:
- 첫 사용자의 불안을 줄임
- 무료 PDF, 유료 교재, 상담으로 자연스럽게 연결
- 각 문장은 80자 이내
- 강한 판매 문구는 피함

구현은 기존 패턴을 따르게 합니다.

기존 글 페이지에서 CTA 패턴을 찾아주세요.
같은 톤으로 이 글 끝에 CTA 하나를 추가하세요.
새 컴포넌트를 만들지 말고, 전역 스타일도 바꾸지 마세요.

처음에는 새 구조를 만들기보다 기존 패턴에 맞추는 것이 안정적입니다.

흔한 실패

첫째, 요청이 너무 큽니다. “앱을 좋게 만들어줘”는 작업이 아닙니다. “검색 입력의 공백 처리를 고치고 확인 방법을 알려줘”가 작업입니다.

둘째, 읽기 단계를 생략합니다. 구조를 설명하지 못한 상태에서 편집하면 위험합니다.

셋째, 권한을 너무 빨리 넓힙니다. 자동 승인보다 diff를 보는 습관이 먼저입니다.

넷째, 완료 메시지만 믿습니다. 테스트, 빌드, 브라우저 확인, git diff 중 하나는 꼭 확인하세요.

다섯째, 긴 대화를 계속 끌고 갑니다. 주제가 바뀌면 요약하고 새 세션으로 넘어가세요. 자세한 방법은 컨텍스트 관리에서 다룹니다.

막혔을 때 체크리스트

• claude --version이 동작하는가
• claude doctor가 무엇을 말하는가
• 현재 디렉터리가 프로젝트 루트인가
• git status가 이해 가능한 상태인가
• Windows에서 PowerShell과 CMD 명령을 섞지 않았는가
• WSL, SSH, 컨테이너라 로그인 코드 흐름이 필요한가
• .env나 키를 읽히려 하지 않았는가
• 위험한 권한 모드를 켜지 않았는가
• 테스트 명령이 실제로 존재하는가

진단 요청은 이렇게 합니다.

Claude Code가 기대대로 동작하지 않습니다.
파일은 수정하지 말고 진단만 도와주세요.

환경:
- OS:
- shell:
- 실행한 명령:
- 오류 메시지:
- 기대한 동작:

가장 안전한 확인부터 순서대로 제안해주세요.

Masa의 검증 메모

Masa가 ClaudeCodeLab 운영에서 반복해본 결과, 가장 안정적인 패턴은 “읽기, 계획, 작은 수정, 검증”이었습니다. 기사 작성, 번역, CSS 수정, 배포 스크립트 모두 같은 결론이었습니다.

작업 경계가 작으면 diff를 이해할 수 있습니다. 반대로 오래 자동 실행하면 나중에 왜 바뀌었는지 추적하기 어렵습니다. 초보자라면 첫 주에는 권한 확인을 남기고, 모든 git diff를 직접 보는 것을 추천합니다.

다음 단계

오늘은 중요하지 않은 저장소 하나를 열고, 읽기 전용 프로젝트 지도 만들기와 작은 README 개선만 해보세요.

명령과 프롬프트를 손元에서 보고 싶다면 무료 Claude Code Quick Reference Cheatsheet를 받으세요. 팀 도입, 교육, 실제 프로젝트 적용이 필요하다면 사이트의 교재와 상담 링크로 이어가면 됩니다.