요약 (TL;DR). 나는 AI 모델에게 내 코드베이스를 세 가지 형태로 변환해 달라고 요청했습니다: 나를 위한 한 페이지 요약본, 다음 AI 에이전트를 위한 JSON 파일, 그리고 클릭 가능한 인터랙티브 맵(interactive map)입니다. 결과는 좋았지만, 코드의 모든 숫자를 일일이 대조해야 하는 지루한 단계를 거친 후에야 가능했습니다. 모델은 구조는 제대로 잡았지만 여러 수치는 틀리게 작성했습니다. 라이브 맵(live map)을 확인해 보세요.

시스템 전체에 걸쳐 하나의 흐름이 밝게 빛나는 인터랙티브 맵 자체. 라이브 버전을 열고 아무 흐름이나 클릭해 보세요.

거대한 코드베이스는 머릿속에 다 담을 수 없습니다. 나의 코드베이스는 31개의 모듈에 걸친 약 146,000줄의 Rust 코드로 이루어져 있습니다. 이 정도 규모의 프로젝트를 처음 열면, 첫 한 시간은 그저 무언가가 어디에 있는지 찾는 데만 쓰게 됩니다.

AI 에이전트들도 똑같은 문제를 겪습니다. 에이전트가 작업을 시작할 때마다, 시스템이 어떻게 구성되어 있는지 파악하기 위해 수많은 파일을 읽어야 합니다. 에이전트는 매번 처음부터 이 과정을 수행합니다. 이는 느리고 비용이 많이 듭니다.

그래서 나는 시도를 해보았습니다. AI 모델에게 전체 코드베이스를 읽고 세 가지를 작성하도록 요청했습니다. 하나는 나를 위한 것, 하나는 다음 에이전트를 위한 것, 그리고 하나는 누구에게나 유용한 것입니다.

세 가지 파일

첫 번째 파일은 인간을 위한 한 페이지 요약본입니다. 여기에는 항상 유지되어야 하는 규칙(rules), 주요 구성 요소와 각 요소의 역할, 요청이 거치는 경로, 그리고 시간을 낭비하게 만드는 함정(traps)들이 나열되어 있습니다. 이는 내가 프로젝트 첫날에 존재했으면 좋았을 페이지입니다.

두 번째 파일은 다음 AI 에이전트를 위한 JSON 맵입니다. 이 파일은 보기 좋게 작성된 것이 아닙니다. 각 불변성(invariants)을 강제하는 파일이나 테스트, 각 일반적인 작업에 대한 짧은 레시피, 알려진 함정, 그리고 핵심 파일들을 나열합니다. 다음 에이전트가 작업을 시작할 때, 이 파일을 먼저 읽음으로써 한 시간 동안의 탐색 과정을 건너뛸 수 있습니다.

세 번째 파일은 모두를 위한 인터랙티브 맵입니다. 구성 요소들을 열(columns) 안의 상자(boxes)로 보여줍니다. "예약된 체크(scheduled check)"나 "에이전트 로그인(agent login)"과 같은 흐름을 선택하면, 번호가 매겨진 단계와 함께 경로가 상자들을 가로질러 밝게 빛납니다. 여기에서 라이브로 확인할 수 있습니다: 아키텍처 맵(the architecture map).

세 개의 파일. JSON 맵(map)이 신뢰할 수 있는 유일한 원천(source of truth)이며, 사람을 위한 페이지와 대화형 맵은 모두 이를 기반으로 구축됩니다.

하나의 파일이 신뢰할 수 있는 원천(source of truth)입니다

JSON 맵은 모든 사실을 보유합니다. 나머지 두 파일은 단지 그것을 보여주는 뷰(view)일 뿐입니다. 맵을 먼저 구축하면, 사람을 위한 페이지와 대화형 맵이 서로 일치하지 않는 일이 발생할 수 없습니다.

마법 같은 프롬프트 하나가 아닌, 하나의 방법론

이 작업을 잘 수행하는 단 하나의 프롬프트는 존재하지 않습니다. 결과는 다음 네 가지 단계를 순서대로 거쳐 나옵니다.

네 가지 단계. 모든 것은 2단계인 맵(map)을 중심으로 이루어집니다.

첫째, 병렬로 탐색합니다. 하나의 에이전트(agent)가 146,000줄을 한 번에 읽을 수는 없습니다. 저는 여러 에이전트가 동시에 서로 다른 부분을 읽도록 한 다음, 그들의 노트를 합쳤습니다. 이 방식이 더 빠르고 더 많은 범위를 다룰 수 있습니다.

둘째, 머신용 맵(machine map)을 먼저 구축합니다. 에이전트를 위한 JSON이 신뢰할 수 있는 원천(source of truth)입니다. 사람을 위한 페이지와 대화형 맵은 단지 그것을 보여주는 뷰(view)일 뿐입니다. 따라서 저는 JSON을 먼저 구축하고 모든 사실을 한 곳에 모았습니다.

셋째, 다른 무엇인가를 구축하기 전에 해당 맵의 모든 숫자를 확인합니다. 이것은 사람들이 건너뛰는 단계이지만, 가장 중요한 단계입니다. 원천(source)에서 한 번 검증함으로써 잘못된 수치가 다른 파일로 퍼지는 것을 방지할 수 있습니다.

넷째, 맵으로부터 뷰(views)를 렌더링합니다. 사람을 위한 페이지와 대화형 맵은 모두 동일한 JSON에서 나오므로 서로 내용이 다를 수 없습니다. 각 뷰는 명확한 독자를 가집니다. 페이지는 신입 엔지니어를 위한 것이고, 맵은 코드를 한 번도 본 적 없는 방문자를 위한 것입니다.

