AI 엔지니어와 알아보는 Claude Code 공략집 - 1편

Claude Code는 터미널에서 동작하는 에이전트형 코딩 도구다. 일반적인 챗봇처럼 코드 조각을 답변으로만 주는 방식이 아니라, 프로젝트 폴더 안에서 파일을 읽고, 코드를 수정하고, 명령을 실행하며, 작업 흐름을 이어간다. Anthropic은 Claude Code를 agentic coding tool로 설명한다.

이 글은 CLI에 익숙하지 않은 초보자를 기준으로 Claude Code를 처음 실행하는 과정을 정리한다. 나는 AI Agent 개발자 관점에서 Claude Code를 보되, 1편에서는 에이전트 구조보다 사용자가 막히기 쉬운 설치, 터미널, 프로젝트 폴더, 첫 실행 흐름을 먼저 다룬다.

Claude Code는 터미널에서 프로젝트를 읽고 수정하는 개발 에이전트로 동작한다.

이 글에서 다루는 범위

1편의 목표는 Claude Code를 설치하고, 프로젝트 폴더에서 실행하고, 첫 질문을 안전하게 던지는 것이다. 복잡한 자동화, MCP, 훅, 멀티 에이전트 워크플로우는 뒤쪽 편에서 다루는 편이 낫다. 초보자가 처음부터 너무 많은 개념을 같이 보면 터미널에서 현재 어느 위치에 있는지도 놓치기 쉽다.

이 글에서 다루는 내용은 다음과 같다.

Claude Code가 무엇인지
CLI와 터미널이 무엇인지
설치 전에 준비해야 할 것
Node.js와 npm의 역할
Claude Code 설치 명령
프로젝트 폴더에서 Claude Code 실행하기
초보자가 처음 입력하면 좋은 프롬프트
권한 요청과 명령 실행을 읽는 방법
자주 막히는 오류의 원인

Claude Code를 한 문장으로 이해하기

Claude Code는 개발자가 터미널에서 Claude에게 코드베이스 작업을 맡길 수 있게 해 주는 도구다. 사용자는 자연어로 작업을 설명하고, Claude Code는 현재 폴더의 파일을 살펴본 뒤 필요한 수정안을 만들거나 명령 실행을 제안한다.

중요한 점은 Claude Code가 브라우저 안에서만 동작하는 채팅 서비스가 아니라는 것이다. Claude Code는 로컬 개발환경 안에 들어온다. 그래서 프로젝트 파일, Git 상태, 테스트 명령, 패키지 설정과 연결된다.

이 차이는 초보자에게도 중요하다. 브라우저에서 “이 코드 고쳐줘”라고 말하면 사용자가 코드를 복사해서 붙여넣어야 한다. Claude Code에서는 프로젝트 폴더에서 바로 “이 에러 고쳐줘”라고 말할 수 있다. 그러면 도구가 현재 파일 구조를 읽고 작업을 이어갈 수 있다.

CLI가 먼저 어려운 이유

Claude Code를 쓰려면 터미널을 열어야 한다. 여기서 많은 초보자가 막힌다. CLI는 Command Line Interface의 줄임말이다. 버튼을 누르는 화면 대신 글자로 명령을 입력하는 방식이다.

터미널은 CLI 명령을 입력하는 창이다. macOS의 Terminal, Windows의 PowerShell, Windows Terminal, Linux의 shell이 여기에 해당한다. Claude Code는 이런 터미널 안에서 실행된다.

터미널은 Claude Code를 실행하고 프로젝트 폴더를 다루는 기본 작업 공간이다.

CLI가 어려운 이유는 명령 자체보다 현재 위치 개념 때문이다. 터미널에는 “현재 폴더”가 있다. 사용자가 어느 폴더에 있는지에 따라 명령 결과가 달라진다. Claude Code도 마찬가지다. 프로젝트 폴더 안에서 실행해야 그 프로젝트를 읽을 수 있다.

