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

> Clean Markdown view of GeekNews topic #26907. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=26907](https://news.hada.io/topic?id=26907)
- GeekNews Markdown: [https://news.hada.io/topic/26907.md](https://news.hada.io/topic/26907.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-02-23T09:37:01+09:00
- Updated: 2026-02-23T09:37:01+09:00
- Original source: [boristane.com](https://boristane.com/blog/how-i-use-claude-code/)
- Points: 86
- Comments: 4

## Summary

AI 코딩 도구를 활용한 새로운 **워크플로우**는 코드 작성 이전에 **명시적 계획 검토 단계를 의무화**해, 실행과 사고를 분리합니다. 핵심 원칙은 “계획 승인 전에는 AI에게 코드를 쓰게 하지 않는다”로, 이를 통해 구조적 통제와 토큰 효율을 동시에 확보합니다. 모든 과정은 *Research → Plan → Annotation → Todo List → Implementation → Feedback*의 순환 구조로 진행되며, markdown 문서를 중심으로 협업해 인간의 판단력과 AI의 실행력을 안정적으로 결합할 수 있습니다.   
  
**“깊이 읽고, 계획을 쓰고, 주석으로 다듬은 뒤, 한 번에 실행하라.”**

## Topic Body

- **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은 인간의 판단을 주입  
- 최종 실행은 **모든 결정이 확정된 후 자동화된 절차로 수행**, 효율적 협업 구조 완성

## Comments



### Comment 51861

- Author: naka98
- Created: 2026-02-25T12:47:06+09:00
- Points: 1

비슷한 문제를 저도 계속 겪고 있습니다. 채팅 기반으로만 AI와 협업하면 작업 단위 분해(WBS), 진척, 결정 기록이 흐려지더라고요.

### Comment 51688

- Author: pcj9024
- Created: 2026-02-23T17:35:00+09:00
- Points: 1

계획 파일을 그냥 레포지토리 안에 넣어버리고 그 계획을 실행함으로써 생긴 적용내용을 저장하게하면 컨텍스트가 제법 유지되더라구요

### Comment 51663

- Author: geekbini
- Created: 2026-02-23T15:45:24+09:00
- Points: 1

이 내용은 claude 에만 국한된 내용은 아니고 범용적으로 다른 CLI 기반의 AI서비스들에게도 적용할 수 있을 것 같군요.

### Comment 51602

- Author: neo
- Created: 2026-02-23T09:37:01+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=47106686) 
- 진짜 핵심은 “계획하느냐 마느냐”가 아니라, 모델이 코드로 굳어지기 전에 **가정들을 드러내게 하는 것**임  
  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](https://kiro.dev/), Google의 [Antigravity](https://antigravity.google/), GitHub의 [Spec Kit](https://github.github.com/spec-kit/), [OpenSpec](https://openspec.dev/) 같은 도구들이 이런 기능을 제공하고 있음

- AI 보조 코딩의 가장 비싼 실패는 문법 오류가 아니라, **부분적으로는 잘 작동하지만 전체 시스템을 깨뜨리는 구현**임  
  그래서 나는 초기에 **brief.md**를 추가해 문제 정의, 목표 지표, 기능 중단 기준 등을 명시함. 이렇게 하면 비즈니스 목표와 기술 구현이 어긋나는 비용을 줄일 수 있음