2026-06-18 Godot RAG 작업 리셋 회고

오늘 상태

어제 카페에서 커피를 1리터 정도 마셨더니 오늘따라 상태가 매우 안 좋았다. 그래서 코딩을 제대로 하지 못했다. 그래도 지금이라도 대략 생각난 내용과, 왜 어제 작업을 정리했는지는 기록해둔다.

현재 아키텍처에서 부족했던 부분

현재 Godot LLM/RAG 아키텍처에서 부족했던 부분은 다음과 같다. 이 부분들은 추후 개선해야 한다.

정적 분석 계층이 약함
GDScript AST/파서 기반 검증이 없음
Godot 프로젝트 의존성 그래프가 약함
실행/문법 검증이 약함
라벨 taxonomy가 아직 뭉툭함
LLM 생성물과 검증된 정답의 provenance 구분이 약함
데이터 누수/중복 제거 설계가 약함

특히 RAG만으로 해결하려고 하면 안 되는 부분이 있다. Godot 코드 판별은 문서 검색만의 문제가 아니라, 실제 GDScript 문법, scene/resource 의존성, 프로젝트 구조, Godot 3/4 API 차이를 함께 봐야 하는 문제다. 그런데 어제 흐름은 공식문서를 청킹하고 그 결과를 다시 LLM에게 던져 피드백을 받는 식으로 진행되었다. 이 방식은 겉으로는 빠르게 진행되는 것처럼 보였지만, 실제로는 검증 기준이 계속 흔들렸다.

6월 17일 작업을 정리한 이유

6월 17일에는 LLM에게 청킹을 맡기고, 그 결과물을 다시 GPT에 던져 피드백을 받는 식으로 작업했다. 그런데 아무리 봐도 이 방식은 아닌 것 같았다.

공식문서를 크롤링해서 가져온 이유는 Godot 문서 전체를 근거로 삼기 위해서였다. 그런데 작업 중간에 LLM이 문서를 제대로 분석하기 전에 “MVP 핵심” 같은 식으로 일부 API를 중요하다고 판단하고, 특정 키워드를 하드코딩하거나 주변 문맥을 과하게 보강하는 방향으로 흘렀다. 이러면 전체 공식문서 기반 RAG가 아니라, 몇 개 키워드에 맞춰진 검색기가 되어버린다.

문제는 단순히 결과가 마음에 안 든 정도가 아니었다. 내가 직접 확인하지 않은 상태에서 LLM이 스스로 기준을 만들고, 그 기준으로 파일을 만들고, 다시 그 결과를 보고 다음 판단을 하는 흐름이 생겼다. 그러다 보니 원본 문서 구조를 보지 않은 상태에서 할루시네이션이 섞였고, 나중에는 LLM 자신도 어떤 파일이 어떤 기준으로 생성되었는지 모르는 상태가 되었다.

더 크게 보면, ChatGPT나 Codex가 내가 지시하지 않은 방향으로 범위를 마음대로 줄이거나 바꾸는 현상이 강하게 드러났다. 나는 공식문서 전체를 기반으로 구조를 보고 싶었던 것이지, “MVP 핵심 API 몇 개”를 골라 하드코딩하라고 지시한 적이 없다. 그런데 LLM은 중간에 스스로 “MVP라면 이 정도가 핵심”이라고 판단하고, 아직 스텝이 끝나지도 않았는데 다음 산출물을 만들어버렸다.

특히 문제가 된 패턴은 다음과 같다.

사용자는 전체 공식문서 기반 구조 분석을 원함
-> LLM이 임의로 MVP 범위를 잡음
-> 일부 API를 핵심이라고 판단함
-> 하드코딩/과보강/카탈로그 생성을 먼저 함
-> 검증 전에 다음 단계 산출물을 만듦
-> 결과가 그럴듯한 숫자로 포장됨
-> 실제로는 원본 구조와 라벨링 기준이 오염됨

이건 단순한 구현 실수가 아니라 작업 방식의 문제다. ChatGPT나 Codex는 답이 아직 나오지 않았는데도 이미 답이 있다고 가정하고, 단계를 잠그기 전에 다음 단계로 넘어가는 경향이 있었다. 지시를 듣는 것처럼 보이지만 실제로는 지시 범위를 재해석하거나, 아예 무시하고, “좋아 보이는 완성 형태”를 먼저 만들려는 현상이 있었다.

이번 작업에서 특히 위험했던 점은 LLM이 자신이 만든 중간 산출물의 신뢰도를 제대로 구분하지 못했다는 점이다. 공식문서에서 확인된 사실, regex로 우연히 걸린 단어, 사용자가 직접 승인한 규칙, LLM이 추측한 보강 정보가 한데 섞였다. 그 상태에서 다시 LLM에게 결과를 평가하게 하니, 결국 LLM이 만든 것을 LLM이 그럴듯하게 합리화하는 흐름이 되었다.

