Claude Code 프로젝트 계획: plan mode와 ak plan (2026)

Claude Code에 코드를 작성하게 하기 전에 왜 계획해야 할까요?

Claude Code에서 가장 흔한 실수는 프롬프트 하나를 입력하고 곧바로 코드를 작성하게 하는 거예요. 빠르게 느껴지지만 위험은 실제로 존재해요. AI는 종종 "엉뚱한 문제를 풀어" 버려요. 즉, 당신이 정말로 필요로 하는 것이 아니라, AI가 원한다고 생각한 것을 그대로 실행하죠. 차이를 확인할 때쯤이면 이미 수십 개의 파일이 바뀌어 있고, 손으로 고칠지 아니면 전부 버리고 처음부터 다시 시작할지 사이에서 오도 가도 못하게 돼요.

먼저 계획하면 바로 그 문제를 해결할 수 있어요. 코드를 건드리기 전에 Claude에게 계획을 세우도록 강제하면, 변경 범위를 미리 확인하고, 오해가 아직 저렴할 때 잡아내고, 작업을 경계 안에 가둘 수 있어요. 덤으로 토큰도 절약돼요. 계획의 한 줄을 고치는 것이, AI가 엉뚱한 것을 작성하게 한 뒤 다시 쓰게 하는 것보다 훨씬 저렴하니까요.

사람들이 좀처럼 언급하지 않는 이점도 있어요. 계획은 당신과 AI가 "완료의 정의"에 합의하는 자리예요. 어떤 파일이 바뀌고 어떻게 검증할지 계획에 명확히 적어 두면, 최종 차이를 대조할 기준이 생겨요. 코드를 읽으면서 "정말 내 의도대로 한 걸까?" 하고 고민할 필요가 없죠. 다시 말해, 계획은 리뷰를 어림짐작에서 체크리스트 대조로 바꿔 줘요.

계획해야 할 때: 변경이 여러 파일에 걸칠 때, 어떻게 접근할지 확신이 없을 때, 또는 아직 흐름을 모르는 낯선 코드베이스에서 작업할 때예요. 속도를 위해 건너뛰어도 될 때: 오타 수정, 상수 변경, 한 줄 손보기. 차이를 정확히 한 문장으로 설명할 수 있다면, 계획은 그저 부담일 뿐이에요. 이 도구가 처음이라면, 먼저 Claude Code가 무엇이고 어떻게 동작하는지를 읽고 아래 섹션으로 돌아오세요.

Claude Code의 plan mode란 무엇이며 & 어떻게 켜나요

Plan mode는 Claude Code의 퍼미션 모드 중 하나예요. 켜져 있을 때 Claude는 당신이 승인하기 전까지 파일을 읽고 계획을 제안하기만 할 뿐, 디스크에 어떤 변경도 쓰지 않아요. 허락하기 전에 AI가 무엇을 하려는지 볼 수 있게 해 주는 안전 브레이크라고 생각하세요.

켜는 방법은 세 가지예요.

1. Shift+Tab을 눌러 모드를 순환시켜요: default → acceptEdits → plan. plan에 도달할 때까지 계속 누르세요.
2. 터미널에서 바로 plan mode로 실행해요:

   claude --permission-mode plan

3. 상태 표시줄에서 확인해요. plan mode가 활성화되면 상태 표시줄에 ⏸ plan mode on이 표시돼요.

덜 알려진 팁: Claude가 계획을 만들고 나면 Ctrl+G를 눌러 그 계획을 텍스트 편집기에서 열고 실행 전에 손으로 편집할 수 있어요. 제약을 추가하거나, 불필요한 단계를 빼거나, 특정 파일을 가리키게 하세요. 계획을 편집하는 것이 이미 작성된 코드를 편집하는 것보다 항상 저렴해요.

위 단축키 동작은 Anthropic 공식 문서(best practices와 common workflows, 2026-08-09 확인)를 따라요. plan mode는 빠르게 발전하고 있으니, 지금 사용 중인 Claude Code 버전에서 단축키를 다시 확인하세요.

