계획 문서가 코드를 이깁니다

Claude Code 9개월째 쓰고 내린 결론

2026.02.25 | 조회 81 |
0
|
에피의 바이브 코딩의 프로필 이미지

에피의 바이브 코딩

클로드 코드, 코딩 에이전트

저는 뉴스레터에서 Plan Mode를 꽤 많이 다뤘어요. Boris Cherny가 "Plan Mode를 빼면 Claude Code를 절반만 쓰는 거"라고 했다는 것도 소개했고, Mitchell Hashimoto의 "설계와 실행을 분리하라"도 다뤘고요. 그래서 "아, Plan Mode 써야 하는구나"가 어느 정도 상식이 됐을 거예요.

근데 얼마 전에 Boris Tane이라는 개발자가 쓴 글을 봤는데요. 이 사람이 9개월 동안 Claude Code를 메인 개발 도구로 쓴 사람이에요. 그 글에서 이렇게 말합니다.

"빌트인 Plan Mode? 별로입니다. 저는 안 씁니다."

읽으면서 솔직히 "어?" 했어요. 제가 지금까지 한 말이랑 충돌하는 것 같잖아요. 근데 글을 끝까지 읽어보니까 충돌이 아니었어요. 같은 목적지를 다른 길로 가는 거였어요. 그리고 이 사람의 길이 꽤 설득력 있었습니다.

오늘은 이 글을 정리하되, 제가 동의하는 부분과 "글쎄..." 하는 부분을 솔직하게 나눠볼게요.

코드 에디터와 계획 문서
코드 에디터와 계획 문서

이 사람의 핵심 원칙은 딱 하나예요

Boris Tane의 워크플로우를 한 문장으로 줄이면 이거예요.

"Claude한테 코드를 짜게 하기 전에, 반드시 문서로 된 계획을 리뷰하고 승인하라."

간단하죠. 근데 이걸 지키는 방법이 독특해요.

보통 우리가 Claude Code를 쓰는 방식이 어때요? "이거 만들어줘" → Plan Mode로 계획 세움 → "좋아, 실행해" → 끝. 아니면 계획도 안 세우고 바로 "만들어줘" 하는 경우도 많죠. Boris Tane은 이 두 가지 다 안 한대요.

이 사람이 하는 건 Research → Plan → Annotate → Todo → Implement → Feedback 순서예요. 6단계. 그리고 이 중에서 가장 중요한 건 3번째 Annotate 단계라고 해요. 대부분의 사람들이 안 하는 단계예요.

하나씩 들어가볼게요.


Research — "깊게 읽어"라는 말이 진짜 차이를 만듭니다

Boris Tane이 모든 작업을 시작하는 방식이 이거예요. 코드베이스를 먼저 읽히는 거예요. 근데 그냥 "읽어봐"가 아니에요.

이 폴더를 깊이 읽어. 어떻게 작동하는지, 뭘 하는지, 
모든 세부사항을 이해해. 다 끝나면 research.md에 
상세 보고서를 작성해.

여기서 핵심은 "깊이(deeply)", "세부사항(specificities)" 같은 단어예요. Boris Tane은 이 단어들이 없으면 Claude가 훑어본다고 해요. 함수 시그니처 수준에서 파악하고 넘어간다고요. "깊이 읽어"라고 하면 실제로 로직을 따라가면서 읽어요.

Hacker News에서 이 부분에 대한 논쟁이 좀 있었어요. "그런 단어가 진짜 차이를 만드냐?"는 거죠. 한 사람은 이렇게 설명했어요.

"LLM은 인터넷 전체를 학습했잖아요. '문제의 세부를 보라' 같은 표현이 들어간 글들은 대체로 전문가 수준의 답변을 담고 있어요. 그래서 그런 단어가 들어가면 모델이 그쪽 데이터에 더 가중치를 두게 돼요."

반론도 있었어요. "이건 미신 같다. 통계적으로 검증된 근거가 없고, 태양신한테 제물 바치는 수준의 주술적 사고 아니냐"는 거예요. 그리고 또 다른 사람은 이렇게 말했고요.

