2026년 6월 27일 토요일2026 년 6 월 27 일
- 26일에 작성했던 docs/roadmaps/2026-06-26-source-to-ast-input-flow.md를 다시 읽고, 문서 전체의 일관성이 부족하다고 판단함
- 처음 작성된 27일 문서는 객체 설명과 구조 설명이 많아, 실제로 입력이 어떻게 흘러가는지 추적하기 어려웠음
- 이후 PR 피드백을 기준으로 문서 방향을 다시 잡음
# <상대경로>로 펼쳐진 입력에서 어느 파일의 어느 라인이 AST Parser로 들어가는지 구체적으로 적는 형태로 수정함player.gd의 E020-E034처럼 실제 줄 범위를 기준으로, 해당 본문 일부가 Retriever 검색과 LLM 판단으로 이어지는 흐름을 정리함- 파일 경로는 추적용이고, Retriever 검색에는 코드/본문 조각의
chunkText만 들어간다는 기준을 다시 고정함
docs_chunks, api_mapping, label_prototypes는 특별 취급 없이 같은 방식으로 검색하고, 검색 후보를 LLM이 다시 검증하는 흐름으로 정리함- 오늘 작업은 실제 구현 전에 AI가 임의로 범위를 바꾸거나 추상적인 구조 설명으로 흐르지 않도록, 입력과 출력이 어느 지점에서 어떻게 이어지는지를 문서로 먼저 고정하는 데 목적이 있었음
- 문서로 정리한 흐름을 확인하기 위해
Source Flow Debugger 웹 도구를 구현함
- 로컬에서
http://127.0.0.1:8010/으로 실행해 Godot 프로젝트 입력을 직접 확인함
# <상대경로>로 펼쳐진 프로젝트 입력을 파일 단위로 다시 나누고, .gd는 AST 성격의 chunk로, .godot과 .tscn은 direct chunk로 분해함- 작은 Godot 프로젝트를 넣어
5 files, 14 chunks, AST 9, Direct 5로 분해되는 것을 확인함
- README.md 같은 문서 파일은 source-analysis 모드에서 제외하고, 제외된 사실과 이유가 화면에 남도록 함
- chunk별 디버깅 UI를 붙임
- 각 chunk 아래에
docs_chunks 검색, api_mapping 검색, label_prototypes 검색, Validate JSONL 버튼을 배치함
- 전역 테이블 체크박스가 아니라, 현재 chunk 바로 아래에서 테이블별 검색을 수행하는 형태로 정리함
- Retriever 입력은 파일 경로, 라인 번호, 프롬프트를 제외하고
{ "chunkText": "..." }만 보여주도록 함
- Qwen 검증은
prompt + chunkText + retrieved JSONL 단계에서만 사용하도록 분리함
- 웹 디버거를 실제로 써보며 발견한 문제를 수정함
- 페이지 로드시 샘플 Godot 코드가 자동으로 들어가던 문제를 제거함
- 같은 파일/폴더를 다시 업로드해도 브라우저
change 이벤트가 다시 발생하도록 upload input 값을 클릭 시점에 비움
- 개발 중 예전 JS가 남지 않도록 정적 파일 응답에
cache-control: no-store를 추가함
- PostgreSQL 검색 경로에서 client 생성/연결 실패가 나도 cleanup이 안전하게 동작하도록
client.end() 호출을 방어함
- 실제 구현 결과를 캡쳐와 함께 별도 문서로 남김
- 지금 기준으로 청크 단위 분해는 어느 정도 성공한 것으로 보고, 다음에 볼 핵심은 DB 검색을 실제로 어떻게 수행할지로 잡음
chunkText만으로 docs_chunks, api_mapping, label_prototypes에서 어떤 JSONL 후보가 돌아오는지 확인해야 함- 검색된 JSONL이 현재 chunk와 관련 있는지 Qwen 검증 단계에서 어떻게 판단하고 폐기할지 확인해야 함
- DB 검색을 붙이기 전에 GPT로 데모용 Godot chunk와 관련/무관 JSONL을 만들어 근거 매칭 프롬프트를 실험함
- 처음에는 “이 JSONL이 소스코드에 해당하는 내용을 담고 있냐, 예/아니오만 답하라” 정도로 물었더니 관련 JSONL과 무관 JSONL이 모두
예로 나오는 문제가 있었음
- 이후
source_api, source_pattern, match_terms, required_when_seen_in_code, before_code 중 하나가 실제 SOURCE_CODE 문자열/API 호출과 직접 일치해야만 예라고 제한함
- 넓은 단어 유사성이나 LLM의 Godot 사전 지식으로 판단하지 말고, JSONL에 적힌 문자열 근거만 보게 하자 관련 JSONL은
예, 무관 JSONL은 아니오로 갈라지는 것을 확인함
- 이 실험을 통해 DB 검색 뒤 Qwen 검증 단계는 “그럴듯한 의미 유사도”가 아니라 “검색된 JSONL 안에 현재 chunk와 직접 맞는 문자열 근거가 있는가”를 먼저 판정해야 한다는 기준을 얻음
- 관찰일지: JSONL 수집 현황 기반 테스트 레포지토리 선정 관찰일지
- 관찰일지: JSONL 근거 매칭 프롬프트 관찰
- 회고: docs/retrospectives/2026-06-27.md
- 내일은 Godot chunk와 관련/무관 JSONL 데모 셋을 여러 개 만들어서, Qwen이 어떤 근거로
예/아니오를 도출하는지 반복 테스트할 예정임
