Claude Code 200% 활용법: 계획과 실행을 분리하는 6단계 워크플로우

AI 코딩 도구를 사용하는 대부분의 개발자는 비슷한 패턴을 따른다. 프롬프트를 입력하고, 생성된 코드를 확인하고, 마음에 안 드는 부분을 수정 요청하고, 다시 확인하고... 이 반복을 끝없이 이어간다.

그런데 이 방식이 정말 최선일까?

Boris Tane이라는 개발자가 Claude Code를 9개월간 주력 개발 도구로 사용하면서 정립한 워크플로우를 공개했다. 그의 핵심 원칙은 단순하지만 강력하다.

"계획을 승인하기 전에는 Claude에게 코드를 작성하게 하지 않는다."

이 글에서는 그의 6단계 워크플로우를 분석하고, 실제로 어떻게 적용할 수 있는지 살펴본다.

왜 계획과 실행을 분리해야 하는가

AI에게 바로 코드를 작성하라고 하면 어떤 일이 벌어지는지 생각해보자. AI는 코드베이스의 맥락을 충분히 파악하지 못한 채로 "그럴듯한" 코드를 만들어낸다. 기존 캐싱 레이어를 무시하거나, 프로젝트의 ORM 규칙을 따르지 않거나, 아키텍처와 맞지 않는 패턴을 도입하는 일이 빈번하게 발생한다.

결국 개발자는 생성된 코드를 뜯어고치는 데 더 많은 시간을 쓰게 된다. 계획 없는 코드 생성은 시간 절약이 아니라 시간 낭비다.

6단계 워크플로우

1단계: 리서치 (Research)

모든 것의 시작은 코드베이스에 대한 깊은 이해다. Claude에게 특정 폴더나 모듈을 깊이 있게 분석하도록 요청하고, 그 결과를 research.md 파일로 정리하게 한다.

여기서 핵심은 프롬프트에 사용하는 단어다. "깊이 있게", "상세하게", "세부 사항까지" 같은 표현을 명시적으로 사용해야 한다. 이런 단어가 없으면 Claude는 표면적인 수준에서만 코드를 읽고 넘어간다.

이 폴더를 깊이 있게 읽고, 어떻게 동작하는지, 무엇을 하는지, 모든 세부 사항을 깊이 이해해. 상세한 research.md 문서를 작성해.

작성된 research.md는 반드시 직접 검토해야 한다. 잘못된 리서치는 잘못된 계획으로 이어지고, 잘못된 계획은 잘못된 구현으로 이어진다. 기초 공사가 부실하면 건물 전체가 흔들리는 것과 같다.

2단계: 계획 (Planning)

리서치가 완료되면 구현 계획을 plan.md 문서로 작성하게 한다. 이 문서에는 다음 내용이 포함되어야 한다.

• 접근 방식에 대한 상세한 설명
• 실제 변경할 코드 스니펫
• 수정될 파일 경로
• 고려사항 및 트레이드오프

이것을 어떻게 구현할지 상세한 plan.md 문서를 작성해. 코드 스니펫도 포함해.

여기서 주목할 점은 Claude Code에 내장된 플랜 모드 대신 직접 .md 파일을 사용한다는 것이다. 에디터에서 전체 내용을 자유롭게 수정할 수 있고, 프로젝트 내에 영구적인 아티팩트로 보존된다는 장점이 있다.

오픈소스에서 좋은 참고 구현을 발견했다면, 이를 계획에 반영할 수도 있다.

이게 그들이 정렬 가능한 ID를 구현한 방식이야. 우리도 비슷한 접근법을 채택할 수 있도록 plan.md를 작성해.

3단계: 주석 달기 사이클 (Annotation Cycle)

이 단계가 전체 워크플로우에서 가장 핵심적인 부분 이다.

프로세스는 이렇다. Claude가 plan.md를 작성하면, 에디터에서 직접 인라인 주석을 추가한다. 그리고 Claude에게 주석을 반영하도록 요청한다. 만족할 때까지 이 과정을 1~6회 반복한다.

주석의 종류는 다양하다.

• 도메인 지식 : "마이그레이션에는 raw SQL이 아니라 drizzle:generate를 써야 해"
• 가정 수정 : "이건 PUT이 아니라 PATCH여야 해"
• 접근법 거절 : "이 섹션은 통째로 제거해. 여기에 캐싱은 필요 없어"
• 스키마 재구성 : "visibility 필드는 개별 아이템이 아니라 리스트 자체에 있어야 해"

이때 반드시 포함해야 하는 가드 문구가 있다.