"지금은 소프트웨어 개발이 정말 이상한 시대예요. 아무도 LLM이 왜 그렇게 행동하는지 몰라요. 우리는 단지 프롬프트가 확률을 잘 움직이길 바랄 뿐이에요."

솔직히 저도 "왜 되는지"는 모르겠어요. 근데 "된다"는 건 경험으로 알아요. "이 폴더를 읽어봐"랑 "이 폴더를 깊이 읽고 모든 세부사항을 파악해"의 결과물은 실제로 달라요. 이론이 어떻든 간에 현장에서 체감되면 쓰는 거예요.

그리고 Boris Tane이 강조하는 게 또 있어요. 리서치 결과를 반드시 파일로 남기라는 거예요. 채팅에서 구두로 요약하게 하면 안 된대요. research.md라는 파일로 써야 한다고요.

이유가 뭐냐면요. 파일로 남기면 "Claude가 제대로 이해했는지"를 내가 검토할 수 있거든요. 리서치가 틀리면 계획이 틀리고, 계획이 틀리면 구현이 틀려요. 이 사람 표현을 빌리면 "Garbage in, garbage out"이에요.

이건 이전 뉴스레터에서 다뤘던 Mitchell Hashimoto의 접근과도 일맥상통해요. Mitchell이 "에이전트가 실수하면 시스템으로 막아라"고 했잖아요. Boris Tane은 그걸 실수가 발생하기 전에 막는 거예요. 리서치 단계에서 잘못된 이해를 잡아내면, 그 뒤로는 문제가 전파 안 되니까요.

그리고 Boris Tane이 이런 말을 했는데, 이게 좀 찔려요.

"AI 코딩에서 가장 비싼 실패는 문법 오류나 나쁜 로직이 아닙니다. 독립적으로는 잘 작동하지만 주변 시스템을 깨뜨리는 구현이에요. 기존 캐싱 레이어를 무시하는 함수. ORM 관례를 고려하지 않은 마이그레이션. 이미 있는 로직을 복제하는 API 엔드포인트."

이거 맞아요. 제가 현업에서 겪은 것도 정확히 이거였어요. AI가 짠 코드가 단독으로 보면 멀쩡해요. 근데 기존 시스템이랑 물리면 깨져요. 왜냐면 AI가 기존 시스템을 제대로 안 읽었으니까요. 리서치 단계는 이걸 막는 거예요.


Plan — 빌트인 Plan Mode를 안 쓴다고요?

여기서부터 Boris Tane의 접근이 갈려요.

리서치가 끝나면 계획을 세우라고 시켜요. 근데 Claude Code의 빌트인 Plan Mode를 안 써요. 대신 plan.md라는 자기만의 마크다운 파일에 계획을 쓰게 시켜요.

이 기능을 구현하기 위한 상세 plan.md를 작성해. 
코드 스니펫도 포함시켜. 소스 파일을 먼저 읽고, 
실제 코드베이스를 기반으로 계획을 세워.

왜 빌트인 Plan Mode를 안 쓰냐면요. 빌트인 Plan Mode는 자기가 통제할 수 없다는 거예요. 채팅 안에서 계획이 보이고 사라지잖아요. 편집도 못 하고, 인라인으로 메모를 달 수도 없고, 세션이 끝나면 날아가요.

plan.md 파일은 다릅니다. 에디터에서 열 수 있어요. 직접 편집할 수 있어요. 인라인 노트를 달 수 있어요. 그리고 세션이 끝나도 파일로 남아있어요. Claude와 내가 공유하는 "변경 가능한 상태(mutable state)"인 거죠.

이 사람은 한 가지 트릭도 알려줬는데요. 잘 만들어진 오픈소스 코드를 레퍼런스로 같이 보여주면 결과물이 확 달라진대요.

예를 들어 정렬 가능한 ID를 추가하고 싶으면, 그걸 잘 구현한 프로젝트의 코드를 복사해서 "이 프로젝트가 하는 방식을 참고해서 우리 프로젝트에 어떻게 적용할지 plan.md를 작성해"라고 시키는 거예요. Claude가 처음부터 설계하는 것보다, 좋은 구현을 참고하게 하면 극적으로 나아진다고요.

