🤖 01. 시작

Claude Code를 처음 붙일 때 초보자가 제일 자주 실패하는 이유는, 실력이 부족해서가 아니라 시작 순서를 잘못 잡아서다. 설치는 했는데 로그인에서 막히고, 로그인은 됐는데 프로젝트 루트를 잘못 잡아 엉뚱한 폴더를 읽고, 결국 “이거 왜 안 돼?”로 끝난다. 이 문서는 그 시행착오를 줄이기 위해, 복붙 가능한 코드 중심으로 처음부터 끝까지 안내한다.

안내: 이 문서는 생성형 AI를 활용해 초안을 구성했고, Claude Code 공식 문서 기준으로 검토·보정했다.

flowchart LR
  A[환경 확인] --> B[설치]
  B --> C[설치 검증]
  C --> D[로그인]
  D --> E[프로젝트 진입]
  E --> F[첫 코드 작업]
  F --> G[검토/반복]

🧠 칠판 치트시트

• 1. OS에 맞는 설치 코드 1개만 실행
• 2. claude --version + claude doctor로 검증
• 3. 프로젝트 루트에서 claude 실행
• 4. 첫 요청은 “프로젝트 구조 설명”으로 시작
• 5. 작은 수정 1개 완료 후 반복 루프 진입

한 줄 결론

Claude Code 입문은 설치 코드 실행보다 설치 검증 → 로그인 → 프로젝트 루트 확인 3단계를 정확히 밟는 것이 핵심이다.

1) 설치 전 2분 프리체크 (실패율 낮추기)

먼저 내 환경이 최소 조건을 충족하는지 본다.
공식 기준: https://code.claude.com/docs/en/setup

macOS / Linux / WSL

uname -a
node -v || true
command -v curl || true

Windows PowerShell

$PSVersionTable.PSVersion
git --version

• Windows는 Git for Windows 준비가 권장된다.
• 메모리 4GB+ / 인터넷 연결은 사실상 필수다.

2) 설치 코드 (OS별 복붙)

공식 Quickstart: https://code.claude.com/docs/en/quickstart

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

대안 경로 (패키지 매니저)

brew install --cask claude-code

winget install Anthropic.ClaudeCode

관측: Homebrew/WinGet 경로는 자동 업데이트가 아니라 brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode를 주기적으로 실행해야 한다.

3) 설치 직후 검증 코드 (이 단계 생략 금지)

설치 끝나면 바로 상태를 확인한다.

claude --version
claude doctor

• --version은 설치 여부 확인
• doctor는 환경/설정 충돌을 빠르게 찾는 용도
• 문제 발생 시: https://code.claude.com/docs/en/troubleshooting

4) 로그인과 계정 타입 정리

인증 문서: https://code.claude.com/docs/en/authentication
요금/플랜: https://claude.com/pricing

claude

첫 실행 시 브라우저 로그인 흐름이 열린다. 계정 전환/재인증이 필요하면 세션 내부에서:

/login

로그아웃 후 재인증이 필요하면:

/logout

어떤 계정으로 로그인할 수 있나

• Claude Pro / Max
• Teams / Enterprise
• Claude Console
• Bedrock / Vertex / Foundry(조직 정책 기반)

5) 프로젝트 루트에서 시작하기 (가장 중요한 실전 포인트)

Claude Code가 “이 프로젝트”를 정확히 이해하게 하려면, 반드시 프로젝트 루트에서 시작해야 한다.

cd /path/to/your/project
pwd
claude

처음 들어가면 /help로 명령 목록을 보고, 이전 대화를 이어가려면 /resume을 사용한다.

6) 첫 10분 프롬프트 (바로 써먹는 버전)

처음부터 큰 기능 구현보다, 코드베이스 이해 질문으로 워밍업하면 정확도가 올라간다.

what does this project do?

where is the main entry point?

explain the folder structure in simple Korean

그다음 아주 작은 변경으로 첫 성공 경험을 만든다.

add a hello world function to the main file and show me the diff first

7) 첫 코드 작업 루프 (안전하게 반복)

아래 루프를 고정하면 초반 품질이 안정된다.

1. 요청: 작은 범위로 명확히 지시
2. 확인: 변경 파일/차이(diff) 먼저 검토
3. 승인: 수정 적용
4. 점검: 테스트/실행 확인
5. 정리: 변경 요약 + 다음 액션

이 흐름을 지키면 “수정은 됐는데 왜 바뀌었는지 모름” 문제를 줄일 수 있다.

8) 설정 파일로 초반 품질 올리기 (선택)

설정 문서: https://code.claude.com/docs/en/settings

개인 기본 설정 예시(개념용):

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "autoUpdatesChannel": "stable",
  "env": {
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "300000"
  }
}

• User/Project/Local 스코프가 다르므로, 팀과 공유할 값인지 개인값인지 먼저 구분한다.
• 민감 정보는 저장 위치와 권한을 분리해 관리한다.

9) 자주 막히는 지점 5개 + 즉시 대응

1. claude: command not found
   → 설치 셸 재시작 후 claude --version 재확인

2. 로그인 루프 반복
   → /logout 후 재로그인, 브라우저 차단 확장/정책 확인

3. 엉뚱한 파일 수정 제안
   → 프로젝트 루트(pwd)와 요청 범위를 다시 고정

4. 응답은 좋은데 실행이 안 됨
   → 테스트 명령/실행 명령을 함께 요청

5. 첫날부터 과도한 범위 요청
   → 기능 단위를 20~40분 작업 크기로 쪼개기

10) 현장형 미니 사례

사례 A (성공)

처음부터 “새 기능 전체 구현”을 요청하던 팀이, 첫 15분을 구조 파악 질문으로 바꿨다. 결과적으로 잘못된 파일 편집 횟수가 줄고 코드 리뷰 시간이 단축됐다.

사례 B (실패 → 복구)

설치 후 바로 기능 구현을 시작했는데 인증 문제가 반복됐다. claude doctor를 루틴에 넣고 /logout → /login으로 정리하니 같은 이슈가 재발하지 않았다.

11) 20분 온보딩 미션 (오늘 바로 실행)

1. OS별 설치 코드 실행
2. claude --version, claude doctor 통과
3. 프로젝트 루트 진입 후 claude
4. 구조 파악 질문 2개
5. 작은 수정 1개 + diff 검토
6. “이번 변경 요약 + 다음 액션 2개” 요청

완료 기준

• 같은 절차를 다른 프로젝트에서도 반복할 수 있다.
• 설치/로그인/첫 수정을 혼자 1회 재현할 수 있다.

다음 차시

• 🤖 02. 모델선택

다음 읽기

• 🤖 03. 운영스택 Skills·Memory·Teams
• 🤖 04. Agent Teams Cowork 심화
• 🤖 06. Chrome 연동 실전
• OpenClaw-10. OpenCode 연동

생성형 AI 활용 고지

이 문서는 Claude Code 공식 문서를 바탕으로 생성형 AI를 활용해 정리했으며, 최종 공개 전 사람이 검토·보정했다.