idea_world_labDEV JOURNAL
2026년 6월 27일 토요일

2026-06-27 회고

오늘은 26일에 작성했던 source-to-AST 입력 흐름 문서의 일관성을 개선하는 것을 목표로 두었던 것 같다.

어제까지는 전체 레이어가 머릿속으로는 구분되어 있었지만, 문서나 코드로는 너무 추상화된 단계에 머물러 있었다. AST, Retriever, LLM 검증, JSONL 근거 같은 말은 구분할 수 있었지만, 실제 프로젝트가 들어왔을 때 어떤 파일이 어떤 순서로 펼쳐지고, 어느 본문이 AST Parser로 들어가고, 어떤 chunk가 Retriever에 그대로 전달되는지까지 구체화되어 있지는 않았다.

머릿속으로는 이해하고 있다고 생각했지만, 그 상태로 코드를 짜기 시작하면 내가 원하는 방향으로 구현되지 않을 것 같다는 불안감이 꽤 강했던 것 같다. 그래서 오늘은 먼저 전체 구조를 다시 잡고, 그 구조를 사람이 눈으로 확인할 수 있는 GUI 형태로 설계하려고 했다.

구체화가 필요했던 이유

AST와 Retriever의 역할은 사실 구분되어 있었다.

.gd 파일은 AST Parser로 들어가고, 함수나 선언 단위로 잘려야 한다. Retriever는 그 결과로 나온 코드 조각을 받아 DB에서 관련 JSONL 근거를 검색해야 한다. 그리고 LLM 검증은 프롬프트, 현재 chunk, 검색된 JSONL을 보고 그 근거가 실제로 관련 있는지 판단해야 한다.

하지만 이것을 말로만 정리하면 계속 흐려졌다. 특히 실제 프로젝트 흐름에서는 파일이 먼저 # <상대경로> 형태로 펼쳐지고, 그 아래 본문이 파일 단위로 나뉘고, .gd 파일의 특정 함수나 선언이 chunk가 되고, 그 chunk의 chunkText만 Retriever로 넘어가야 한다.

나는 이 흐름을 똑바로 보고 싶었다. 어떤 파일의 어느 본문이 어떤 chunk가 되었는지, Retriever가 받은 입력이 정말 그 chunk 그대로인지, 파일 경로나 라인 번호나 프롬프트가 검색 입력에 섞이지 않았는지를 웹 화면에서 직접 확인하고 싶었다.

그래서 단순히 문서만 쓰는 것이 아니라, 사용자가 보기 쉬운 GUI로 확인할 수 있는 도구가 필요하다고 생각했다.

Source Flow Debugger

결과적으로 Source Flow Debugger를 만들면서 AST와 Retriever의 흐름을 한 화면에서 볼 수 있게 됐다.

처음에는 소스코드를 어떻게 AST 쪽에 넘길지 정리하려고 했는데, 하다 보니 AST chunk, direct chunk, Retriever 입력, DB 검색 버튼, Qwen 검증 preview까지 한 화면에 붙었다. 어쩌다 보니 AST와 Retriever, LLM 검증이 통합된 구조가 되었고, 생각보다 더 편해진 것 같다.

나름 머리를 잘 쓴 지점은, 이걸 처음부터 완성된 시스템으로 만들려고 하지 않고 관찰 도구로 만든 점이다. 지금 단계에서 필요한 것은 “정답을 자동으로 내는 도구”가 아니라, 내가 의도한 흐름대로 데이터가 이동하는지 확인하는 도구였다.

오늘 확인한 것은 다음과 같다.

  • Godot 프로젝트를 # <상대경로> 형태로 펼친다.
  • .gd 파일은 AST 성격의 chunk로 나눈다.
  • .godot, .tscn 같은 텍스트 리소스는 direct chunk로 나눈다.
  • README.md 같은 문서 파일은 source-analysis 모드에서 제외하고, 제외 이유를 화면에 남긴다.
  • Retriever 입력에는 파일 경로, 라인 번호, 프롬프트를 넣지 않고 chunkText만 넣는다.
  • 각 chunk 아래에서 docs_chunks, api_mapping, label_prototypes를 테이블별로 검색할 수 있게 한다.
  • 이후 Qwen 검증은 prompt + chunkText + retrieved JSONL 구조로 넘어간다.

작은 Godot 프로젝트를 넣었을 때 5 files, 14 chunks, AST 9, Direct 5로 분해되는 것도 확인했다. 이 정도면 청크 단위로 쪼개는 흐름은 어느 정도 성공한 것 같다.

GPT 데모 테스트