이건 저도 동의해요. 이전 뉴스레터에서 StrongDM 이야기를 할 때 "시나리오를 먼저 쓰라"고 했잖아요. 레퍼런스 구현을 보여주는 것도 같은 맥락이에요. AI한테 "알아서 해"보다 "이런 식으로 해"가 훨씬 나은 결과를 만들어요.

프로젝트 계획과 아키텍처 설계
프로젝트 계획과 아키텍처 설계

Annotation Cycle — 여기가 진짜 핵심이에요

이 파트가 Boris Tane 워크플로우에서 가장 독특한 부분이에요. 그리고 제가 가장 많이 배운 부분이기도 하고요.

plan.md가 만들어졌잖아요. 보통은 "좋아, 실행해"라고 하죠. Boris Tane은 안 그래요. plan.md를 에디터로 열어서, 문서 안에 직접 메모를 적어요. 그리고 Claude한테 돌려보내요.

문서에 몇 가지 노트를 달아놨어. 
노트를 전부 반영해서 문서를 업데이트해. 
아직 구현하지 마.

이 사이클이 1~6번 반복된대요. 만족할 때까지요.

어떤 노트를 다냐면요. 진짜 다양해요.

노트 유형예시
가정 수정"아니요 — 이건 PUT이 아니라 PATCH여야 해요"
도메인 지식"마이그레이션은 raw SQL 말고 drizzle:generate를 써요"
접근법 거부"이 섹션 전부 삭제해요. 여기 캐싱 필요 없어요"
방향 전환"visibility가 개별 아이템이 아니라 리스트 자체에 있어야 해요. 스키마 섹션을 재구조화하세요"
불필요한 로직"큐 컨슈머가 이미 재시도를 처리하니까, 이 재시도 로직은 중복이에요. 삭제하세요"

두 단어짜리 메모("not optional")도 있고, 한 문단짜리 설명도 있어요. 길이는 상관없어요. 핵심은 문서 안에서 정확한 위치를 짚어서 수정을 지시한다는 거예요.

그리고 매번 반드시 "아직 구현하지 마(don't implement yet)"를 붙인대요. 이거 안 붙이면 Claude가 "이 정도면 됐겠지" 하고 바로 코드를 짜기 시작한다고요.

왜 이게 잘 되냐면요

이전 뉴스레터에서 제가 여러 번 강조한 게 있어요. "프롬프트를 잘 쓰려고 하지 마. 컨텍스트를 설계하라." Boris Tane의 Annotation Cycle이 정확히 이거예요.

채팅에서 "아, 그거 말고 이렇게 해줘"라고 하면 뭐가 문제예요? 대화가 쌓이면서 맥락이 흩어져요. 어떤 결정이 언제 어디서 내려졌는지 추적이 안 돼요. 스크롤을 올려가면서 "아까 뭐라고 했더라..." 하게 되잖아요.

plan.md는 다릅니다. 하나의 문서에 모든 결정이 응축돼 있어요. 전체를 한눈에 볼 수 있어요. "3번째 섹션의 이 부분이 잘못됐어"라고 정확히 짚을 수 있어요. 그리고 Claude한테 그 문서를 업데이트하게 시키면, 다음 라운드에서는 수정된 문서가 곧 최신 맥락이 되는 거예요.

Boris Tane 표현을 빌리면, plan.md는 "나와 Claude 사이의 공유 가변 상태(shared mutable state)"예요. 프로그래밍 용어를 빌려온 건데, 적절한 표현이에요. 두 사람이 하나의 변수를 같이 읽고 쓰는 거잖아요.

Hacker News에서 한 사람이 이 Annotation 패턴을 강의 자료에 적용한 경험을 공유했어요. Quarto로 강의 노트를 쓰고, Claude한테 슬라이드로 변환시킨 다음에, 슬라이드에 직접 인라인 주석을 달아서 피드백을 줬대요. "이건 두 장으로 나눠", "여기 이미지 추가" 같은 식으로요. 코드가 아닌 문서에도 이 패턴이 먹히는 거예요.