예를 들어 아래 명령은 현재 폴더 위치를 출력한다.

pwd

macOS와 Linux에서는 pwd가 현재 위치를 보여준다. Windows PowerShell에서도 pwd를 사용할 수 있다. 출력된 경로가 내가 작업하려는 프로젝트 폴더인지 확인하는 습관이 필요하다.

폴더 안의 파일 목록을 보는 명령은 운영체제마다 조금 다르다.

# macOS / Linux
ls

# Windows PowerShell
dir

처음에는 명령을 많이 외우려 하지 않아도 된다. Claude Code를 시작하는 데 필요한 것은 현재 폴더를 확인하고, 프로젝트 폴더로 이동하고, 설치 명령을 실행하는 정도다.

설치 전에 준비할 것

Claude Code를 설치하기 전에 세 가지를 준비한다.

Node.js
npm
Claude 계정 또는 Anthropic API 사용 환경

Claude Code의 공식 설치 흐름은 npm을 사용한다. Claude Code setup 문서에 따르면 설치 명령은 npm install -g @anthropic-ai/claude-code 형식이다. npm은 Node.js 생태계의 패키지 관리자다.

Node.js를 설치하면 보통 npm도 함께 설치된다. 그래서 초보자는 Node.js부터 설치하면 된다. Node.js는 공식 다운로드 페이지에서 운영체제에 맞게 받을 수 있다.

Claude Code 설치에는 Node.js와 npm 환경이 필요하다.

설치가 끝났으면 터미널에서 아래 명령으로 버전을 확인한다.

node -v
npm -v

두 명령이 각각 버전 번호를 출력하면 Node.js와 npm이 설치된 상태다. 예를 들어 v20.x.x처럼 나오면 Node.js가 실행되고 있다는 뜻이다.

만약 command not found, not recognized 같은 메시지가 나오면 Node.js가 설치되지 않았거나, 터미널이 Node.js 실행 경로를 찾지 못하는 상태다. 이 경우 터미널을 완전히 닫았다가 다시 열어보는 것부터 확인한다.

Claude Code 설치하기

Claude Code 설치 명령은 다음과 같다.

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

여기서 npm install은 npm 패키지를 설치한다는 뜻이다. -g는 global 설치를 의미한다. 특정 프로젝트 안에만 설치하는 것이 아니라, 터미널 어디에서나 claude 명령을 사용할 수 있게 설치한다는 의미다.

설치가 끝나면 아래 명령으로 Claude Code가 실행되는지 확인한다.

claude --version

버전이 출력되면 설치가 된 상태다. 이후 프로젝트 폴더로 이동해서 claude 명령을 실행하면 된다.

claude

Claude Code의 CLI 명령과 옵션은 CLI reference에 정리되어 있다. 초보자는 처음부터 모든 옵션을 볼 필요는 없다. 1편에서는 claude 명령으로 대화형 세션을 여는 것만 이해하면 충분하다.

프로젝트 폴더로 이동하기

Claude Code는 현재 폴더를 기준으로 프로젝트를 이해한다. 그래서 실행 전에 내가 작업할 프로젝트 폴더로 이동해야 한다.

예를 들어 바탕화면에 my-first-app이라는 폴더가 있다면 macOS에서는 대략 이런 흐름이 된다.

cd ~/Desktop/my-first-app
pwd
ls
claude

Windows PowerShell에서는 경로 형태가 다르다.

cd $HOME\Desktop\my-first-app
pwd
dir
claude

cd는 change directory의 줄임말이다. 현재 터미널 위치를 다른 폴더로 바꾼다. pwd로 현재 위치를 확인하고, ls 또는 dir로 파일 목록을 확인한 뒤, 그 위치에서 claude를 실행한다.

Claude Code는 현재 터미널이 위치한 프로젝트 폴더를 기준으로 파일을 읽는다.

