코드베이스를 AI 에이전트용 지식 카드로 바꾸는 오픈소스 도구 okf-generator
가 함수 하나를 이해하려 할 때마다 파일 전체를 읽거나 저장소를 grep으로 뒤지는 방식은 토큰을 크게 낭비한다. 600줄짜리 파일에서 하나를 찾는 데만 약 1만 4천 토큰이 든다. RAG(검색 후 생성) 방식으로 저장소를 청크 단위로 쪼개 임베딩하고 유사도 검색을 시도했지만, 청크 경계가 코드 문법을 무시해서 함수가 중간에 잘리거나 클래스 정의와 그 메서드가 서로 분리되는 문제가 있었다.
그 결과 에이전트가 문맥은 받았지만 정확하지 않은 문맥이었고, 존재하지 않는 호출 관계를 지어내기도 했다. 이를 해결하기 위해 만든 okf-generator는 텍스트를 청크로 나누는 대신 AST(추상 구문 트리)를 파싱한다. 를 이용해 18개 에 걸쳐 를 한 번 스캔하고, 함수·클래스·모듈마다 하나씩 '타입이 있는 개념 카드'로 컴파일하며, 호출·피호출·임포트 관계까지 미리 연결해 둔다.
그 결과 조회 한 번에 필요한 문맥이 원문 파일 약 1만 4천 토큰이 아니라 정확하고 타입이 명시된 약 140토큰으로 줄어든다. 핵심 추출 과정은 결정적(같은 입력엔 항상 같은 결과)이며 없이 오프라인으로 동작한다. 로 무료 공개되었고, 개발자가 판매 목적이 아니라 다른 에이전트 도구 개발자들에게 도움이 되길 바라며 공유했고 어디서 문제가 생기는지 피드백을 구하고 있다.
핵심 포인트
- 함수/클래스 하나를 찾기 위해 파일 전체를 읽으면 약 1만 4천 토큰이 소모된다
- RAG의 텍스트 청크 방식은 코드 문법 경계를 무시해 함수나 클래스가 잘려나가는 문제가 있다
- AST를 파싱해 함수·클래스·모듈 단위의 '개념 카드'로 미리 컴파일하는 방식(okf-generator)
- 이 방식으로 조회 시 필요한 토큰이 약 140토큰까지 줄어든다(약 100배 절감)
- 기반으로 18개 언어를 지원하며 없이 오프라인·결정적으로 동작, 무료 공개