세 번의 Annotation 라운드가 돌면 어떻게 되냐면요. 일반적인 구현 계획이 현재 시스템에 딱 맞는 구체적인 계획으로 변해요. 처음에 Claude가 "이렇게 하면 되겠죠?"라고 내놓은 제네릭한 계획이, 제 도메인 지식과 판단이 주입되면서 우리 프로젝트에만 맞는 정밀한 설계가 되는 거예요.

Boris Tane이 이런 말을 했어요. "Claude는 코드를 이해하고, 솔루션을 제안하고, 구현을 작성하는 데 뛰어나요. 근데 제 제품의 우선순위, 사용자의 페인 포인트, 제가 감수할 수 있는 엔지니어링 트레이드오프는 모릅니다. Annotation Cycle은 제가 그 판단을 주입하는 방법이에요."

이건 제가 강의에서 계속 하는 말이랑 같아요. AI가 못하는 건 코딩이 아니에요. "이 상황에서 뭐가 중요한지"를 판단하는 거예요. 그 판단은 사람의 몫이고, Annotation Cycle은 그 판단을 구조적으로 전달하는 방법인 거죠.


구현 — "지루해야 한다"

계획이 확정되면 구현을 시키는데요. Boris Tane이 거의 매번 쓰는 프롬프트가 있어요.

전부 구현해. 작업이나 단계를 끝낼 때마다 plan 문서에 
완료 표시를 해. 모든 작업과 단계가 완료될 때까지 멈추지 마. 
불필요한 주석이나 jsdoc을 달지 마. any나 unknown 타입을 쓰지 마. 
지속적으로 타입체크를 돌려서 새로운 이슈를 만들지 않는지 확인해.

이 프롬프트에 다 들어있어요.

  • "전부 구현해": 계획에 있는 건 전부 해. 골라서 하지 마.
  • "plan 문서에 완료 표시": 계획 문서가 진행 상황의 소스 오브 트루스.
  • "멈추지 마": 중간에 "이렇게 해도 될까요?" 묻지 마.
  • "불필요한 주석 달지 마": 코드를 깨끗하게 유지해.
  • "타입체크를 지속적으로 돌려": 문제를 끝에 가서가 아니라 만들면서 잡아.

Boris Tane이 이런 말을 했어요. "'전부 구현해'라고 말하는 시점에서, 모든 결정은 이미 다 내려져 있고 검증된 상태예요. 구현은 기계적인 거지, 창의적인 게 아니에요. 이건 의도적입니다. 구현이 지루하길 원해요. 창의적인 작업은 Annotation Cycle에서 다 끝났어요."

이 말에 좀 울림이 있었어요. 보통 코딩이라고 하면 "창의적인 문제 해결"이잖아요. 근데 AI 시대에는 그 창의적인 부분이 계획 단계로 이동한 거예요. 구현은 그냥 실행일 뿐이고요.

이전 뉴스레터에서 Every 팀의 Compound Engineering을 다루면서 "Plan과 Review에 80%의 시간을 쓰라"고 한 것과 같은 맥락이에요. Boris Tane도 시간의 대부분을 리서치와 Annotation에 쓰고, 구현은 "그냥 돌아가게 두는" 단계인 거예요.

근데 Hacker News에서 이 부분에 대한 비판도 꽤 있었어요. 한 사람이 이런 말을 했거든요.

"한 번에 모든 코드를 생성하는 빅뱅 방식은 이해하기 어려운 거대한 코드 덩어리를 만들어요. 단계별로 계획을 세우고 실행하는 게 낫다고 봅니다."

또 다른 사람은 이렇게요.

"계획이 완벽하지 않으면 처음부터 다시 해야 한다는 게 이 워크플로우의 단점이에요. 저는 디자인 → 계획 → 실행을 여러 배치로 나누고, 1,500줄 이하의 계획 단위로 쪼개요."

이 비판은 일리가 있어요. 저도 이 부분은 좀 다르게 생각하거든요. 이건 뒤에서 더 얘기할게요.

구현 중 피드백은 짧게

