Claude Code 설치부터 사용까지: 바이브코딩 시작 가이드

Claude Code는 터미널과 IDE에서 동작하는 에이전트형(agentic) AI 코딩 도구다. 단순 자동완성 수준을 넘어 레포 전체를 이해하고, 계획을 세우며, 파일 수정과 테스트, 빌드, 깃 작업까지 워크플로우 단위로 수행한다. GitHub Copilot 계열이 에디터 안에서의 생산성 향상에 초점을 둔다면, Claude Code는 프로젝트 단위의 작업을 끝까지 밀어붙이는 도구에 가깝다.

1. Claude Code란 무엇인가

Claude Code는 Anthropic의 Claude 모델을 기반으로 한 AI 코딩 에이전트다. 핵심 특징은 다음과 같다.

코드베이스 전체를 문맥으로 이해한다
자연어 지시를 계획 단계와 실행 단계로 분리해 처리한다
파일 수정 시 항상 diff를 제시하고 사용자 승인을 요구한다
로컬 개발 환경의 도구(git, 테스트 러너, 린터 등)를 직접 호출한다

즉, Claude Code는 “단순히 코드를 잘 써주는 도구”가 아니라 “개발자가 하던 일련의 작업을 대신 수행하는 에이전트”라는 성격을 가진다.

2. 실행 환경 준비

Linux 또는 macOS 환경 (윈도우도 가능)
Bash, Zsh, Fish 중 하나의 셸
npm 설치 방식을 사용할 경우 Node.js 18 이상

대부분의 개발 환경에서는 별도 추가 패키지 없이 바로 사용 가능하다.

3. Ubuntu에 Claude Code 설치하기

방법1: 네이티브 설치(권장)

가장 간단하고 권장되는 방식은 공식 설치 스크립트를 사용하는 것이다.

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

설치가 끝나면 설치 경로가 출력된다. 보통 ~/.local/bin/claude에 설치된다.

3.1.1 설치했는데 `claude`가 실행되지 않을 때

설치는 정상인데 claude: command not found가 나온다면, 설치 경로( ~/.local/bin/claude )가 PATH에 없기 때문이다.

다음의 파일이 보이면 설치는 이미 끝난 상태다.

ls ~/.local/bin/claude

PATH에 추가는 다음 한 줄이면 충분하다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

최종적으로 설정이 적용되었는지 확인한다.

claude --version

root 계정에서 사용하는 경우

서버나 컨테이너에서 root로 사용 중이라면, 가장 깔끔한 방법은 심볼릭 링크를 하나 만드는 것이다.

ln -sf /root/.local/bin/claude /usr/local/bin/claude
claude --version

이렇게 하면 이후 어떤 셸에서도 추가 설정 없이 claude를 바로 사용할 수 있다.

방법2: npm 기반 설치

Node.js 환경이 이미 준비되어 있다면 npm으로도 설치할 수 있다.

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

설치 위치는 보통 npm의 global bin 경로에 잡힌다.

npm bin -g

그 경로가 PATH에 없다면 같은 방식으로 PATH에 추가해야 한다.

export PATH="$(npm bin -g):$PATH"

개인 개발 환경에서는 네이티브 설치가, 재현성이 중요한 환경에서는 npm 설치가 유리한 편이다.

4. 터미널에서 Claude Code 사용하기(CLI)

4.1 기본 실행

프로젝트 루트에서 claude를 실행한다.

cd your-project
claude

이후부터는 대화형 프롬프트로 동작한다.

5. VS Code에서 GUI로 사용하기

Claude Code는 VS Code 확장 프로그램으로도 제공된다.

CLI가 더 강력한 기능을 제공하지만 대부분의 기능들은 GUI에서도 편하게 사용 할 수 있다.

5.1 설치

VS Code 확장 검색에서 Claude Code를 설치한다.

5.2 사용 방식

에디터 우측 패널에서 Claude Code 패널을 연다
단축키로 현재 파일이나 선택 영역을 프롬프트에 첨부한다
변경 시 diff와 승인 UI가 표시된다

