Godot 소스 분석 점수화 아키텍처
작성일: 2026년 6월 25일
목적
Godot 공식문서 RAG를 이용해 GitHub 소스코드를 프로젝트 단위로 분류하고, 이후 SFT/DPO 데이터 생성으로 이어지는 흐름을 정리한다.
이번 정리의 핵심은 docs_chunks, api_mapping, label_prototypes를 모두 같은 공식문서 Markdown -> JSONL 분류 대상으로 두는 것이다. 문서 성격에 따라 설명 청크는 docs_chunks, 함수명/클래스명/심볼명 변경은 api_mapping, 함수 사용 방식/인자 구성/호출 패턴 변경은 label_prototypes로 보낸다.
현재 결론
초기 공식문서 수집 단계에서 준비할 핵심 테이블은 다음 세 개다.
| 테이블 | 역할 |
|---|---|
docs_chunks |
공식문서 설명 본문, 튜토리얼, class reference 청크 저장 대상 |
api_mapping |
Godot 3 -> Godot 4에서 함수명, 클래스명, 심볼명이 어떻게 바뀌었는지 저장하는 대상 |
label_prototypes |
함수 사용 방식, 인자 구성, 호출 패턴이 통째로 바뀐 경우 어떻게 써야 하는지 저장하는 대상 |
| 항목 | 정리 |
|---|---|
| 기존 혼란 | 처음에는 세 테이블이 서로 다른 동작 흐름을 갖는 것처럼 생각했다. |
| 새 경계 | 세 테이블은 모두 공식문서 Markdown을 JSONL로 분류할 때 쓰는 저장 대상이다. |
| 현재 우선순위 | 원래 계획대로 세 테이블을 유지하고, 문서 성격에 따라 하나 이상의 JSONL로 분류 저장한다. |
최종 분석 단위
입력은 GitHub 프로젝트 또는 로컬 프로젝트 디렉터리다.
분석기는 파일시스템을 훑고, Godot 관련 파일을 AST 또는 코드 조각 단위로 쪼갠다.
초기 대상:
| 파일 | 용도 |
|---|---|
.gd |
GDScript AST/라인/함수 단위 분석 |
.tscn, .tres |
씬/리소스 안의 class, script, node type 단서 추출 |
project.godot |
프로젝트 버전, feature, renderer, autoload 등 프로젝트 단서 추출 |
| README/문서 | 프로젝트 설명과 Godot 버전 힌트 보조 |
On-demand LLM 호출 흐름
LLM은 상시 켜두는 것이 아니라, 필요한 AST/코드 조각마다 온디맨드로 호출한다.
각 AST 조각은 다음 근거와 함께 LLM에 전달된다.
AST/code chunk
+ 필요한 공식문서 JSONL 검색 결과
+ 출력 JSONL 스키마
+ 프로젝트/파일 식별 정보LLM 응답 스키마와 score DB 저장 컬럼은 아직 확정하지 않는다. 현재 문서에서는 어떤 테이블을 어떤 흐름에서 검색하고, 그 결과가 파일시스템 분류에 어떻게 쓰이는지만 기록한다.
코드 설명 생성 데이터 흐름
코드 설명 생성에서는 docs_chunks가 핵심 근거다.
흐름:
- 사용자가 “이거 뭔 뜻이야?”와 소스코드를 입력한다.
- AST Parser가 코드를 조각으로 나눈다.
- Retriever가
docs_chunks에서 관련 공식문서를 검색한다. - Qwen 3.6이 프롬프트, 소스코드 조각, 검색 근거가 서로 관련 있는지 검증한다.
- 관련 없는 검색 결과는 폐기한다.
- 관련 있는 근거와 코드 조각을 다시 Qwen 3.6에 전달해 설명 JSONL을 생성한다.
- Validator가 응답을 검증한다.
- 검증된 결과를 score DB에 저장한다.
- score DB 결과로 파일시스템을 분류한다.
Godot 3 -> Godot 4 함수명 변환 흐름
마이그레이션에서는 api_mapping이 핵심 근거다.
흐름:
- 사용자가 “이거 변환 필요해?”와 소스코드를 입력한다.
- AST Parser가 Godot API 후보 심볼을 추출한다.
- Retriever가
api_mapping에서 source API, target API, change type을 검색한다. - Qwen 3.6이 검색 결과가 해당 코드 조각과 실제로 관련 있는지 검증한다.
- 관련 없는 mapping은 폐기한다.
- 관련 있는 mapping만 이용해 Godot 3 -> 4 마이그레이션 JSONL을 생성한다.
- Validator가 변환 응답을 검증한다.
- 검증된 결과를 score DB에 저장한다.
- score DB 결과로 파일시스템을 분류한다.
Godot 3 -> Godot 4 사용 패턴 변환 흐름
사용 패턴 변환에서는 label_prototypes가 핵심 근거다.
흐름:
- 사용자가 “이거 변환 필요해?”와 소스코드를 입력한다.
- AST Parser가 함수 호출, 인자 구성, 호출 패턴 후보를 추출한다.
- Retriever가
label_prototypes에서 사용 방식/인자/호출 패턴 변환 근거를 검색한다. - Qwen 3.6이 검색 결과가 해당 코드 조각과 실제로 관련 있는지 검증한다.
- 관련 없는 prototype은 폐기한다.
- 관련 있는 prototype만 이용해 Godot 3 -> 4 사용 패턴 변환 JSONL을 생성한다.
- Validator가 변환 응답을 검증한다.
- 검증된 결과를 score DB에 저장한다.
- score DB 결과로 파일시스템을 분류한다.
Score DB
AST 조각별 Retriever 검색 결과, LLM 검증 결과, Validator 통과 결과는 최종적으로 score DB에 저장한다.
score DB는 학습 데이터 원본이 아니라 파일시스템을 분류하기 위한 판단 결과 저장소다. 소스 분석 과정에서 나온 Retriever/LLM/Validator 결과를 기록한다.
docs_chunks검색 결과: 코드 설명 요청에서 공식문서 근거가 실제 코드와 관련 있는지 검증한 결과api_mapping검색 결과: Godot 3 -> Godot 4 함수명/심볼 변환 근거가 실제 코드와 관련 있는지 검증한 결과label_prototypes검색 결과: 함수 사용 방식, 인자 구성, 호출 패턴 변환 근거가 실제 코드와 관련 있는지 검증한 결과
score DB의 컬럼, 집계 방식, 분류 라벨은 아직 정하지 않는다. 이 문서에서는 score DB가 “분류 전 판단 결과를 모으는 저장소”라는 역할만 고정한다.
최종 파일시스템 분류:
project source
-> AST/code chunks
-> official docs JSONL retrieval
-> on-demand LLM verification
-> score DB
-> classified filesystemSFT와 DPO 생성
SFT와 DPO의 세부 설계는 아직 정하지 않는다. 현재 확정한 것은 score DB 자체가 학습 데이터 소스가 아니라는 점이다. 먼저 파일시스템을 분류하고, 이후에는 분류된 파일시스템을 기반으로 SFT와 DPO를 설계할 소스로 만들 예정이다.
Git 업로드 안전 기준
이번 문서화에서는 웹 UI, 로컬 변환 스크립트, AST 분석 스크립트, API 키, JSONL 산출물, 테스트 소스코드는 올리지 않는다.
업로드 허용:
- 아키텍처 문서
- 흐름도 이미지
- 공개해도 되는 회고/로드맵 텍스트
업로드 금지:
- Streamlit 웹앱 코드
- Markdown -> JSONL 변환 실험 스크립트
- Retriever/AST 분석 실험 스크립트
- API key, endpoint,
.env - 수집한 전체 Markdown 원본 zip
- AST/code chunk 분석 결과
- JSONL 중간 산출물
- 테스트용으로 클론한 외부 Godot 프로젝트 소스