청킹 산출물을 비운 이유

오늘은 어제 만들었던 RAG 청킹 관련 파일을 정리했다.

정리한 대상은 다음 계열이다.

v1 docs_chunks.jsonl
v2 docs_chunks_v2.jsonl
v3/v3.1 catalog/index/mapping 산출물
청킹/후처리/검증 초안 스크립트
초기 RAG chat/index 초안

처음에는 v3/v3.1만 문제라고 생각했지만, 다시 보면 v1과 v2도 뿌리부터 다시 봐야 하는 상태였다. 원래는 청크 자체부터 분석했어야 했다. 예를 들어 Godot class reference가 실제로 어떤 구조로 되어 있는지, method/property 단위가 원본 문서에서 어떻게 표현되는지, Sphinx 변환 결과가 어떤 식으로 깨지는지 먼저 봐야 했다.

그런데 실제로는 원본 문서 분석보다 청킹 결과 생성이 먼저 갔다. 그 결과, v1은 글자 수 기준 조각에 가까웠고, v2는 그 위에 후처리를 얹은 형태였다. 겉으로는 청크 수, JSONL 파싱 성공, doc_type 분포 같은 숫자가 나왔지만, 정작 중요한 “이 청크가 Godot 3/4 판별 근거로 쓸 수 있는가”는 충분히 검증되지 않았다.

특히 class reference에서 CharacterBody2D.move_and_slide 같은 구조가 안정적으로 살아 있는지, velocity 같은 property가 정확히 분리되는지, migration 문서에서 old/new 관계를 어떻게 추출해야 하는지부터 봐야 했다. 이걸 하지 않은 상태에서 trusted_api_symbols, syntax_symbols, api_mapping 같은 이름을 붙이면, 이름만 그럴듯한 오염된 데이터가 된다.

그래서 오늘은 v1/v2까지 포함해서 청킹 산출물을 비웠다. 이것은 작업을 포기한 것이 아니라, 잘못된 기준선을 더 이상 기준선이라고 부르지 않기 위한 정리다.

오늘의 결론

오늘의 결론은 단순하다.

청킹부터 다시 해야 한다.
그 전에 `outputs/godot_docs_full/pages` 원본 문서 구조를 먼저 분석해야 한다.
LLM이 만든 중간 산출물을 검증 없이 다음 단계의 근거로 쓰면 안 된다.

내가 확인도 안 했는데 LLM이 마음대로 판단하고, 원본도 제대로 보지 않은 상태에서 할루시네이션까지 섞이면, 결국 LLM이 자기가 한 일을 모르는 상태가 된다. 그 상태에서 계속 파일을 만들면 디버깅 파일만 늘어나고, 무엇이 기준인지 모르게 된다.

앞으로는 ChatGPT나 Codex가 “알아서 좋은 방향”으로 넓혀서 구현하는 것을 신뢰하지 않는다. 특히 데이터셋, 라벨러, RAG 판별기처럼 기준이 중요한 작업에서는 다음 원칙이 필요하다.

LLM이 임의로 MVP 범위를 정하면 중단
사용자가 승인하지 않은 하드코딩이 들어가면 중단
원본 구조 분석 없이 산출물을 만들면 중단
검증 리포트 없이 다음 단계로 넘어가면 중단
LLM 생성물과 검증된 정답의 provenance가 섞이면 중단

내일 다시 한다면 첫 작업은 새 catalog 생성이 아니다. 먼저 godot_docs_full 자체를 분석해야 한다. 즉 outputs/godot_docs_full/pages에 들어 있는 공식문서 Markdown들이 실제로 어떤 구조인지 확인하고, 그 구조를 기준으로 어떤 단위를 청크로 만들지 다시 고민해야 한다.

지금 필요한 질문은 “어떤 API를 먼저 넣을까”가 아니라 다음에 가깝다.

godot_docs_full 안의 class reference 문서는 어떤 패턴으로 구성되어 있는가
method/property/signal/constant 목록은 원본 Markdown에서 안정적으로 분리 가능한가
migration 문서의 표/목록/문장 구조는 어떤 형태인가
tutorial 문서는 class reference와 같은 청킹 기준을 쓰면 안 되는가
문서 타입별로 청크 단위를 다르게 잡아야 하는가
페이지 단위, 섹션 단위, API 멤버 단위 중 무엇을 기본 청크로 삼아야 하는가
청킹 전에 어떤 검증 리포트를 먼저 정의해야 하는가

결국 다음 작업은 “RAG를 다시 만든다”가 아니라, godot_docs_full을 분석해서 Godot 공식문서에 맞는 청크 단위 설계부터 다시 하는 것이다. 그 다음에야 청킹을 다시 해야 한다.