5.3 VS Code에서 Bedrock을 사용할 때 추가 설정이 필요한가

결론부터 말하면 필수는 아니다. VS Code 확장은 기본적으로 로컬에 설치된 Claude Code CLI 설정을 그대로 사용한다.

다만, VS Code에서만 명시적으로 Bedrock 설정을 고정하고 싶다면 VS Code 설정(JSON)으로 직접 지정하는 방식도 가능하다.

5.3.1 VS Code 설정으로 Bedrock 환경 변수 지정

다음은 VS Code settings.json에 직접 Bedrock 관련 환경 변수를 지정하는 예시다.

{
  "claudeCode.disableLoginPrompt": true,
  "claudeCode.environmentVariables": [
    {
      "name": "AWS_PROFILE",
      "value": "default"
    },
    {
      "name": "AWS_REGION",
      "value": "us-east-1"
    },
    {
      "name": "CLAUDE_CODE_USE_BEDROCK",
      "value": "1"
    }
  ],
  "claudeCode.selectedModel": "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
}

이 방식의 의미는 다음과 같다.

VS Code 내부에서 실행되는 Claude Code 프로세스에만 환경 변수를 주입한다
셸 환경 변수에 의존하지 않는다
Bedrock 사용 시 로그인 프롬프트를 완전히 비활성화한다

5.3.2 이 방식이 유용한 경우

GUI로 실행한 VS Code에서 환경 변수가 전달되지 않는 경우
CLI와 VS Code에서 서로 다른 AWS Profile을 쓰고 싶은 경우
개발 환경별로 VS Code 설정을 분리하고 싶은 경우

5.3.3 어떤 방식을 쓰는 게 좋은가

개인 개발 환경: CLI 환경 변수 방식이 단순하고 직관적이다
서버, 컨테이너, 원격 개발: VS Code 설정 방식이 더 안정적이다

두 방식은 동시에 사용할 수 있으며, VS Code 설정이 존재할 경우 해당 값이 우선 적용된다.

6. 구독제 계정 연결 방식

Claude Code는 Anthropic 계정 기반 구독제(Pro, Teams, Enterprise 등)와 연동할 수 있다.

/login 명령으로 계정을 연결한다
개인 사용자는 Pro 계정이 적합하다
조직 환경에서는 Teams 또는 Enterprise가 적합하다

이 방식은 Anthropic 콘솔 기준으로 사용량과 비용을 관리한다.

7. API 키 기반 연결 방식

로그인 대신 API 키로 Claude Code를 운영할 수도 있다. 이는 CI 환경이나 키 회전이 필요한 조직 환경에서 유용하다.

7.1 설정 파일 위치

사용자 설정: ~/.claude/settings.json
프로젝트 설정: .claude/settings.json
로컬 전용 설정: .claude/settings.local.json

7.2 API 키 주입 예시

export ANTHROPIC_API_KEY="your-api-key"

{
  "apiKeyHelper": "printf %s \"$ANTHROPIC_API_KEY\""
}

이 방식은 키를 파일에 직접 저장하지 않아 보안상 유리하다.

8. Amazon Bedrock과 함께 Claude Code 사용하기

Claude Code는 Anthropic 계정이나 구독 없이 Amazon Bedrock을 통해 Claude 모델을 사용할 수 있다. 이 경우 비용은 AWS 계정으로 과금된다.

8.1 필수 환경 변수

아래 방식으로 export 하면 현재 셸 세션에만 적용된다. 서버나 재접속 환경에서는 영구 설정이 필요하다.

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

영구 적용 방법(권장)

Bash 기준으로 다음 중 하나에 추가한다.

사용자 단위: ~/.bashrc 또는 ~/.profile
시스템 전역(root/서버): /etc/profile.d/claude-code.sh

예시(사용자 단위):

echo 'export CLAUDE_CODE_USE_BEDROCK=1' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc

예시(시스템 전역):

cat << 'EOF' > /etc/profile.d/claude-code.sh
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
EOF

이렇게 설정하면 재로그인/재시작 후에도 Bedrock 설정이 유지된다.