구현이 돌아가는 동안 Boris Tane은 감독자 역할로 전환해요. 계획 단계에서는 한 문단씩 메모를 달았지만, 구현 중에는 극단적으로 짧아져요.

"deduplicateByTitle 함수를 구현 안 했어."
"설정 페이지를 메인 앱에 만들었는데, 어드민 앱에 있어야 해. 옮겨."

프론트엔드 작업은 더 짧아요.

"더 넓게"
"아직 잘렸어"
"2px 갭 있어"

그리고 시각적 이슈는 스크린샷을 첨부한대요. 표가 어긋난 스크린샷 하나가 말로 설명하는 것보다 빠르다는 거예요.

또 하나 인상적인 건, 잘못된 방향으로 가면 고치려고 하지 않고 git revert를 한다는 거예요.

"전부 되돌렸어. 이제 리스트 뷰를 더 미니멀하게 만드는 것만 해. 
다른 건 건드리지 마."

잘못된 접근을 패치하려고 하는 것보다 되돌리고 범위를 좁히는 게 거의 항상 더 나은 결과를 만든다고요. 이건 저도 수없이 겪었어요. AI가 엉뚱한 방향으로 갔을 때 "아니 그게 아니라..."라고 수정을 요청하면 점점 더 꼬여요. 차라리 git reset --hard하고 다시 시작하는 게 빨라요.

깊은 집중과 코드 리뷰
깊은 집중과 코드 리뷰

운전석에서 내리지 마라

Boris Tane이 반복적으로 강조하는 게 있어요. Claude한테 실행을 위임하지만, 뭘 만들지에 대한 자율은 절대 주지 않는다는 거예요.

구체적으로 어떻게 하냐면요.

제안을 골라서 수용/거부해요. Claude가 여러 이슈를 찾아냈으면, 하나씩 판단해요.

"첫 번째 건 그냥 Promise.all 써. 복잡하게 만들지 마. 
세 번째 건 가독성을 위해 별도 함수로 분리해. 
네 번째, 다섯 번째는 무시해. 복잡도 대비 가치가 없어."

범위를 적극적으로 잘라내요. 계획에 nice-to-have가 포함되면 쳐내요.

"다운로드 기능은 계획에서 빼. 지금 구현 안 해."

기존 인터페이스를 보호해요. 함부로 바꾸면 안 되는 것에 하드 제약을 걸어요.

"이 세 함수의 시그니처는 바뀌면 안 돼. 
호출하는 쪽이 적응해야지, 라이브러리가 바뀌면 안 돼."

기술적 선택을 오버라이드해요. Claude가 모르는 프로젝트 고유의 선호가 있을 때.

"이 모델 말고 저 모델 써" 
"커스텀으로 만들지 말고 이 라이브러리의 빌트인 메서드 써"

이게 Hacker News에서 나온 인상 깊은 코멘트와 연결돼요.

"진짜 핵심은 '계획하느냐 마느냐'가 아니라, 모델이 코드로 굳어지기 전에 가정들을 드러내게 하는 것이에요. LLM은 문법보다는 아키텍처나 제약조건 같은 보이지 않는 전제에서 실패하거든요."

이 코멘트가 Boris Tane의 워크플로우를 한 문장으로 설명해요. plan.md의 Annotation Cycle은 결국 "Claude의 가정을 코드가 되기 전에 수면 위로 끌어올리는 작업"이에요.


단일 긴 세션 — 여기서부터 의견이 갈려요

Boris Tane이 독특한 주장을 하나 더 해요. 리서치, 계획, 구현을 하나의 긴 세션에서 다 한다는 거예요. 세션을 나누지 않아요.

"다들 컨텍스트 윈도우 50% 넘으면 성능이 떨어진다고 하는데, 저는 그걸 못 느끼겠어요. 오히려 '전부 구현해'라고 하는 시점에서 Claude는 세션 내내 이해를 쌓아온 상태예요. 리서치하면서 파일을 읽고, Annotation 사이클에서 제 도메인 지식을 흡수하고."

그리고 컨텍스트 윈도우가 차면 Claude의 자동 압축(auto-compaction)이 작동하는데, plan.md 문서가 파일로 존재하니까 압축 이후에도 계획은 온전히 남아있다는 거예요.