문서에 몇 가지 메모를 추가했어. 모든 메모를 반영해서 문서를 업데이트해. 아직 구현하지 마.

"아직 구현하지 마" — 이 한 마디가 Claude가 흥분해서 코드를 작성하기 시작하는 것을 막아준다.

이 방식의 장점은 마크다운 문서를 인간과 AI 사이의 공유 상태 로 활용한다는 점이다. 채팅으로 주고받는 것보다 훨씬 구조적이고, 자신의 속도로 사고하며 정확히 원하는 부분을 지적할 수 있다.

4단계: 할 일 목록 (Todo List)

주석 사이클이 완료되면 계획 문서에 세부 작업 항목을 추가한다.

계획에 상세한 할 일 목록을 추가해. 모든 단계와 개별 작업 항목을 포함해. - 아직 구현하지 마.

이 할 일 목록은 곧 구현 단계에서 진행 상황을 추적하는 체크리스트가 된다.

5단계: 구현 (Implementation)

여기까지 오면 모든 의사결정은 이미 끝났다. 구현은 기계적이고 지루해야 한다. 창의적인 작업은 이미 계획 단계에서 완료되었기 때문이다.

전부 구현해. 작업이나 단계를 완료할 때마다 계획 문서에 완료 표시를 해. 모든 작업과 단계가 완료될 때까지 멈추지 마. 불필요한 주석이나 JSDoc을 추가하지 마. any나 unknown 타입을 사용하지 마. 새로운 문제를 만들지 않도록 지속적으로 타입체크를 실행해.

이 프롬프트의 각 부분이 의미하는 바는 명확하다.

• "전부 구현해" → 선택적으로 구현하지 말고 전부 실행
• "완료 표시를 해" → 계획 문서가 곧 진행 추적 도구
• "멈추지 마" → 중간에 확인 요청 없이 끝까지 진행
• "지속적으로 타입체크를 실행해" → 구현하면서 실시간으로 오류 검증

6단계: 피드백 (Feedback)

구현 중에도 피드백은 필요하다. 하지만 계획 단계와 구현 단계에서의 피드백 스타일은 완전히 다르다.

• 계획 단계 : 여러 문단에 걸친 상세한 주석
• 구현 단계 : 한 문장의 간결한 지적

실제 피드백 예시를 보면 이 차이가 확연하다.

• "deduplicateByTitle 함수를 구현하지 않았잖아."
• "설정 페이지를 메인 앱에 만들었는데, admin 앱에 있어야 해. 옮겨."
• "더 넓게", "아직 잘려", "2px 갭이 있어"

만약 구현이 완전히 잘못된 방향으로 갔다면, 점진적으로 패치하려 하지 말고 과감하게 되돌린다.

전부 되돌렸어. 이제 내가 원하는 건 리스트 뷰를 더 미니멀하게 만드는 것뿐이야. 그 외에는 아무것도 건드리지 마.

핵심 원칙: 운전석에 앉아 있기

이 워크플로우 전체를 관통하는 원칙은 하나다. Claude는 실행을 담당하고, 개발자는 판단을 담당한다.

유형	예시
항목별 선택	"첫 번째는 Promise.all 사용, 세 번째는 별도 함수로 분리, 네 번째는 무시"
스코프 정리	"계획에서 다운로드 기능 제거"
인터페이스 보호	"이 세 함수의 시그니처는 변경 금지"
기술 선택 오버라이드	"이 라이브러리의 내장 메서드를 사용해"

실전 팁: 긴 단일 세션 활용

리서치부터 구현까지 하나의 세션 에서 진행하는 것이 좋다. 컨텍스트 윈도우가 가득 차더라도 자동 압축이 동작하고, plan.md와 research.md는 파일로 존재하기 때문에 압축 후에도 언제든 참조할 수 있다.

세션을 나누면 맥락이 끊기고, 같은 설명을 반복해야 하는 비효율이 발생한다.

마무리

이 워크플로우를 한 문장으로 요약하면 이렇다.

깊이 있게 읽고, 계획을 작성하고, 계획이 완벽해질 때까지 주석을 달고, 그 다음 Claude가 모든 걸 타입체크하며 완료할 때까지 구현하도록 하라.

결국 AI 코딩 도구의 핵심은 "더 빠르게 코드를 생성하는 것"이 아니라, "더 나은 의사결정을 더 빠르게 실행하는 것" 이다. 계획과 실행을 분리하는 이 접근법은, AI를 단순한 코드 생성기가 아닌 진정한 개발 파트너로 활용하는 방법을 보여준다.

---

참고 : 이 글은 Boris Tane의 How I Use Claude Code 포스트를 바탕으로 작성되었습니다.