Claude Code의 기초

Claude Code는 Anthropic이 개발한 CLI(터미널) 기반 AI 코딩 에이전트입니다. "이 버그 고쳐줘" 같은 자연어 지시만으로 파일을 읽고 고치고, 명령을 실행하고, Git 커밋까지 스스로 처리합니다. 기존 AI 도구가 "코드를 짜 주는" 데서 멈췄다면, Claude Code는 "태스크를 완수해 주는" 쪽으로 한 걸음 더 나간 도구입니다.

이 글을 읽고 나면 Claude Code가 무엇인지 설명할 수 있고, 내 컴퓨터에 설치해 첫 대화를 시작할 수 있습니다.

핵심 요약

• Claude Code는 터미널에서 동작하는 AI 코딩 에이전트로, 자연어 지시만으로 코드 작성부터 편집·실행까지 자율적으로 수행합니다
• 기존 AI 지원 도구와 달리 태스크 전체를 위임할 수 있는 에이전트형입니다
• 파일 조작·Git 조작·셸 명령 실행을 자동화해 자잘한 작업에서 벗어날 수 있습니다
• MCP(Model Context Protocol)로 데이터베이스·Notion 같은 외부 도구와 연동됩니다
• 설치는 npm 한 줄, 실행은 프로젝트 폴더에서 claude 한 단어입니다

기존 AI 채팅과 무엇이 다른가

일반 AI 채팅은 대화 상대입니다. 코드를 보여주면 답을 알려주지만, 그 답을 실제로 적용하는 건 사람의 몫입니다. Claude Code는 동료에 가깝습니다. 파일을 직접 열고, 고치고, 테스트를 돌려 결과를 확인합니다.

요리법을 알려주는 사람 vs 부엌에 들어와 실제로 요리하는 사람.

이 차이는 Claude Code가 택한 "에이전트형" 접근에서 나옵니다. 터미널에서 동작하기 때문에 특정 에디터에 얽매이지 않고, VS Code·JetBrains·Vim 등 어떤 환경과도 조합해 쓸 수 있습니다. 2025년 출시 이후 국내외에서 빠르게 퍼진 이유도 여기에 있습니다.

지원형 도구와 에이전트형 도구

GitHub Copilot 같은 기존 AI 지원 도구는 코드 자동완성이 주 기능입니다. 사람이 코드를 쓰는 도중에 다음 줄을 예측해 제안하는 방식이라, 주도권은 항상 사람에게 있고 AI는 보조 역할입니다.

반면 Claude Code는 AI가 자율적으로 정보를 모으고, 실행하고, 검증하는 루프를 돌립니다. 사람은 지시를 내리고 결과를 확인하면 됩니다. 즉 AI "지원" 개발에서 AI "주도" 개발로의 전환입니다.

에이전트 루프는 어떻게 도나

Claude Code는 아래 세 단계를 태스크가 끝날 때까지 자율적으로 반복합니다.

1. 컨텍스트를 모은다 — 파일을 읽고, 검색하고, 프로젝트 구조를 파악합니다
2. 행동한다 — 코드를 쓰고, 명령을 실행합니다
3. 결과를 검증한다 — 테스트나 빌드로 확인합니다

각 단계의 결과를 보고 다음에 무엇을 할지 판단하므로, 몇 번 반복할지와 어떤 순서로 진행할지는 태스크마다 달라집니다. 이것이 "코드를 짜 준다"와 "태스크를 완수해 준다"의 차이입니다.

다만 모든 태스크를 맡기면 되는 건 아닙니다. 단순한 오타 수정이나 한 줄짜리 변경은 손으로 하는 편이 빠를 때도 있습니다. 규모와 복잡도에 따라 가려 쓰는 것이 중요합니다.

Cursor·Codex 같은 다른 도구와의 상세 비교는 Claude Code vs Cursor vs Codex 비교에서 다룹니다.

핵심이 되는 5가지 능력

Claude Code는 다재다능하지만, 실무에서 체감이 큰 능력은 아래 다섯 가지입니다.

1. 코드 생성

"○○ 만들어줘"라고 지시하면 필요한 파일을 만들고 코드를 구현합니다. 복잡한 애플리케이션이라면 기술 선택을 놓고 먼저 질문을 던지기도 하므로, 대화하면서 진행하는 형태가 됩니다.

2. 파일 조작

사람이 직접 파일을 열어 고칠 필요가 없습니다. 기존 코드베이스를 읽고 이해한 뒤 적절한 위치에 적절한 변경을 가합니다. 수수해 보여도 가장 자주 쓰이는 능력입니다.

3. Git 연동

브랜치 생성, 커밋, 풀 리퀘스트 작성까지 한 번에 처리합니다. 다만 커밋 메시지 내용은 완전히 맡겨 두기보다 그때그때 확인하는 편이 좋습니다. 자세한 흐름은 Git 조작 자동화에서 다룹니다.

4. 외부 도구 연동

MCP(Model Context Protocol)를 통해 데이터베이스, Notion, GitHub Issues 같은 외부 서비스에 접속합니다. 처음에는 서버 설정이 진입 장벽처럼 느껴지지만, 한 번 설정해 두면 활용 범위가 크게 넓어집니다. MCP — 외부 도구 연결하기를 참고하세요.

