JSONL 수집 현황 기반 테스트 레포지토리 선정 관찰일지

작성일: 2026년 6월 27일

목적

현재까지 생성된 JSONL을 기준으로 어떤 성격의 Godot 레포지토리를 먼저 클론해서 테스트하는 것이 좋은지 판단한다.

여기서 목표는 “유명한 레포를 아무거나 하나 고르는 것”이 아니다. 지금 DB에 쌓이고 있는 근거가 어떤 영역에 강하고, 어떤 영역에는 아직 약한지를 먼저 본 뒤, Retriever가 실제로 근거를 찾을 수 있는 레포 성격을 고르는 것이다.

분석 기준은 다음 두 파일이다.

/Users/joyeongjin/make_md/work/web_jsonl/docs_chunks/docs_chunks.jsonl
/Users/joyeongjin/make_md/work/web_jsonl/api_mapping/api_mapping.jsonl

state.json에는 변환 상태, 분류 프롬프트, 원본 응답 디버그가 들어 있지만 런타임 설정값도 함께 섞일 수 있으므로, 공개 문서에는 원문을 옮기지 않는다. 이 관찰일지에는 JSONL 통계와 판단만 남긴다.

스냅샷 상태

관찰 시점 기준 변환은 아직 진행 중이다.

docs_chunks.jsonl: 153 records
api_mapping.jsonl: 117 records
label_prototypes.jsonl: 아직 생성 파일 없음

웹 변환 상태는 대략 다음 흐름이었다.

done: 132 files
pending: 1425 files
deferred: 11 files
converting: 2 files
classified: 144 files

따라서 이 문서는 최종 결론이 아니라 “현재까지 수집된 JSONL 기준의 1차 레포 선정 기준”이다.

docs_chunks 관찰

docs_chunks는 153개 record가 생성되어 있었다.

구성은 다음에 가깝다.

class_reference: 127
about: 26

95개 Markdown 원본 파일에서 chunk가 만들어졌고, 129개 record에는 API symbol이 들어 있었다. code block을 가진 record는 36개였다.

현재까지 docs_chunks에서 강하게 보이는 영역은 다음이다.

Animation 계열
Audio 계열
Camera 계열
Canvas/CanvasItem 계열
Array/Callable/GlobalScope 같은 기초 API
AnimatedSprite2D 일부
AStar/AStarGrid2D 일부

반대로 아직 약하게 보이는 영역은 다음이다.

KinematicBody / CharacterBody migration
move_and_slide 호출 방식
yield -> await 전환
Color8 -> Color.from_rgba8 전환
TileMap migration
RigidBody / physics body migration
HTTPRequest / networking

즉 지금 시점의 docs_chunks는 “Godot 4 공식문서 설명 근거”로는 어느 정도 쓸 수 있지만, 아직 전형적인 Godot 3 -> Godot 4 2D 액션 게임 migration 근거가 충분히 쌓였다고 보기는 어렵다.

api_mapping 관찰

api_mapping은 117개 record가 생성되어 있었다.

변경 유형은 다음처럼 나뉜다.

rename_or_replacement: 82
behavior_change: 24
deprecated: 11

모든 record의 confidence는 verified_from_docs로 들어가 있었다.

현재까지 강하게 보이는 mapping 영역은 다음이다.

Array 메서드와 동작 차이
AnimationPlayer / AnimationMixer / AnimationTree / AnimationNode 계열
AudioStream / AudioEffect / AudioEffectSpectrumAnalyzer 계열
Camera / Camera3D / CameraAttributes 계열
CanvasItem draw/modulate 계열
GlobalScope 일부 함수와 deprecated constant
AStarGrid2D 일부

예를 들어 현재 JSONL에는 다음 성격의 근거가 들어 있다.

Camera -> Camera3D
Camera.get_transform -> Camera3D.get_camera_transform
WorldEnvironment exposure 설정 -> CameraAttributes 계열
AnimationPlayer의 일부 기능 -> AnimationMixer 분리
AnimationNode._process -> AnimationNodeExtension._process_animation_node
AudioEffectLimiter -> AudioEffectHardLimiter
Array.sort 동작 변화
Array.has의 C# 명칭 차이
CanvasItem.modulate 동작 변화
CanvasItem.draw_string / draw_rect 동작 변화

이 말은 지금 당장 migration 테스트를 한다면, 2D platformer의 KinematicBody2D나 move_and_slide보다 Camera, Animation, Audio, CanvasItem, Array 쪽 코드가 더 잘 걸릴 가능성이 높다는 뜻이다.

label_prototypes 관찰

현재 스냅샷에서는 label_prototypes.jsonl 파일이 없다.

