Claude Code 활용 방식: 계획과 실행의 분리
(boristane.com)- 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은 인간의 판단을 주입
- 최종 실행은 모든 결정이 확정된 후 자동화된 절차로 수행, 효율적 협업 구조 완성
댓글과 토론
Hacker News 의견들
-
진짜 핵심은 “계획하느냐 마느냐”가 아니라, 모델이 코드로 굳어지기 전에 가정들을 드러내게 하는 것임
LLM은 문법보다는 아키텍처나 제약조건 같은 보이지 않는 전제에서 실패함. 그래서 문서화된 계획이 그 전제를 디버깅할 수 있는 표면이 되어줌- 이런 면에서 서브 에이전트 구조가 큰 도움이 됨. 하나는 계획, 하나는 구현, 또 다른 하나는 리뷰를 맡게 하면 역할이 명확해짐. 블루팀/레드팀 식으로도 가능함. 결국 핵심은 LLM이 더 명확한 지시로 올바르게 추론하게 돕는 것임
- 전체 사용 사례 흐름을 지침에 포함시키면, 모델이 엉뚱한 행동을 하지 않게 됨
- 하지만 이런 가정을 드러내는 행위 자체가 모델의 행동을 바꿀 수도 있음. 마치 printf() 한 줄 넣었더니 Heisenbug가 사라지는 것처럼 말임
- 문법 오류가 거의 없다고? 내 경험은 다름. 작은 Rust 프로젝트에서 S3 백엔드 추가하려다 Claude가 API 환각 루프에 빠져 30분 만에 $20을 태워버림. 단순한 문법 문제였는데도 말임
- 혹시 이 글 ChatGPT로 쓴 거 아님?
-
“깊게”, “세부적으로” 같은 단어를 써야 Claude가 피상적으로 읽지 않는다는 말이 있는데, 솔직히 왜 그런지 직관적으로 이해가 안 됨
- 그건 attention 메커니즘 때문임. LLM은 인터넷 전체를 학습했는데, “문제의 세부를 보라” 같은 표현이 들어간 글들은 대체로 전문가 수준의 답변을 담고 있음. 그래서 그런 단어가 들어가면 모델이 그쪽 데이터에 더 가중치를 두게 됨. “MIT 교수처럼 행동하라” 같은 프롬프트가 통하는 이유도 같음
- 하지만 이런 설명은 미신 같음. 통계적으로 검증된 근거가 없고, 마치 태양신에게 제물 바치는 수준의 주술적 사고처럼 느껴짐. 정말 효과가 있다면 최적화 문제로 증명할 수 있을 텐데, 아무도 데이터를 공개하지 않음
- 지금은 소프트웨어 개발이 정말 이상한 시대임. 아무도 LLM이 왜 그렇게 행동하는지 모름. 우리는 단지 프롬프트가 확률을 잘 움직이길 바랄 뿐임. 예전엔 결정론적이던 분야였는데, 이제는 AGENTS.md 파일에 부모가 아이에게 말하듯 굵은 글씨로 명령을 써넣고 있음
- 이런 얘기를 보고도 여전히 진지하게 받아들이는 게 신기함. 거의 공학판 점성술 같음
- 모델의 잠재 공간(latent space) 을 지형처럼 생각하면 이해가 쉬움. 프롬프트는 공을 특정 지점에 떨어뜨리는 것과 같고, 단어 선택이 그 공이 어느 골짜기로 굴러갈지를 정함. “깊이 있게” 같은 표현은 그 공을 원하는 지역에 더 잘 머물게 함. 완벽한 설명은 아닐 수 있지만, 그렇게 생각하니 실제로 잘 작동했음
-
나는 세 가지 문서 타입과 두 가지 스킬로 구성된 구조를 씀
Specs는 프로젝트의 정적 설계 문서, Plans는 LLM이 생성한 실행 계획, Working memory 파일은 진행 상태를 추적함.
Gemini Pro의 planner skill로 새 계획을 만들고, Codex의 implementer skill로 실행함.
이렇게 하면 컨텍스트가 가볍고 집중적이라 효율이 높음. Codex/Gemini의 $20 플랜으로도 충분히 빠르게 진행 가능함- 나도 비슷한 접근을 함. 논문 기반으로 spec 파일을 만들고 Claude와 상호작용하며 계획을 발전시킴. IEEE 스타일의 시스템 엔지니어링 문서처럼 요구사항–테스트–정의서를 관리함. Claude는 가드레일을 주면 잘 따름. Codex보다 Claude가 내 스타일에 더 맞음
- 좋은 접근임. 그런데 모노레포가 AI 시대에 더 나은 선택인지 궁금함. 우리 회사는 Next.js 앱을 여러 리포로 나눠놨는데, 하나로 합치는 게 나을지 고민 중임
-
계획 문서에 직접 주석을 남기는 아이디어가 신선하게 느껴짐. 혹시 그 주석을 따로 저장하거나 나중에 검토할 수 있게 관리하는 방법이 있는지 궁금함
-
이 접근법에는 몇 가지 마음에 안 드는 점이 있음
첫째, 한 번에 모든 코드를 생성하는 빅뱅 방식은 이해하기 어려운 거대한 코드 덩어리를 만듦. 단계별로 계획을 세우고 실행하는 게 낫다고 봄.
둘째, 피드백을 주면서도 지식 베이스를 갱신하지 않는 점이 아쉬움. 오류 원인을 기록해 다음엔 반복하지 않게 해야 함.
마지막으로 테스트 언급이 없음. 테스트 주도 개발(TDD) 을 일부라도 포함해야 함. AI 지원 개발이 이런 방법론과 어떻게 융합될지 흥미로움- 나도 비슷한 경험을 했음. PLAN.md를 단계별로 나누고, 각 단계만 실행하도록 프롬프트를 조심히 작성함. 테스트도 계획의 일부로 포함시키지만, 아직은 후반부에 추가하는 편임
-
이 워크플로우는 사실 Anthropic이 권장하는 Claude Code의 표준 방식임. 하지만 단점은 계획이 완벽하지 않으면 처음부터 다시 해야 한다는 것임.
그래서 나는 디자인 → 계획 → 실행을 여러 배치로 나눠서 함. 1,500줄 이하의 계획 단위로 나누면 복잡도를 관리하기 쉬움.
내 3만 LOC 앱엔 10만 줄의 계획이 있음. 한 번에 만드는 건 불가능함- 나도 같은 경험을 함. 그래서 더 작은 계획 단위로 나누고, 기능별 브랜치로 커밋을 관리함. AI 덕분에 오히려 개발 습관이 좋아졌음
- 사실 “급진적으로 다르다”는 워크플로우가 그냥 기본 Plan 모드를 쓰는 거라 좀 민망함
- 나도 단계적 실행이 정답이라고 생각함. 거대한 프로젝트를 한 번에 완성하는 건 아직 환상에 불과함
- 완벽한 계획이 아니어도 괜찮음. AI가 수정한 부분만 되돌리고 이전 단계에서 다시 반복하면 됨. 작은 단위 변경으로 복잡도를 줄이는 게 핵심임
- 10만 줄의 계획은 거의 백만 단어임. 그냥 읽는 데만 66시간 걸림. 현실적으로 불가능함
-
나는 plan.md 대신 실행 가능한 스캐폴드와 검증 루프를 중심으로 작업함
Kolibri Tickets라는 실제 결제 시스템을 AI와 함께 구축했음. 핵심은 모델이 빠르게 코드를 치는 게 아니라, 검증 루프를 설계하는 것임- 초기에 실행 가능한 뼈대를 유지하고
- 한 번에 얇은 수직 슬라이스만 추가하고
- 테스트·타입·상태머신 등 검증 가능한 산출물을 강제하고
- 리팩터링을 일상화함
이렇게 하면 “속도 착각”이 아니라 실제로 더 빠르게 배포할 수 있음. Plan 문서는 공유 상태를 유지하는 한 방법이고, 검증 가능한 하네스도 또 다른 방법임 - 나도 코드가 싸진 시대에 100% 테스트 커버리지를 목표로 함. Python으로 정적 타이핑, Playwright 테스트, mutation testing까지 도입 중임. 이제 에이전트가 1시간 루프를 돌며 거의 수정할 필요 없는 코드를 내놓음
-
나는 Claude Code를 강의 준비용으로 씀
Quarto로 강의 노트를 작성하고, Claude가 이를 Slidev 슬라이드로 변환하게 함. 이후 슬라이드에 “이건 두 장으로 나누기”, “여기 이미지 추가” 같은 주석을 달아 피드백을 줌.
이런 주석 기반 피드백이 매우 강력함. 토큰 거리와 문맥 유지에 큰 도움이 됨- Quarto 자체로도 PowerPoint, PDF, HTML 등 다양한 포맷을 지원하는데, 왜 Slidev를 쓰는지 궁금함. Claude에게 Quarto 문서를 다시 생성하게 하면 되지 않나?
- 피드백은 인라인 주석으로 남기는지 궁금함. 예를 들어
# 이 부분을 X로 바꾸기같은 식으로? - 혹시 그 Claude skill을 오픈소스로 공개했는지 알고 싶음
-
이미 Amazon의 Kiro, Google의 Antigravity, GitHub의 Spec Kit, OpenSpec 같은 도구들이 이런 기능을 제공하고 있음
-
AI 보조 코딩의 가장 비싼 실패는 문법 오류가 아니라, 부분적으로는 잘 작동하지만 전체 시스템을 깨뜨리는 구현임
그래서 나는 초기에 brief.md를 추가해 문제 정의, 목표 지표, 기능 중단 기준 등을 명시함. 이렇게 하면 비즈니스 목표와 기술 구현이 어긋나는 비용을 줄일 수 있음