Claude Code 완전 정복 1편 — 무엇이고, Mac에 설치해서 첫 작업까지

채팅창에 코드를 복사해 붙이는 일에 지쳤다면

AI에게 코드를 물어보는 가장 흔한 방법은 이렇습니다. 에러 메시지를 복사하고, 관련 파일을 몇 개 붙여 넣고, 답을 받아 다시 에디터에 옮깁니다. 파일이 많아질수록 "이 파일도 보여줘야 하나?"를 계속 고민하게 됩니다.

Claude Code는 이 과정을 뒤집습니다. 내가 파일을 옮겨 주는 대신, Claude가 직접 프로젝트 폴더 안에서 파일을 읽고, 수정하고, 명령어를 실행합니다. 이 글은 Claude Code 시리즈의 첫 편으로, Claude Code가 무엇인지와 Mac에 설치해서 첫 작업을 해 보는 과정까지 정리합니다.

이 시리즈는 2026년 10월 기준 Claude Code 공식 문서를 바탕으로 정리했습니다. Claude Code는 업데이트가 잦아서 세부 동작은 버전에 따라 달라질 수 있습니다.

Claude Code는 무엇인가

Claude Code는 Anthropic이 만든 에이전트형 코딩 도구입니다. 일반 채팅과 다른 점은 Claude가 도구를 직접 쓴다는 것입니다.

	일반 AI 채팅	Claude Code
코드 전달	사용자가 복사해서 붙여 넣음	Claude가 필요한 파일을 직접 찾아 읽음
수정	답변을 보고 사용자가 옮김	Claude가 파일을 직접 수정 (승인 후)
실행	사용자가 터미널에서 실행	테스트, 빌드, git 명령을 Claude가 실행하고 결과를 읽음
반복	결과를 다시 붙여 넣으며 대화	실행 결과를 보고 스스로 다시 고침

쓸 수 있는 곳도 여러 군데입니다. 터미널(CLI), VS Code·Cursor 확장, JetBrains 플러그인, 데스크톱 앱, 웹(claude.ai/code)에서 같은 Claude Code를 쓸 수 있습니다. 이 글은 기능이 가장 많은 터미널 버전을 기준으로 합니다.

준비물

• macOS 13.0 이상 (Intel, Apple Silicon 모두 가능)
• 작업할 코드 프로젝트 폴더
• 다음 중 하나의 계정
  • Claude 구독 (Pro, Max, Team, Enterprise) — 공식 문서에서 권장하는 방식
  • Claude Console 계정 (선불 크레딧으로 API 사용)
  • Amazon Bedrock, Google Cloud, Microsoft Foundry 같은 클라우드 제공자 (회사 환경)

공식 문서가 안내하는 로그인 계정에 무료 플랜은 포함되어 있지 않습니다. 요금제별 가격과 사용량 한도는 자주 바뀌므로 Claude 요금제 페이지에서 직접 확인하는 것을 권합니다.

Mac에 설치하기

방법은 두 가지입니다.

방법 1. 공식 설치 스크립트 (권장)

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

설치 중에는 진행 표시가 나오지 않으니 끝날 때까지 기다리면 됩니다. 완료되면 새 터미널 창을 열고 확인합니다.

1claude --version

버전 번호가 나오면 성공입니다. 이 방식으로 설치하면 백그라운드에서 자동 업데이트됩니다.

command not found: claude가 나온다면 설치 경로가 PATH에 잡히지 않은 것입니다. 이 경우 공식 문서의 설치 문제 해결 페이지를 참고하세요.

방법 2. Homebrew

1brew install --cask claude-code

Homebrew 버전은 두 가지 채널이 있습니다.

• claude-code: 안정 채널. 보통 최신 버전보다 1주 정도 늦고, 큰 문제가 있는 릴리스는 건너뜁니다.
• claude-code@latest: 최신 채널. 새 버전이 나오자마자 받습니다.

주의할 점은 Homebrew 설치는 자동 업데이트되지 않는다는 것입니다. 주기적으로 brew upgrade claude-code를 실행해야 합니다.

첫 실행과 로그인

작업할 프로젝트 폴더로 이동해서 실행합니다.

1cd ~/projects/my-app
2claude

처음 실행하면 로그인을 요청합니다. 브라우저가 열리면 Claude 계정으로 인증하면 되고, 한 번 로그인하면 다음부터는 다시 할 필요가 없습니다. 실행 중에 계정을 바꾸고 싶으면 /login을 입력합니다.

처음 여는 폴더에서는 **이 폴더를 신뢰할지 묻는 창(workspace trust)**이 뜹니다. Claude Code는 프로젝트 안의 설정 파일을 읽고 명령을 실행할 수 있기 때문에, 내가 받은 출처를 알 수 있는 프로젝트에서만 신뢰를 허용하는 것이 안전합니다.