AI가 틀린 숫자들

모델은 구조를 파악하는 데 뛰어났습니다. 부분, 흐름, 그리고 규칙을 찾아냈습니다. 하지만 숫자를 추측했고, 그 추측 중 일부는 틀렸습니다.

그것은 알림 채널이 13개라고 말했습니다. 실제 숫자는 14개입니다.

그것은 에러 코드 (error codes)가 약 80개라고 말했습니다. 실제 숫자는 155개입니다.

그것은 블로그 포스트가 19개라고 말했습니다. 실제 숫자는 18개입니다.

이 중 어느 것도 사소한 차이가 아닙니다. 만약 이것들을 그대로 게시한다면 당신은 부주의해 보일 것이고, 다음 에이전트 (agent)는 잘못된 지도를 신뢰하게 됩니다. 저는 소스 코드 (source code)와 각 수치를 대조해 보았기 때문에 이 오류들을 찾아낼 수 있었습니다.

수치를 소스 코드에서 직접 확인하세요

AI 모델은 형태와 단어에는 강하지만, 정확한 숫자에는 약합니다. 무엇인가를 구축하기 전에, 지도에 포함된 모든 수치를 반드시 한 번씩 검증하십시오. 그 후 중요한 수치들은 직접 확인하십시오.

프롬프트 (The prompts)

제가 실행한 순서대로 세 가지 프롬프트를 소개합니다. 먼저 지도를 구축하고, 이를 검증한 다음, 뷰 (views)를 만드세요. 여러분의 프로젝트에 맞춰 세부 사항을 변경하되, 첫 번째 프롬프트의 "소스 코드와 대조하여 검증하라 (verify against the source)"라는 문구는 유지하십시오.

머신용 지도 (machine map)를 위해, 이것을 가장 먼저 구축하세요:

내 전체 코드베이스 (codebase)를 읽으세요. 기능을 추가할 다음 AI 에이전트 (AI agent)를 위해 하나의 JSON 파일을 작성하세요. 불변량 (invariants)을 포함하고, 각 불변량을 강제하는 파일이나 테스트를 명시하세요. 각 일반적인 작업에 대한 짧은 레시피 (recipe)를 추가하세요: ...

지도로부터 만들어지는 인간용 요약 (human summary):

검증된 해당 JSON으로부터, 새로운 엔지니어에게 시스템을 설명하는 하나의 독립적인 HTML 페이지를 작성하세요. 항상 유지되어야 하는 규칙, 주요 구성 요소와 각 요소의 역할, 요청 (request)이 거치는 경로, 데이터가 거치는 경로...를 포함하세요.

동일한 지도로부터 만들어지는 인터랙티브 지도 (interactive map):

동일한 JSON으로부터, 하나의 독립적인 인터랙티브 HTML 페이지를 구축하세요. 구성 요소들을 열 형태의 박스로 표시하세요. 각 흐름 (flow)을 번호가 매겨진 경로로 표시하고, 클릭 시 박스들을 가로질러 불이 들어오게 하세요. 모든 스타일과 스크립트는 ... 안에 유지하세요.

이것을 수행할 가치가 있는 이유

인간용 페이지는 다음 주에 제 시간을 절약해 주었습니다. 지도는 한 화면 안에서 시스템을 설명하는 데 도움을 줍니다. 그리고 JSON은 제가 예상치 못하게 만족스러웠던 부분입니다. 이 코드를 다루는 다음 에이전트는 먼저 지도를 읽기 때문에, 0단계가 아닌 1단계부터 시작할 수 있습니다.

다음 에이전트는 0단계가 아닌 1단계부터 시작합니다

맵 파일 (map file)은 다음 AI 에이전트에게 규칙, 작업, 그리고 함정들을 미리 전달합니다. 에이전트는 매번 코드베이스 전체를 다시 읽는 대신 하나의 작은 파일을 읽게 됩니다.

핵심 요약 (Key takeaways)

• 머신 맵 (machine map, JSON)을 먼저 구축하세요. 사람을 위한 페이지와 인터랙티브 맵 (interactive map)은 단지 그것을 보여주는 뷰 (view)일 뿐이므로, 데이터가 어긋날 일이 없습니다.
• AI 모델은 구조에는 강하지만 숫자에는 약합니다. 무언가를 구축하기 전에 소스에서 모든 수치를 검증하세요.
• 다음 AI 에이전트를 위한 맵 파일을 작성하세요. 그래야 에이전트가 코드베이스 전체를 다시 읽는 대신 1단계부터 시작할 수 있습니다.
• 병렬로 탐색하세요. 여러 에이전트가 서로 다른 부분을 읽는 것이, 한 명의 에이전트가 모든 것을 읽는 것보다 더 많은 범위를 커버합니다.
• 각 파일에는 하나의 명확한 독자 (reader)를 지정하세요. 그래야 작성 작업이 단순하게 유지됩니다.
• 모델이 실제 수치를 틀리는 경우가 있었습니다. 예를 들어 실제 숫자가 14인데 13개의 채널이라고 답하는 식입니다. 확인되지 않은 숫자는 게시하지 마세요.

출력 결과를 보고 싶다면 인터랙티브 맵 (interactive map)을 열어보세요. 프로젝트 전체가 오픈 소스이므로, 모든 박스 뒤에 숨겨진 실제 코드를 읽어볼 수 있습니다.

만약 AI 에이전트를 위해 코드베이스를 매핑해 본 적이 있다면: 에이전트가 실제로 어떤 형식을 사용했나요? 그리고 실행 과정에서 모델이 몇 개의 숫자를 틀렸나요? 제 경우에는 세 개를 놓쳤습니다. 이것이 일반적인 현상인지 알고 싶습니다.