에이전틱 코딩 · 방법론

지도는 영토가 아니다 — AI 코딩 에이전트의 미지수를 찾는 법

AI 코딩 에이전트의 결과물 품질을 가르는 것은 모델의 성능만이 아니다. 내가 무엇을 모르는지를 얼마나 정확히 짚어내느냐가 병목이 된다. 앤스로픽(Anthropic)의 타릭(Thariq)이 정리한 현장 가이드를 바탕으로, '미지수(unknowns)'를 찾아내는 실전 기법을 정리한다.

01지도와 영토

1931년, 수학자이자 의미론 학자였던 알프레드 코집스키(Alfred Korzybski)는 뉴올리언스에서 발표한 논문에서 한 문장을 남겼다. "지도는 영토가 아니다(The map is not the territory)." 지도는 현실을 압축한 표상일 뿐, 현실 그 자체가 아니라는 뜻이다. 어떤 지도도 도시의 온도, 냄새, 소음, 골목의 실제 폭까지 담지는 못한다. 우리는 지도를 통해 세상을 다루지만, 그 지도가 세상과 어긋나는 지점에서 문제가 시작된다.

이 오래된 통찰은 AI 에이전트와 함께 일할 때 매번 다시 배우게 된다. 여기서 지도는 내가 에이전트에게 건네는 것—프롬프트, 스킬, 맥락(context)—이다. 영토는 작업이 실제로 벌어지는 곳—코드베이스, 현실, 그리고 그 안의 진짜 제약들—이다. 그리고 지도와 영토 사이의 간극, 그것이 바로 미지수(unknowns)다.

에이전트는 미지수에 부딪히면 '내가 무엇을 원하는지'에 대한 최선의 추측으로 결정을 내린다. 맡기는 일이 많고 복잡할수록 부딪히는 미지수도 늘어난다. 그래서 작업의 품질은 종종 모델의 능력이 아니라, 그 미지수들을 내가 얼마나 명료하게 정리해 주느냐에 의해 결정된다.

중요한 점은, 미리 계획을 세운다고 미지수가 사라지지 않는다는 것이다. 미지수는 구현 한복판에서 튀어나오기도 하고, 때로는 "애초에 이 문제를 완전히 다른 방식으로 풀어야 한다"는 신호로 나타나기도 한다. 결국 미지수를 다루는 일은 구현 전·중·후에 걸쳐 반복적으로 발견해 나가는 과정이다.

02미지수의 4분면

문제를 들고 에이전트 앞에 앉을 때, 내가 마주한 미지수는 네 갈래로 나뉜다. 이 분류는 갑자기 등장한 것이 아니다. 1955년 심리학자 조지프 루프트(Joseph Luft)와 해링턴 잉햄(Harrington Ingham)이 만든 조하리 창(Johari Window)이 원형이고, 2002년 2월 미국 국방장관 도널드 럼즈펠드(Donald Rumsfeld)가 브리핑에서 "아는 앎, 아는 미지, 모르는 미지"를 언급하며 대중화되었다. 이후 이 2×2 격자는 '럼즈펠드 매트릭스'로 불리며 미 항공우주국(NASA)의 위험 분석 같은 실무에도 쓰였다.

• 아는 앎(Known Knowns) — 프롬프트에 적어 넣은 것. 에이전트에게 명시적으로 요구하는 바다.
• 아는 미지(Known Unknowns) — 아직 정하지 못했지만, 물어봐야 한다는 사실은 내가 인지하고 있는 질문들.
• 모르는 앎(Unknown Knowns) — 너무 당연해서 굳이 적지 않지만, 결과물을 보면 곧바로 "이게 아니지"라고 알아채는 암묵적 기준.
• 모르는 미지(Unknown Unknowns) — 아예 고려조차 못 한 것. 그 길에 구덩이가 있을 수 있다는 사실 자체를 몰랐던 경우다.

뛰어난 에이전틱 코더들의 공통점은 두 가지다. 첫째, 미지수가 애초에 적다. 그들은 자신이 원하는 바를 세밀하게 알고 있고, 코드베이스와 모델의 행동 방식 양쪽에 깊이 동기화되어 있다. 둘째, 그럼에도 그들은 미지수의 존재를 가정한다. 미지수를 줄이고 대비하는 일이야말로 에이전틱 코딩의 핵심 기술이며, 다행히 이 기술은 에이전트와 함께 일하며 키울 수 있다.

03지나친 구체성과 지나친 모호함, 양쪽의 실패

에이전트에게 지시하는 일은 미묘한 균형이다. 너무 구체적으로 지시하면, 방향을 트는 편이 나은 상황에서도 에이전트는 지시를 곧이곧대로 따른다. 반대로 너무 모호하게 지시하면, 에이전트는 업계 관행에 기대어 내 과제에는 맞지 않는 선택과 가정을 해버린다.

