Claude Code란: Pro 플랜 기본 포함과 2026년 달라진 점
Claude Code는 터미널에서 직접 Claude와 대화하며 코드를 작성·수정·탐색할 수 있는 CLI 도구다. 공식 pricing 페이지 기준으로 Pro($20/월) 이상 모든 유료 플랜에 기본 포함되어 있고, 더 많은 사용량이 필요하다면 Max 플랜($100/월, Pro 대비 5배 사용량)을 선택할 수 있다.
2026년 들어 변화 속도가 눈에 띄게 빨라졌다. 릴리스 노트 기준으로 v2.1.152(2026-05-27)부터 Fast mode의 기본 모델이 Opus 4.7로 업그레이드됐다. Fast mode는 Opus의 추론 능력을 더 빠른 응답 속도로 제공하는 옵션인데, 이번 업그레이드로 속도와 품질 두 축을 동시에 끌어올리는 구성이 됐다.
2026-03-23부터 Computer Use 기능이 Pro/Max 플랜 대상 리서치 프리뷰로 추가됐다. 파일 열기, 화면 클릭, 내비게이션까지 Claude Code가 직접 수행할 수 있는 수준으로 확장됐다. 아직 프리뷰 단계이므로 프로덕션 환경보다는 탐색·실험용으로 쓰는 게 안정적이다.
Claude Cowork도 눈여겨볼 변화다. 2026-04-09 GA로 전환되면서 Pro 이상 모든 유료 플랜에 무료 포함됐고, Claude Code와 통합된 데스크톱 에이전트 앱 형태로 제공된다. CLI에 익숙하지 않은 팀원과 작업을 공유할 때 유용한 진입점이 된다.
설치와 초기 설정: 최신 버전 유지가 보안상 필수인 이유
Node.js가 설치된 환경이라면 설치는 한 줄이다.
npm install -g @anthropic-ai/claude-code이미 설치했다면 업데이트도 같은 명령으로 처리한다. Claude Code는 자체 업데이트 알림을 띄우기도 하지만, 놓치는 경우가 많으니 주기적으로 직접 실행하는 편이 낫다.
v2.1.149(2026-05-22)에서 PowerShell 퍼미션 바이패스 취약점이 패치됐다. 이 취약점은 Windows 환경에서 권한 확인을 우회할 수 있는 경로를 열어두는 문제였다. 공식 릴리스 노트에서 보안 픽스로 명시되어 있으므로, 아직 구버전을 쓰고 있다면 즉시 업데이트가 필요하다. claude --version으로 현재 버전을 확인한다.
설치 후 첫 실행은 프로젝트 디렉토리로 이동한 뒤 claude 명령을 입력하면 된다. 첫 실행 시 Anthropic 계정 인증 플로우가 진행되고, 이후 대화형 프롬프트가 열린다.
퍼미션 모드는 기본값이 수동 확인이다. Claude가 파일을 편집하거나 셸 명령을 실행할 때마다 승인 여부를 묻는다. --dangerously-skip-permissions 플래그로 자동 승인으로 전환할 수 있지만, 이름 그대로 위험한 선택이다. 신뢰하는 프로젝트에서도 처음에는 수동 확인으로 시작해서 어떤 액션이 발생하는지 파악한 뒤 허용 범위를 단계적으로 확장하는 게 낫다.
CLAUDE.md 작성법: 프로젝트 맥락을 LLM에 주입하는 핵심 파일
CLAUDE.md는 Claude Code가 프로젝트를 시작할 때 자동으로 읽어들이는 컨텍스트 파일이다. 세션마다 “이 프로젝트는 어떤 구조인가요?”를 반복 설명하지 않아도 되는 가장 확실한 방법이다.
로드 우선순위는 다음 순서다. 글로벌 설정인 ~/.claude/CLAUDE.md가 먼저 로드되고, 프로젝트 루트의 CLAUDE.md가 그 위에 적용된다. 하위 디렉토리에 있는 CLAUDE.md는 해당 디렉토리에서 작업할 때 추가로 로드된다. 모노레포처럼 여러 서브 패키지가 있는 구조라면 각 패키지 디렉토리에 별도 CLAUDE.md를 두는 방식이 효과적이다.
파일에 포함할 내용은 네 가지가 핵심이다.
디렉토리 권한 정의 — 어느 경로에 쓰기가 허용되고, 어디는 읽기만 가능한지 명시한다. “절대 수정 금지” 경로를 명문화하면 Claude가 실수로 중요한 파일을 건드리는 일을 크게 줄일 수 있다.
자주 쓰는 명령어 목록 — 빌드, 테스트, 린트, 배포 명령어를 코드 블록으로 정리해두면 Claude가 직접 실행할 수 있다. 환경 변수 이름, 패키지 매니저 선택(npm vs yarn vs uv 등)도 함께 기록한다.
아키텍처 결정사항 — 왜 이 기술 스택을 선택했는지, 어떤 패턴을 따르는지 한 문장씩 이유를 달아두면 Claude가 엉뚱한 방향으로 설계를 제안하는 빈도가 줄어든다.
금지 행동 — “테스트에서 DB를 mock하지 않는다”, “레거시 auth 모듈은 수정하지 않는다” 같은 제약을 명시적으로 쓴다. LLM은 암묵적 합의를 추론하지 못하므로 문자로 남겨야 한다.
효과적인 구조는 표와 코드 블록을 적극 활용하는 것이다. 긴 문단보다 표 한 줄이 LLM이 참조하기에 훨씬 정확하다. CLAUDE.md가 없을 때와 있을 때의 차이를 가장 빠르게 체감하는 방법은, 빌드 명령어 하나를 CLAUDE.md에 적어두고 Claude에게 “빌드해줘”라고 요청해보는 것이다. CLAUDE.md 없이는 “어떤 명령어인가요?”를 다시 묻지만, 있으면 바로 실행한다.
CLAUDE.md는 처음 한 번 만들고 끝내는 파일이 아니다. 세션에서 새로운 가드 조건을 발견했다면 그 자리에서 파일에 추가하는 습관을 들이면, 반복 교정 없이도 점점 정확해지는 작업 환경을 만들 수 있다.
서브에이전트로 복잡한 작업 병렬 처리하기
서브에이전트는 Claude Code 안에서 독립된 컨텍스트와 별도 도구 권한을 갖는 작업 단위다. 메인 에이전트가 작업을 정의하고, 서브에이전트가 실제 수행을 맡은 뒤 결과를 반환하는 구조다.
서브에이전트가 유리한 상황은 분명히 있다. 대용량 코드베이스에서 특정 패턴을 찾거나, 동시에 여러 파일의 분석이 필요하거나, 메인 에이전트의 컨텍스트를 오염시키지 않고 실험을 해야 할 때다. 단순한 파일 편집 한두 건에 서브에이전트를 굳이 띄울 필요는 없다.
에이전트 타입 선택은 역할 기준으로 결정한다. 코드베이스를 읽고 위치를 파악하는 작업에는 읽기 전용 탐색에 특화된 Explore 타입이 적합하다. 구현 전 설계·계획을 잡는 단계에서는 Plan 타입을 쓴다. 두 타입 모두 파일을 편집하거나 코드를 실행하지 않으므로, 메인 컨텍스트를 보호하는 사전 탐색 단계로 활용하기 좋다.
병렬 실행이 진가를 발휘하는 패턴은 독립적인 리서치를 동시에 위임할 때다. “프론트엔드의 폼 유효성 검사 로직을 찾아라”와 “백엔드 API 엔드포인트 목록을 정리해라”는 서로 의존성이 없으므로 두 서브에이전트를 동시에 실행할 수 있다. 순차 실행 대비 시간을 절반으로 줄일 수 있고, 각 에이전트가 독립적인 컨텍스트에서 작동하므로 서로의 결과에 영향을 받지 않는다.
서브에이전트 결과를 받은 뒤 통합할 때는 요약만 믿지 말고, 에이전트가 실제로 어떤 파일을 읽었는지 경로와 내용을 교차 확인하는 게 좋다. 검증 단계가 빠지면 서브에이전트를 쓴 의미가 줄어든다.
MCP 서버 연동: Claude Code 능력을 외부 도구로 확장하기
MCP(Model Context Protocol)는 Claude Code가 외부 도구·서비스에 접근하는 표준 인터페이스다. MCP 서버를 연동하면 Claude Code가 단순한 파일 편집기를 넘어, GitHub 이슈 조회, 데이터베이스 쿼리, Slack 메시지 전송까지 직접 수행하는 에이전트로 확장된다.
MCP 서버를 등록하는 방법은 두 가지다. 첫 번째는 claude mcp add 명령이다.
claude mcp add my-server --transport stdio -- /path/to/server/executable두 번째는 .claude/settings.json을 직접 편집하는 방법이다. 서버를 여러 개 등록하거나 세밀한 옵션 제어가 필요할 때는 직접 편집이 더 낫다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
}
}
}
}실전에서 많이 쓰는 MCP 서버 카테고리는 다음과 같다. filesystem은 지정된 디렉토리 내 파일 읽기·쓰기 권한을 부여한다. github는 이슈, PR, 코드 검색을 Claude Code에서 직접 수행하게 해준다. postgres나 sqlite 같은 데이터베이스 서버는 스키마 탐색과 쿼리 실행을 자연어로 처리할 수 있게 한다. Slack이나 Linear 같은 협업 도구 MCP 서버도 공식·커뮤니티 구현체가 있다.
인증 처리가 연동 시 가장 주의할 부분이다. API 키나 토큰은 환경 변수로 주입하고, .claude/settings.json에 평문으로 직접 적지 않는다. 파일이 Git에 커밋될 경우 토큰이 외부에 노출될 위험이 있다. env 필드에는 변수 이름만 적고, 실제 값은 셸 환경에서 로드하거나 별도 secret 관리 도구를 경유하는 방식이 안전하다.
실전 워크플로 최적화: 비용·속도·안전 균형 잡기
Pro와 Max 중 어느 플랜이 맞는지는 사용 패턴으로 결정한다. 하루에 수십 건의 짧은 질의 수준이라면 Pro로 충분하다. 코드베이스 전체를 분석하거나, 서브에이전트를 다수 띄우거나, 긴 컨텍스트가 필요한 리팩토링을 자주 한다면 Pro 한도를 빠르게 소진하게 된다. 사용량 초과가 잦다면 Max가 비용 대비 효율적인 선택이다.
hooks 설정은 반복 작업을 없애는 가장 실용적인 옵션이다. .claude/settings.json의 hooks 필드에 도구 호출 전후로 실행할 셸 명령을 등록할 수 있다. 예를 들어 파일 저장 후 자동 린트를 실행하거나, Claude가 특정 디렉토리를 변경하기 전에 git 상태를 확인하는 식이다. 설정 한 번으로 반복 확인 단계를 자동화할 수 있다.
컨텍스트 관리는 응답 품질에 직접 영향을 준다. 세션이 길어질수록 이전 대화 내용이 컨텍스트를 차지해 새 요청에 집중할 여유가 줄어든다. /clear 명령으로 대화 히스토리를 초기화하면 컨텍스트를 깔끔하게 비울 수 있다. 큰 작업이 완료되거나 전혀 다른 주제로 전환할 때 /clear를 습관적으로 실행하면 응답 정확도가 유지된다.
흔히 범하는 실수 세 가지다. 첫째, CLAUDE.md를 너무 장황하게 쓰는 것이다. 수백 줄이 넘어가면 정작 중요한 정보가 희석된다. 핵심 가드와 명령어만 남기고 상세 설명은 별도 문서로 분리하는 게 낫다. 둘째, 퍼미션을 과잉 허용하는 것이다. 자동 승인 범위를 넓게 설정할수록 Claude가 의도치 않은 파일을 변경하거나 삭제할 위험이 커진다. 셋째, 업데이트를 미루는 것이다. Claude Code는 빠른 릴리스 사이클로 보안 패치와 기능 추가가 자주 이뤄지므로, 구버전을 오래 유지하면 보안 위험과 기능 격차가 동시에 쌓인다.
자주 묻는 질문
Q. CLAUDE.md와 시스템 프롬프트는 어떻게 다른가?
시스템 프롬프트는 각 API 호출 시 직접 전달하는 방식인 반면, CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽어들이는 파일이다. 개발자가 직접 API를 호출하는 환경에서는 시스템 프롬프트를 매번 수동으로 관리해야 하지만, Claude Code 환경에서는 CLAUDE.md를 한 번 작성해두면 매 세션마다 자동으로 적용된다. 프로젝트 루트에 놓고 Git으로 관리하면 팀 전체가 동일한 컨텍스트를 공유할 수 있다는 점도 장점이다.
Q. MCP 서버를 추가했는데 Claude Code가 인식하지 못한다면?
가장 흔한 원인은 서버 프로세스가 제대로 실행되지 않는 경우다. claude mcp list 명령으로 등록된 서버 목록을 확인하고, 각 서버의 실행 명령(command, args)이 올바른지 점검한다. stdio transport를 쓰는 경우 실행 파일 경로가 절대 경로인지 확인하는 것도 중요하다. 상대 경로는 작업 디렉토리에 따라 달라져 오류가 생기기 쉽다.
Q. 서브에이전트를 적극적으로 쓰면 비용이 얼마나 늘어나나?
서브에이전트도 동일한 LLM 호출 비용이 발생한다. 병렬로 여러 서브에이전트를 띄우면 그만큼 토큰 소비가 늘어난다. Pro 플랜에서 서브에이전트를 자주 쓰다 보면 사용량 한도에 빠르게 도달할 수 있으므로, 정말 병렬 처리가 필요한 탐색·분석 작업에만 서브에이전트를 쓰고 단순 작업은 메인 세션에서 처리하는 게 비용 효율적이다. 사용량 패턴을 며칠 관찰한 뒤 Max 플랜 전환 여부를 결정하는 방식을 권장한다.
Q. Computer Use 기능은 어떻게 활성화하나?
현재 Pro/Max 플랜 대상 리서치 프리뷰로 제공되며, 별도 활성화 없이 플랜 조건을 만족하면 접근할 수 있다. 다만 아직 프리뷰 단계이므로 예상치 못한 클릭이나 입력이 발생할 수 있다. 실험적 용도로 쓸 때는 스크린샷 확인 단계를 유지하면서 진행하는 방식이 안전하다.
단계별 실행 가이드
1단계. Claude Code 설치 및 최신 버전 확인
npm install -g @anthropic-ai/claude-code 명령으로 설치하고, 이미 설치된 경우 같은 명령으로 업데이트한다. claude --version으로 현재 버전을 확인하고, v2.1.149 이상인지 반드시 점검한다. 그 이전 버전에는 PowerShell 퍼미션 바이패스 취약점이 있으므로 즉시 업데이트가 필요하다.
2단계. 프로젝트 디렉토리에서 첫 실행
작업할 프로젝트 디렉토리로 이동한 뒤 claude 명령을 실행한다. 첫 실행 시 Anthropic 계정 인증이 진행된다. 대화 프롬프트가 열리면 /help 명령으로 사용 가능한 슬래시 커맨드 목록을 확인한다.
3단계. CLAUDE.md 작성
프로젝트 루트에 CLAUDE.md 파일을 생성한다. 디렉토리 권한, 빌드·테스트 명령어, 금지 행동을 최우선으로 채운다. 파일이 완성되면 Claude Code를 재시작해 컨텍스트가 정상 로드되는지 확인한다.
4단계. 퍼미션 설정 조정
.claude/settings.json에서 허용할 도구 범위를 설정한다. 처음에는 파일 읽기만 자동 승인하고, 편집·셸 실행은 수동 확인 상태로 두는 것을 권장한다. 며칠 사용하면서 자주 허용하는 액션이 생기면 그때 allowlist에 추가한다.
5단계. MCP 서버 등록
필요한 외부 서비스의 MCP 서버를 claude mcp add 또는 .claude/settings.json 직접 편집으로 등록한다. 인증 토큰은 환경 변수로만 주입하고 파일에 평문으로 쓰지 않는다. 등록 후 claude mcp list로 연결 상태를 확인한다.
6단계. 서브에이전트 활용 및 컨텍스트 관리
복잡한 탐색·분석 작업은 독립적인 서브에이전트로 병렬 위임하고, 메인 세션에서는 통합과 실행에 집중한다. 큰 작업 단위가 끝날 때마다 /clear 명령으로 컨텍스트를 초기화해 이후 응답 품질을 유지한다.