Claude Code 활용 방식: 계획과 실행을 분리한 구조적 개발 워크플로우

AI 코딩 도구를 사용하다 보면 이런 고민이 생깁니다.
“코드는 빠르게 나오는데, 왜 점점 통제가 안 될까?”
“수정은 반복되는데, 구조는 더 복잡해지는 느낌이 드는 이유는 무엇일까?”

이 글은 단순한 프롬프트 입력과 코드 생성 반복 방식이 아니라, 계획과 실행을 명확히 분리하는 구조적 워크플로우를 통해 Claude Code를 활용하는 방법을 정리합니다. 핵심은 단 하나입니다. 계획이 승인되기 전에는 절대 코드를 작성하지 않는다.

약 9개월간 Claude Code를 주 개발 도구로 사용하며 정립된 이 방식은 Research → Plan → Annotation → Todo List → Implementation → Feedback의 순환 구조를 기반으로 합니다. 이 글에서는 각 단계의 목적과 실제 운영 방식, 그리고 이 접근이 왜 복잡한 시스템에서도 안정적인 결과를 만드는지 설명합니다.

반응형

---

기존 AI 코딩 방식의 한계

일반적인 AI 코딩 방식은 다음과 같습니다.

프롬프트 입력 → 코드 생성 → 수정 요청 → 다시 코드 생성

겉으로 보기에는 빠르고 효율적입니다. 하지만 다음과 같은 문제가 발생합니다.

• 아키텍처 통제력 상실
• 잘못된 가정 위에 코드가 누적됨
• 반복 수정으로 인한 토큰 낭비
• 구조적 일관성 저하

즉, 사고(Thinking)와 실행(Typing)이 동시에 진행되기 때문에 통제력이 약해집니다.

이를 해결하기 위해 도입한 것이 바로 계획과 실행의 분리 전략입니다.

---

전체 워크플로우 개요

이 방식은 다음 단계로 구성됩니다.

Research → Plan → Annotation → Todo List → Implementation → Feedback

핵심 원칙은 다음과 같습니다.

• 계획 승인 전에는 Claude에게 코드를 쓰게 하지 않는다.
• 모든 실행은 plan.md 기준으로만 진행한다.
• 사람은 판단, Claude는 실행을 담당한다.

이 구조는 AI의 실행력과 인간의 판단력을 분리하면서도 결합하는 방식입니다.

---

Phase 1: Research – 깊이 있는 코드베이스 분석

모든 작업은 철저한 분석에서 시작합니다.

Claude에게 특정 폴더나 기능을 “깊이 읽고(detailed, intricacies)” 분석하도록 지시하고, 결과를 반드시 research.md 파일에 정리하게 합니다.

Research 단계의 목적

• Claude의 이해도를 검증하는 리뷰 표면 확보
• 잘못된 가정 사전 차단
• 시스템 구조 오해 방지

이 단계에서 오해를 잡지 못하면, 이후 계획과 구현이 모두 잘못된 방향으로 흘러갑니다.

예방 가능한 문제 사례:

• 캐싱 레이어 무시
• ORM 규칙 미반영
• 기존 로직과 중복 구현
• 아키텍처 계층 위반

Research는 “무지한 변경”을 막는 단계입니다.

---

Phase 2: Planning – 실행 전 상세 구현 설계

리서치 검토가 끝나면 Claude에게 plan.md 작성을 지시합니다.

plan.md에 포함되는 요소

• 수정 파일 경로
• 실제 코드 스니펫
• 구조 변경 설명
• 트레이드오프 분석

중요한 점은 내장된 plan 모드 대신 직접 관리 가능한 markdown 파일을 사용한다는 것입니다. 이렇게 하면 상태가 명확히 기록되고 추적이 가능합니다.

오픈소스 참조 구현(reference implementation)을 함께 제공하면 계획 품질은 크게 향상됩니다.

하지만 여기서 끝이 아닙니다. 진짜 핵심은 다음 단계입니다.

---

Annotation Cycle – 인간의 판단을 주입하는 과정

plan.md가 작성되면 작성자가 직접 문서를 열어 인라인 주석을 추가합니다.

예시:

• “이건 PATCH여야 함”
• “캐싱 불필요”
• “visibility 필드는 리스트 단위로 이동”
• “이 접근은 도메인 정책과 충돌”

그 후 Claude에게 다음과 같이 지시합니다.

“주석을 반영해 문서를 갱신하되, 아직 구현하지 말라.”

이 주석-갱신 사이클을 1~6회 반복합니다.
핵심 안전장치는 바로 “don’t implement yet” 규칙입니다.