8.2 AWS 인증 방식

Claude Code가 Bedrock을 사용하는 데 AWS CLI는 필수 요소는 아니다. 다만 가장 간단한 초기 설정 방법이 aws configure이다. AWS CLI를 설치하면 aws configure 명령을 사용할 수 있다. 또는 ~/.aws/credentials 파일을 직접 작성해도 된다.

AWS CLI 를 설치하는 방법은 다음과 같다.

Ubuntu 최신 버전이나 minimal 이미지에서는 awscli 패키지가 기본 apt 저장소에 없는 경우가 많다. 이때는 아래 방법 중 하나를 사용한다.

AWS 공식 v2 CLI 설치(권장)

apt update
apt install -y curl unzip
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip
./aws/install

설치 확인:

aws --version
aws configure

또 다른 방법으로 snap을 사용할 수도 있다.

snap install aws-cli --classic
aws configure

이후 Access Key, Secret Key, Region만 입력하면 된다.

AWS CLI 없이 환경 변수로 직접 설정하는 방법도 있다.

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

임시 자격 증명(STS)을 사용하는 경우에는 다음도 함께 설정한다.

export AWS_SESSION_TOKEN=your-session-token

Claude Code는 AWS SDK의 기본 자격 증명 체인을 그대로 사용하므로, 위 방식 중 하나만 충족되면 Bedrock 호출이 가능하다.

8.3 모델 설정

export ANTHROPIC_MODEL="global.anthropic.claude-sonnet-4-5-20250929-v1:0"
export ANTHROPIC_SMALL_FAST_MODEL="us.anthropic.claude-haiku-4-5-20251001-v1:0"

8.4 토큰 튜닝

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096
export MAX_THINKING_TOKENS=1024

사용하지 않는걸 권장하지만 제한이 필요하다면, 에이전트형 도구 특성상 출력 토큰 여유를 두는 것이 좋다.

9. Claude Code의 내부 구조와 설계 철학

Claude Code의 본질은 단순한 LLM UI가 아니라 로컬 도구 실행 레이어에 있다. 모델은 코드를 직접 실행하는 주체가 아니라, 무엇을 해야 하는지 계획하고 판단하는 역할을 맡는다. 실제 파일 수정, 테스트 실행, 빌드, 깃 명령과 같은 작업은 모두 로컬 개발 환경의 도구에 위임되며, Claude Code는 그 과정을 안전하게 중개한다. 이 과정에서 파일 변경이나 명령 실행처럼 위험할 수 있는 작업은 항상 사용자에게 명시적으로 제안되고, 승인 절차를 거친 뒤에만 수행된다.

이러한 구조를 기반으로 설정 또한 사용자, 프로젝트, 로컬, 조직 단위로 계층화되어 있다. 개인 개발 환경에서는 최소한의 설정으로 빠르게 사용할 수 있고, 조직 환경에서는 권한과 정책을 명확히 분리해 안전하게 운영할 수 있도록 설계되어 있다.

10. 더 깊게 사용하는 방법

10.1 CLAUDE.md 활용

CLAUDE.md는 특정 레포지토리에서 Claude Code가 따라야 할 운영 규칙과 작업 맥락을 정의하는 문서다. 브랜치 전략이나 커밋 규칙, 테스트 실행 방식, 민감 파일에 대한 접근 제한처럼 프로젝트마다 다른 기준을 이 파일에 명시해두면, Claude Code는 이후 모든 작업에서 이를 전제로 판단하고 행동한다. 다시 말해 CLAUDE.md는 Claude Code에게 해당 레포지토리의 암묵적인 룰과 관례를 학습시키는 역할을 하며, 사람이 반복해서 설명하지 않아도 일관된 방식으로 작업을 수행하도록 만드는 핵심 수단이다.

10.2 권한 제한

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

AI 도입 시 가장 우려되는 보안 문제를 구조적으로 해결할 수 있다.

10.3 MCP 확장