초보자에게 가장 중요한 기준은 “package.json, pyproject.toml, requirements.txt, README.md 같은 프로젝트 파일이 보이는 위치인가”이다. 이 위치에서 Claude Code를 실행해야 도구가 프로젝트를 제대로 읽을 수 있다.

첫 실행에서 기대할 수 있는 흐름

처음 claude를 실행하면 인증이나 권한 관련 안내가 나올 수 있다. Claude Code는 로컬 파일과 명령 실행에 관여할 수 있기 때문에, 사용자가 작업 범위와 권한을 이해하는 것이 중요하다.

Claude Code에는 권한과 보안 모델이 있다. Anthropic은 Claude Code가 파일 수정, 명령 실행 같은 작업에서 사용자의 승인을 요구할 수 있다고 설명한다. 관련 개념은 identity and access management와 settings 문서에서 이어진다.

초보자는 첫 실행에서 다음 태도를 유지하는 것이 안전하다.

모르는 명령은 승인하지 않는다.
파일 삭제, 패키지 삭제, 데이터베이스 초기화 명령은 특히 주의한다.
Claude가 제안한 명령을 읽고 이해한 뒤 승인한다.
처음에는 개인 연습용 프로젝트에서 테스트한다.

Claude Code가 명령 실행을 제안하면 “무슨 명령인지”, “어느 폴더에서 실행되는지”, “파일을 바꾸는지”를 본다. 이 세 가지를 확인하면 사고 가능성이 줄어든다.

처음 입력하기 좋은 프롬프트

Claude Code를 처음 켠 뒤에는 큰 작업을 바로 맡기지 않는 편이 좋다. 먼저 프로젝트를 읽고 요약하게 만든다.

이 프로젝트 구조를 초보자도 이해할 수 있게 설명해 줘. 파일을 수정하지 말고 읽기만 해 줘.

이 프롬프트에는 중요한 조건이 있다. “파일을 수정하지 말고 읽기만 해 줘”라고 명시했다. 처음에는 읽기 중심으로 시작해야 Claude Code가 어떤 방식으로 프로젝트를 파악하는지 볼 수 있다.

다음 단계에서는 실행 방법을 물어볼 수 있다.

이 프로젝트를 로컬에서 실행하려면 어떤 순서로 명령을 입력해야 하는지 알려줘. 아직 명령을 실행하지 말고 설명만 해 줘.

이것도 안전한 방식이다. Claude Code가 곧바로 설치나 실행 명령을 돌리기보다, 먼저 설명하게 만든다.

세 번째 단계에서 실제 실행을 요청한다.

설명한 실행 절차 중 첫 번째 명령만 실행해 줘. 실행 전에 어떤 명령인지 다시 보여줘.

이 흐름은 AI Agent를 다룰 때도 기본에 가깝다. 한 번에 큰 목표를 던지는 대신, 관찰, 계획, 실행을 분리한다. 초보자는 특히 실행 단계를 작게 나누는 편이 안전하다.

Claude Code에게 맡기기 좋은 작업

Claude Code는 코드베이스를 읽고 수정하는 작업에 강점이 있다. 처음에는 아래 정도의 작업부터 시작하는 편이 좋다.

README를 읽고 실행 방법 정리하기
에러 로그를 보고 원인 후보 설명하기
작은 버그 수정하기
함수 하나에 주석 추가하기
테스트가 실패하는 이유 찾기
변경 전후 diff 설명하기

반대로 처음부터 맡기기 어려운 작업도 있다.

전체 아키텍처를 한 번에 갈아엎기
인증, 결제, 권한 로직을 검토 없이 수정하기
운영 데이터베이스에 연결된 명령 실행하기
대량 파일 삭제 또는 자동 포맷팅 실행하기
의존성 버전을 한꺼번에 올리기

Claude Code는 강력하지만, 모든 변경을 무조건 맡기는 도구는 아니다. 로컬 개발환경에서 실제 파일을 바꿀 수 있기 때문에 작업 범위를 작게 나누는 것이 중요하다.

