Claude Code 입문 — CLI 하나로 코딩하는 법

게시일 2026-04-28수정일 2026-04-28

코드 에디터 없이 코딩한다는 게 무슨 뜻일까

"CLI로 코딩한다"는 말을 처음 들으면 대부분 이런 반응이 나옵니다. "터미널이요? 그거 개발자들만 쓰는 거 아닌가요?" 원래는 그랬습니다.

그런데 Claude Code는 그 터미널 위에서 AI가 코드를 대신 짜 주는 도구입니다. 직접 코드를 작성하는 게 아니라, AI에게 "이런 기능을 만들어줘"라고 지시하면 AI가 파일을 열고, 수정하고, 실행해 결과를 확인합니다.

2026년 4월 기준, AI 바이브코딩(vibe coding, AI에게 의도를 전달해 코드를 만들게 하는 방식)이 빠르게 확산되면서 Claude Code는 이 방식의 대표 도구 중 하나가 됐습니다. VSCode나 Cursor 같은 에디터가 "눈에 보이는 인터페이스"라면, Claude Code는 "터미널 한 줄로 실행하는 AI 에이전트"입니다.

Claude Code란 정확히 무엇인가

Claude Code는 Anthropic이 제공하는 CLI(Command Line Interface, 명령줄 인터페이스) 기반 AI 코딩 도우미입니다. 터미널에서 claude 명령어를 실행하면 대화형 세션이 열리고, 그 안에서 AI와 주고받으며 코드를 작성·수정·실행할 수 있습니다.

핵심은 "에이전트 방식"입니다. Claude Code는 단순히 답변을 텍스트로 주는 게 아니라, 실제로 파일을 읽고 수정하고 터미널 명령을 실행합니다. 하나의 프로젝트 폴더 안에서 AI가 직접 일을 처리하는 구조입니다.

다른 AI 코딩 도구와의 차이

Claude.ai 웹: 코드를 텍스트로 생성합니다. 복사해서 직접 붙여넣어야 합니다.
GitHub Copilot: 에디터 안에서 자동완성 방식으로 도움을 줍니다.
Claude Code: 프로젝트 전체를 파악하고, 파일을 직접 수정하며, 명령을 실행해 결과까지 확인합니다.

차이가 단순해 보이지만 실제 작업 흐름은 완전히 달라집니다. 웹 인터페이스에서는 AI가 생성한 코드를 복사해 에디터에 붙여넣고, 오류가 나면 다시 AI에게 가져가는 왕복 과정이 반복됩니다. Claude Code는 이 왕복을 없앱니다. AI가 처음부터 파일을 직접 다루기 때문입니다.

어떻게 작동하나 — 내부 구조 이해

Claude Code가 한 번의 지시로 여러 단계를 수행할 수 있는 이유는 도구(Tool) 시스템 때문입니다. 내부적으로 파일 읽기, 파일 쓰기, 터미널 명령 실행이라는 도구를 조합해 작업을 처리합니다.

"로그인 기능을 추가해줘"라고 입력하면 Claude Code는 다음 순서로 동작합니다.

프로젝트 구조를 파악합니다 — 파일 목록을 읽어 전체 맥락을 이해합니다.
관련 파일을 열어 현재 코드를 분석합니다.
수정할 내용을 계획합니다.
파일을 직접 편집합니다.
변경 사항을 요약해 보여줍니다.

이 모든 과정이 허락을 구하며 진행됩니다. 파일을 수정하거나 명령을 실행하기 전에 "이 작업을 해도 될까요?"라고 확인을 요청하는 권한 모드(Permission Mode)가 기본값입니다. 실수로 파일이 삭제되는 상황을 방지할 수 있는 구조입니다.

컨텍스트 관리가 중요한 이유

Claude Code는 대화 내용을 컨텍스트 창(context window)에 담아 작업합니다. 프로젝트가 크거나 대화가 길어지면 이전 내용이 잘려 나갈 수 있습니다. 이때 /compact 명령어로 대화를 요약하거나 /clear로 새 대화를 시작해 컨텍스트를 관리합니다.

