저널 AI 활용

Claude Code 시작하기: 설치부터 첫 코드 수정, 권한 모드까지

터미널 창과 git 브랜치, 로봇 캐릭터로 Claude Code의 작업 흐름을 표현한 일러스트

핵심 요약

  • Claude Code는 코드베이스를 읽고 파일을 고치고 명령을 실행하는 에이전트형 코딩 도구입니다. 터미널 CLI, VS Code·JetBrains 확장, 데스크톱 앱, 웹에서 씁니다.
  • 준비물은 터미널, 프로젝트 폴더, Claude 구독(Pro·Max·Ultra·Team·Enterprise) 또는 Claude Console 계정입니다.
  • 설치는 운영체제별 설치 스크립트 한 줄이면 되고, 설치 후 claude --version으로 확인합니다.
  • 프로젝트 폴더에서 claude를 실행해 로그인한 뒤, 프로젝트 설명을 묻고 작은 수정부터 맡기면 됩니다.
  • Shift+Tab으로 바뀌는 권한 모드가 실행 범위를 정하므로, 처음에는 확인을 거치는 모드로 두는 편이 안전합니다.

Claude Code는 Anthropic이 만든 에이전트형 코딩 도구입니다. 터미널에서 실행하면 프로젝트 폴더를 읽고, 파일을 고치고, 명령을 실행하면서 작업을 끝까지 진행합니다. 처음 시작하려면 설치 명령 한 줄과 로그인만 있으면 됩니다. 이 글은 2026년 11월 기준 공식 문서(code.claude.com)의 설치·빠른 시작 안내를 따라, 설치부터 첫 코드 수정까지 순서대로 정리했습니다.

Claude Code는 무엇을 하는 도구인가

공식 문서는 Claude Code를 “코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며, 개발 도구와 연동하는 에이전트형 코딩 도구”로 설명합니다. 기능 요청이나 버그 수정을 평범한 문장으로 적으면, 여러 파일에 걸친 계획을 세우고 코드를 고친 뒤 동작을 확인하는 흐름으로 진행합니다. 테스트가 없는 코드에 테스트를 붙이거나, 린트 오류를 정리하거나, 의존성을 업데이트하는 일처럼 미뤄 둔 작업을 맡기기에도 적합합니다.

쓰는 자리도 여러 곳입니다. 터미널 CLI가 기본이고, VS Code와 JetBrains 확장, 데스크톱 앱, 브라우저(claude.ai/code)에서도 같은 도구를 쓸 수 있습니다. Slack, GitHub Actions, GitLab CI/CD에 연결해 자동화에 넣는 방법도 문서에 안내돼 있습니다.

준비물

  • 터미널 또는 명령 프롬프트
  • 작업할 코드 프로젝트 폴더
  • Claude 구독(Pro, Max, Ultra, Team, Enterprise) 또는 Claude Console 계정. Amazon Bedrock, Google Cloud, Microsoft Foundry 같은 클라우드 제공자로도 쓸 수 있습니다.

터미널 CLI와 VS Code·JetBrains 확장은 서드파티 제공자 연결도 지원하고, 데스크톱 앱은 유료 구독이 필요합니다. 처음에는 터미널 CLI로 시작하는 편이 가장 간단합니다.

설치하기

공식 문서가 권장하는 기본 설치 스크립트는 운영체제마다 다릅니다. macOS, Linux, WSL에서는 아래 한 줄이면 됩니다.

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

Windows는 PowerShell과 CMD 중 하나를 골라 실행합니다.

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

설치가 끝나면 새 터미널을 열고 claude --version을 실행해 버전 번호가 나오는지 확인합니다. 명령을 찾을 수 없다는 메시지가 뜨면 설치 경로가 PATH에 없는 경우이므로 공식 문서의 안내를 따라 경로를 추가하면 됩니다. Homebrew(brew install --cask claude-code)와 WinGet(winget install Anthropic.ClaudeCode)으로 설치한 경우에는 자동 업데이트가 되지 않으므로 주기적으로 업그레이드해야 합니다.

첫 세션 열기와 로그인

프로젝트 폴더로 이동해 claude를 실행하면 세션이 열립니다. 처음 한 번은 브라우저로 로그인하라는 안내가 나오고, 구독이나 Console 계정으로 인증하면 자격 증명이 저장되어 다음부터는 다시 로그인하지 않습니다. ANTHROPIC_API_KEY 환경 변수를 설정해 두었다면 키 사용을 승인하는 것으로 로그인을 건너뛸 수 있습니다.

claude
  • 세션이 열리면 /help로 명령 목록을, /resume으로 이전 대화를 이어갈 수 있습니다.
  • 계정을 바꾸거나 다시 인증하려면 세션 안에서 /login을 입력합니다.
  • Console 계정으로 처음 로그인하면 비용 추적을 위한 “Claude Code” 워크스페이스가 자동으로 만들어집니다.

첫 질문과 첫 코드 수정

