Claude Code 활용법 - 계획과 실행 분리 워크플로우
목차
개요
AI 코딩 도구가 빠르게 발전하면서, 개발자들은 이를 효율적으로 활용하는 방법을 모색하고 있다. Cloudflare의 엔지니어링 리드이자 Baselime의 전 창업자인 Boris Tane은 Claude Code를 활용한 체계적인 3단계 워크플로우를 공개했다. 이 방법론의 핵심은 “계획을 검토하고 승인하기 전까지는 코드를 작성하지 않는다”는 원칙이다. 이 원칙을 통해 불필요한 작업을 줄이고, 아키텍처 결정권을 개발자가 유지할 수 있다.
핵심 원칙 - 계획 우선
Claude Code 활용 시 가장 큰 리스크 중 하나는 AI가 잘못된 방향으로 코드를 작성하기 시작하면 되돌리기 어렵다는 점이다. 이를 방지하기 위해 명시적인 계획 단계를 거치는 워크플로우가 효과적이다. 이 방식은 구조적 통제와 토큰 효율성을 동시에 달성한다. 단순히 AI에게 모든 것을 맡기는 것이 아니라, 인간의 판단력과 AI의 실행 능력을 적절히 분리하는 것이 핵심이다.
3단계 워크플로우
1단계 - 리서치
Claude에게 코드베이스의 관련 부분을 깊이 있게 분석하도록 지시한다. 분석 결과는 단순 구두 요약이 아닌 research.md와 같은 영구적인 마크다운 파일로 작성하게 한다. “깊이”, “세부사항”, “모든 것을 살펴봐라” 같은 언어를 사용해 표면적인 분석이 아닌 심층 분석을 요구한다. 이 문서는 Claude가 코드베이스를 정확히 이해했는지 검토할 수 있는 중요한 아티팩트가 된다.
2단계 - 플래닝
리서치 완료 후 Claude는 별도의 마크다운 파일에 상세한 구현 계획을 작성한다. 이 문서에는 설명, 코드 스니펫, 파일 경로, 트레이드오프 분석이 포함된다. Claude Code의 내장 플랜 모드 대신 커스텀 마크다운을 선호하는 이유는 더 많은 제어권을 제공하기 때문이다. 계획 파일을 레포지토리에 저장하면 세션 간 컨텍스트 유지에도 효과적이다.
3단계 - 구현
계획이 최종 승인된 후에만 구현 단계로 넘어간다. 표준화된 프롬프트를 사용해 모든 구현 요구사항을 인코딩한다. Claude는 계획 문서에 완료된 작업을 표시하며 멈추지 않고 계속 진행한다. 타입체크 실행처럼 구현 요구사항을 프롬프트에 함께 인코딩하면 일관성을 유지할 수 있다.
어노테이션 사이클
계획 문서 작성 후 개발자가 인라인 주석으로 피드백을 추가하는 “어노테이션 사이클”이 이 워크플로우의 핵심이다. 이 사이클은 1~6회 반복될 수 있으며, 각 반복마다 계획이 더 정확해진다. 주석을 통해 잘못된 가정을 수정하고, 부적절한 접근 방식을 거부하며, 도메인 지식을 제공한다. 중요한 점은 “아직 구현하지 말라”는 명시적 가드를 포함시켜 Claude가 성급하게 코드를 작성하지 않도록 하는 것이다.
실제 적용 예시는 다음과 같다.
| 상황 | 어노테이션 내용 |
|---|---|
| 데이터베이스 마이그레이션 | 잘못된 마이그레이션 접근 방식 수정 |
| 중복 로직 | 불필요한 중복 로직 제거 지시 |
| 스키마 변경 | 비즈니스 제약에 따른 스키마 재구조화 |
실행 중 제어 유지
구현 중에도 개발자는 항목별 결정을 내리고, 범위를 조정하며, 기존 인터페이스를 보호하는 역할을 한다. 수정이 필요할 때는 간결한 한 문장 지시나 시각적 이슈의 경우 스크린샷으로 피드백을 전달한다. 방향이 잘못된 경우 점진적 패치보다는 전체 접근 방식을 되돌리는 것이 더 효과적이다. 리서치, 플래닝, 구현은 하나의 연속적인 세션에서 진행해 Claude가 문맥을 점진적으로 쌓아갈 수 있도록 한다.
결론
Claude Code를 효율적으로 활용하려면 AI의 자동화 능력과 인간의 판단력을 효과적으로 결합해야 한다. “계획 승인 전 코드 작성 금지”라는 원칙은 불필요한 작업을 줄이고 아키텍처 결정권을 개발자가 유지하는 데 핵심적이다. 리서치 → 플래닝 → 어노테이션 → 구현으로 이어지는 3단계 워크플로우는 특히 복잡한 코드베이스나 중요한 기능을 구현할 때 효과적이다. 이 방법론은 Claude Code뿐만 아니라 다른 AI 코딩 도구에도 범용적으로 적용 가능하다.