4단계 계획 루프: Explore → Plan → Implement → Commit

이것은 Anthropic이 권장하는 루프이자 가장 기억하기 쉬운 방식이에요. 각 단계에는 저마다의 목표가 있으니, 뭉뚱그리지 마세요.

Explore (plan mode에서)

해결책을 논의하기 전에, Claude가 기존 코드를 읽고 이해하게 하세요. plan mode에서는 읽기만 하고 편집은 하지 않으니, 마음껏 살펴보게 해도 돼요:

Read src/payments/ and src/orders/ to understand how the system handles payments today. No proposals yet - just summarize the flow.

큰 프로젝트에서는 조사를 subagent에게 넘겨 메인 세션의 컨텍스트를 깨끗하게 유지하세요. subagent가 읽고 요약을 돌려주므로, 메인 컨텍스트 윈도우가 수천 줄로 가득 차지 않아요. 이 단계의 목표는 해결책이 아니에요. 시스템이 지금 어떻게 동작하는지를 Claude가 자기 말로 설명하게 하는 거예요. 요약이 틀리면, 문제를 이해하지 못했다는 걸 바로 알 수 있어요.

Plan

Claude가 코드를 이해했다면, 구체적인 계획을 요청하세요:

I want to add discount codes to orders. Which files need to change? How does the flow work? Write a detailed plan before coding.

계획을 꼼꼼히 읽으세요. 뭔가 어긋나면 Ctrl+G를 눌러 손으로 편집하거나, 답장해서 Claude가 수정하게 하세요. 서둘러 승인하지 마세요.

Implement

계획을 승인하면(또는 Shift+Tab을 눌러 plan mode를 빠져나오면) Claude가 코딩을 시작해요. 핵심은 계획을 검증 기준으로 고정하는 것이에요. 완료를 증명하기 위해 AI가 무엇을 해야 하는지 정확히 명시하세요:

Execute the plan. When finished, run npm test and make sure every test passes. If any test fails, fix it until it is green.

Commit

마지막으로, 깔끔한 커밋으로 정리하고 PR을 여세요:

Commit the changes with a clear descriptive message, then open a pull request with a summary of what changed.

이 단계를 표준화하려면 Claude Code로 Git 워크플로 & PR 만들기도 함께 참고하세요.

큰 프로젝트를 페이즈 & 로드맵으로 나누기

위의 4단계 루프는 독립적인 기능에는 잘 맞아요. 하지만 며칠에서 몇 주씩 이어지는 프로젝트에서는 평면적인 계획이 무너져요. 컨텍스트가 옅어지고, Claude는 앞선 결정을 잊고, 당신은 통제력을 잃게 돼요.

더 오래가는 접근법은 Claude에게 여러 페이즈로 된 로드맵을 만들게 하는 거예요. 각 페이즈에는 목표, 건드릴 파일, 그리고 "완료" 기준을 명확히 적어요. 로드맵은 파일에 저장해서(예: PLAN.md나 plans/ 폴더) /clear를 실행해도 사라지지 않게 하세요. 그런 다음 각 페이즈를 저마다의 세션에서, 깨끗한 컨텍스트로 실행하세요. 페이즈 사이에 /clear를 실행해, 각 페이즈가 필요한 로드맵 조각만 불러와 가볍게 시작하도록 하세요.

페이즈를 나누는 원칙: 각 페이즈는 그 자체로 성립하고 그린 상태(테스트 통과, 앱 실행)로 끝나야 해요. 그래야 어느 시점에 멈춰도 코드가 어중간하게 남지 않아요. 페이즈 순서는 토대에서 바깥쪽으로 나아가야 해요. 백엔드/로직을 먼저 만들고 인터페이스는 나중에 만들어야, 뒤따르는 페이즈가 늘 단단한 바탕 위에 쌓일 수 있어요.

"Google로 로그인(OAuth)" 기능의 로드맵 예시예요:

