| source | https://boristane.com/blog/how-i-use-claude-code/ |
|---|---|
| created | 2026-04-18 |
| by | openai:gpt-5.4 |
약 9개월 동안 클로드 코드(Claude Code)를 주 개발 도구로 써 왔다. 그 과정에서 정착한 워크플로는 대부분이 AI 코딩 도구를 쓰는 방식과는 크게 다르다. 대다수 개발자는 프롬프트를 입력하고, 가끔 계획 모드를 쓰고, 오류를 고치고, 다시 반복한다. 인터넷에 아주 깊이 잠겨 있는 사람들은 ralph 루프, MCP, 가스 타운(그거 기억나는가?) 같은 것들을 이어 붙인다. 하지만 두 경우 모두 조금만 복잡해져도 결과물이 엉망이 되기 쉽고 쉽게 무너진다.
내가 설명하려는 워크플로에는 하나의 핵심 원칙이 있다. 문서로 작성된 계획을 검토하고 승인하기 전까지는 클로드가 코드를 쓰게 두지 말라. 계획과 실행을 분리하는 이 원칙이 내가 하는 일 가운데 가장 중요하다. 이 방식은 불필요한 노력을 막고, 아키텍처 결정에 대한 통제권을 유지하게 해 주며, 곧바로 코드로 뛰어드는 것보다 훨씬 적은 토큰으로도 훨씬 나은 결과를 만들어 낸다.
flowchart LR
R[Research] --> P[Plan]
P --> A[Annotate]
A -->|repeat 1-6x| A
A --> T[Todo List]
T --> I[Implement]
I --> F[Feedback & Iterate]
의미 있는 모든 작업은 정독 지시에서 시작한다. 나는 클로드에게 먼저 코드베이스의 관련 부분을 철저히 이해하라고 요청한다. 그리고 그 결과를 채팅 안의 구두 요약으로 끝내지 않고, 항상 영속적인 마크다운 파일에 기록하게 한다.
이 폴더를 깊이 있게 읽고, 어떻게 동작하는지, 무엇을 하는지, 어떤 구체적 특성이 있는지 철저히 이해하라. 끝나면 배운 내용과 발견한 점을 자세히
research.md에 작성하라.알림 시스템을 매우 자세히 분석하고, 그 복잡한 세부 사항까지 이해한 뒤, 알림이 어떻게 동작하는지에 대해 알아야 할 모든 내용을 담은 상세한
research.md문서를 작성하라.작업 스케줄링 흐름을 전반적으로 살펴보고 깊이 이해한 다음, 잠재적 버그를 찾아라. 이 시스템은 취소됐어야 할 작업을 가끔 실행하므로 분명 버그가 있다. 모든 버그를 찾을 때까지 계속 조사하라. 모든 버그를 찾기 전에는 멈추지 말라. 끝나면 발견한 내용을 자세한 보고서로
research.md에 작성하라.
표현을 보라. “깊이 있게(deeply)”, “매우 자세히(in great details)”, “복잡한 세부 사항(intricacies)”, “전부 살펴보라(go through everything)”. 이것은 군더더기가 아니다. 이런 말을 넣지 않으면 클로드는 훑어보기만 한다. 파일 하나를 읽고 함수가 시그니처 수준에서 무슨 일을 하는지만 확인한 뒤 넘어간다. 피상적인 읽기는 허용되지 않는다는 신호를 분명히 줘야 한다.
문서 결과물인 research.md는 매우 중요하다. 클로드에게 숙제를 시키려는 게 아니다. 이것은 내가 검토하는 표면이다. 나는 이 문서를 읽고 클로드가 시스템을 실제로 이해했는지 확인할 수 있다. 그리고 계획 단계로 넘어가기 전에 오해를 바로잡을 수 있다. 리서치가 틀리면 계획도 틀리고, 구현도 틀린다. 입력이 엉망이면 출력도 엉망이다.
AI 보조 코딩에서 가장 비용이 큰 실패 방식은 잘못된 문법이나 나쁜 로직이 아니다. 따로 떼어 놓고 보면 작동하지만 주변 시스템을 망가뜨리는 구현이다. 기존 캐시 계층을 무시하는 함수, ORM 관례를 고려하지 않은 마이그레이션, 이미 다른 곳에 있는 로직을 또 만드는 API 엔드포인트가 그런 예다. 리서치 단계는 이런 문제를 막아 준다.
리서치를 검토하고 나면, 별도의 마크다운 파일에 상세한 구현 계획을 요청한다.
시스템이 <비즈니스 결과>를 수행하도록 확장하는 새로운 기능 <이름과 설명>을 만들고 싶다. 이를 어떻게 구현할지 설명하는 상세한
plan.md문서를 작성하라. 코드 스니펫도 포함하라.목록 엔드포인트는 오프셋이 아니라 커서 기반 페이지네이션을 지원해야 한다. 이를 어떻게 달성할지에 대한 상세한
plan.md를 작성하라. 변경안을 제안하기 전에 소스 파일을 읽고, 실제 코드베이스를 바탕으로 계획을 세워라.
생성된 계획에는 항상 접근 방식에 대한 자세한 설명, 실제 변경 사항을 보여 주는 코드 스니펫, 수정될 파일 경로, 그리고 고려해야 할 사항과 트레이드오프가 담긴다.
나는 클로드 코드의 내장 계획 모드 대신 내 .md 계획 파일을 쓴다. 내장 계획 모드는 별로다. 마크다운 파일을 쓰면 내가 완전히 통제할 수 있다. 편집기에서 직접 수정할 수 있고, 인라인 메모를 추가할 수 있으며, 프로젝트 안에 실제 산출물로 남는다.
내가 아주 자주 쓰는 요령 하나가 있다. 범위가 잘 정의된 기능이고, 오픈소스 저장소에서 좋은 구현을 본 적이 있다면 계획 요청과 함께 그 코드를 참고 자료로 제공한다. 예를 들어 정렬 가능한 ID를 추가하고 싶다면, 그 기능을 잘 구현한 프로젝트의 ID 생성 코드를 붙여 넣고 “이 프로젝트는 정렬 가능한 ID를 이렇게 구현한다. 비슷한 접근을 우리에게 어떻게 도입할 수 있을지 설명하는 plan.md를 작성하라”라고 말한다. 클로드는 처음부터 설계하게 할 때보다 구체적인 참고 구현이 있을 때 훨씬 더 잘한다.
하지만 흥미로운 것은 계획 문서 자체가 아니다. 진짜 중요한 것은 그다음에 일어나는 일이다.
이 부분이 내 워크플로에서 가장 특징적인 부분이다. 그리고 내가 가장 큰 가치를 더하는 단계이기도 하다.
flowchart TD
W[Claude writes plan.md] --> R[I review in my editor]
R --> N[I add inline notes]
N --> S[Send Claude back to the document]
S --> U[Claude updates plan]
U --> D{Satisfied?}
D -->|No| R
D -->|Yes| T[Request todo list]
클로드가 계획을 작성하면, 나는 편집기에서 그것을 열고 문서 안에 직접 인라인 메모를 추가한다. 이 메모는 가정을 바로잡고, 접근 방식을 거부하고, 제약 조건을 추가하고, 클로드가 모르는 도메인 지식을 제공한다.
메모 길이는 천차만별이다. 어떤 때는 클로드가 선택 사항이라고 적어 둔 매개변수 옆에 “선택 아님”이라고 두 단어만 적는다. 또 어떤 때는 비즈니스 제약을 설명하는 문단을 쓰거나, 내가 기대하는 데이터 형태를 보여 주는 코드 스니펫을 붙여 넣는다.
내가 실제로 넣는 메모는 이런 식이다.
drizzle:generate를 사용하라” — 클로드가 모르는 도메인 지식visibility 필드는 개별 항목이 아니라 목록 자체에 있어야 한다. 목록이 공개라면 모든 항목도 공개다. 스키마 섹션을 그에 맞게 재구성하라” — 계획의 한 섹션 전체를 방향 전환그다음 나는 클로드를 다시 문서로 돌려보낸다.
문서에 몇 가지 메모를 추가했다. 모든 메모를 반영해서 문서를 수정하라. 아직 구현하지는 말라.
이 사이클은 1회에서 6회까지 반복된다. 여기서 “아직 구현하지는 말라”라는 명시적 가드가 핵심이다. 이 문구가 없으면 클로드는 계획이 그럭저럭 괜찮다고 판단하는 순간 바로 코드를 쓰기 시작한다. 하지만 내가 괜찮다고 말하기 전까지는 충분히 좋은 계획이 아니다.
마크다운 파일은 나와 클로드 사이의 공유 가능한 변경 상태(shared mutable state) 역할을 한다. 나는 내 속도에 맞춰 생각할 수 있고, 무엇이 잘못됐는지 정확한 위치에 주석을 달 수 있으며, 맥락을 잃지 않고 다시 작업에 들어갈 수 있다. 채팅 메시지 하나에 모든 걸 설명하려고 애쓰는 게 아니다. 문서에서 문제가 있는 정확한 지점을 짚고, 바로 그곳에 수정 내용을 적는다.
이 방식은 채팅 메시지로 구현 방향을 조정하려는 것과 근본적으로 다르다. 계획 문서는 구조화되어 있고 완결된 명세이기 때문에 전체를 한꺼번에 검토할 수 있다. 반면 채팅 대화는 결정을 다시 파악하려면 계속 스크롤해 가며 재구성해야 한다. 언제나 계획 문서 쪽이 낫다.
“메모를 추가했으니 계획을 업데이트하라”는 과정을 세 번만 반복해도, 평범한 구현 계획이 기존 시스템에 정확히 들어맞는 계획으로 바뀔 수 있다. 클로드는 코드를 이해하고, 해결책을 제안하고, 구현을 작성하는 데 뛰어나다. 하지만 내 제품의 우선순위, 사용자들이 실제로 겪는 불편, 내가 감수할 엔지니어링 트레이드오프까지는 알지 못한다. 주석 사이클은 그런 판단을 내가 주입하는 방식이다.
구현을 시작하기 전에 나는 항상 세분화된 작업 분해를 요청한다.
계획을 완료하는 데 필요한 모든 단계와 개별 작업을 포함한 상세한 할 일 목록을 계획에 추가하라. 아직 구현하지는 말라.
이렇게 하면 구현 중 진행 상황을 추적할 수 있는 체크리스트가 생긴다. 클로드는 진행하면서 항목을 완료로 표시하므로, 나는 어느 시점이든 계획 문서를 흘끗 보기만 해도 현재 어디까지 왔는지 정확히 알 수 있다. 몇 시간씩 이어지는 세션에서는 특히 유용하다.
계획이 준비되면 구현 명령을 내린다. 나는 여러 세션을 거치며 이것을 재사용 가능한 표준 프롬프트로 다듬었다.
전부 구현하라. 작업이나 단계를 끝낼 때마다 계획 문서에 완료로 표시하라. 모든 작업과 단계가 끝날 때까지 멈추지 말라. 불필요한 주석이나 jsdoc을 추가하지 말고,
any나unknown타입도 쓰지 말라. 새 문제를 만들고 있지 않은지 확인하려고 타입 체크를 계속 실행하라.
이 한 문장에 중요한 요소가 모두 들어 있다.
any나 unknown 타입을 쓰지 말라”: 엄격한 타이핑을 유지하라.나는 거의 모든 구현 세션에서 이 표현을 그대로, 혹은 약간만 바꿔서 쓴다. 내가 “전부 구현하라”라고 말할 때쯤이면 모든 결정은 이미 내려졌고 검증도 끝난 상태다. 구현은 창의적 작업이 아니라 기계적인 작업이 된다. 이것은 의도적이다. 나는 구현이 지루해지길 바란다. 창의적인 일은 주석 사이클에서 이미 끝났다. 계획만 올바르면 실행은 단순해야 한다.
계획 단계가 없으면 대체로 이런 일이 벌어진다. 클로드가 초반에 그럴듯하지만 틀린 가정을 하고, 그 위에 15분 동안 구현을 쌓아 올린다. 그러면 나는 바뀐 것들을 줄줄이 되돌려야 한다. “아직 구현하지는 말라”는 가드는 이런 문제를 완전히 없앤다.
클로드가 계획을 실행하기 시작하면, 내 역할은 아키텍트에서 감독자로 바뀐다. 프롬프트도 훨씬 짧아진다.
flowchart LR
I[Claude implements] --> R[I review / test]
R --> C{Correct?}
C -->|No| F[Terse correction]
F --> I
C -->|Yes| N{More tasks?}
N -->|Yes| I
N -->|No| D[Done]
계획 단계의 메모가 한 문단일 수 있다면, 구현 단계의 수정 지시는 대개 한 문장으로 끝난다.
deduplicateByTitle 함수를 구현하지 않았다.”클로드는 계획과 현재 세션의 전체 맥락을 갖고 있으므로, 짧은 수정 지시만으로도 충분하다.
프런트엔드 작업은 가장 반복적이다. 나는 브라우저에서 테스트해 보고 빠르게 수정 지시를 던진다.
시각적인 문제에는 가끔 스크린샷도 첨부한다. 정렬이 어긋난 표를 설명하는 것보다 스크린샷 한 장이 문제를 더 빨리 전달한다.
또한 나는 기존 코드를 계속 참조한다.
이 방식은 처음부터 디자인을 설명하는 것보다 훨씬 정확하다. 성숙한 코드베이스의 기능 대부분은 기존 패턴의 변형이다. 새 설정 페이지는 기존 설정 페이지처럼 보여야 한다. 참고 대상을 가리키면 암묵적인 요구 사항까지 일일이 설명하지 않아도 된다. 보통 클로드는 수정하기 전에 해당 참고 파일을 먼저 읽는다.
무언가가 잘못된 방향으로 가기 시작하면, 나는 억지로 덧대어 고치려 하지 않는다. git 변경 사항을 버리고 되돌린 뒤 범위를 다시 잡는다.
되돌린 다음 범위를 좁히면, 나쁜 접근을 점진적으로 고치려 할 때보다 거의 항상 더 나은 결과가 나온다.
실행은 클로드에게 위임하더라도, 무엇을 만들지에 대한 완전한 자율성은 절대 주지 않는다. 실제 방향 조정의 대부분은 plan.md 문서 안에서 내가 한다.
이 점이 중요한 이유는, 클로드가 기술적으로는 맞지만 프로젝트에는 맞지 않는 해결책을 제안할 때가 있기 때문이다. 접근 방식이 과도하게 복잡할 수도 있고, 시스템의 다른 부분이 의존하는 공개 API 시그니처를 바꿔 버릴 수도 있고, 더 단순한 방법으로 충분한데 굳이 더 복잡한 쪽을 고를 수도 있다. 나는 시스템 전체, 제품 방향, 엔지니어링 문화에 대한 맥락을 알고 있지만 클로드는 그렇지 않다.
flowchart TD
P[Claude proposes changes] --> E[I evaluate each item]
E --> A[Accept as-is]
E --> M[Modify approach]
E --> S[Skip / remove]
E --> O[Override technical choice]
A & M & S & O --> R[Refined implementation scope]
제안에서 필요한 것만 취사선택하기: 클로드가 여러 문제를 짚어 내면, 나는 그것을 하나씩 검토한다. “첫 번째는 그냥 Promise.all을 써라. 너무 복잡하게 만들지 말라. 세 번째는 가독성을 위해 별도 함수로 추출하라. 네 번째와 다섯 번째는 무시하라. 그 복잡성을 들일 가치가 없다.” 지금 무엇이 중요한지에 대한 내 판단에 따라 항목 단위로 결정을 내리는 것이다.
범위 줄이기: 계획에 있으면 좋지만 지금 당장 필요하지 않은 요소가 들어 있으면 적극적으로 쳐낸다. “계획에서 다운로드 기능은 빼라. 지금은 이것을 구현하고 싶지 않다.” 이렇게 해야 범위가 불어나는 것을 막을 수 있다.
기존 인터페이스 보호하기: 어떤 것은 바뀌면 안 된다는 걸 알고 있을 때는 강한 제약을 건다. “이 세 함수의 시그니처는 바뀌면 안 된다. 라이브러리가 아니라 호출자가 적응해야 한다.”
기술적 선택 덮어쓰기: 가끔은 클로드가 알 수 없는 내 선호가 분명할 때가 있다. “저것 말고 이 모델을 사용하라”, “커스텀 구현을 쓰지 말고 이 라이브러리의 내장 메서드를 사용하라” 같은 식이다. 빠르고 직접적인 덮어쓰기다.
기계적인 실행은 클로드가 맡고, 판단이 필요한 결정은 내가 한다. 큰 결정은 계획에 미리 담기고, 구현 중 새로 드러나는 작은 결정은 선택적인 지도로 해결한다.
나는 리서치, 계획, 구현을 하나의 긴 세션 안에서 처리한다. 각각을 별도 세션으로 나누지 않는다. 하나의 세션은 폴더를 깊이 읽는 것에서 시작해서, 계획 주석을 세 번 정도 반복하고, 그다음 전체 구현으로 이어지는 연속된 대화가 될 수 있다.
사람들이 말하는, 컨텍스트 창의 50%를 넘기면 성능이 떨어진다는 현상은 나는 체감하지 못하고 있다. 오히려 내가 “전부 구현하라”라고 말할 때쯤이면, 클로드는 세션 내내 이해를 쌓아 왔다. 리서치 단계에서 파일을 읽었고, 주석 사이클에서 머릿속 모델을 정교하게 다듬었고, 내가 제공한 도메인 지식 교정을 흡수했다.
컨텍스트 창이 차면 클로드의 자동 압축이 충분한 맥락을 유지해 준다. 그리고 영속적인 결과물인 계획 문서는 압축 이후에도 손실 없이 남는다. 나는 언제든 클로드에게 그 문서를 다시 가리킬 수 있다.
깊이 읽고, 계획을 쓰고, 계획이 맞아질 때까지 주석을 달고, 그다음에는 중간에 멈추지 말고 타입 체크를 하면서 전부 실행하게 하라.
그게 전부다. 마법 같은 프롬프트도 없고, 복잡한 시스템 지시도 없고, 영리한 꼼수도 없다. 생각과 타이핑을 분리하는 훈련된 파이프라인이 있을 뿐이다. 리서치는 클로드가 무지한 변경을 하지 못하게 막는다. 계획은 잘못된 변경을 막는다. 주석 사이클은 내 판단을 주입한다. 그리고 구현 명령은 모든 결정이 끝난 뒤 방해 없이 달리게 해 준다.
내 워크플로를 한번 써 보라. 코드와 너 사이에 주석이 달린 계획 문서 하나 없이 코딩 에이전트로 어떻게든 제품을 배포해 왔다는 사실이 이상하게 느껴질 것이다.
나는 또한 nominal.dev를 만들고 있다. 2026년에 누구도 온콜을 서서는 안 되기 때문이다.