MCP(Model Context Protocol)를 사용하면 Claude Code를 외부 서비스와 자연스럽게 연동할 수 있다. 이슈 트래커나 문서 관리 도구, 내부 API와 같은 시스템을 MCP로 연결하면, Claude Code는 단순히 코드만 수정하는 도구를 넘어 프로젝트 전반의 맥락을 이해하고 작업할 수 있게 된다. 이를 통해 코드 변경과 이슈 관리, 문서 갱신, 내부 시스템 연동이 하나의 흐름으로 이어지며, Claude Code는 개발 환경 전반을 아우르는 플랫폼에 가까운 역할을 수행하게 된다.

11. 마무리

Claude Code는 강력한 에이전트형 코딩 경험을 제공하는 도구 중 하나다. 특히 Amazon Bedrock과 결합하면 구독 의존 없이도 조직 단위에서 안정적으로 운영할 수 있다.

단순히 AI가 코드를 대신 써주는 시대는 지났다. 이제는 AI가 개발자의 작업을 이해하고, 계획하고, 책임지고 실행하는 단계로 넘어가고 있다. Claude Code는 그 전환점에 서 있는 대표적인 도구이다.

[개개블] - 개발⌨️ 개발🐶 블로그

Claude Code 설치부터 사용까지: 바이브코딩 시작 가이드

1. Claude Code란 무엇인가

2. 실행 환경 준비

3. Ubuntu에 Claude Code 설치하기

방법1: 네이티브 설치(권장)

3.1.1 설치했는데 `claude`가 실행되지 않을 때

방법2: npm 기반 설치

4. 터미널에서 Claude Code 사용하기(CLI)

4.1 기본 실행

5. VS Code에서 GUI로 사용하기

5.1 설치

5.2 사용 방식

5.3 VS Code에서 Bedrock을 사용할 때 추가 설정이 필요한가

5.3.1 VS Code 설정으로 Bedrock 환경 변수 지정

5.3.2 이 방식이 유용한 경우

5.3.3 어떤 방식을 쓰는 게 좋은가

6. 구독제 계정 연결 방식

7. API 키 기반 연결 방식

7.1 설정 파일 위치

7.2 API 키 주입 예시

8. Amazon Bedrock과 함께 Claude Code 사용하기

8.1 필수 환경 변수

영구 적용 방법(권장)

8.2 AWS 인증 방식

8.3 모델 설정

8.4 토큰 튜닝

9. Claude Code의 내부 구조와 설계 철학

10. 더 깊게 사용하는 방법

10.1 CLAUDE.md 활용

10.2 권한 제한

10.3 MCP 확장

11. 마무리

티스토리툴바

Claude Code 설치부터 사용까지: 바이브코딩 시작 가이드

1. Claude Code란 무엇인가

2. 실행 환경 준비

3. Ubuntu에 Claude Code 설치하기

방법1: 네이티브 설치(권장)

3.1.1 설치했는데 claude가 실행되지 않을 때

방법2: npm 기반 설치

4. 터미널에서 Claude Code 사용하기(CLI)

4.1 기본 실행

5. VS Code에서 GUI로 사용하기

5.1 설치

5.2 사용 방식

5.3 VS Code에서 Bedrock을 사용할 때 추가 설정이 필요한가

5.3.1 VS Code 설정으로 Bedrock 환경 변수 지정

5.3.2 이 방식이 유용한 경우

5.3.3 어떤 방식을 쓰는 게 좋은가

6. 구독제 계정 연결 방식

7. API 키 기반 연결 방식

7.1 설정 파일 위치

7.2 API 키 주입 예시

8. Amazon Bedrock과 함께 Claude Code 사용하기

8.1 필수 환경 변수

영구 적용 방법(권장)

8.2 AWS 인증 방식

8.3 모델 설정

8.4 토큰 튜닝

9. Claude Code의 내부 구조와 설계 철학

10. 더 깊게 사용하는 방법

10.1 CLAUDE.md 활용

10.2 권한 제한

10.3 MCP 확장

11. 마무리

티스토리툴바

3.1.1 설치했는데 `claude`가 실행되지 않을 때