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

4 days ago 4

AI 코딩 도구 사용 방식을 근본적으로 재구성해, 코드 작성 전 반드시 명시적 계획 검토 단계를 거치는 워크플로우를 제시
핵심 원칙은 “계획 승인 전에는 Claude에게 코드를 쓰게 하지 않는다” 로, 이를 통해 구조적 통제와 효율적 토큰 사용을 달성
전체 과정은 Research → Plan → Annotation → Todo List → Implementation → Feedback의 순환 구조로 진행
각 단계에서 markdown 문서(research.md, plan.md) 를 중심으로 협업하며, 주석과 수정 과정을 반복해 완성도를 높임
이 방식은 AI의 실행력과 인간의 판단력을 분리·결합해, 복잡한 시스템에서도 안정적이고 일관된 결과를 얻는 데 중점

전체 워크플로우 개요

약 9개월간 Claude Code를 주 개발 도구로 사용하며, 일반적인 “프롬프트 입력 → 코드 생성 → 수정 반복” 방식 대신 계획과 실행을 분리한 체계적 절차를 구축
Claude가 코드를 작성하기 전, 반드시 작성자가 검토·승인한 계획 문서(plan.md) 를 기반으로만 실행하도록 함
이 접근은 불필요한 시행착오를 줄이고, 아키텍처 결정권을 유지하며, 토큰 사용량 대비 품질을 극대화함

Phase 1: Research

모든 작업은 깊이 있는 코드베이스 분석으로 시작
- Claude에게 특정 폴더나 기능을 “깊이 읽고(detailed, intricacies)” 분석하도록 지시
- 결과는 반드시 research.md 파일로 기록하게 함
이 문서는 Claude의 이해도를 검증하는 리뷰 표면(review surface) 역할을 하며, 오해가 있으면 이 단계에서 수정
잘못된 리서치는 잘못된 계획과 구현으로 이어지므로, 가장 비용이 큰 실패 요인을 사전에 차단
예시로 캐싱 레이어 무시, ORM 규칙 미반영, 중복 로직 생성 등의 문제를 예방

Phase 2: Planning

리서치 검토 후, Claude에게 상세 구현 계획(plan.md) 을 작성하게 함
- 실제 코드 스니펫, 수정 파일 경로, 트레이드오프 등을 포함
- 내장된 plan 모드 대신 직접 관리 가능한 markdown 파일을 사용
오픈소스의 참조 구현(reference implementation) 을 함께 제공하면, Claude의 계획 품질이 크게 향상
계획 문서 자체보다 중요한 것은 이후의 주석(Annotation) 사이클임

Annotation Cycle

작성자는 plan.md를 열어 직접 인라인 주석을 추가
- 잘못된 가정 수정, 접근법 거부, 도메인 지식 추가 등
- 예: “이건 PATCH여야 함”, “캐싱 불필요”, “visibility 필드는 리스트 단위로 이동” 등
이후 Claude에게 “주석을 반영해 문서를 갱신하되, 아직 구현하지 말라”고 지시
이 주석-갱신 사이클을 1~6회 반복, “don’t implement yet” 명령으로 조기 실행을 방지
markdown 문서는 공유 가능한 상태(state) 로 작동해, 대화형 지시보다 명확하고 구조적
반복을 통해 일반적 계획이 실제 시스템에 완벽히 맞는 사양으로 진화

Todo List 생성

구현 전, Claude에게 세부 작업 목록(todo list) 을 추가하게 함
- 각 단계별 세부 태스크를 포함해 진행 상황을 추적
- Claude가 완료 항목을 표시하므로, 장시간 세션에서도 상태 파악이 용이

Phase 3: Implementation

모든 결정이 확정된 후, 표준화된 프롬프트로 실행 지시
- “모든 태스크를 완료할 때까지 멈추지 말 것”, “불필요한 주석 금지”, “any/unknown 타입 금지”, “지속적 타입체크 수행” 등
이 명령은 계획을 그대로 실행하는 기계적 단계로, 창의적 판단은 이미 완료된 상태
계획 없이 바로 구현하면 잘못된 가정 위에 코드를 쌓게 되므로, “don’t implement yet” 규칙이 핵심 안전장치

Feedback During Implementation

실행 중에는 작성자가 감독자 역할로 전환
- 피드백은 짧고 명확하게 전달: “이 함수 누락됨”, “admin 앱으로 이동” 등
- 프론트엔드 수정 시에는 “wider”, “2px gap” 등 단문 지시나 스크린샷 활용
기존 코드 참조를 자주 사용해, 일관된 UI/UX 유지
잘못된 방향으로 진행되면 git revert 후 범위 축소 재시도, 점진적 수정보다 효과적

Staying in the Driver’s Seat

Claude에게 완전한 자율권을 주지 않음, 최종 결정은 항상 사람이 내림
Claude의 제안 중 일부만 선택하거나 수정, 삭제, 기술 선택을 재정의
- 예: “첫 번째는 Promise.all 사용”, “네 번째, 다섯 번째는 무시”
- “다운로드 기능 제거”, “함수 시그니처 변경 금지”, “특정 라이브러리 메서드 사용” 등
Claude는 기계적 실행, 사람은 판단과 우선순위 결정 담당

Single Long Sessions

리서치부터 구현까지 하나의 긴 세션에서 연속 수행
- 세션 중 Claude는 지속적으로 맥락을 축적하며, auto-compaction으로 충분한 문맥 유지
- plan.md는 세션 내내 완전한 형태로 보존, 언제든 참조 가능

핵심 요약

“깊이 읽고, 계획을 쓰고, 주석으로 다듬은 뒤, 한 번에 실행하라.”
복잡한 프롬프트나 시스템 지시 없이도, 사고(Thinking)와 타이핑(Typing)을 분리한 규율적 파이프라인으로 높은 품질 확보
Research는 무지한 변경을 막고, Plan은 잘못된 변경을 막으며, Annotation은 인간의 판단을 주입
최종 실행은 모든 결정이 확정된 후 자동화된 절차로 수행, 효율적 협업 구조 완성

Read Entire Article