코드에서 컨텍스트, 그리고 의사결정까지: GitLab Orbit을 활용한 GitLab Knowledge Navigator 구축하기

소프트웨어 엔지니어링에서 가장 어려운 부분 중 하나는 코드를 작성하는 것이 아니라, 이미 존재하는 코드를 이해하는 것입니다.

모든 개발자가 다음과 같은 경험을 해보았을 것입니다:

기존 프로젝트에 합류합니다.
이슈 (Issue)를 맡습니다.
의존성 (Dependency)을 검색합니다.
스스로에게 질문합니다:

이것이 왜 존재하는가?

대부분의 도구는 다음과 같은 질문에 답할 수 있습니다:

이 클래스 (Class)는 무엇을 하는가?
이 함수 (Function)는 어디에서 사용되는가?
어떤 파일들이 이 모듈 (Module)을 임포트 (Import)하는가?

이것들은 유용한 질문들입니다.

하지만 더 가치 있는 질문은 대개 다음과 같습니다:

이것이 어떻게 여기에 있게 되었는가?

진짜 문제

저장소 (Repository) 지식은 보통 누락된 것이 아닙니다.

파편화되어 있을 뿐입니다.

그 지식의 일부는 다음 항목들에 흩어져 있습니다:

머지 리퀘스트 (Merge Requests)
이슈 (Issues)
커밋 히스토리 (Commit history)
코드 관계 (Code relationships)
소유권 (Ownership)
아키텍처 (Architecture)

개발자들은 안전하게 변경 사항을 적용하기 전에, 이러한 조각들을 수동으로 연결하는 데 수 시간을 소비합니다.

전통적인 AI 어시스턴트들은 코드를 설명합니다.

하지만 코드 뒤에 숨겨진 의사결정 (Decisions)을 설명하는 경우는 드뭅니다.

저장소 히스토리가 중요한 이유

다음과 같은 라인을 발견했다고 가정해 봅시다:

import httpx

일반적인 AI 어시스턴트는 다음과 같이 설명할 것입니다:

"httpx는 Python을 위한 비동기 HTTP 클라이언트 (asynchronous HTTP client)입니다."

기술적으로는 맞습니다.

하지만 진짜 엔지니어링 질문에는 답하지 못합니다.

질문은 이것입니다:

왜 이 의존성 (Dependency)이 여기에 있는가?

유용한 답변은 다음과 같은 형태일 것입니다:

비동기 통신을 지원하기 위해 도입되었습니다.
이전의 HTTP 클라이언트를 대체했습니다.
특정 머지 리퀘스트 (Merge Request)를 통해 추가되었습니다.
현재 여러 컴포넌트 (Components)가 이를 의존하고 있습니다.

이것이 바로 단순한 코드 설명을 넘어선 저장소 인텔리전스 (Repository intelligence)입니다.

---Demo Video:- https://youtu.be/xLBaZ2sFMEI

GitLab Knowledge Navigator 구축하기

이 아이디어를 탐구하기 위해, 저는 GitLab AI Hackathon 2026을 위해 GitLab Knowledge Navigator를 구축했습니다.

이 프로젝트는 저장소를 단순한 소스 코드 (Source code)로 취급하는 대신, GitLab Orbit을 지식 계층 (Knowledge layer)으로 사용합니다.

이 프로젝트는 다음을 결합합니다:

저장소 구조 (Repository structure)
머지 리퀘스트 (Merge Requests)
이슈 (Issues)
소유권 (Ownership)
의존성 관계 (Dependency relationships)
로컬 코드 그래프 분석 (Local code graph analysis)

저장소 이력 (repository history)에 근거한 질문에 답변하기 위해.

몇 가지 예시는 다음과 같습니다:

새로운 기여자 온보딩 (Onboarding new contributors)
아키텍처 설명 (Explaining architecture)
의사결정 타임라인 (Decision timelines)
변경 영향 분석 (Change impact analysis)
아키텍처 드리프트 탐지 (Architecture drift detection)
저장소 인텔리전스 점수 산정 (Repository intelligence scoring)
경영진 대상 엔지니어링 보고서 (Executive engineering reports)

하이브리드 아키텍처 (The Hybrid Architecture)

개발 과정에서 배운 교훈 중 하나는, 다양한 진실의 원천 (sources of truth)을 결합할 때 저장소 인텔리전스 (repository intelligence)가 더욱 향상된다는 점이었습니다.

이 프로젝트는 다음을 사용합니다:

Orbit Remote

작업 항목 (Work Items)
머지 리퀘스트 (Merge Requests)
프로젝트 멤버 (Project members)
저장소 관계 (Repository relationships)

그리고

Orbit Local

파일 (Files)
정의 (Definitions)
의존성 그래프 (Dependency graph)
DuckDB를 통한 SQL 쿼리 (SQL queries through DuckDB)

이들이 결합되어 이력적 컨텍스트 (historical context)와 소스 코드 구조 (source-code structure)를 모두 제공합니다.

특히 자랑스럽게 생각하는 기능 하나

한 가지 워크플로우는 다음과 같이 질문합니다:

왜 이 의존성이 존재하는가?

이 도구는 일반적인 설명을 내놓는 대신, GitLab Orbit을 사용하여 저장소 이력을 재구성함으로써 해당 의존성 뒤에 숨겨진 아키텍처 의사결정을 설명합니다.

**무엇 (what)**에서 **왜 (why)**로의 이러한 단순한 전환은 대화의 성격을 완전히 바꿉니다.

더 큰 저장소에서의 검증

이 접근 방식이 자체 코드베이스에만 국한되지 않음을 확인하기 위해, 저는 GitLab Runner의 포크(fork) 버전에서 이를 검증했습니다.

해당 저장소는 다음을 포함하고 있습니다:

1,366개의 파일
9,314개의 정의
58,340개의 인덱싱된 관계

동일한 분석을 실행한 결과, 이 접근 방식이 작은 데모 프로젝트를 넘어 확장 가능하다는 것을 입증했습니다.

배운 점

프로젝트 전반에 걸쳐 눈에 띄는 관찰 결과가 하나 있었습니다.

저장소의 현재 상태는 단지 최종 스냅샷 (snapshot)일 뿐이라는 점입니다.

진정한 가치는 그것을 만들어낸 의사결정의 순서를 이해하는 데 있습니다.

이는 다른 복잡한 시스템과 마찬가지로 소프트웨어 아키텍처에도 동일하게 적용됩니다.

코드는 **무엇 (what)**이 존재하는지 알려줍니다.

저장소 이력은 그것이 왜 (why) 존재하는지를 알려줍니다.

이 두 가지 관점을 결합하는 것이 바로 저장소 인텔리전스가 진정으로 유용해지는 지점입니다.

마치며

AI는 코드를 설명하는 데 매우 능숙해지고 있습니다.

다음 단계는 개발자가 해당 코드 뒤에 숨겨진 의사결정(decisions), 이력(history), 그리고 컨텍스트(context)를 이해하도록 돕는 것입니다.

그것이 바로 GitLab Knowledge Navigator의 핵심 아이디어입니다.

단순한 코드 분석이 아닙니다.

저장소 인텔리전스 (Repository intelligence).

코드(Code) → 컨텍스트(Context) → 의사결정(Decisions).

여러분의 팀은 저장소 온보딩(onboarding)과 아키텍처 지식 공유(architectural knowledge sharing)에 어떻게 접근하고 있는지 듣고 싶습니다. 문서(documentation)에 의존하시나요, 아니면 암묵지(tribal knowledge), AI 어시스턴트(AI assistants), 혹은 다른 무언가에 의존하시나요?