5. Bash 실행

셸 명령을 직접 실행해 빌드·테스트·배포까지 자동화합니다. "테스트를 실행해 보고 실패하면 고쳐줘" 같은 지시가 가능한 이유입니다. 파괴적인 명령을 실행하기 전에는 먼저 확인을 요청하므로, "실수로 지워버렸다" 같은 사고를 막을 수 있습니다.

설치와 첫 실행은 어떻게 하나

터미널을 열고 한 줄을 입력합니다.

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

npm이 없다면 먼저 Node.js를 설치해야 합니다. 공식 사이트에서 LTS 버전을 받으세요. 설치가 끝났는지 확인합니다.

claude --version

버전 숫자가 나오면 성공입니다. 작업할 폴더로 이동한 뒤 실행합니다.

cd 내프로젝트폴더
claude

처음이라면 브라우저가 열리며 로그인을 요구합니다. Claude 계정으로 인증하면 끝입니다. 운영체제별 상세 절차는 설치와 초기 설정 (Mac·Windows), 계정·인증 방식은 로그인과 인증 설정에서 다룹니다.

첫 대화는 무엇부터 하나

가장 안전한 첫 지시는 "읽기만 하는" 질문입니다.

이 폴더에 뭐가 들어 있는지 설명해줘.

Claude가 파일을 직접 훑어보고 정리해 줍니다. 이때 "파일을 읽어도 될까요?" 하고 물어볼 수 있습니다. 승인하면 진행됩니다.

데모: TODO 앱을 한마디로 만들기

읽기에 익숙해졌다면 만들기를 시켜 봅니다.

# Claude Code 실행
claude

# 사용자 지시
> TODO 앱 만들어줘

Claude Code는 먼저 기술 선택을 물어봅니다. "React와 Vue.js 중 어느 쪽을 쓸까요?", "데이터는 로컬 스토리지에 저장할까요?" 같은 확인입니다. 선택지를 고르거나 직접 입력해 답하면, 아래 단계를 자동으로 실행합니다.

1. 프로젝트 디렉터리 생성
2. 필요한 패키지 설치
3. 파일 구조 설계
4. 코드 구현
5. 로컬 서버 실행

간단한 앱이라면 이것만으로 돌아가는 결과물이 나옵니다. 사람은 지시를 내리고, 질문에 답하고, 마지막에 동작 확인만 하면 됩니다.

Claude Code가 질문해 오는 이유

Claude Code는 사용자의 의도를 정확히 파악하기 위해 필요에 따라 질문을 던집니다. 예를 들어 "인증 기능 추가해줘"라고 지시하면 이런 질문이 돌아올 수 있습니다.

• 인증 방식은 무엇을 쓸까요? (JWT, 세션, OAuth)
• 사용자 정보는 어디에 저장할까요?
• 비밀번호 재설정 기능은 필요한가요?

질문을 생략하고 멋대로 구현을 밀어붙이는 게 아니라 중요한 결정은 사람에게 맡긴다는 설계 철학 덕분에, 의도와 다른 구현이 나오기 어렵습니다. 질문이 귀찮게 느껴진다면 프로젝트 규칙을 미리 적어 두는 CLAUDE.md 작성법이 답입니다.

알아두면 좋은 안전장치

기본 설정에서는 파일을 고치거나 명령을 실행하기 전에 항상 확인을 요청합니다. 익숙해지기 전까지 이 설정을 그대로 두세요. 무엇을 하려는지 읽고 승인하는 과정이 곧 학습입니다.

교육 현장에서도 처음 며칠은 확인 요청을 일일이 읽는 분이 훨씬 빨리 "이 도구가 무엇을 할 수 있는지"를 체득합니다. 승인이 번거로워지는 시점이 오면 퍼미션 설정 최적화에서 허용 범위를 조정하면 됩니다.

연습 문제

1. 아무 폴더에서나 claude를 실행하고 "이 폴더 구조를 설명해줘"라고 물어보세요.
2. 답변이 실제 폴더 내용과 맞는지 직접 확인해 보세요.
3. 작은 폴더를 새로 만들고 "TODO 앱 만들어줘"를 시도해, 어떤 질문이 돌아오는지 기록해 보세요.
4. 종료는 Ctrl+C 두 번 또는 /exit입니다.

정리

• Claude Code는 Anthropic이 개발한 CLI 기반 AI 코딩 에이전트로, 에디터를 가리지 않습니다
• 자연어 지시로 코드 작성·편집·Git 조작·외부 도구 연동·셸 실행까지 자율적으로 처리합니다
• "컨텍스트 수집 → 행동 → 검증" 루프를 돌리는 에이전트형이라 태스크 전체를 위임할 수 있습니다
• 중요한 결정은 사람에게 묻고, 파괴적 조작 전에는 확인을 요청하는 안전장치가 기본입니다
• 설치 후 첫 세션의 흐름은 첫 세션 실전, 세션 조작법은 기본 조작과 명령어로 이어집니다