Claude Code를 9개월간 주력 개발 도구로 써온 엔지니어가 있습니다. 그의 결론은 단 하나였습니다. “코드를 쓰게 두기 전에, 반드시 계획을 검토하고 승인하라.”

Cloudflare에서 Workers 옵저버빌리티 팀을 이끌고 있는 Boris Tane이 자신의 블로그에 Claude Code 실전 워크플로우를 공개했습니다. 대부분의 개발자가 프롬프트를 입력하고, 오류를 고치고, 반복하는 방식으로 AI 코딩 도구를 쓰는 것과 달리, 그는 계획과 실행을 철저히 분리하는 구조화된 파이프라인을 사용합니다.

출처: How I Use Claude Code – boristane.com

AI 코딩 도구의 가장 비싼 실패

AI 보조 코딩에서 가장 흔한 실패는 문법 오류나 잘못된 로직이 아닙니다. 그것은 따로 작동하지만 주변 시스템을 망가뜨리는 구현입니다. 기존 캐싱 레이어를 무시하는 함수, ORM 관례를 고려하지 않은 마이그레이션, 이미 존재하는 로직을 중복 구현한 API 엔드포인트.

Claude가 코드베이스를 표면적으로만 이해한 채 구현을 시작하면 이런 일이 벌어집니다. 처음에는 그럴듯해 보이다가, 15분 뒤 잘못된 가정 위에 쌓인 변경 사항들을 전부 되돌려야 하는 상황이 됩니다.

Boris가 고안한 해법은 단계를 강제로 분리하는 것입니다. 연구(Research) → 계획(Plan) → 주석 달기(Annotate) → 구현(Implement)의 순서로, 각 단계가 완료되고 검토될 때까지 다음 단계로 넘어가지 않습니다.

계획 문서를 공유 작업 공간으로 쓰기

워크플로우에서 가장 독특한 부분은 ‘주석 사이클(Annotation Cycle)’입니다. Claude가 plan.md를 작성하면, Boris는 에디터에서 그 문서를 열고 잘못된 부분에 직접 인라인 노트를 작성합니다. “no — this should be a PATCH, not a PUT” 같은 두 단어짜리 교정부터, 비즈니스 제약을 설명하는 단락까지 다양합니다. 그런 다음 Claude를 다시 그 문서로 보내 “노트를 반영해 문서를 업데이트하라, 아직 구현하지 말라”고 지시합니다.

이 사이클은 1~6회 반복됩니다. 핵심은 계획 문서가 채팅 대화가 아니라는 점입니다. 채팅 메시지로 구현 방향을 수정하려면 스크롤을 되짚으며 결정 사항을 재구성해야 합니다. 반면 문서는 정확히 문제가 있는 지점에 교정을 기록할 수 있는 구조화된 공간입니다. Claude도, 작성자도 언제든 전체 맥락을 한눈에 파악할 수 있죠.

“구현을 지루하게 만드는 것이 목표”라는 그의 표현이 이 철학을 잘 담고 있습니다. 모든 창의적 판단은 주석 사이클에서 이루어지고, 구현 단계는 승인된 계획을 기계적으로 실행하는 것이 되어야 한다는 뜻입니다.

Claude가 모르는 것을 채우는 것이 개발자의 역할

Boris가 강조하는 또 다른 지점은 “Claude는 코드를 이해하고 구현하는 데 탁월하지만, 제품 우선순위나 사용자의 고통, 엔지니어링 트레이드오프는 모른다”는 것입니다. 주석 사이클은 이 도메인 지식을 계획 문서에 주입하는 과정입니다.

구현 중에도 그의 역할은 계속됩니다. 다만 방식이 달라집니다. 계획 단계에서는 단락 수준의 설명을 쓰지만, 구현 피드백은 한 문장으로 줄어듭니다. “You built the settings page in the main app when it should be in the admin app, move it.” 이미 공유된 계획과 세션 맥락이 있으니, 짧은 교정으로도 충분하다는 논리입니다.

방향이 완전히 틀렸을 때는 수정을 시도하지 않습니다. git 변경 사항을 폐기하고 범위를 좁혀 다시 시작합니다. 잘못된 접근 방식을 점진적으로 고치려다 더 복잡해지는 것보다 낫다는 경험에서 나온 판단입니다.

이 워크플로우의 구체적인 프롬프트 예시와 세션 관리 방식, 컨텍스트 윈도우 처리 전략은 원문에서 자세히 확인할 수 있습니다.

참고자료: Boris Tane 블로그