Claude Fable 5로 일하다 보면 오래된 교훈을 계속 다시 배웁니다. 지도는 영토가 아니다.
지도는 해야 할 일을 나타낸 그림입니다. 내가 Claude에게 건네는 프롬프트, 스킬, 맥락이 바로 지도입니다. 영토는 일이 실제로 벌어지는 곳입니다. 코드베이스, 현실 세계, 그리고 거기 놓인 진짜 제약입니다.
지도와 영토의 차이를 저는 미지수(unknowns)라고 부릅니다. Claude가 미지수를 만나면, 내가 뭘 원하는지 가장 그럴듯하게 추측해서 결정을 내려야 합니다. 하는 일이 많아질수록 Claude가 마주칠 미지수도 늘어납니다.
Fable은 일의 품질이 미지수를 얼마나 잘 밝혀내느냐에 걸려 있다고 느끼게 만든 첫 모델입니다.
중요한 건, 미리 계획하는 것만으로는 늘 충분하지 않다는 점입니다. 미지수는 구현 깊숙한 곳에서 튀어나오기도 하고, 애초에 이 문제를 전혀 다른 방식으로 풀어야 한다는 사실을 미지수가 드러내기도 합니다.
Fable과 일하는 건 구현 전, 구현 중, 구현 후에 걸쳐 나의 미지수를 반복해서 찾아내는 과정이라는 걸 알게 됐습니다.
미지수를 찾는 예시 아티팩트를 여기 몇 개 만들어 뒀습니다. 다만 언제 이걸 써야 할지 감을 잡으려면 꼭 다시 돌아와서 읽어 보세요.
나의 미지수 알기
당신의 미지수는 무엇인가요? 저는 Claude에게 문제를 가져갈 때 네 가지로 나눠 봅니다.
- Known Knowns(아는 걸 아는 것): 사실상 내 프롬프트에 담긴 내용입니다. 내가 원하는 걸 에이전트에게 무엇이라고 말하나요?
- Known Unknowns(모른다는 걸 아는 것): 아직 못 정했지만, 내가 못 정했다는 사실은 알고 있는 것.
- Unknown Knowns(안다는 걸 모르는 것): 너무 당연해서 적어 둘 생각조차 안 하지만, 보면 바로 알아챌 것.
- Unknown Unknowns(모른다는 것조차 모르는 것): 아예 고려해 본 적 없는 것. 내가 모르고 있다는 것조차 모르는 지식. 이게 얼마나 좋아질 수 있는지 내가 알고 있나요?
가장 뛰어난 에이전트 코더는 미지수가 상대적으로 적습니다. Boris나 Jarred 같은 사람이 프롬프트를 짜는 걸 보면, 자기가 원하는 걸 세세하게 알고 있다는 게 확연히 드러납니다. 이들은 코드베이스와 모델 동작 양쪽을 깊이 이해하고 있습니다.
하지만 이들도 미지수가 있다고 전제합니다. 여러모로 미지수를 줄이고 대비하는 것이 에이전트 코딩의 핵심 기술입니다. 다행히 이 기술은 Claude와 일하면서 늘릴 수 있습니다.
Claude가 당신을 돕게 하기
Claude에게 지시하는 건 미묘한 균형 잡기입니다. 너무 구체적이면 방향을 트는 게 더 나을 때조차 Claude가 지시를 그대로 따릅니다. 너무 모호하면 당신의 일에 안 맞을 수도 있는 업계 관행에 기대어 Claude가 알아서 선택하고 가정합니다.
미지수를 챙기지 않으면 양쪽 모두에서 실패합니다. 길이 언제 장애물로 막힐지도 모르고, 길이 언제 뻥 뚫려 있을지도 모릅니다. 그런데도 그럴 때 Claude가 방향을 틀어 주길 바랍니다.
Claude는 당신이 미지수를 더 빨리 찾도록 도울 수 있습니다. 코드베이스와 인터넷을 아주 빠르게 뒤지고, 웬만한 주제는 당신보다 훨씬 많이 압니다. 실패에서 다시 시도하는 것도 더 빠릅니다.
이 과정에서 가장 중요한 건 당신의 출발점에 대한 맥락을 Claude에게 주는 것입니다. 예를 들어 지금 생각이 어디쯤 와 있는지 말해 주고, 이 문제와 코드베이스에 대한 경험을 털어놓고, Claude가 생각의 동반자처럼 함께 일하게 하세요.
전에도 Claude와 HTML을 함께 쓰는 법을 쓴 적이 있는데, 거의 모든 경우 HTML 아티팩트가 무언가를 시각화하고 표현하는 가장 좋은 방법입니다.
이 글에서는 이런 미지수를 드러내는 데 쓰는 몇 가지 패턴을 자세히 다룹니다. 매번 모든 기법을 쓰지는 않지만, 갖춰 두면 쓸모 있는 기법 모음입니다.
구현 전
사각지대 훑기(Blind Spot Pass)
일을 시작할 때 가장 쓸모 있는 것 하나는 나의 사각지대를 파악하는 겁니다. 예를 들어 코드베이스의 새로운 부분에서 기능을 만들거나, 디자인을 다듬는 것처럼 낯선 일을 Claude와 함께 한다면, Unknown Unknowns가 많을 가능성이 큽니다.
무슨 질문을 해야 할지, 좋은 게 어떤 모습인지, 과거에 어떤 작업이 있었는지, 어떤 함정을 피해야 하는지 모를 수 있습니다.
이럴 때는 Claude에게 나의 Unknown Unknowns를 찾아서 설명해 달라고 하면 됩니다. 저는 "blindspot pass", "unknown unknowns"라는 말을 문자 그대로 즐겨 씁니다. 당신이 누구이고 무엇을 아는지 맥락을 주는 것이 대개 중요합니다.
예시 프롬프트:
"새 인증 제공자를 붙이려는데 이 코드베이스의 인증 모듈은 하나도 몰라. 사각지대 훑기를 해서 내가 알아야 할 unknown unknowns를 짚어 주고, 내가 프롬프트를 더 잘 쓰도록 도와줘."
"컬러 그레이딩이 뭔지 모르는데 이 영상을 그레이딩해야 해. 컬러 그레이딩에 대한 내 unknown unknowns를 이해하도록 가르쳐 줘서, 프롬프트를 더 잘 쓰게 해 줘."
브레인스토밍과 프로토타입
봐야만 정의할 수 있는 기준처럼 Unknown Knowns가 많은 영역에서 일할 때는, Claude와 함께 브레인스토밍하고 프로토타입을 만들어 봅니다.
Unknown Knowns를 프로토타이핑 단계에서 일찍 찾아내고 말로 옮기는 건 아주 값집니다. 구현 중에 발견하면 (상대적으로) 비싸게 치이기 때문입니다. 기능이나 명세가 조금만 바뀌어도 코드 구현은 크게 달라질 수 있고, 에이전트가 앞서 만든 변경을 되돌리기가 더 어려워질 수 있습니다.
예를 들어 백엔드 라우트를 연결하거나 프런트엔드에 상태를 더 두지 않고도, 프레임에 버튼을 하나 넣으면 어떻게 보이는지만 보고 싶을 수 있습니다.
시각 디자인은 제게 말로 옮기기 어려운 영역이지만, 보면 원하는 게 뭔지 압니다. 이럴 때는 하나의 아티팩트에 대해 여러 디자인 방향을 요청합니다.
저는 거의 모든 코딩 세션을 탐색이나 브레인스토밍 단계로 시작합니다. 이렇게 하면 의도를 가지고 프로젝트 범위를 정하는 데서 출발합니다. Claude는 제가 놓쳤을 값진 접근을 찾아내기도 하고, 때로는 큰 그림을 놓치기도 합니다. 브레인스토밍은 제가 범위를 너무 좁게도, 너무 넓게도 잡지 않게 막아 줍니다.
예시 프롬프트:
"이 데이터로 대시보드를 원하는데 나는 시각 감각이 없고 뭐가 가능한지도 몰라. 내가 반응할 수 있게 완전히 다른 디자인 방향 4개를 담은 HTML 페이지를 만들어 줘."
"뭘 연결하기 전에, 가짜 데이터로 새 에디터 툴바를 흉내 낸 HTML 파일 하나만 만들어 줘. 실제 앱을 건드리기 전에 레이아웃부터 보고 반응하고 싶어."
"내 문제는 대충 이래. 온보딩 뒤에 사용자가 이탈해. 코드베이스를 뒤져서 손볼 수 있는 지점 10개를, 가장 값싼 것부터 가장 야심 찬 것까지 브레인스토밍해 줘. 어떤 게 와닿는지는 내가 알려 줄게."
인터뷰
브레인스토밍을 충분히 하고 나서도 미지수는 여전히 남아 있기 마련입니다.
이럴 때는 Claude에게 애매한 부분을 두고 나를 인터뷰해 달라고 합니다. 인터뷰를 부탁할 때는 질문 방향을 잡아 주도록 문제에 대한 맥락을 주려고 해 보세요. 예시는 이렇습니다.
예시 프롬프트:
"애매한 부분에 대해 한 번에 하나씩 질문해서 나를 인터뷰해 줘. 내 답이 아키텍처를 바꿀 만한 질문을 먼저 해 줘."
레퍼런스
원하는 걸 자세히 말로 못 할 때가 있습니다. 예를 들어 그걸 표현할 언어가 없거나, 너무 복잡해서 설명에 한참이 걸릴 수 있습니다.
이럴 때 가장 좋은 답은 레퍼런스입니다. 다이어그램, 문서, 사진을 넣을 수도 있지만, 단연 최고의 레퍼런스는 소스 코드입니다.
어떤 라이브러리가 무언가를 특정 방식으로 구현했거나 정말 마음에 드는 디자인 컴포넌트가 있다면, 그 폴더를 Fable에게 가리키고 뭘 봐야 하는지 말해 주면 됩니다. 언어가 달라도 상관없습니다.
Claude Design이 작동하는 방식도 이렇습니다. 파일을 건네지 않아도 됩니다(건네도 되지만요). 마음에 드는 웹사이트의 한 모듈을 가리키면, Claude는 스크린샷만이 아니라 그 밑의 코드를 읽습니다. 그러면 마크업, 구조, 그 컴포넌트가 실제로 어떻게 만들어졌는지에 대해 훨씬 풍부한 정보를 얻습니다.
예시 프롬프트:
"vendor/rate-limiter에 있는 이 Rust 크레이트가 내가 원하는 백오프 동작을 정확히 구현하고 있어. 이걸 읽고 우리 TypeScript API 클라이언트에 같은 의미로 다시 구현해 줘."
구현 계획
이제 구현할 준비가 됐다 싶으면, 저는 Claude에게 구현 계획을 짜서 검토하게 해 달라고 합니다. 이때 가장 바뀔 가능성이 큰 부분, 예를 들어 데이터 모델, 타입 인터페이스, UX 흐름에 초점을 맞추게 합니다. 그래야 제가 실제로 손봐야 할 것들을 Claude가 먼저 드러내 줍니다.
예시 프롬프트:
"구현 계획을 HTML로 써 줘. 단, 내가 가장 손댈 만한 결정부터 앞세워. 데이터 모델 변경, 새 타입 인터페이스, 사용자에게 보이는 모든 것 말이야. 기계적인 리팩터링은 맨 아래에 묻어 둬. 그 부분은 너를 믿어."
구현 중
구현 노트
계획이 만족스러우면 새 세션을 열고 아티팩트를 프롬프트에 넘깁니다. 예를 들어 명세 파일과 프로토타입을 넣고 에이전트에게 구현을 맡깁니다.
하지만 아무리 계획을 많이 세워도 Unknown Unknowns는 늘 숨어 있는 게 사실입니다. 에이전트가 일하다가 코드에서 발견한 예외 상황 때문에 다른 방향을 잡아야 한다는 걸 깨달을 수도 있습니다.
저는 Claude Code에게 임시 'implementation-notes.md'(또는 .html) 파일을 두고, 내리는 결정을 기록하게 합니다. 그래야 다음 시도에서 배울 수 있습니다.
예시 프롬프트:
"implementation-notes.md 파일을 유지해. 계획에서 벗어나게 만드는 예외 상황을 만나면, 보수적인 쪽을 골라 'Deviations' 항목에 기록하고 계속 진행해."
구현 후
설득 자료와 설명 자료
무언가를 출시할 때 가장 중요한 부분 하나는 동의와 승인을 받는 것입니다. 최종 문서에 설득 자료와 설명 자료를 담아 두면 이렇게 도움이 됩니다.
- 검토자가 당신이 처음 겪었던 것과 같은 미지수에서 출발할 때, 이해를 앞당깁니다.
- 전문가가 당신이 예상 가능한 미지수와 흔한 실패 지점을 챙겼는지 보고 싶어 할 때, 승인을 앞당깁니다.
예시 프롬프트:
"프로토타입, 명세, 구현 노트를 Slack에 올려 동의를 받을 수 있는 문서 하나로 묶어 줘. 데모 GIF를 맨 앞에 둬."
퀴즈
긴 작업 세션이 끝나면, Claude가 내 생각보다 훨씬 많은 걸 해냈을 수 있습니다. 코드 diff만 읽어서는 무슨 일이 있었는지 얕게밖에 이해가 안 됩니다. 동작 상당수가 기존 코드 경로에 달려 있기 때문입니다.
맥락을 잔뜩 준 뒤 Claude에게 이번 변경에 대해 나를 퀴즈로 시험해 달라고 하면, 무슨 일이 일어났는지 이해하는 데 도움이 됩니다. 저는 퀴즈를 완벽하게 맞힌 뒤에야 머지합니다.
예시 프롬프트:
"이번 변경에서 벌어진 일을 전부 확실히 이해하고 싶어. 변경 내용을 맥락, 직관, 무엇을 왜 했는지와 함께 읽고 이해할 수 있게 HTML 리포트로 만들어 주고, 맨 아래에는 내가 반드시 통과해야 할 변경 내용 퀴즈를 붙여 줘."
이 모든 게 합쳐지는 방식: Fable 출시
Fable 출시 영상은 전부 Claude Code로 편집했습니다. 제게는 새로운 분야였고, 결코 전문가가 아니었습니다.
그래서 아는 것부터 시작했습니다. Claude가 코드로 영상을 편집하고 받아쓸 수 있다는 건 알았지만, 그게 충분히 정확한지는 확신이 없었습니다. 그래서 Whisper 같은 받아쓰기가 어떻게 작동하는지, ffmpeg로 '음…' 같은 군말이나 긴 침묵을 정확히 잘라낼 수 있는지 Claude에게 설명해 달라고 했습니다.
저는 제가 말하는 단어에 맞춰 타이밍이 잡힌 UI를 Claude가 만들어 주길 원했지만, 될지 확신이 없어서 Remotion과 받아쓰기로 프로토타입 영상을 만들어 되는지 보게 했습니다.
마지막으로 영상 자체가 좀 칙칙해 보였는데, 이게 컬러 그레이딩 때문이라는 건 알았지만 컬러 그레이딩이 정확히 뭔지는 몰랐습니다. 처음엔 Claude에게 변형을 몇 개 만들게 해서 고르려 했지만, 컬러 그레이딩에서 '좋은' 게 어떤 모습인지 제가 모른다는 걸 깨달았습니다. 그래서 대신 Claude에게 컬러 그레이딩을 가르쳐 달라고 해서 나의 미지수를 찾아냈습니다.
이에 대한 더 자세한 설명은 여기서 볼 수 있습니다.
지도와 영토 맞추기
모델이 좋아질수록 올바른 접근으로 이룰 수 있는 게 많아집니다. 긴 호흡의 작업이 엉뚱한 결과로 돌아온다면, 미지수를 정의하는 데 시간을 더 들이거나, Claude가 그 미지수를 헤쳐 나가며 즉흥적으로 대응할 수 있는 구현 계획을 세워야 한다는 신호일 가능성이 큽니다.
모든 설명 자료, 브레인스토밍, 인터뷰, 프로토타입, 레퍼런스는 고치는 데 비싸지기 전에 몰랐던 걸 싸게 알아내는 방법입니다.
그러니 다음 프로젝트는 Claude에게 나의 미지수를 찾도록 도와 달라고 하는 것으로 시작해 보세요.