코드 그래프 및 지식 베이스

코드 그래프는 실험 기능입니다. 인터페이스, 데이터 형식, 인덱싱 동작은 이후 버전에서 바뀔 수 있습니다.

코드 그래프는 CodeGraph를 사용하여 프로젝트의 심볼과 심볼 간 관계를 분석합니다. 세션 지식 베이스에는 설계 결정, 제약 조건, 교훈이 저장됩니다. 코드 참조가 이 둘을 연결하므로, 코드의 현재 구조와 그렇게 만들어진 이유를 함께 확인할 수 있습니다.

페이지 구성

코드 그래프는 "개요", "심볼", "코드 탐색", "파일" 탭이 있는 대화 상자로 열립니다. "지식 베이스" 버튼을 클릭하면 지식 베이스가 열립니다.

개요: 파일, 심볼, 관계의 개수, 언어별 및 심볼 종류별 분포, 동기화 상태("자동 동기화 활성" 또는 "쿼리 전 동기화")를 표시합니다. 분포 항목을 클릭하면 해당하는 결과가 표시됩니다.
심볼: 이름이나 파일 경로로 검색합니다("심볼 또는 파일 경로 검색…"). 심볼 페이지에는 구문 강조가 적용된 소스와 함께 "들어오는 관계"와 "나가는 관계"가 관계 유형 및 파일별로 묶여 표시됩니다. 분석으로 추론한 관계에는 "추론된 관계"가 표시되며, 줄 번호를 클릭하면 호출 위치로 이동합니다.
코드 탐색: 기능이나 흐름을 설명하거나 파일 또는 심볼 이름을 입력하면 관련 소스와 관계가 표시됩니다. 이 조회는 로컬에서 실행되며 AI 모델을 사용하지 않습니다.
파일: 인덱싱된 파일을 탐색합니다. 파일을 클릭하면 해당 파일의 심볼이 나열됩니다.
호출하는 심볼과 호출되는 심볼: 심볼 페이지에서 여러 단계의 호출 관계를 표시합니다. "탐색 깊이"의 기본값은 3이며 최대 6까지 지정할 수 있습니다. 결과는 최대 500개까지 표시되며, 그보다 많으면 전체 개수와 안내 문구가 표시됩니다.
영향 분석: 심볼 페이지에서 변경의 영향을 받을 수 있는 심볼과 파일을 선택한 깊이(기본값 3, 최대 6)까지 표시합니다. 심볼은 최대 500개, 관계는 최대 2,000개까지 표시되며, 결과가 잘리면 전체 개수와 안내 문구가 표시됩니다.
호출 경로: 심볼 페이지에서 대상 심볼을 검색하면("대상 심볼 검색…") 호출 관계를 따라가는 최단 경로가 표시됩니다. "인덱스에서 방향이 있는 호출 경로를 찾지 못했습니다."는 인덱스에 그러한 경로가 없다는 뜻일 뿐입니다.

작업 디렉터리는 디렉터리 메뉴에서 전환하며, 이 메뉴에는 전체 경로도 표시됩니다. 페이지, 코드 탐색의 질문, 심볼, 깊이, 대상, 소스 줄은 모두 URL에 포함되므로 페이지를 새로 고치거나, 새 탭에서 열거나, 브라우저의 뒤로 및 앞으로 버튼을 사용할 수 있습니다. 링크는 같은 백엔드에 유효하게 로그인되어 있을 때 동작합니다.

프로젝트 인덱스 활성화

사이드바에서 프로젝트나 컬렉션을 마우스 오른쪽 버튼으로 클릭하고 "실험 기능" → "코드 그래프"를 선택합니다.
처음 사용할 때는 "CodeGraph 다운로드"를 클릭합니다. 현재 연결된 백엔드가 GitHub에서 버전이 고정된 CodeGraph 1.6.0 릴리스를 내려받아 내장된 SHA-256 체크섬으로 검증합니다("다운로드 체크섬이 일치하지 않아 런타임을 설치하지 않았습니다."는 검증에 실패했다는 뜻입니다). Node.js를 따로 설치할 필요는 없습니다.
"작업 디렉터리"를 선택하고 "인덱싱 활성화"를 클릭합니다. 프로젝트 디렉터리와, 프로젝트의 세션 및 그룹이 사용하는 다른 작업 디렉터리가 각각 나열되며, Git 워크트리마다 별도의 인덱스가 있습니다. 컬렉션에는 유효한 작업 디렉터리를 가진 세션이 하나 이상 있어야 합니다.
상태가 "사용 가능"이 될 때까지 기다린 다음 심볼이나 파일 경로를 검색합니다. 인덱싱은 백그라운드에서 실행되며("인덱싱 작업이 진행 중입니다. 이 페이지를 닫거나 인덱싱을 비활성화하여 작업을 중지할 수 있습니다."), 페이지를 닫아도 취소되지 않습니다.