이 접근은... 솔직히 좀 양면적이에요.

맞는 말이긴 해요. plan.md가 파일로 존재하니까, 컨텍스트 윈도우가 압축돼도 Claude가 plan.md를 다시 읽으면 맥락을 복구할 수 있어요. 계획 문서가 세션의 백업 메모리 역할을 하는 거예요.

근데 저는 이전 뉴스레터에서 병렬 워크트리로 여러 세션을 동시에 돌리는 방식을 소개했잖아요. Boris Cherny 팀도 "3~5개 워크트리를 동시에 돌리라"고 했고요. Boris Tane은 이걸 안 해요. 하나의 세션에서 다 해요.

어떤 게 맞을까요? 둘 다 맞는 것 같아요. 작업의 성격에 따라 다른 거예요.

상황적합한 방식
복잡한 단일 기능 (아키텍처 변경, 대규모 리팩터링)Boris Tane 방식 — 단일 긴 세션
독립적인 여러 작업 (버그 3개, 기능 2개)Boris Cherny 방식 — 병렬 워크트리
리서치가 중요한 작업 (처음 보는 코드베이스 파악)Boris Tane 방식 — 맥락 축적이 중요
반복적인 패턴의 작업 (비슷한 API 여러 개 추가)병렬 방식 — 각각 독립적이니까

Hacker News에서도 비슷한 토론이 있었어요. 한 사람이 이렇게 말했거든요.

"한 번에 모든 코드를 생성하는 건 불가능해요. 저는 1,500줄 이하의 계획 단위로 나누고, 기능별 브랜치로 커밋을 관리해요. 3만 줄짜리 앱에 10만 줄의 계획이 있어요. 한 번에 만드는 건 불가능했어요."

또 다른 사람은 이렇게 반론했고요.

"완벽한 계획이 아니어도 괜찮아요. AI가 수정한 부분만 되돌리고 이전 단계에서 다시 반복하면 돼요. 작은 단위 변경으로 복잡도를 줄이는 게 핵심이에요."

결국은 프로젝트 규모와 작업 성격에 따라 달라지는 거예요. Boris Tane의 방식이 모든 상황에 맞는 건 아니에요. 근데 "plan.md를 중심으로 맥락을 관리한다"는 아이디어 자체는 세션을 어떻게 나누든 적용할 수 있어요.


Hacker News에서 나온 확장 아이디어들

커뮤니티에서 Boris Tane의 워크플로우를 확장한 흥미로운 아이디어들이 나왔어요. 몇 개 골라봤습니다.

서브 에이전트로 역할 분리

"하나는 계획, 하나는 구현, 또 다른 하나는 리뷰를 맡게 하면 역할이 명확해져요. 블루팀/레드팀 방식으로도 가능하고요."

이건 이전 뉴스레터에서 다뤘던 Writer/Reviewer 패턴의 확장이에요. Boris Tane은 한 세션에서 리서치~구현을 다 하는데, 이걸 서브 에이전트로 나누면 각 역할이 더 선명해질 수 있어요.

세 가지 문서 + 두 가지 스킬 구조

한 사람이 자기 시스템을 공유했는데 꽤 체계적이었어요.

문서역할
Specs프로젝트의 정적 설계 문서
PlansLLM이 생성한 실행 계획
Working memory진행 상태 추적

Boris Tane의 research.md + plan.md를 더 정교하게 나눈 거예요. 저도 이 구조가 마음에 들어요. 특히 Working memory 개념이요. 에이전트가 "지금 어디까지 했고 뭐가 남았는지"를 파일로 추적하게 하면, 세션이 끊겨도 이어갈 수 있거든요.

검증 루프 중심 접근

한 사람이 Boris Tane의 접근과 대비되는 방식을 공유했어요.

"저는 plan.md 대신 실행 가능한 스캐폴드와 검증 루프를 중심으로 작업해요. 초기에 실행 가능한 뼈대를 유지하고, 한 번에 얇은 수직 슬라이스만 추가하고, 테스트/타입/상태머신 등 검증 가능한 산출물을 강제해요."

