01-개념

01. 개념 — Claude Code는 무엇이고 무엇이 아닌가

한 문장 정의

Anthropic 공식 문서는 Claude Code를 다음과 같이 설명한다.

“Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser.”

의역: Claude Code는 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하고, 개발 도구들과 연동하는 에이전트형 코딩 도구다. 터미널, IDE, 데스크톱 앱, 브라우저에서 모두 쓸 수 있다.

— Anthropic, Claude Code overview (sources/01-anthropic-official/claude-code/claude-code-overview.md)

채팅 LLM과 무엇이 다른가

ChatGPT 같은 채팅형 LLM은 사용자가 코드를 복사해서 붙여넣고, 답변을 받아서 다시 IDE에 붙여넣는다. 컨텍스트의 운반은 사람이 한다.

Claude Code는 다르다. 그 자체가 다음 권한을 가진다.

파일 시스템 접근: 코드베이스 전체를 직접 읽는다.
파일 편집: 사용자의 승인 후 직접 파일을 수정한다(diff를 먼저 보여줌).
명령 실행: git, npm, pytest 같은 로컬 도구를 직접 호출한다.
다중 파일 작업: 한 작업이 여러 파일에 걸쳐 있어도 스스로 묶어서 처리한다.

한국어 자료 중 wookingwoo의 가이드(sources/21-korean-resources/blogs/wookingwoo-claude-code-vibe-coding-start.md)는 같은 차이를 다음 4개 특징으로 정리한다.

코드베이스 전체를 문맥으로 이해
자연어 지시를 계획과 실행으로 분리 처리
파일 수정 시 diff 제시 및 사용자 승인 요구
로컬 개발 도구(git, 테스트 등) 직접 호출

”에이전트형”이 의미하는 것

Anthropic 공식 문서가 예시로 드는 명령 한 줄이 에이전트형의 의미를 가장 잘 보여준다.

claude "write tests for the auth module, run them, and fix any failures"

이 한 줄은 다음을 모두 포함한다.

auth 모듈을 코드베이스에서 찾는다.
테스트를 작성한다.
테스트를 실행한다.
실패한 테스트를 수정한다.

사람이 단계마다 끼어들지 않는다. Claude Code 내부의 도구 호출 루프(Tool Loop)가 끝까지 돌아간다. 이 루프 자체를 우리는 **하네스(Harness)**라고 부르며, Part 2에서 자세히 다룬다.

무엇이 아닌가

오해를 줄이기 위해 Claude Code가 아닌 것도 정리한다.

❌ 단순 자동완성: GitHub Copilot처럼 다음 줄을 제안하는 도구가 아니다.
❌ IDE 플러그인: VS Code 확장이 있지만, 본체는 CLI이다.
❌ 클라우드 전용: 로컬 머신에서 도는 것이 기본이며, Anthropic API/Bedrock 등 다양한 백엔드를 쓴다.
❌ 자율 무인 시스템: 파일 쓰기·명령 실행마다 권한을 묻는 것이 기본 동작이다(Plan Mode 등 변형은 Part 5에서).

설치 30분이 의미 있는 이유

이 챕터의 목적은 단순 설치 가이드가 아니다. 30분 안에 첫 세션을 띄우면 “에이전트가 진짜로 내 파일을 만지고 있다”는 감각을 얻는다. 이 감각이 없으면 이후 챕터의 모든 설명이 추상적으로 들린다.