Claude Code 다단계 계획 워크플로: 대규모 기능을 컨텍스트 한도 안에서 개발하기

핵심 메시지

• 큰 작업은 코드를 짜기 전에 플랜 모드로 코드베이스를 먼저 탐색하고 계획을 세운다.
• 계획을 여러 단계(multi-phase)로 쪼개면 한 컨텍스트 창을 넘어서는 기능도 나눠서 구현할 수 있다.
• 메모리(rules) 파일에 "극도로 간결하게"라는 지침을 넣으면 계획과 커밋 메시지가 읽기 쉬워진다.
• 계획을 GitHub 이슈로 저장하면 컨텍스트를 비워도 다음 창에서 이어서 작업할 수 있다.
• 단계마다 컨텍스트 사용량을 확인하며 진행하면 한도 초과로 인한 품질 저하를 피할 수 있다.

쉽게 이해하기

발표자는 자신의 내부 CLI에 새 명령어를 추가하는, 한 번의 컨텍스트 창으로는 끝나기 어려운 큰 기능을 예로 든다. 그는 코드를 바로 짜지 않고 받아쓰기 도구로 대충 적은 초기 프롬프트를 넣은 뒤, 탭(또는 시프트+탭)으로 플랜 모드를 켜는 것부터 시작한다.

플랜 모드는 Claude Code가 먼저 코드베이스를 탐색하도록 강제한다. 실제로 explore 서브에이전트가 현재 CLI 구조를 살피고 여러 파일과 패턴을 검색한 뒤, 명세에서 불분명한 부분에 대해 구체적인 확인 질문을 되던진다. 예를 들어 커밋 diff를 어느 저장소에서 가져올지, 위치 인자와 필수 옵션 중 무엇으로 받을지 등을 물어 사용자의 의도를 명확히 한다.

그가 받는 계획은 일반적인 Claude Code 계획과 달리 매우 간결하다. 이는 사용자 메모리(약 43줄) 파일 최상단에 "모든 상호작용과 커밋 메시지에서 문법을 희생해서라도 극도로 간결하게 쓰라"는 규칙을 넣어 두었기 때문이다. 또 "각 계획 끝에 미해결 질문 목록을 달라"는 규칙 덕분에 계획 직후 바로 답해야 할 질문들이 정리돼 나온다.

작업이 크다고 판단되면 그는 "계획을 계속 세워라, 그리고 다단계로 만들어라"라고 지시해 계획을 여러 구현 단계로 쪼갠다. 그런 다음 컨텍스트 사용량을 확인하고(예: 33k 토큰, 여유 83.7%) 오토액셉트로 전환해 "1단계 실행"처럼 단계별로 구현을 진행한다.

핵심은 컨텍스트 관리다. 그는 완료된 계획과 체크리스트를 GitHub 이슈로 만들어 두고 컨텍스트 창을 깨끗이 비운다. 이후 "이슈 24번을 가져와 4단계를 수행하라"처럼 클라우드에 저장된 계획을 다시 불러와 남은 단계를 이어간다. 이렇게 하면 작업 자산이 컨텍스트 밖에 남아 여러 창에 걸쳐 협업과 비동기 코멘트도 가능해진다.

주요 인사이트

• 충분한 사전 사고(계획)를 한 뒤에는 accept edits 모드로 공격적으로 맡겨도 되는데, 이미 구현을 이해하고 있기 때문이다.
• 자동 포매터가 파일을 바꾸는 등 Claude가 모르는 변경이 생기면 "파일을 다시 컨텍스트로 읽어라"라고 직접 알려 줘야 한다.
• Claude를 종료(Ctrl+C 두 번)하고 VS Code를 연 뒤 "claude continue"로 대화를 그대로 이어가는 흐름이 편리하다.
• 단계 사이에 변경을 커밋하거나 스테이징해 두면 어떤 단계에서 무엇이 추가됐는지 구분이 명확해진다.
• 상태줄에 현재 저장소·브랜치·스테이징/미스테이징/신규 파일 수를 표시하도록 커스터마이즈하면 진행 상황을 한눈에 볼 수 있다.

자주 묻는 질문

관련 AI 소식