이건 제가 이전 뉴스레터에서 "AI가 짠 코드를 믿지 마라, AI한테 검증시켜라"에서 다뤘던 내용과 맥이 같아요. Boris Tane의 워크플로우에서 아쉬운 점 중 하나가 테스트 이야기가 없다는 건데, 이 접근이 그 빈 곳을 채워줘요.

비즈니스 목표 문서 추가

"저는 초기에 brief.md를 추가해서 문제 정의, 목표 지표, 기능 중단 기준 등을 명시해요. 이렇게 하면 비즈니스 목표와 기술 구현이 어긋나는 비용을 줄일 수 있어요."

이것도 좋은 확장이에요. research.md가 기술적 맥락이라면, brief.md는 비즈니스 맥락인 거예요. 둘 다 Claude한테 주면 "왜 이걸 만드는지"까지 이해하고 코드를 짤 수 있으니까요.


솔직히 이렇게 느꼈습니다

이 글을 읽으면서 가장 찔린 부분은 Annotation Cycle이에요.

저도 Plan Mode를 쓰긴 해요. 근데 대부분 "계획 나왔네, 괜찮네, 실행해"로 끝내거든요. plan.md를 열어서 인라인으로 메모를 달고, 3번이나 돌려보내고, 만족할 때까지 다듬는 건... 안 해봤어요. 솔직히 귀찮다고 생각했어요.

근데 Boris Tane이 하는 말이 맞는 게요. 계획 단계에서 30분을 더 쓰면, 구현 단계에서 2시간을 절약할 수 있어요. 잘못된 방향으로 15분 달리다가 엎고 다시 시작하는 것보다, 처음에 방향을 제대로 잡는 게 훨씬 싼 거잖아요.

동시에 동의 못 하는 부분도 있어요.

테스트 이야기가 없다는 거예요. Hacker News에서도 이 비판이 나왔고, 저도 같은 생각이에요. Boris Tane의 워크플로우는 "계획이 좋으면 구현이 좋다"를 전제로 해요. 맞아요, 대부분은요. 근데 계획이 아무리 좋아도 엣지 케이스는 구현하면서 발견되는 경우가 많거든요. 테스트 없이 "계획대로 됐으니 끝"이라고 하면, 이전 뉴스레터에서 경고한 "작동하지만 주변 시스템을 깨뜨리는 코드"가 나올 수 있어요.

그리고 CLAUDE.md / knowledge base 갱신 이야기도 없어요. Annotation Cycle에서 "이건 PUT이 아니라 PATCH여야 해"라고 수정했으면, 그 지식이 CLAUDE.md에 축적돼야 다음에 같은 실수를 안 하잖아요. Boris Tane의 워크플로우는 매 세션이 독립적이에요. 이전 뉴스레터에서 다뤘던 Mitchell Hashimoto의 하네스 엔지니어링이나 Compound Engineering의 "오늘의 삽질이 내일의 자산이 되게 하라"와는 결이 좀 다르죠.

결국 Boris Tane의 워크플로우 + 이전 뉴스레터들에서 다뤘던 검증/축적 시스템을 합치면 꽤 완성도 높은 AI 코딩 프로세스가 될 것 같아요.

Boris Tane에서 가져올 것기존 뉴스레터에서 가져올 것
Research → Plan → Annotate 사이클Writer/Reviewer 패턴으로 테스트 분리
plan.md를 공유 상태로 활용CLAUDE.md에 실패 패턴 축적
구현 프롬프트 표준화린팅/타입체크 자동 검증
레퍼런스 구현 활용Compound 단계로 지식 축적
개발 워크플로우
개발 워크플로우

오늘 바로 해보세요

1. 다음 작업에서 research.md 만들어보기 (10분)

다음에 좀 복잡한 작업을 시작할 때, 바로 "만들어줘"라고 하지 마세요. 이렇게 해보세요:

이 모듈을 깊이 읽어. 어떻게 작동하는지, 모든 세부사항을 파악해.
다 끝나면 research.md에 상세 보고서를 작성해.