"동기화"는 인덱스를 직접 갱신하거나, 실패한 뒤 다시 시도할 때 사용합니다. VelaTerm은 코드를 조회하기 전에도 매번 인덱스를 최신 상태로 맞춥니다. 같은 백엔드와 작업 디렉터리에서는 하나의 조회 프로세스를 재사용하며, 이 프로세스가 실행되는 동안에는 파일 변경 사항을 바로 반영합니다. 조회가 5분 동안 없으면 프로세스가 종료되고, 다음 조회 때 인덱스를 다시 열어 그동안의 변경 사항을 반영합니다. 개요 탭은 30초마다 동기화 상태를 새로 고칩니다. 자동 동기화를 사용할 수 없는 경우에도 VelaTerm은 조회할 때마다 먼저 동기화하므로, 오래된 결과를 최신 결과처럼 표시하지 않습니다.

"인덱싱 비활성화"는 실행 중인 인덱싱 작업을 중지하지만, 인덱스 파일과 지식 항목 연결은 유지하므로 나중에 다시 활성화할 수 있습니다. 작업이 중단되면 약 2분 안에 다시 시도할 수 있는 실패 상태로 바뀝니다("이전 작업이 중단되었습니다. 동기화하여 다시 시도하세요."). 인덱싱 작업 하나는 최대 30분 동안 실행될 수 있습니다.

인덱스는 각 작업 디렉터리의 .codegraph/ 폴더에 저장되며 CodeGraph가 관리합니다. 인덱싱은 VelaTerm이 직접 실행하며, CodeGraph의 에이전트 설치 프로그램을 실행하거나 Git 훅을 설치하지 않습니다. 프로젝트 디렉터리가 저장소의 하위 폴더이면 그 폴더만 인덱싱합니다.

코드 관계 보기

검색 결과에는 각 심볼의 이름, 종류, 위치가 표시됩니다. 심볼 페이지에는 소스, 들어오는 관계와 나가는 관계, 연결된 지식 항목이 표시되며, 인접한 심볼을 클릭하여 계속 탐색할 수 있습니다.

관계는 정적 분석으로 얻은 것이므로 불완전하거나 불확실할 수 있으며("관계는 정적 분석 결과이며 불완전하거나 불확실할 수 있습니다."), 코드를 실제로 실행하여 확인하는 것을 대신하지 않습니다. 심볼 페이지에는 방향별로 최대 200개의 관계와 최대 600줄의 소스가 표시되며, 그보다 많으면 안내 문구가 표시됩니다. 4MiB보다 큰 소스 파일은 표시되지 않습니다. 보고 있는 동안 파일이 변경되면, VelaTerm은 줄 번호를 신뢰하기 전에 다시 동기화하라고 안내합니다.

항목 연결과 검토

심볼 페이지에서 "지식 항목 연결"을 선택하고 기존 항목을 고른 다음, 항목의 내용과 코드를 비교하고 저장합니다. 항목 페이지의 "코드 참조"를 클릭하면 코드로 돌아가며, 코드 그래프의 항목 링크를 클릭하면 항목 전체가 열립니다.

연결에는 프로젝트, 작업 디렉터리, 파일 경로, 심볼 식별 정보, 검토 당시 파일의 SHA-256 다이제스트가 저장됩니다. 파일이 변경되면 연결에 "검토 필요"가 표시되고, 파일을 더 이상 읽을 수 없거나 파일이 삭제되었으면 "사용 불가"가, 그 밖의 경우에는 "변경 없음"이 표시됩니다. 검사는 파일 단위로 이루어지므로, 같은 파일에서 어느 부분이 바뀌든 검토가 필요한 상태가 됩니다. 열려 있는 항목 페이지는 참조를 주기적으로 확인합니다.

"코드와 항목 검토"를 선택하면 현재 코드를 볼 수 있으며, 항목의 내용이 여전히 유효하면 "검토 완료 확인"을 선택합니다. 백엔드는 그사이에 파일과 항목이 변경되지 않았는지 다시 확인하고, 변경되었으면 다시 불러오도록 요청합니다. 검토를 확인하면 코드 참조만 갱신되고 항목의 텍스트는 변경되지 않습니다. 결론을 바꾸려면 평소처럼 항목을 편집합니다.

