Claude Code 활용법: 계획과 실행의 분리

TL;DR Highlight

Claude Code에서 리서치 → 계획 → 어노테이션 → 실행을 순서대로 분리하는 워크플로우가 AI 코딩 도구의 결과물 품질을 극적으로 향상시킨다.

Who Should Read

Claude Code나 Cursor 같은 AI 코딩 도구를 쓰고 있지만, 결과물이 기존 코드베이스와 안 맞거나 품질이 들쭉날쭉해서 고민인 개발자. 특히 중규모 이상 프로젝트에서 AI를 체계적으로 활용하고 싶은 사람.

Core Mechanics

핵심 원칙은 단순하다. Claude가 코드를 한 줄이라도 쓰기 전에, 반드시 서면 계획을 만들고 내가 검토·승인한 뒤에만 구현을 시작하게 한다. 이 '계획과 실행의 분리'가 토큰 낭비를 줄이고, 아키텍처 결정권을 개발자가 유지하는 핵심이다.
모든 작업은 리서치 단계부터 시작한다. Claude에게 관련 코드를 '깊이 있게' 읽으라고 지시하고, 그 결과를 research.md 파일에 쓰게 한다. 'deeply', 'in great details', 'intricacies' 같은 강조 표현을 안 넣으면 Claude가 함수 시그니처 수준에서 대충 훑고 넘어가기 때문에, 표면적 읽기가 아님을 명시적으로 신호해야 한다.
AI 코딩의 가장 비싼 실패 모드는 문법 오류가 아니라, 기존 시스템과 맞지 않는 구현이다. 이미 있는 캐싱 레이어를 무시하거나, ORM 컨벤션을 안 지키거나, 이미 존재하는 로직을 중복 구현하는 식이다. 리서치 단계가 이걸 막아준다.
계획은 Claude Code 내장 plan mode 대신 직접 만든 plan.md 파일을 쓴다. 내장 plan mode는 편집이 불편하고, 마크다운 파일은 에디터에서 직접 수정하고 인라인 노트를 달 수 있으며, 프로젝트에 실제 파일로 남기 때문이다.
계획 파일의 진짜 위력은 '어노테이션 사이클'에 있다. plan.md를 받은 뒤, 코드 주석처럼 인라인으로 피드백을 달아서 Claude에게 다시 넘긴다. '이 부분은 두 단계로 나눠라', '여기는 기존 유틸리티를 써라' 같은 식으로 1~6회 반복하며 계획을 다듬는다.
오픈소스에서 좋은 구현을 본 경우, 그 코드를 레퍼런스로 함께 붙여서 계획을 요청하면 Claude의 결과물이 훨씬 좋아진다. 예를 들어 sortable ID를 추가하고 싶으면, 잘 만든 프로젝트의 ID 생성 코드를 붙이고 '이 방식을 우리 프로젝트에 어떻게 도입할지 계획해줘'라고 하는 식이다.
구현 단계에서는 계획이 이미 충분히 구체적이므로, Claude가 중간에 멈추지 않고 한 번에 전체를 구현하도록 한다. 타입 체크를 중간중간 돌리면서 진행하게 하면, 구현 완료 후 '작동하는 코드'가 바로 나온다.
저자는 이 워크플로우를 9개월간 사용했으며, 대부분의 개발자가 하는 '프롬프트 → 에러 수정 → 반복' 방식이나 복잡한 MCP/도구 조합보다 비사소한 작업에서 훨씬 안정적인 결과를 낸다고 말한다.

Evidence