미지수를 헤아리지 못하면 이 두 방향 모두에서 실패한다. 길이 장애물로 가득 찰 때가 언제인지 모르고, 반대로 길이 뻥 뚫려 있는데도 에이전트가 방향을 틀어주길 바라는 때가 언제인지도 모른다. 관건은 "언제 못을 박고, 언제 자유를 줄 것인가"를 아는 것이다.

04에이전트를 나의 사고 파트너로

다행히 에이전트는 미지수를 더 빨리 찾도록 도울 수 있다. 코드베이스와 인터넷을 매우 빠르게 훑고, 평균적인 주제에 대해 나보다 많이 알며, 실패로부터 빠르게 다시 시도한다. 이 속도를 미지수 발굴에 쓰는 것이다.

이 과정에서 가장 중요한 것은 출발점에 대한 맥락을 주는 것이다. 내가 지금 사고의 어디쯤 와 있는지, 이 문제와 코드베이스에 얼마나 익숙한지를 솔직히 밝히고, 에이전트를 지시 수행자가 아니라 함께 고민하는 사고 파트너(thought partner)로 대하는 것이다. 그리고 이렇게 발굴한 것을 눈으로 확인하고 다룰 때, 대부분의 경우 HTML 아티팩트가 가장 좋은 표현 수단이 된다. 화면에서 곧바로 반응하고 고칠 수 있기 때문이다.

05전·중·후: 미지수를 찾는 작업 흐름

아래는 미지수를 발견하기 위한 기법들을 구현 단계별로 정리한 것이다. 매번 전부 쓸 필요는 없다. 상황에 맞게 꺼내 쓰는 도구 모음으로 보면 된다.

06구현 전 — 판을 짜기

블라인드 스팟 패스

새로운 코드 영역에서 기능을 짜거나, 디자인처럼 낯선 작업을 맡길 때는 '모르는 미지'가 잔뜩 깔려 있다. 무엇을 물어야 할지, 무엇이 '좋은 결과'인지, 과거에 어떤 시도가 있었는지, 어떤 함정을 피해야 하는지조차 모른다. 이때는 에이전트에게 직접 내 사각지대를 찾아 설명해 달라고 요청한다. "블라인드 스팟 패스", "모르는 미지" 같은 표현을 문자 그대로 써도 좋다. 내가 누구이고 무엇을 아는지 맥락을 함께 주는 것이 특히 중요하다.

브레인스토밍과 프로토타입

'모르는 앎'이 많은 영역—즉 보기 전에는 정의할 수 없지만 보면 곧바로 판단할 수 있는 기준이 많은 영역—에서는 에이전트와 함께 브레인스토밍하고 프로토타입을 만든다. 이 암묵적 기준을 프로토타이핑 단계에서 일찍 말로 끄집어내는 것은 매우 값지다. 구현 도중에 발견하면 상대적으로 비싸기 때문이다. 사양이나 기능의 작은 변화가 코드에서는 전혀 다른 구현으로 이어지고, 이미 만든 것을 되돌리기는 어렵다.

예컨대 버튼 하나를 화면에 얹었을 때 어떤 느낌인지 보고 싶을 뿐이라면, 백엔드 경로를 연결하거나 프론트엔드 상태를 관리할 필요 없이 목업만으로 충분하다. 나는 거의 모든 코딩 세션을 탐색·브레인스토밍 단계로 시작한다. 그래야 의도를 가지고 범위를 정할 수 있고, 에이전트가 내가 놓쳤을 고가치 접근을 제안해 주기도 한다.

인터뷰

충분히 브레인스토밍을 해도 미지수는 남는다. 이때는 에이전트에게 나를 인터뷰해 달라고 요청한다. 모호하거나 애매한 지점을 한 번에 하나씩 물어보게 하되, 문제에 대한 맥락을 함께 줘서 질문의 초점을 잡아준다.

참조(References)

원하는 것을 말로 상세히 설명할 수 없을 때가 있다. 표현할 언어가 없거나, 설명하려면 시간이 너무 걸리는 경우다. 이때 최선의 답은 레퍼런스다. 다이어그램·문서·그림도 되지만, 가장 강력한 레퍼런스는 소스 코드다. 원하는 동작을 이미 구현한 라이브러리나 마음에 드는 디자인 컴포넌트가 있다면, 다른 언어로 쓰였더라도 그 폴더를 가리키며 무엇을 볼지 알려주면 된다.

참고로 클로드 디자인(Claude Design)이 작동하는 방식도 이와 같다. 마음에 드는 웹사이트의 한 모듈을 가리키면, 스크린샷이 아니라 그 아래의 실제 코드를 읽는다. 마크업과 구조, 컴포넌트가 실제로 어떻게 만들어졌는지에 대한 훨씬 풍부한 정보를 얻는 것이다.

