Claude Code의 Plan Mode와 CLAUDE.md

Claude Code는 전체 코드베이스를 이해하고 여러 파일을 수정하며 기능을 구축하고, 버그를 수정하고, 명령을 실행하는 에이전트 코딩 도구이다. 터미널, IDE, 데스크톱 앱 및 브라우저에서 사용할 수 있다.

단순히 질문에 답하는 챗봇이 아니라, 코드베이스를 이해하고 개발 작업을 함께 진행하는 도구이기 때문에, Claude가 프로젝트를 얼마나 이해하고 있는지, 어떤 범위까지 작업을 허용할 것인지, 변경 전에 충분히 분석하는 과정을 거치는지가 결과의 품질에 큰 영향을 준다.

Claude Code에서는 이를 위해 Permission Mode, Plan Mode, CLAUDE.md 같은 기능을 제공한다.

Permission Mode란?

Claude Code는 파일 수정, 명령 실행 등 실제 작업을 수행할 수 있기 때문에, 이러한 작업을 어느 범위까지 허용할지 설정하는 과정이 필요하다.
Permission Mode는 Claude가 이런 작업을 수행할 때 어느 수준까지 자동으로 실행할 수 있는지를 결정하는 설정이다.
기본 설정에서는 중요한 작업 전에 사용자의 승인을 요청하고, 자동 승인 수준을 높이면 Claude가 더 긴 작업 흐름을 중단 없이 진행할 수 있다.

Claude Code에서는 여러 permission mode를 제공하며, 그중 하나가 Plan Mode이다.
Permission Mode는 Shift + Tab 단축키를 통해 순환하며 변경할 수 있으며, 현재 어떤 모드로 동작하고 있는지는 Claude Code 화면 하단에서 확인할 수 있다.

Mode	설명
Default	작업에 따라 사용자 확인을 요청한다.
Accept Edits	파일 수정과 관련된 작업을 자동 승인한다.
Plan	코드 수정 없이 분석과 계획 수립에 집중한다.
Bypass Permissions	권한 확인 없이 작업을 수행한다.

Plan Mode란?

다른 permission mode가 실행 권한의 범위를 결정한다면, Plan Mode는 실행 자체를 유보하고 계획 수립에 집중하는 모드이다.
파일을 읽고 코드 구조를 분석하는 것은 가능하지만, 파일 편집이나 명령 실행은 하지 않는다.
관련 파일 탐색, 코드 구조 파악, 의존 관계 확인, 변경 범위 분석을 수행하여 수정 계획을 작성한다. 사용자가 계획을 검토한 뒤 구현 단계로 넘어갈 수 있다.
작은 기능 추가보다 리팩토링, 구조 변경, 처음 보는 레포지토리 분석처럼 영향 범위가 큰 작업에서 특히 유용하다.

CLAUDE.md는 무엇인가

CLAUDE.md는 Claude Code가 프로젝트 작업을 수행할 때 불러와서 참고하는 프로젝트 지침 파일이다.

Plan Mode가 ‘어떻게 변경할 것인가’를 고민하는 과정이라면, CLAUDE.md는 Claude가 어떤 기준으로 판단해야 하는가를 알려주는 파일이다.
프로젝트의 구조, 개발 규칙, 자주 사용하는 명령어 등을 작성해두면 Claude가 작업 과정에서 해당 내용을 참고한다.

주로 아래와 같은 정보를 작성한다.

• 프로젝트 실행 및 테스트 방법
• 디렉토리 구조
• 코드 작성 규칙
• 상태 관리 방식
• API 호출 패턴
• 수정하면 안 되는 영역

중요한 점은 CLAUDE.md를 프로젝트 설명서처럼 모든 정보를 넣는 공간으로 사용하는 것이 아니라, Claude가 작업하면서 실수하기 쉬운 부분을 알려주는 지침으로 활용하는 것이다.
또한 CLAUDE.md는 Claude의 장기 기억이나 학습 데이터가 아니라, Claude Code가 작업 과정에서 참고하는 프로젝트 컨텍스트이다.
CLAUDE.md는 Claude Code 세션이 시작될 때 자동으로 로드된다.

추가 활용법

• ~/.claude/CLAUDE.md는 전역으로 적용되며, 프로젝트 루트의 경우 해당 프로젝트 영역에서만 읽힌다. 하위 디렉토리에 작성한 내용은 해당 디렉토리 관련 작업에서 참고한다.
• @을 통해 다른 파일을 import 할 수 있다.
• 지시가 너무 많으면 컨텍스트 한계로 인해 일부가 충분히 반영되지 않을 수 있으므로, 간결하게 유지하는 것이 좋다.
• CLAUDE.local.md 파일을 .gitignore에 추가하여 개인적인 CLAUDE.md로 사용할 수 있다. (오버라이드)
• /init 명령어를 Claude Code 실행 디렉토리에서 실행하면, 프로젝트를 분석하여 CLAUDE.md 초안을 자동으로 만들 수 있다.

결론

결국 Claude Code를 잘 활용한다는 것은 코드를 더 많이 생성하게 만드는 것이 아니라, Claude가 올바른 판단을 할 수 있도록 컨텍스트와 작업 방식을 설계하는 것이다.
이러한 원리는 Claude Code뿐 아니라 다른 AI Agent를 활용할 때도 동일하게 적용된다.