research.md를 읽어보세요. Claude가 제대로 이해했는지 확인하세요. 잘못된 부분이 있으면 "이 부분은 틀렸어. X가 아니라 Y야"라고 수정시키세요. 이 10분이 나중에 삽질 1시간을 절약해줄 거예요.

2. plan.md에 인라인 노트 달아보기 (15분)

research.md가 괜찮으면, plan.md를 만들게 시키세요:

이 기능을 구현하기 위한 상세 plan.md를 작성해.
코드 스니펫도 포함시켜. 아직 구현하지 마.

plan.md가 나오면 에디터로 열어서 직접 메모를 달아보세요. "이건 아니야", "여기는 이렇게 해야 해", "이 섹션은 필요 없어". 그리고 Claude한테 돌려보내세요:

문서에 노트를 달아놨어. 전부 반영해서 업데이트해.
아직 구현하지 마.

한 번만 해봐도 "아, 계획 단계에서 이렇게 조율하는 거구나"가 체감될 거예요.

3. 구현 프롬프트 저장해두기 (1분)

Boris Tane의 구현 프롬프트를 CLAUDE.md나 메모장에 저장해두세요. 매번 새로 쓸 필요 없어요:

전부 구현해. 작업이나 단계를 끝낼 때마다 plan.md에 완료 표시를 해. 
모든 작업과 단계가 완료될 때까지 멈추지 마.
불필요한 주석이나 jsdoc을 달지 마.
any나 unknown 타입을 쓰지 마.
지속적으로 타입체크를 돌려서 새로운 이슈를 만들지 않는지 확인해.

이건 프로젝트에 맞게 변형하면 돼요. "타입체크" 대신 "테스트를 돌려"일 수도 있고, "any/unknown 금지" 대신 여러분 프로젝트의 금기 사항이 들어갈 수도 있고요.


마무리

Boris Tane의 워크플로우를 읽으면서 계속 떠오른 문장이 있어요. 이전 뉴스레터에서 인용했던 말인데요.

"AI에게 더 많은 자유를 주려면, 더 단단한 울타리가 필요하다."

plan.md가 그 울타리예요. Claude한테 "전부 구현해, 멈추지 마"라고 할 수 있는 이유는, 그 전에 3번이나 계획을 다듬었기 때문이에요. 울타리가 단단하니까 그 안에서 자유롭게 달리게 할 수 있는 거예요.

프롬프트 기법도 중요하고, 워크트리도 중요하고, CLAUDE.md도 중요해요. 근데 결국 가장 레버리지가 높은 건 "코드를 짜기 전에 얼마나 생각했느냐"인 것 같아요. 도구가 뭐든 간에요.

강의에서도 "탐색 → 설계 → 구현 → 커밋" 순서를 강조하는데요. Boris Tane의 Annotation Cycle은 그 "설계" 단계를 더 정밀하게 만드는 방법이에요. 한 번 해보시면 계획 문서 없이 코드를 짜는 게 불안해질 거예요.

매주 바이브 코딩 실전 인사이트를 보내드립니다.

Claude Code로 진짜 제품을 만드는 법이 궁금하시면,

👉 에피코딩 강의 보러 가기 (https://effycoding.pages.dev)

이 뉴스레터가 도움이 됐다면, 동료 개발자에게 공유해주세요.

다가올 뉴스레터가 궁금하신가요?

지금 구독해서 새로운 레터를 받아보세요

✉️

이번 뉴스레터 어떠셨나요?

에피의 바이브 코딩 님에게 ☕️ 커피와 ✉️ 쪽지를 보내보세요!

댓글

의견을 남겨주세요

확인
의견이 있으신가요? 제일 먼저 댓글을 달아보세요 !
© 2026 에피의 바이브 코딩

클로드 코드, 코딩 에이전트

메일리 로고

도움말 자주 묻는 질문 오류 및 기능 관련 제보

서비스 이용 문의admin@team.maily.so

메일리 사업자 정보

메일리 (대표자: 이한결) | 사업자번호: 717-47-00705 | 서울특별시 성동구 왕십리로10길 6, 11층 1109호

이용약관 | 개인정보처리방침 | 정기결제 이용약관 | 라이선스