구현 계획

이제 구현할 준비가 됐다 싶으면, 에이전트에게 구현 계획을 짜 오게 해서 검토한다. 이때 핵심은 가장 바뀔 가능성이 큰 부분—데이터 모델, 타입 인터페이스, 사용자 흐름(UX)—을 앞쪽에 배치하게 하는 것이다. 기계적인 리팩터링은 뒤로 미룬다. 그래야 내가 실제로 손봐야 할 지점이 위로 떠오른다.

07구현 중 — 이탈을 기록하기

계획이 만족스러우면 새 세션을 열고 사양 파일과 프로토타입 같은 아티팩트를 프롬프트에 넘겨 구현을 맡긴다. 그러나 아무리 계획을 세워도 '모르는 미지'는 늘 숨어 있다. 에이전트가 작업 도중 코드에서 예외 상황을 발견해 다른 접근을 취해야 할 때가 온다.

그래서 에이전트에게 임시 구현 노트(implementation-notes.md 또는 .html) 파일을 두게 한다. 자신이 내린 결정을 여기에 기록하게 하면, 다음 시도에서 배울 수 있다.

08구현 후 — 이해와 합의

피치와 설명자료

무언가를 세상에 내보내는 데 가장 중요한 부분 하나는 동의와 승인을 얻는 것(buy-in)이다. 최종 문서 안에 피치·설명 아티팩트를 함께 담으면 두 가지가 빨라진다. 첫째, 리뷰어가 나와 똑같은 미지수에서 출발할 때 이해가 빨라진다. 둘째, 전문가들이 내가 그 미지수와 흔한 실패 지점을 이미 고려했음을 확인하고 싶어 할 때 승인이 빨라진다. 핵심은 데모로 시작하는 것이다.

퀴즈

긴 세션이 끝나면, 에이전트는 내가 파악한 것보다 훨씬 많은 일을 해냈을 수 있다. 코드 변경분(diff)만 읽어서는 얕게밖에 이해하지 못한다. 동작의 상당 부분이 기존 코드 경로에 의존하기 때문이다. 그래서 나는 에이전트에게 충분한 맥락을 주게 한 뒤, 변경 내용에 대해 나를 퀴즈로 시험하게 한다. 그리고 그 퀴즈를 완벽히 통과했을 때에만 병합한다.

09사례: Fable을 세상에 내보내며

이 방법론이 실제로 어떻게 맞물리는지, Fable 출시 영상 제작 과정이 좋은 예다. 이 영상은 전부 클로드 코드(Claude Code)로 편집되었고, 작업자에게는 낯선 영역이었다. 그는 자신이 아는 것에서 출발했다. 클로드가 코드로 영상을 편집하고 전사(transcribe)할 수 있다는 것은 알았지만, 그 정확도가 충분한지는 몰랐다. 그래서 위스퍼(Whisper) 같은 전사 기술이 어떻게 작동하는지, ffmpeg로 '음—' 같은 군말이나 긴 침묵을 정확히 잘라낼 수 있는지 먼저 클로드에게 설명하게 했다.

말하는 단어에 맞춰 타이밍이 도는 UI를 원했지만 구현 가능 여부가 불확실했다. 그래서 리모션(Remotion)과 전사문으로 프로토타입 영상을 만들어 실제로 되는지부터 확인했다. 마지막으로 영상 색감이 밋밋했는데, 이것이 색 보정(color grading) 문제라는 것은 알았지만 정작 색 보정이 무엇인지는 몰랐다. 여러 변형본을 만들어 고르려다, 자신이 '좋은 색 보정'이 무엇인지 모른다는 사실을 깨달았다. 그래서 방향을 바꿔, 클로드에게 색 보정을 가르쳐 달라고 하여 자신의 미지수부터 발견했다.

10지도와 영토를 맞추기

모델이 좋아질수록, 올바른 접근으로 달성할 수 있는 일의 폭은 넓어진다. 긴 호흡의 작업(long-horizon task)이 잘못된 결과로 돌아온다면, 대개는 미지수를 정의하거나 구현 계획을 다듬는 데 시간을 더 써야 한다는 신호다. 클로드가 미지수를 스스로 헤쳐 나갈 수 있도록 여지를 남긴 계획 말이다.

설명자료, 브레인스토밍, 인터뷰, 프로토타입, 레퍼런스—이 모든 것은 비싸지기 전에 값싸게 미지수를 찾아내는 방법이다. 구현 도중이나 이후에 발견하면 되돌리는 비용이 크지만, 그 전에 발견하면 문서 한 장, 목업 하나로 끝난다.

그러니 다음 프로젝트는 이렇게 시작해 보자. 클로드에게 당신의 미지수를 함께 찾아 달라고 요청하는 것이다.