초보자를 위한 작업 단위 쪼개기

좋은 요청은 작고 확인 가능하다. 예를 들어 “이 프로젝트 고쳐줘”는 범위가 너무 넓다. 대신 다음처럼 나누는 편이 낫다.

현재 발생한 TypeScript 에러의 원인을 찾아줘. 아직 파일은 수정하지 말고, 어떤 파일을 봐야 하는지만 알려줘.

방금 찾은 원인 중 가장 작은 수정으로 해결할 수 있는 방법을 제안해 줘. 수정 전후 코드를 비교해서 설명해 줘.

제안한 수정만 적용해 줘. 다른 파일은 건드리지 말아 줘.

이런 방식은 에이전트에게 목표와 제한 조건을 함께 주는 방식이다. 목표만 주면 Claude Code가 넓게 탐색할 수 있다. 제한 조건을 같이 주면 작업 범위가 줄어든다.

작업 범위를 작게 나누면 Claude Code의 수정 결과를 검토하기 쉬워진다.

파일 수정 전후를 확인하는 습관

Claude Code를 사용할 때 Git은 거의 필수에 가깝다. Git은 파일 변경 이력을 관리하는 도구다. Claude Code가 파일을 수정한 뒤에는 변경 내용을 확인해야 한다.

기본 확인 명령은 다음과 같다.

git status
git diff

git status는 어떤 파일이 바뀌었는지 보여준다. git diff는 실제 변경 내용을 보여준다. 초보자는 git diff 화면이 길게 나와도 당황하지 말고, 어떤 파일에서 어떤 줄이 바뀌었는지부터 보면 된다.

Git이 설치되어 있지 않다면 Git 공식 다운로드 페이지에서 설치할 수 있다. Claude Code를 본격적으로 사용하기 전에는 Git으로 변경 사항을 되돌릴 수 있는 상태를 만들어 두는 것이 안전하다.

권한 요청을 읽는 방법

Claude Code가 작업 중 명령 실행이나 파일 수정을 요청할 수 있다. 이때 사용자는 단순히 승인 버튼을 누르는 사람이 아니라, 실행 책임을 가진 개발자다.

권한 요청을 읽을 때는 네 가지를 본다.

실행하려는 명령이 무엇인지
현재 폴더가 어디인지
파일을 읽는 작업인지, 쓰는 작업인지
되돌릴 수 있는 작업인지

예를 들어 npm install은 의존성을 설치하고 lock 파일을 바꿀 수 있다. rm -rf는 파일을 삭제할 수 있다. git checkout -- .는 변경 내용을 되돌릴 수 있다. 명령마다 영향 범위가 다르다.

초보자는 모르는 명령이 나오면 Claude Code에게 먼저 설명을 요구한다.

방금 실행하려는 명령이 어떤 의미인지 초보자 기준으로 설명해 줘. 위험한 부분이 있으면 먼저 말해 줘.

이 한 문장을 습관으로 만들면 무심코 위험한 명령을 승인할 가능성이 줄어든다.

Claude Code의 메모리와 프로젝트 규칙

Claude Code는 프로젝트별 지침을 활용할 수 있다. Anthropic 문서에는 Claude Code의 memory 기능이 정리되어 있다. 프로젝트에서 반복적으로 지켜야 할 규칙, 빌드 명령, 테스트 명령, 코드 스타일을 기록해 두면 Claude Code가 이후 작업에서 참고할 수 있다.

다만 1편에서는 메모리를 깊게 설정하지 않는다. 초보자가 처음부터 규칙 파일을 복잡하게 만들면 오히려 디버깅이 어려워진다. 먼저 Claude Code를 직접 실행해 보고, 반복해서 알려줘야 하는 규칙이 생겼을 때 정리하는 편이 자연스럽다.

예를 들어 프로젝트 규칙은 이런 식으로 시작할 수 있다.