'깊이 읽어라'는 표현이 LLM에 왜 효과가 있는지 직관적으로 이해가 안 된다는 의견이 있었다. 이에 대해 실제 가치는 '계획 vs 비계획'이 아니라, 모델이 아키텍처·제약·불변조건에 대한 가정을 코드로 굳히기 전에 표면화하도록 강제하는 데 있다는 반론이 나왔다. LLM은 문법이 아니라 보이지 않는 가정에서 실패하고, 서면 계획이 그 가정을 디버깅하는 표면이 된다는 분석이다.
이 방식의 한계를 지적하는 댓글도 많았다. 한 번에 수천 줄을 생성하는 'big bang' 방식 대신 기술적 단계로 쪼개서 하나씩 구현해야 한다는 의견, 피드백을 장기적 지식베이스에 축적해야 같은 실수를 반복하지 않는다는 의견, 그리고 테스트 전략이 빠져 있다는 비판이 있었다. 특히 TDD 스타일로 특정 단계에서 특정 유형의 테스트를 계획에 포함시켜야 한다는 주장이 제기됐다.
3만 LOC 앱을 만든 개발자는 계획을 1,500줄 이하 배치로 나누는 방식을 추천했다. 그의 앱 뒤에는 약 10만 줄의 계획 문서가 있으며, 이 규모를 한 번에 만드는 건 불가능하다고 했다. 또 다른 개발자는 실제 결제(Stripe)가 되는 티켓팅 시스템을 이 방식으로 만들었는데, 핵심은 '빠른 코딩'이 아니라 병목을 '타이핑'에서 '검증'으로 옮기고, 실행 가능한 스캐폴드 + 얇은 수직 슬라이스 + 검증 하네스로 클로즈드 루프를 만드는 것이라고 강조했다.
spec 문서(~1k줄/10k LOC), plan, working memory(status.md + project_status) 3종류 문서 체계를 쓰는 개발자가 있었다. Gemini Pro로 계획을 생성하고 Codex로 실행하는데, Claude Code 월 $100보다 $20 플랜으로 더 빠르게 움직이며, Codex는 PR 올릴 때 가용 컨텍스트가 70% 이상 남아 있어 토큰 소진 문제가 없다고 했다. PR 성공률도 4/5로 CC 대비 역전됐다고 보고했다.
이미 Amazon Kiro, Google Antigravity, GitHub Spec Kit, OpenSpec 등 이 워크플로우를 제품화한 도구들이 나와 있다는 지적이 있었다. 다만 Antigravity를 쓴 개발자는, 계획에서 '가중 평균을 써야 한다'고 정확히 추론해놓고도 구현에서 슬쩍 일반 평균으로 다운그레이드하는 문제를 경험했다며, Claude Code가 구현 모호성을 사용자에게 물어보는 면에서는 더 낫다고 평가했다.

How to Apply

AI에게 코드를 바로 시키지 말고, 먼저 'research.md에 관련 코드를 분석해서 써줘'라고 지시한 뒤 그 문서를 검토하라. 그다음 'plan.md에 구현 계획을 써줘'라고 하고, 그 파일에 인라인 주석으로 피드백을 달아 1~6회 반복 수정한 뒤에야 구현을 시작하라. 이것만으로 기존 시스템과 충돌하는 구현이 크게 줄어든다.
Claude에게 코드를 읽으라고 할 때 'read this folder', 'understand how it works'만으로는 부족하다. 'deeply', 'in great details', 'all specificities' 같은 강도 표현을 넣어야 함수 시그니처 수준의 피상적 읽기를 넘어서게 된다. CLAUDE.md나 커스텀 스킬에 이 패턴을 기본으로 넣어두면 매번 타이핑할 필요가 없다.
큰 기능을 구현할 때는 계획을 1,500줄 이하 배치로 나누고, 각 배치마다 계획 → 검토 → 구현 → 검증 사이클을 돌려라. 한 번에 전체를 계획하고 구현하면 중간에 틀어졌을 때 처음부터 다시 해야 하지만, 배치 단위로 하면 손실을 최소화할 수 있다.
오픈소스에서 비슷한 기능의 좋은 구현을 발견하면, 그 코드를 레퍼런스로 프롬프트에 붙여서 계획을 요청하라. Claude가 처음부터 설계하는 것보다 레퍼런스 구현을 적용하는 방향이 훨씬 정확하고 빠르다.

Terminology

Annotation Cycle계획 문서에 코드 리뷰처럼 인라인 주석(피드백)을 달고, AI가 그걸 반영해 계획을 수정하는 반복 과정. 코드 PR 리뷰를 계획 단계에서 하는 것과 비슷하다.

Plan ModeClaude Code에 내장된 기능으로, 코드를 바로 쓰지 않고 먼저 계획을 세우는 모드. 저자는 이걸 안 쓰고 직접 마크다운 파일을 만들어 쓴다.

Vertical Slice기능의 전체 레이어(프론트엔드~백엔드~DB)를 얇게 한 줄로 관통하는 구현 단위. 한 번에 전체를 만들지 않고, 동작하는 최소 단위를 먼저 만드는 방식.

Closed-loop vs Open-loopOpen-loop는 프롬프트 → 큰 diff → 디버깅하는 방식이고, Closed-loop는 스캐폴드 + 제약조건 + 검증기를 두고 매 단계 확인하며 진행하는 방식. 후자가 통합 비용을 줄인다.

Working Memory FileAI가 현재 작업 상태를 추적하는 파일(status.md 등). 세션이 바뀌거나 컨텍스트가 리셋돼도 작업 연속성을 유지하기 위한 장치.