처음에는 코드를 고치기 전에 프로젝트를 설명하게 해 보는 편이 좋습니다. 파일을 일일이 첨부하지 않아도 필요한 파일을 스스로 읽습니다. 세션에 아래처럼 물어보는 것만으로 시작할 수 있습니다.

what does this project do?

“where is the main entry point?”, “explain the folder structure”처럼 이어서 물으면 진입점과 폴더 구조까지 정리해 줍니다. 구조를 파악했다면 작은 수정부터 맡겨 봅니다. “add a hello world function to the main file”처럼 범위가 좁은 요청을 넣으면 해당 파일을 찾아 수정안을 보여 주고 적용 여부를 묻습니다. 이때 Shift+Tab으로 세션의 권한 모드를 바꿀 수 있습니다. 어떤 동작을 묻지 않고 실행할지 정하는 설정이므로, 처음에는 확인을 거치는 모드로 두는 편이 안전합니다.

Git 작업도 문장으로 맡긴다

Claude Code는 git과 직접 연동합니다. 변경 사항을 정리해 커밋 메시지를 쓰고, 브랜치를 만들고, 병합 충돌 해결을 도울 수 있습니다. 커밋 전에는 어떤 파일이 바뀌었는지 먼저 물어보는 습관이 좋습니다.

  • “what files have I changed?”
  • “commit my changes with a descriptive message”
  • “create a new branch called feature/quickstart”
  • “help me resolve merge conflicts”

프로젝트 규칙을 기억시키기: CLAUDE.md

Claude Code는 세션마다 새 컨텍스트로 시작합니다. 대신 프로젝트 폴더에 CLAUDE.md 파일을 두면 빌드 명령, 코딩 규칙, 폴더 구조 같은 내용을 매 세션 처음에 읽습니다. AGENTS.md를 쓰는 저장소라면 그 파일을 대신 읽습니다. 내가 고친 내용을 바탕으로 스스로 메모를 쌓는 자동 메모리 기능도 있고, /memory로 확인하고 고칠 수 있습니다. 규칙을 반드시 지키게 하려면 훅(hook)으로 특정 동작을 막는 방법을 함께 쓰는 것이 문서의 권장 방식입니다.

도입 전 체크리스트

  • 처음에는 확인을 거치는 권한 모드로 쓰고, 익숙해진 뒤 Shift+Tab으로 조정한다.
  • 프로젝트마다 CLAUDE.md에 빌드·테스트 명령과 규칙을 적어 두어 매번 설명하지 않는다.
  • 커밋과 브랜치 작업은 무엇을 바꿨는지 먼저 확인한 뒤 맡긴다.
  • 구독과 Console 과금 방식을 구분하고, 오래 걸리는 작업은 사용량을 확인한다.
  • 자동 업데이트되지 않는 설치 방식(Homebrew·WinGet)은 주기적으로 업그레이드한다.

자주 묻는 질문

Q. Claude Code는 무료로 쓸 수 있나요?

공식 문서 기준으로 Claude 구독(Pro, Max, Ultra, Team, Enterprise)이나 Claude Console 계정, 또는 Amazon Bedrock·Google Cloud 같은 클라우드 제공자가 필요합니다. 데스크톱 앱은 유료 구독이 필요하고, 터미널 CLI와 VS Code·JetBrains 확장은 서드파티 제공자 연결도 지원합니다.

Q. 설치했는데 claude 명령을 찾을 수 없다고 나옵니다

설치 경로가 PATH에 없을 때 나오는 메시지입니다. 공식 문서의 PATH 설정 안내를 따라 경로를 추가한 뒤 새 터미널에서 다시 실행해 보세요.

Q. 코드가 갑자기 바뀌지 않게 하려면 어떻게 하나요?

Shift+Tab으로 권한 모드를 바꿀 수 있습니다. 처음에는 변경 전에 확인을 받는 모드로 쓰고, 익숙해진 뒤 범위를 넓히는 편이 안전합니다.

Q. 매번 같은 설명을 반복하지 않으려면 어떻게 하나요?

프로젝트 폴더의 CLAUDE.md에 빌드·테스트 명령과 규칙을 적어 두면 매 세션 시작 시 읽습니다. AGENTS.md를 쓰는 저장소는 그 파일을 대신 읽습니다.

함께 보면 좋은 글

비슷한 도구의 가격 구조가 궁금하다면 GitHub Copilot 요금제 정리에서 2026년 기준 무료·유료 플랜과 AI 크레딧 계산 방식을 함께 볼 수 있습니다.

참고한 문서

  • Claude Code 개요: https://code.claude.com/docs/en/overview
  • 빠른 시작: https://code.claude.com/docs/en/quickstart
  • 프로젝트 기억(CLAUDE.md와 자동 메모리): https://code.claude.com/docs/en/memory

확인일: 2026년 11월 20일. 설치 명령과 화면 구성은 버전에 따라 달라질 수 있으므로, 처음 설치할 때는 공식 문서의 최신 안내를 함께 확인하시길 권합니다.