이 프로젝트에서는 TypeScript를 사용한다. 기존 코드 스타일을 유지한다. 파일을 수정하기 전에는 변경 계획을 먼저 설명한다. 테스트가 있으면 수정 후 관련 테스트를 실행한다.

핵심은 Claude Code에게 “무엇을 할지”뿐 아니라 “어떤 순서와 기준으로 할지”를 알려주는 것이다.

자주 막히는 문제

`claude` 명령을 찾을 수 없는 경우

설치 후 claude 명령을 찾을 수 없다는 메시지가 나오면 전역 npm 실행 경로가 터미널 PATH에 잡히지 않았을 가능성이 있다. 먼저 터미널을 닫았다가 다시 연다. 그래도 안 되면 npm 전역 설치 경로를 확인해야 한다.

npm config get prefix

이 명령은 npm이 전역 패키지를 설치하는 위치를 보여준다. 해당 위치의 실행 파일 경로가 PATH에 포함되어야 claude 명령을 어디서든 실행할 수 있다.

권한 오류가 나는 경우

macOS나 Linux에서 전역 npm 설치 중 권한 오류가 날 수 있다. 이때 무조건 sudo를 붙이는 방식은 장기적으로 권장하기 어렵다. npm의 전역 설치 경로를 사용자 홈 디렉터리 아래로 바꾸거나, Node 버전 관리 도구를 사용하는 방식이 더 안전하다.

초보자는 먼저 공식 Node.js 설치 후 터미널을 다시 열어 보고, 그래도 권한 오류가 반복되면 오류 메시지를 그대로 Claude나 검색에 넣어 원인을 확인하는 편이 낫다.

프로젝트를 못 읽는 것처럼 보이는 경우

Claude Code가 프로젝트 파일을 제대로 못 읽는 것처럼 보이면 현재 폴더가 잘못되었을 가능성이 높다. pwd와 ls 또는 dir로 현재 위치를 다시 확인한다.

프로젝트 루트에는 보통 다음 파일 중 하나 이상이 있다.

package.json
README.md
pyproject.toml
requirements.txt
.git

이런 파일이 전혀 보이지 않는다면 상위 폴더나 다른 폴더에 있을 수 있다.

응답은 맞는 것 같은데 수정이 이상한 경우

Claude Code가 만든 수정이 의도와 다르면 바로 추가 수정을 맡기기보다 변경 내용을 먼저 확인한다.

git diff

그 다음 Claude Code에게 변경 이유를 설명하게 한다.

방금 변경한 내용을 파일별로 설명해 줘. 내가 요청한 범위를 벗어난 수정이 있는지도 확인해 줘.

이 방식은 AI Agent 작업에서 매우 중요하다. 에이전트가 작업을 끝냈다고 해서 검토가 끝난 것은 아니다. 사용자는 변경 내용을 확인하고, 필요하면 되돌린다.

1편 정리

Claude Code를 처음 배울 때 가장 먼저 넘어야 하는 벽은 AI가 아니라 터미널이다. 현재 폴더가 어디인지, 어떤 명령을 실행하는지, 파일이 실제로 바뀌는지 이해해야 Claude Code를 안전하게 사용할 수 있다.

1편의 핵심은 다음과 같다.

Claude Code는 터미널에서 동작하는 에이전트형 코딩 도구다.
설치에는 Node.js와 npm이 필요하다.
설치 명령은 npm install -g @anthropic-ai/claude-code다.
프로젝트 폴더로 이동한 뒤 claude를 실행한다.
처음에는 파일을 수정하지 말고 읽기와 설명부터 시킨다.
명령 실행과 파일 수정 권한은 반드시 읽고 승인한다.
Git으로 변경 전후를 확인하는 습관이 필요하다.

다음 편에서는 Claude Code를 실제 프로젝트에 붙여서 “읽기 전용 분석 → 수정 계획 → 코드 변경 → 테스트 → diff 검토” 흐름으로 사용하는 방법을 정리한다.

AI 엔지니어와 알아보는 Claude Code 공략집 - 1편