프로젝트 루트에 CLAUDE.md 파일을 두면 AI에게 프로젝트 규칙을 사전에 전달할 수 있습니다. 예를 들어 "이 프로젝트는 TypeScript만 사용한다", "커밋 메시지는 한국어로 작성한다"와 같은 규칙을 기록해 두면, 세션을 새로 시작해도 AI가 해당 규칙을 지킵니다. 매번 반복해서 지시할 필요가 없어집니다.

지금 당장 따라하기 — 설치부터 첫 대화까지

1단계: 설치 환경 확인

Claude Code는 Node.js 18 이상이 필요합니다. 터미널을 열고 아래 명령어로 버전을 확인합니다.

v18.0.0 이상이 출력되면 바로 설치할 수 있습니다. Node.js가 없다면 nodejs.org에서 LTS 버전을 설치합니다.

2단계: Claude Code 설치

설치 후 아래 명령어로 정상 설치됐는지 확인합니다.

3단계: 실행 및 인증

프로젝트 폴더로 이동한 뒤 실행합니다.

처음 실행하면 인증이 필요합니다. Claude.ai 계정으로 로그인하거나 Anthropic API 키를 입력합니다. 2026년 4월 기준, Claude Max 플랜 구독자는 추가 API 비용 없이 사용할 수 있습니다.

4단계: 첫 번째 지시 내리기

세션이 열리면 자연어로 바로 지시할 수 있습니다.

Claude Code가 파일 목록을 읽고, README 초안을 만들어 보여준 뒤 "저장할까요?"라고 묻습니다. y를 입력하면 실제 파일이 생성됩니다. 처음에는 작은 프로젝트나 테스트용 폴더에서 이 흐름을 익히는 것이 좋습니다.

유용한 슬래시 명령어

/help — 사용 가능한 명령어 목록 확인
/clear — 현재 대화 컨텍스트 초기화 (토큰 절약에 유용)
/compact — 긴 대화를 요약해 컨텍스트 압축
/review — 현재 변경 사항을 AI가 코드 리뷰하도록 요청

언제 쓰고 언제 쓰지 말아야 할까

Claude Code가 강력한 상황이 있고, 오히려 비효율적인 상황이 있습니다. 판단 기준을 명확히 가져가면 도구를 잘못 쓰는 실수를 줄일 수 있습니다.

Claude Code가 유리한 경우

기존 프로젝트에 새 기능을 추가할 때 — 전체 파일 맥락을 AI가 직접 파악합니다.
여러 파일에 걸친 리팩터링이나 변수명 일괄 변경 작업
버그 원인을 추적하고 수정하는 과정
반복 작업 자동화 스크립트 작성
CLAUDE.md와 함께 사용하는 장기 프로젝트 관리

다른 도구가 더 나은 경우

단일 코드 스니펫 생성만 필요할 때 — Claude.ai 웹이 빠릅니다.
실시간 자동완성이 핵심일 때 — GitHub Copilot이 에디터에서 더 자연스럽습니다.
코드 변경 없이 개념 질문만 할 때 — 웹 인터페이스로 충분합니다.

주의: Claude Code는 파일을 직접 수정합니다. 처음 시작할 때는 git으로 버전 관리가 된 프로젝트에서 연습하는 것을 권장합니다. 변경 내역을 git diff로 확인하고 필요하면 git checkout으로 되돌릴 수 있어야 합니다.

여기까지 왔다면, 다음은

설치와 첫 대화까지 완료했다면, 이제 실제 프로젝트에 적용해 볼 차례입니다. 다음 학습 경로를 참고합니다.

Claude Code 공식 문서 — 슬래시 명령어 전체 목록과 고급 설정 참고
CLAUDE.md 파일 작성법 — 프로젝트 루트에 이 파일을 두면 AI에게 프로젝트 규칙을 사전에 전달할 수 있어 반복 지시를 줄일 수 있습니다.
MCP(Model Context Protocol) 연결 — Notion, GitHub 등 외부 서비스와 Claude Code를 연동해 작업 범위를 확장하는 방법

Claude Code를 처음 쓸 때 가장 흔한 실수는 "코드를 전부 AI에게 맡기겠다"는 기대입니다. 실제로는 AI가 초안을 만들고 사람이 검토·판단하는 협업 구조에서 가장 잘 작동합니다. 어디를 수정할지 지시하고, 결과물을 검토하는 역할이 여전히 필요합니다. 그 역할이 바이브코딩에서 말하는 "기획자의 감각"입니다.