복잡한 기능에는 interview → SPEC.md → 새 세션 패턴을 사용하세요. Claude에게 "요건에 대해 한 번에 하나씩 질문해서 나를 인터뷰하고, 그것을 SPEC.md에 적어 줘"라고 말한 다음, SPEC을 읽고 깨끗한 컨텍스트로 실행하는 새 세션을 여세요. 이것이 스펙 주도 개발(먼저 SPEC.md 작성)의 핵심이고, 많은 현업 개발자가 이미 사용하는 brainstorm → plan → cook → ship 워크플로와도 맞아떨어져요.

더 높은 품질의 계획을 위한 팁

• 검증 기준으로 고정하세요. 좋은 계획에는 늘 확인 방법이 담겨요. 어떤 테스트가 통과해야 하는지, 빌드가 돌아가야 하는지, 스크린샷이 일치해야 하는지 같은 것들이죠. /goal로 조건을 설정하면 AI가 각 단계 뒤에 스스로 평가하게 되어, 아직 끝나지 않았는데 "완료"라고 선언하는 걸 막아요. 다시 말해, 명확한 수용 기준이 있어야 /goal을 안전하게 실행할 수 있어요.
• CLAUDE.md를 작성하세요. 프로젝트 규칙(폴더 구조, 명명 규칙, 테스트 커맨드)을 CLAUDE.md 파일에 기록해 두면, 매번 반복하지 않아도 모든 계획이 올바른 컨텍스트 안에 머물러요.
• 프롬프트는 구체적으로. 정확한 파일을 가리키고, 따라야 할 샘플 패턴을 지목하고, 무엇이 범위 밖인지 밝히세요. 구체적일수록 계획이 목표에 더 가깝게 떨어져요.
• subagent로 계획을 리뷰하세요. 새로운 컨텍스트를 가진 subagent에게 계획이나 차이를 살펴보게 하세요. "깨끗한" 관점은 메인 세션이 익숙해져 놓치게 된 빈틈을 자주 잡아내요.
• /rewind를 사용하세요. 계획의 방향이 잘 풀리지 않으면, 그 위에 계속 덧대지 말고 되감아 다른 접근을 시도하세요.

차이를 한눈에 보도록 나란히 비교해 볼게요:

약한 프롬프트: "앱에 Google 로그인을 추가해 줘."

강한 프롬프트: "src/auth/와 src/routes/를 읽어 줘. src/auth/session.ts에 이미 있는 세션 패턴을 그대로 따라 Google 로그인(OAuth)을 추가하고 싶어. 범위 밖: 리프레시 토큰은 아직 없음. 계획을 작성해 줘: 어떤 파일이 바뀌는지, 콜백 흐름이 어떻게 동작하는지, 그리고 검증 기준(auth.spec.ts 통과)."

ak plan — 바로 쓸 수 있는 계획 스킬 (AgentKit)

혼동을 피하기 위한 짧은 참고: 여기서 말하는 AgentKit은 Claude Code용 키트(agentkit.best, ak CLI 사용)로, "OpenAI AgentKit"과는 완전히 다른 것이에요.

기능을 시작할 때마다 "계획을 세워 줘"라고 프롬프트를 치고 있는 자신을 발견한다면, 그 과정을 패키지로 만든 스킬이 있어요. ak-plan이에요. 프롬프트를 직접 쓰는 대신 스킬을 호출하면, 일관된 프레임워크로 로드맵이 포함된 멀티 페이즈 계획을 생성해 줘요. --html(보고 공유할 수 있는 자기 완결형 아티팩트)과 --wiki(AgentWiki에 게시)를 지원해요. 이 스킬은 Engineer Kit에 들어 있어요. 60개 이상의 스킬과 30개 이상의 워크플로를 갖춘 $99 패키지예요(사이트에 반복 요금 표기는 없어요). 바로 써 보고 싶다면 ak CLI를 활성화(링크로 20% 할인)하고 거기서 키트를 설치하면 돼요.

솔직히 말하면, 대부분의 작업에서는 네이티브 plan mode만으로도 이미 충분하고, 무료예요. 잘 계획하는 데 키트가 필요하지는 않아요. ak plan은 팀 전체를 위해 표준화되고 반복 가능하며 문서화된(아티팩트/wiki) 계획이 필요할 때 고려할 만한 것이지, 시작을 위한 전제 조건은 아니에요.