심볼이 삭제되거나 이름이 바뀌어도 연결이 같은 이름의 다른 심볼로 옮겨지지는 않습니다. "연결 제거"를 선택한 뒤 올바른 심볼에 다시 연결합니다. 항목을 삭제하면 그 항목의 연결도 삭제됩니다. 프로젝트를 삭제하면 인덱스 기록과 연결은 삭제되지만, 다른 항목이나 작업 디렉터리의 인덱스 파일은 삭제되지 않습니다.

세션에서 조회하기

VelaTerm이 시작하는 모든 터미널 세션과 에이전트 세션에서는 vkb 명령을 사용할 수 있습니다. 터미널 명령을 실행할 수 있는 다른 에이전트도 이 명령을 사용할 수 있습니다. 업데이트 후 기존 세션에서 vkb를 찾을 수 없으면 세션을 다시 시작합니다.

"Vela Skills"를 설치하면(설정 ▸ 일반) Claude에서는 /vkb를, Codex에서는 $vkb를 사용할 수 있습니다. 이 스킬은 사용자가 명시적으로 요청할 때만 실행되며, 에이전트가 다른 작업 중에 스스로 호출하지 않습니다. 업데이트 후 에이전트에 스킬이 표시되지 않으면 "Reinstall"을 클릭하고 해당 에이전트 세션을 다시 시작합니다.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore는 코드 탐색과 같은 결과를 반환합니다.
callers, callees, impact에는 깊이를 선택적으로 지정할 수 있으며, 결과에는 relations, total, depth, truncated가 포함됩니다.
path는 검색 결과에서 얻은 정확한 심볼 ID 두 개를 받으며, files는 경로로 필터링할 수 있습니다.
search는 코드 결과(관련성 순으로 정렬되며, 결과가 더 있으면 hasMore 포함), 지식 항목, 로컬 노트를 각각 구분하여 반환합니다.
node는 심볼의 소스, 관계, 연결된 항목을 반환합니다.
memories와 memory는 세션 지식 베이스 항목을 검색하고 읽으며, 출처, 수정본, 코드 참조도 함께 반환합니다.
notes와 note는 로컬 지식 베이스를 검색하고 읽습니다(로컬 지식 베이스 참조).

코드 조회에는 명령을 실행한 디렉터리의 인덱스가 사용됩니다. 하위 폴더에서는 해당 프로젝트의 인덱스를 사용하며, 안에 중첩된 별도의 워크트리는 메인 체크아웃의 인덱스를 빌려 쓰지 않습니다. 활성화된 인덱스가 없거나 조회에 실패하면 결과에 코드를 사용할 수 없다고 표시되며, 지식 조회는 계속 동작합니다. 이 명령들은 아무것도 설치하지 않으며, 인덱싱을 활성화하거나 항목을 변경하지 않습니다.

데이터 저장 위치

CodeGraph 런타임은 애플리케이션 데이터 디렉터리의 codegraph/1.6.0/에 설치됩니다. 인덱싱 작업과 항목 연결은 애플리케이션 데이터베이스(knowledge_* 테이블)에 저장됩니다. 인덱싱은 코드가 있는 백엔드에서 실행되며, 브라우저 클라이언트와 SSH 연결은 기존 연결을 통해 결과를 읽으므로 추가 포트를 열지 않습니다. 백엔드마다 별도의 인덱스 설정과 지식 베이스를 가집니다.

CodeGraph의 원격 측정, 업데이트 확인, 별도의 백그라운드 서비스는 꺼져 있습니다. VelaTerm은 조회 프로세스를 직접 관리하며, 포트를 열지 않고 전용 표준 입출력 채널로 통신합니다. 인덱싱 자체에는 AI를 사용하지 않습니다. 다만 에이전트가 vkb로 읽은 코드나 항목은 에이전트가 소스 파일을 읽을 때와 마찬가지로 해당 에이전트에 설정된 모델 서비스로 전송될 수 있습니다.

코드 그래프 이벤트는 애플리케이션 데이터 디렉터리의 logs/runtime-*.log에 기록됩니다. VLX_LOG_DIR이 설정되지 않은 경우 VLX_KNOWLEDGE_LOG_DIR로 로그 디렉터리를 지정합니다. VLX_KNOWLEDGE_LOG_LEVEL로 기록할 이벤트를 걸러 낼 수 있습니다(예: error 또는 off). 로그에는 소스 코드, 조회 텍스트, 항목 텍스트, 자격 증명이 포함되지 않습니다.

CodeGraph는 github.com/colbymchenry/codegraph에서 개발되며 MIT 라이선스로 배포됩니다.