많은 개발자가 AI 코딩 도구를 사용할 때 "이거 구현해줘"라는 단순한 프롬프트를 던지고, 결과물이 나오면 버그를 수정하는 과정을 반복하곤 합니다. 하지만 복잡한 프로젝트에서는 이런 방식이 금방 한계에 부딪히죠.
오늘은 Boris Tane이 제안하는 Claude Code를 활용한 고효율 개발 워크플로우 를 정리해 보았습니다. 핵심은 'AI가 코드를 쓰기 전에 먼저 생각하게 만드는 것'입니다.
🚀 워크플로우 한 줄 요약
"깊게 리서치하고, 계획서를 작성하며, 계획이 완벽해질 때까지 수정(Annotation)한 뒤, 마지막에 한 번에 구현하게 하세요."
Phase 1: 리서치 (Research)
무작정 코드를 수정하기 전에 Claude에게 현재 코드베이스를 깊이 이해하도록 지시해야 합니다.
- 방법: 단순히 채팅으로 요약받지 말고,
research.md라는 파일에 결과를 기록하게 하세요. - 핵심 프롬프트: > "이 폴더를 아주 깊게 분석하고 어떻게 동작하는지 파악해줘. 겉핥기 식이 아니라 세부 로직까지 파악한 뒤
research.md에 보고서를 작성해."
이렇게 문서화된 리서치 결과는 개발자가 AI의 이해도를 검증하는 '리뷰 면표'가 됩니다. 리서치가 틀리면 이후의 모든 코드가 망가지기 때문입니다.
Phase 2: 계획 및 주석 사이클 (Planning & Annotation)
리서치가 끝났다면 구현 계획을 세울 차례입니다. 여기서 Boris는 Claude Code의 내장 플랜 모드 대신 직접 만든 plan.md 파일을 사용합니다.
1. 계획서 작성
Claude에게 구현할 기능의 상세 계획을 plan.md에 작성하라고 시킵니다. 여기에는 수정할 파일 목록, 코드 스니펫, 고려해야 할 트레이드오프가 포함됩니다.
2. 주석(Annotation) 달기 (핵심!)
작성된 plan.md를 에디터에서 열고, 개발자가 직접 인라인 노트를 남깁니다.
- "이 부분은 SQL이 아니라 Prisma를 써야 해."
- "이 API는 PUT이 아니라 PATCH가 맞을 것 같아."
- "이 로직은 이미 다른 파일에 있으니 재사용하자."
수정이 끝나면 다시 Claude에게 말합니다. "내가 남긴 노트를 확인해서 계획서를 업데이트해줘. 아직 구현은 하지 마." 이 과정을 1~6번 정도 반복하며 설계를 완벽하게 다듬습니다.
Phase 3: 구현 (Implementation)
설계가 확정되었다면 이제 AI가 가장 잘하는 '타이핑'을 맡길 차례입니다.
# Boris가 추천하는 필살 구현 프롬프트
implement it all.
when you're done with a task or phase, mark it as completed in the plan document.
do not stop until all tasks and phases are completed.
do not add unnecessary comments or jsdocs, do not use any or unknown types.
continuously run typecheck to make sure you're not introducing new issues.- All-in-one: 계획서의 모든 내용을 한 번에 구현하게 합니다.
- 체크리스트:
plan.md에 작업 진척도를 체크하게 하여 흐름을 추적합니다. - 엄격한 제약:
any타입 금지, 불필요한 주석 금지, 실시간 타입 체크 등을 강제합니다.
왜 이 방식이 더 나을까요?
- 컨텍스트 유지: 채팅창은 길어지면 이전 내용을 잊기 쉽지만,
plan.md파일은 프로젝트의 영구적인 자산으로 남습니다. - 아키텍처 제어: AI가 독자적으로 판단하게 두지 않고, 설계 단계에서 개발자가 개입하여 코드의 질을 유지합니다.
- 효율적인 토큰 사용: 코드 작성과 수정을 반복하며 토큰을 낭비하는 대신, 텍스트 기반의 계획 수정으로 비용을 아낍니다.
마치며
AI 코딩 도구의 진정한 가치는 단순히 코드를 빨리 짜주는 것이 아니라, 개발자가 '구현'이라는 기계적인 작업에서 벗어나 '설계와 의사결정'에 집중할 수 있게 해주는 것 에 있습니다.
다음 프로젝트에서는 Claude에게 바로 코딩을 시키는 대신, research.md와 plan.md를 먼저 요구해 보는 건 어떨까요?