원래는 수집된 JSONL 셋을 기반으로 관련된 GitHub 레포지토리를 찾고, 그 레포지토리를 클론해서 테스트하려고 했다.

그런데 생각해보니 꼭 처음부터 실제 GitHub 레포를 찾아야만 하는 것은 아니었다. 지금 확인하고 싶은 것은 “검색된 JSONL이 현재 Godot 코드 chunk와 진짜 관련 있는지 LLM이 제대로 판정하는가”였다. 그러면 GPT에게 데모용 Godot chunk와 관련 JSONL, 무관 JSONL을 만들게 해서 먼저 테스트해보는 편이 빠르겠다고 생각했다.

그래서 일부러 Godot 3 코드 chunk를 만들고, 거기에 맞는 Godot 3 -> Godot 4 변환 JSONL과 전혀 관련 없는 JSONL을 함께 만들어 테스트했다.

처음에는 단순히 이렇게 물었다.

이 JSONL이 소스코드에 해당하는 내용을 담고 있어?
답변은 예 / 아니오만

그랬더니 관련 JSONL도 예, 무관 JSONL도 예로 나왔다.

처음에는 아쉽게 보일 수도 있지만, 오히려 다행이라는 생각이 들었다. 지금 단계에서 이런 문제가 드러나지 않았다면, 나중에 실제 DB 검색을 붙였을 때 엉뚱한 JSONL도 LLM이 자기 지식으로 그럴듯하게 이어붙일 수 있었을 것이다.

그래서 프롬프트를 더 강하게 바꿨다.

너는 JSONL 근거 매칭 판정기다.

아래 SOURCE_CODE에 대해 아래 JSONL이 직접적인 변환 근거를 포함하는지 판정하라.

판정 기준:
- JSONL의 source_api, source_pattern, match_terms, required_when_seen_in_code, before_code 중 하나가 SOURCE_CODE 안의 실제 문자열 또는 API 호출과 직접 일치해야만 "예"다.
- 단순히 Godot, Godot3, Godot4, migration, 2D, physics 같은 넓은 단어가 같으면 관련 없음이다.
- JSONL에 "does not describe", "not related", "unrelated", "does not apply"처럼 부정적으로 언급된 내용은 관련 근거로 인정하지 않는다.
- JSONL이 다른 API, 다른 노드, 다른 시스템에 대한 내용이면 "아니오"다.
- 네가 알고 있는 Godot 지식은 사용하지 말고, JSONL에 적힌 문자열 근거만 사용하라.
- 답변은 반드시 "예" 또는 "아니오" 하나만 출력하라.

이렇게 바꾸자 관련 JSONL은 예, 무관 JSONL은 아니오로 갈라졌다.

오늘 이 실험에서 얻은 기준은 중요하다. Retriever가 JSONL 후보를 가져온 뒤 LLM에게 검증시킬 때는 넓은 의미 유사도를 보게 하면 안 된다. JSONL 안의 source_api, source_pattern, match_terms, required_when_seen_in_code, before_code 같은 필드가 현재 chunk의 실제 문자열/API 호출과 직접 맞는지 먼저 보게 해야 한다.

내일 할 일

내일은 데모 셋을 더 만들어야 할 것 같다.

Godot chunk와 관련 JSONL, 무관 JSONL을 여러 개 만들고, Qwen이 답변을 어떻게 도출하는지 여러 번 테스트할 필요가 있다. 한두 번 성공했다고 바로 기준으로 삼기에는 아직 이르다.

특히 다음 케이스를 더 확인해야 한다.

  • 관련 JSONL이 여러 개 섞였을 때 Qwen이 실제 근거를 잘 고르는지
  • 무관 JSONL이 주제어만 비슷할 때 아니오로 잘 버리는지
  • api_mapping과 label_prototypes의 차이를 Qwen이 문자열 근거 기준으로 잘 구분하는지
  • docs_chunks처럼 설명 문서 성격의 JSONL도 같은 방식으로 검증 가능한지
  • Godot 3 코드처럼 보이지만 JSONL 근거가 없을 때 임의 마이그레이션을 하지 않는지

오늘은 전체적으로 추상적인 구조를 실제 화면과 입력 흐름으로 끌어내린 날이었다. 머릿속으로는 이미 알고 있다고 생각한 것들도, 실제로 웹에서 펼치고 쪼개고 검색 입력으로 보여주니 훨씬 명확해졌다.

이제 다음 단계는 실제 DB 검색과 Qwen 검증을 여러 번 반복하면서, 이 흐름이 흔들리지 않는지 확인하는 것이다.