따라서 지금 단계에서 “함수 사용 방식 전체가 바뀌는 예시”를 Retriever로 테스트하려면 근거가 부족하다. 물론 api_mapping에도 behavior_change가 들어 있긴 하지만, 그것은 아직 “통째 사용 패턴 예시”라기보다 문서에서 추출한 API 변경 근거에 가깝다.

그래서 지금 레포를 고를 때는 label_prototypes를 적극적으로 테스트하는 레포보다, docs_chunks와 api_mapping이 이미 가지고 있는 영역을 먼저 검증하는 레포가 낫다.

지금 바로 클론하기 좋은 레포 성격

현재 JSONL 기준으로 가장 먼저 클론하기 좋은 레포는 “작고, Godot 버전 단서가 분명하고, 지금 쌓인 mapping과 겹치는 API를 실제 코드에서 쓰는 레포”다.

우선순위는 다음과 같다.

1순위: Godot 3 기반의 작은 Camera/WorldEnvironment/Animation 예제

가장 좋은 첫 테스트 후보는 Godot 3 프로젝트 중에서 Camera, WorldEnvironment, AnimationPlayer, AnimationTree, CanvasItem draw, AudioEffect 같은 기능을 실제로 쓰는 작은 예제 레포다.

이유는 현재 api_mapping에 다음 근거가 이미 들어 있기 때문이다.

Camera -> Camera3D
Camera.get_transform -> Camera3D.get_camera_transform
WorldEnvironment exposure 설정 -> CameraAttributes
AnimationPlayer -> AnimationMixer 관련 변화
AnimationNode / AnimationTree 계열 변화
CanvasItem draw/modulate 동작 변화
AudioEffect / AudioStream 계열 변화

이런 레포를 클론하면 AST 조각에서 Camera, WorldEnvironment, AnimationPlayer, CanvasItem, AudioEffect 같은 단서가 나오고, Retriever가 현재 JSONL에서 근거를 찾을 가능성이 높다.

테스트 목적도 분명하다.

Godot 3 코드 조각
-> AST 조각
-> api_mapping 검색
-> docs_chunks 보조 검색
-> LLM 판단 프롬프트 미리보기

즉 “이 코드가 Godot 3 API를 쓰는지, Godot 4에서는 어떤 근거로 바뀌어야 하는지”를 현재 데이터로 바로 확인할 수 있다.

2순위: Godot 4 기반의 작은 Animation/Audio/Camera 예제

두 번째 후보는 Godot 4로 작성된 작은 예제 레포다.

이 레포는 migration 검증보다는 “정상 Godot 4 코드 설명”과 “Retriever가 엉뚱한 Godot 3 migration을 끌고 오지 않는지”를 확인하는 데 좋다.

현재 docs_chunks에는 Animation, Audio, Camera, CanvasItem, Array 쪽 공식문서 설명이 꽤 들어 있다. 그래서 Godot 4 코드 조각을 넣었을 때 docs_chunks 중심으로 설명 근거가 잡히는지 보기 좋다.

이 레포는 다음 성격이면 좋다.

project.godot이 있는 완성된 작은 프로젝트
.gd 파일이 5~30개 정도
.tscn 파일이 함께 있음
AnimationPlayer 또는 AnimationTree 사용
AudioStreamPlayer 또는 AudioEffect 사용
Camera2D/Camera3D 사용
Array/Callable 같은 기초 API 사용
대용량 에셋이 많지 않음

3순위: Godot 3과 Godot 4 버전이 나뉜 동일 주제 예제

가능하다면 같은 주제를 Godot 3 버전과 Godot 4 버전으로 나눠 제공하는 예제가 가장 좋다.

예를 들어 같은 카메라/애니메이션/오디오 예제가 Godot 3 브랜치와 Godot 4 브랜치를 따로 가지고 있다면, Retriever와 LLM 판단을 비교하기 쉽다.

이런 레포는 다음을 확인하기 좋다.

Godot 3 조각에서 api_mapping이 잘 걸리는지
Godot 4 조각에서 docs_chunks 설명 근거가 잘 걸리는지
같은 기능의 버전별 코드 차이를 LLM 프롬프트에 어떻게 보여줄 수 있는지
프로젝트 단위로 godot3/godot4/mixed 판단을 어떻게 누적할지

지금 바로 클론하기 애매한 레포 성격

현재 JSONL만 놓고 보면, 다음 성격의 레포는 아직 첫 테스트로는 애매하다.

전형적인 Godot 3 2D platformer

KinematicBody2D, move_and_slide, yield, TileMap, Color8 같은 단서가 많은 Godot 3 2D platformer는 나중에는 반드시 필요하다.

하지만 현재 스냅샷에서는 해당 단서가 JSONL에 거의 없다. 지금 바로 이런 레포를 넣으면 Retriever가 근거를 못 찾거나, 관련 없는 Animation/Audio/Camera 근거를 끌고 올 가능성이 있다.