AI로 계획할 때 흔한 실수

• 너무 작은 것을 계획하기. 한 줄 바꾸려고 plan mode를 켜는 건 시간 낭비예요. 차이를 한 문장으로 설명할 수 있다면 그냥 실행하게 하세요.
• 검증 기준이 없는 긴 계획. 십수 단계짜리 계획은 그럴듯해 보이지만, 확인 기준이 없으면 AI는 실제로는 아무것도 돌아가지 않는데도 쉽게 "완료된 것처럼" 보일 수 있어요. 항상 테스트/빌드/명확한 조건을 붙이세요.
• 한 세션에 여러 작업을 몰아넣기. 서로 관련 없는 세 기능을 같은 컨텍스트 윈도우에서 진행하면 AI가 혼란스러워해요. 작업 사이에 /clear를 실행해 컨텍스트를 가볍게 유지하세요.
• 계획을 믿고 차이를 건너뛰기. 계획이 맞다고 코드가 맞는 건 아니에요. 커밋하기 전에 실제 차이를 반드시 읽어야 해요.

자주 묻는 질문 (FAQ)

plan mode는 추가 비용이 드나요?

아니요. plan mode는 Claude Code에 내장된 모드이지 유료 부가 기능이 아니에요. 현재 플랜(예: Pro는 월 $20, Max 5x는 월 $100) 안에서 사용해요.

어떤 키로 plan mode를 켜나요?

Shift+Tab을 눌러 default → acceptEdits → plan을 순환시키고 plan에서 멈추세요. 또는 claude --permission-mode plan으로 실행하세요. 상태 표시줄에 ⏸ plan mode on이 표시돼요.

plan mode가 스스로 파일을 편집하나요?

아니요. plan mode에서 Claude는 파일을 읽고 계획을 제안하기만 할 뿐, 당신이 승인하기 전까지 디스크에 변경을 쓰지 않아요. 그것이 이 모드의 핵심 안전 기능이에요.

plan mode는 extended thinking(think/ultrathink)과 어떻게 다른가요?

서로 달라요. plan mode는 퍼미션 모드로, AI에게 파일 편집을 허용할지 제어해요. extended thinking(think/ultrathink)은 모델의 추론 깊이를 늘려요. 둘을 함께 쓸 수 있어요. 안전을 위해 plan mode를 켜고, 문제가 복잡할 때는 더 깊은 사고를 요청하세요.

ak plan은 필수인가요, 그리고 네이티브 plan mode와 어떻게 다른가요?

필수가 아니에요. 네이티브 plan mode는 대부분의 경우에 충분하고 무료예요. ak plan은 표준화된 멀티 페이즈 계획을 --html/--wiki 아티팩트와 함께 생성하는, 바로 쓸 수 있는 스킬(AgentKit의 Engineer Kit 내)이에요. 과정을 반복하고 팀용 문서가 필요할 때 편리해요.

큰 프로젝트는 어떻게 나눠야 하나요?

Claude에게 멀티 페이즈 로드맵(각 페이즈에 목표, 건드리는 파일, 완료 기준)을 만들게 하고, 그것을 PLAN.md에 저장한 다음, 각 페이즈를 저마다의 세션에서 실행하고 페이즈 사이에 /clear를 실행해 컨텍스트를 깨끗하게 유지하세요.

결론 + 다음 단계

결론: Claude Code에 곧바로 코드를 작성하게 하지 마세요. Explore → Plan → Implement → Commit으로 진행하고, Shift+Tab으로 plan mode를 켜서 승인 전에 미리 보고, 큰 프로젝트는 깨끗한 컨텍스트로 페이즈에 나누세요. 다음으로, 완성된 실전 프레임워크로 brainstorm → plan → cook → ship 워크플로를, 그리고 큰 기능에 엄밀한 계획이 필요할 때는 스펙 주도 개발을 읽어 보세요.