첫 작업 해 보기

어떤 파일을 보여 줘야 하는지 고민하지 않아도 됩니다. 그냥 질문하면 Claude가 필요한 파일을 찾아 읽습니다.

1이 프로젝트가 뭘 하는 건지 설명해줘

1이 프로젝트에서 쓰는 기술 스택이 뭐야?

1로그인 처리는 어느 파일에서 하고 있어?

수정도 같은 방식입니다.

1src/utils/date.ts의 formatDate 함수에 잘못된 날짜가 들어오면
2빈 문자열을 반환하도록 고치고, 테스트도 추가해줘

Claude가 파일을 고치려고 하면 변경 내용을 보여 주고 승인을 받습니다. 처음에는 하나하나 확인하면서 Claude가 어떻게 일하는지 익히는 것이 좋습니다.

권한 모드: Claude가 어디까지 혼자 해도 되는가

Claude Code에는 "물어보지 않고 해도 되는 범위"를 정하는 권한 모드가 있습니다. 실행 중에 Shift+Tab을 누르면 모드가 바뀝니다.

모드	묻지 않고 하는 일	언제 쓰나
Manual (default)	파일 읽기만	모든 작업을 직접 확인하고 싶을 때
acceptEdits	읽기, 파일 수정, 기본 파일 명령(mkdir, mv 등)	코드 수정을 빠르게 반복할 때
plan	읽기 위주 (수정 전에 계획부터 승인)	고치기 전에 구조부터 파악할 때
auto	대부분의 작업 (별도 모델이 위험한 동작을 검사)	긴 작업, 승인 창이 너무 많을 때

이 밖에 CI용 dontAsk, 모든 확인을 건너뛰는 bypassPermissions도 있습니다. bypassPermissions는 공식 문서에서도 격리된 컨테이너나 VM에서만 쓰라고 안내합니다. 내 Mac에서 평소에 켜 둘 모드가 아닙니다.

어떤 모드로 시작하는지는 버전과 요금제에 따라 다릅니다. 화면 아래쪽의 모드 표시를 확인하고, 익숙해질 때까지는 Manual이나 acceptEdits를 쓰는 것을 권합니다.

꼭 알아야 할 명령어

터미널에서 실행하는 명령

명령	하는 일
claude	대화형 세션 시작
claude "빌드 에러 고쳐줘"	첫 메시지를 넣은 채로 시작
claude -p "이 함수 설명해줘"	한 번 답하고 바로 종료 (스크립트용)
claude -c	이 폴더에서 가장 최근 대화 이어 하기
claude -r	지난 대화 목록에서 골라 이어 하기

세션 안에서 쓰는 명령

명령	하는 일
/help	사용 가능한 명령 보기
/clear	대화 기록 비우고 새로 시작
/init	프로젝트를 분석해서 CLAUDE.md 초안 생성
/usage	사용량 확인
/exit 또는 Ctrl+D 두 번	종료

/init은 처음 쓰는 프로젝트라면 꼭 한 번 실행해 볼 만합니다. 빌드 명령, 테스트 방법, 코드 규칙을 정리한 CLAUDE.md 파일을 만들어 주고, Claude는 다음 세션부터 이 파일을 읽고 시작합니다. CLAUDE.md를 다루는 법은 3편에서 자세히 정리합니다.

처음 쓸 때 기억할 세 가지

1. 구체적으로 요청합니다. "버그 고쳐줘"보다 "잘못된 비밀번호를 입력하면 빈 화면이 뜨는 로그인 버그 고쳐줘"가 훨씬 정확한 결과를 냅니다.
2. 큰 작업은 단계로 나눕니다. "DB 테이블 추가 → API 만들기 → 화면 만들기"처럼 순서를 적어 주면 중간에 확인하기 쉽습니다.
3. 먼저 탐색하게 합니다. 바로 고치게 하기보다 "먼저 관련 코드를 분석해줘"로 시작하면 엉뚱한 곳을 고치는 일이 줄어듭니다.

핵심 한 줄

Claude Code는 Claude가 내 프로젝트 폴더 안에서 직접 읽고, 고치고, 실행하는 도구입니다. Mac에서는 설치 스크립트 한 줄로 시작할 수 있고, 처음에는 권한 모드를 보수적으로 두고 Claude가 일하는 방식을 지켜보는 것이 좋습니다.

다음 편에서는 Mac 터미널 설정, VS Code·데스크톱 앱·Chrome 연동처럼 Mac에서 더 편하게 쓰는 방법을 다룹니다.

참고 자료

• Claude Code 개요
• Quickstart
• 설치 및 고급 설정
• 권한 모드