이 과정의 효과는 명확합니다.

• 일반적 계획이 실제 시스템에 맞는 사양으로 진화
• 도메인 지식이 문서에 구조적으로 반영
• 대화형 지시보다 훨씬 명확한 협업 상태 유지

Annotation은 “잘못된 변경”을 막는 단계입니다.

---

Todo List 생성 – 실행 준비 상태 확정

구현 직전, Claude에게 세부 작업 목록(todo list)을 작성하게 합니다.

포함 요소:

• 단계별 세부 태스크
• 파일 단위 작업 구분
• 진행 상태 체크 가능 구조

Claude가 완료 항목을 표시하도록 하면 장시간 세션에서도 현재 상태를 명확히 파악할 수 있습니다.

이 단계는 실행을 위한 체크리스트 확정 과정입니다.

---

Phase 3: Implementation – 기계적 실행 단계

모든 결정이 확정되면 표준화된 프롬프트로 구현을 시작합니다.

예시 지시:

• 모든 태스크를 완료할 때까지 멈추지 말 것
• 불필요한 주석 금지
• any/unknown 타입 금지
• 지속적 타입 체크 수행

이 단계는 창의적 판단이 아니라 기계적 실행입니다.
사고는 이미 Plan과 Annotation 단계에서 끝났습니다.

계획 없이 바로 구현하면 잘못된 가정 위에 코드를 쌓게 됩니다.
그래서 “don’t implement yet” 규칙이 가장 중요한 안전장치입니다.

---

Implementation 중 Feedback 방식

구현 중 작성자는 감독자 역할을 수행합니다.

피드백은 짧고 명확해야 합니다.

• “이 함수 누락됨”
• “admin 앱으로 이동”
• “2px gap”
• “wider”

기존 코드 참조를 자주 활용하면 UI/UX 일관성을 유지할 수 있습니다.

잘못된 방향으로 진행되면 점진적 수정 대신 git revert 후 범위를 축소해 재시도하는 것이 더 효과적입니다.

---

Staying in the Driver’s Seat – 최종 결정권 유지

이 방식의 핵심은 Claude에게 완전한 자율권을 주지 않는 것입니다.

사람이 담당하는 영역:

• 기술 선택
• 아키텍처 결정
• 우선순위 판단
• 기능 제거 여부 결정

예시:

• “첫 번째는 Promise.all 사용”
• “네 번째, 다섯 번째는 무시”
• “다운로드 기능 제거”
• “함수 시그니처 변경 금지”

Claude는 실행 담당자이고, 사람은 판단자입니다.

---

Single Long Sessions – 맥락 유지 전략

리서치부터 구현까지 하나의 긴 세션에서 연속 수행합니다.

• Claude는 세션 내에서 맥락을 축적
• auto-compaction으로 문맥 유지
• plan.md는 완전한 상태로 유지되어 언제든 참조 가능

이 방식은 중간에 컨텍스트가 끊겨 발생하는 품질 저하를 방지합니다.

---

이 방식의 핵심 가치

이 워크플로우는 단순한 사용 팁이 아닙니다.
AI 코딩 도구 사용 방식을 근본적으로 재구성하는 접근입니다.

핵심 문장으로 정리하면 다음과 같습니다.

깊이 읽고, 계획을 쓰고, 주석으로 다듬은 뒤, 한 번에 실행하라.

• Research는 무지한 변경을 막는다.
• Plan은 잘못된 변경을 막는다.
• Annotation은 인간의 판단을 주입한다.
• Implementation은 확정된 결정을 자동 실행한다.

복잡한 프롬프트 기술 없이도, 사고와 타이핑을 분리하는 규율적 파이프라인만으로 높은 품질을 확보할 수 있습니다.

---

728x90

Claude Code를 단순한 코드 생성 도구로 사용하면 반복 수정 루프에 빠지기 쉽습니다. 하지만 계획과 실행을 분리하면 다음과 같은 효과를 얻을 수 있습니다.

• 아키텍처 통제력 유지
• 토큰 대비 품질 극대화
• 시행착오 감소
• 일관된 시스템 구조 유지

결국 이 방식은 AI를 대체자가 아니라 실행 엔진으로 사용하는 전략입니다.
판단은 사람이 하고, 실행은 AI가 합니다.

복잡한 시스템일수록 이 구조는 더 강력해집니다.
AI 시대의 개발 생산성은 속도가 아니라 통제력에서 결정됩니다.

300x250

https://boristane.com/blog/how-i-use-claude-code/

Boris Tane