그래서 이 성격의 레포는 “좋은 최종 테스트 후보”지만 “현재 JSONL로 바로 검증하기 좋은 첫 후보”는 아니다.

큰 게임 전체 레포

에셋이 많고 .gd 파일이 수백 개 있는 큰 게임 레포는 아직 이르다.

지금 필요한 것은 모델에게 큰 프로젝트를 던지는 것이 아니라, 코드 조각이 어떤 JSONL 근거를 검색하는지 끝까지 추적하는 것이다. 큰 레포는 디버깅 대상이 너무 넓어서, 어떤 근거가 왜 검색됐는지 보기가 어려워진다.

첫 테스트는 작고 기능이 분명한 예제가 낫다.

C# 중심 레포

현재 JSONL에는 C# 언급과 일부 C# 명칭 차이가 있지만, 전체 흐름은 GDScript AST와 .gd 조각을 기준으로 설계하고 있다.

따라서 C# 중심 Godot 레포는 지금 단계의 첫 테스트 대상으로 적합하지 않다.

GDExtension / Native plugin 중심 레포

GDExtension, C++, Rust binding, native plugin 중심 레포도 아직 이르다.

현재 목표는 Godot 프로젝트의 .gd, .tscn, project.godot을 조각으로 나누고 Retriever가 공식문서 근거를 찾는 흐름을 보는 것이다. native extension 중심 레포는 분석 축이 달라진다.

레포 선정 기준

현재 기준으로 클론 후보는 다음 조건을 만족하는 것이 좋다.

Godot 버전이 README나 project.godot에서 확인 가능해야 함
project.godot 파일이 있어야 함
.gd 파일이 있어야 함
.tscn 파일이 함께 있으면 좋음
대용량 에셋이 적어야 함
기능 범위가 작고 명확해야 함
현재 JSONL에 있는 API와 겹치는 코드가 있어야 함

현재 JSONL과 잘 맞는 키워드는 다음이다.

Camera
Camera3D
WorldEnvironment
CameraAttributes
AnimationPlayer
AnimationTree
AnimationNode
AnimationMixer
AudioStream
AudioEffect
CanvasItem
draw_string
draw_rect
modulate
Array.sort
Array.has
AnimatedSprite2D
AStar2D
AStarGrid2D

반대로 지금 첫 테스트에서 핵심 기준으로 삼기에는 이른 키워드는 다음이다.

KinematicBody2D
CharacterBody2D
move_and_slide
yield
await
Color8
TileMap
RigidBody2D
HTTPRequest
multiplayer
GDExtension

판단

현재까지 수집된 JSONL을 기준으로 하면, 첫 클론 대상은 “작은 Godot 3 migration 후보 레포”가 좋다. 다만 흔한 2D platformer가 아니라, Camera/WorldEnvironment/Animation/Audio/CanvasItem 계열을 실제로 쓰는 프로젝트가 더 적합하다.

이유는 단순하다.

지금 api_mapping은 Camera, Animation, Audio, CanvasItem, Array 쪽 근거를 이미 가지고 있다. 반면 Godot 3 2D physics migration의 대표 단서인 KinematicBody2D, move_and_slide, yield, TileMap은 아직 현재 JSONL에 거의 없다.

따라서 첫 테스트는 다음 흐름이 가장 현실적이다.

작은 Godot 3 Camera/Animation/Audio 예제 클론
-> .gd와 .tscn 조각화
-> 현재 JSONL로 Retriever 검색
-> api_mapping hit가 실제 코드와 관련 있는지 확인
-> LLM에 들어갈 프롬프트 미리보기 확인

그 다음에는 Godot 4로 작성된 작은 Animation/Audio/Camera 예제를 클론해 docs_chunks 기반 설명 생성 흐름을 확인하는 것이 좋다.

최종적으로 label_prototypes가 생성되고 KinematicBody2D, move_and_slide, yield, Color8, TileMap 계열 근거가 쌓이면, 그때 전형적인 Godot 3 2D platformer나 action game 레포를 클론해서 migration 판단을 테스트하는 것이 더 맞다.

결론

지금 당장 클론할 레포 성격은 다음으로 정한다.

1차 후보:
  작고 버전이 분명한 Godot 3 예제
  Camera / WorldEnvironment / AnimationPlayer / AnimationTree / Audio / CanvasItem 중 일부를 실제로 사용
  .gd, .tscn, project.godot 포함
  에셋이 과하게 크지 않음

2차 후보:
  같은 영역을 사용하는 Godot 4 예제
  migration보다 코드 설명과 docs_chunks 검색 품질 검증에 사용

보류:
  KinematicBody2D / move_and_slide / yield / TileMap 중심의 Godot 3 2D platformer
  label_prototypes와 관련 migration 근거가 더 쌓인 뒤 테스트

이 순서가 현재 수집된 JSONL을 가장 낭비 없이 검증하는 방법으로 보인다.