Claude Code를 제대로 쓰는 방법: 계획과 실행을 분리한 개발 워크플로우 정리

이 글은 Claude Code를 단순한 코드 자동 생성 도구가 아니라, 개발 생산성을 근본적으로 끌어올리는 ‘워크플로우 파트너’로 사용하는 방법을 정리한 글입니다.
약 9개월간 Claude Code를 실전 개발 도구로 사용하며 정착된 하나의 개발 방식이 어떻게 시행착오를 줄이고, 구조적인 실수를 막고, 더 나은 결과를 만들어내는지 단계별로 설명합니다.
핵심은 단 하나입니다. “계획을 승인하기 전까지는 절대 코드를 작성하게 하지 않는다.”

반응형

---

왜 기존 AI 코딩 방식은 한계가 있을까?

대부분의 개발자는 AI 코딩 도구를 이렇게 사용합니다.

• 프롬프트 입력
• (가끔) 플랜 모드 사용
• 오류 수정
• 다시 요청

또 다른 극단에서는 여러 자동화 루프나 에이전트를 엮어 복잡한 구조를 만듭니다.
하지만 두 방식 모두 조금만 복잡해져도 전체 구조가 무너진다는 공통된 문제를 갖고 있습니다.

그 이유는 명확합니다.

• 시스템 전체 맥락을 이해하지 못한 채 구현이 시작됨
• 초반의 잘못된 가정이 연쇄적으로 확산됨
• “동작은 하지만 시스템을 망가뜨리는 코드”가 만들어짐

이를 막기 위해 등장한 것이 계획과 실행을 강제로 분리하는 워크플로우입니다.

---

전체 워크플로우 한눈에 보기

이 방식은 다음 단계를 반복하며 진행됩니다.

1. Research
2. Plan
3. Annotate
4. Todo List
5. Implement
6. Feedback & Iterate

핵심은 1~4단계에서는 절대 구현하지 않는 것입니다.

---

Phase 1: Research — 얕은 이해를 원천 차단하기

모든 작업은 “깊이 있는 조사”로 시작합니다.
이 단계에서 Claude에게 요구하는 것은 요약이 아닙니다.

연구 단계의 핵심 지시 방식

• “deeply”, “in great detail”, “intricacies” 같은 표현을 명시적으로 사용
• 코드베이스를 전반적으로 읽고 이해하도록 지시
• 결과물을 반드시 markdown 파일(research.md) 로 작성하게 함

왜 문서가 중요한가?

이 문서는 Claude를 위한 숙제가 아닙니다.
내가 검토하기 위한 검증 도구입니다.

• Claude가 시스템을 제대로 이해했는지 확인
• 오해가 있다면 이 단계에서 바로 수정
• 잘못된 이해 → 잘못된 계획 → 잘못된 구현으로 이어지는 최악의 흐름 차단

이 단계는 시간이 가장 많이 들지만, 가장 비싼 실패를 예방하는 단계이기도 합니다.

---

Phase 2: Planning — 구현 전에 모든 결정을 끝낸다

리서치 검토가 끝나면, 다음은 구현 계획 문서(plan.md) 작성입니다.

계획 문서에 반드시 포함되는 것

• 전체 접근 방식 설명
• 변경될 파일 경로
• 코드 스니펫 예시
• 고려 사항과 트레이드오프

여기서 중요한 점은 Claude의 내장 플랜 모드를 사용하지 않는다는 것입니다.
직접 관리 가능한 markdown 문서를 사용하면:

• 에디터에서 직접 수정 가능
• 주석을 통한 정확한 피드백 가능
• 프로젝트에 영구적으로 남는 산출물 확보

---

Annotation Cycle — 이 워크플로우의 핵심

이 단계가 가장 차별화된 부분입니다.

진행 방식

1. Claude가 plan.md 작성
2. 내가 에디터에서 직접 주석 추가
3. 수정된 문서를 Claude에게 다시 전달
4. “아직 구현하지 말 것”을 명확히 지시
5. 만족할 때까지 1~6회 반복

주석에는 무엇이 들어갈까?

• 잘못된 가정에 대한 수정
• 불필요한 접근 방식 제거
• 비즈니스 제약 조건 설명
• 기술 선택에 대한 강제 지시

이 과정은 채팅으로 설명하는 것보다 훨씬 정확합니다.
문서의 “문제 있는 바로 그 지점”에 판단을 직접 남길 수 있기 때문입니다.

---

Todo List — 구현을 위한 체크리스트 만들기

계획이 확정되면, 구현 전에 반드시 Todo 리스트를 요청합니다.

• 단계별 작업 목록
• 세부 태스크 분해
• 구현 중 완료 여부를 표시할 기준

이 리스트는 구현 단계에서 진행 상황을 한눈에 파악하는 대시보드 역할을 합니다.

---

Phase 3: Implementation — 실행은 기계적으로

이제서야 구현을 허용합니다.
이때 사용하는 프롬프트는 매우 단순하지만 강력합니다.

• 계획된 모든 작업을 구현할 것
• 완료 시 plan 문서에 체크할 것
• 중간에 멈추지 말 것
• 불필요한 주석 추가 금지
• 타입 안정성 유지

이 시점의 구현은 창의적인 작업이 아닙니다.
이미 모든 판단은 끝났고, Claude는 실행만 합니다.

---

구현 중 피드백 — 짧고 정확하게

구현 단계에서의 피드백은 길 필요가 없습니다.

• “이 함수 구현이 빠졌음”
• “이 화면은 admin 앱에 있어야 함”
• “2px 여백 있음”

Claude는 이미 전체 맥락을 알고 있기 때문에,
짧은 지시만으로도 정확한 수정이 가능합니다.

---

이 워크플로우가 효과적인 이유

이 방식이 잘 작동하는 이유는 명확합니다.

• 리서치로 무지에서 오는 실수 차단
• 계획으로 구조적 실수 차단
• 주석 사이클로 인간의 판단 주입
• 구현 단계는 중단 없는 실행

Claude는 구현을 잘합니다.
하지만 무엇을 구현해야 하는지는 결국 사람이 결정해야 합니다.

---

728x90

이 워크플로우는 복잡한 프롬프트나 트릭이 아닙니다.
생각과 타이핑을 분리하는 규율입니다.

• 깊이 읽고
• 문서로 계획하고
• 판단을 주석으로 남긴 뒤
• 확정된 계획만 실행하게 한다

이 방식에 익숙해지면,
“왜 예전에는 계획 없이 코드를 맡겼을까?”라는 생각이 들게 됩니다.

AI 코딩 에이전트를 쓰고 있다면,
코드와 나 사이에 ‘주석 달린 계획 문서’ 하나를 두는 것
그것만으로도 결과는 완전히 달라질 수 있습니다.

300x250

https://boristane.com/blog/how-i-use-claude-code/?_bhlid=e435f53e2d4dfe23f6c61d9c12ecee2d18b31367&fbclid=IwY2xjawQ4wf1leHRuA2FlbQIxMQBzcnRjBmFwcF9pZBAyMjIwMzkxNzg4MjAwODkyAAEemcsATqmC0SQQxH0FFDxMVYjFVXhDJ_BT54tYqP_M2loyaXTJniQiv-bWXk0_aem_NCIVMFm0vDJDkHjfl51s9w#staying-in-the-drivers-seat

Boris Tane