코드베이스가 수행한 모든 것을 기억하는 코드 리뷰 에이전트를 구축한 방법

대부분의 코드 리뷰 (Code review) 도구들은 기억력이 없습니다. 모든 풀 리퀘스트 (Pull request)는 제로 상태에서 시작됩니다. 3개월 전에 왜 특정 패턴이 거절되었는지에 대한 맥락도 없고, 이 새로운 서비스가 하류(downstream)의 취약한 모듈과 밀접하게 결합되어 있다는 인식도 없으며, 내재된 조직적 지식 (Institutional knowledge)도 없습니다. 그들은 코드베이스가 아닌 코드만을 리뷰합니다.

저는 우리 프로젝트에서 동일한 실수가 반복되는 것을 보는 것에 지쳤습니다. 개발자들이 부주의해서가 아니라, 그 지식이 오래된 Slack 스레드나 잊혀진 PR 댓글 속에 머물러 있었기 때문입니다. 그래서 저는 ReviewMind를 구축했습니다. 이는 지속적인 메모리 (Persistent memory)를 가진 AI 코드 리뷰 에이전트이며, 전체 저장소 이력에 대해 모든 변경 사항을 시각적으로 매핑하는 실시간 대화형 의존성 그래프 (Dependency graph)를 갖추고 있습니다.

내가 실제로 해결하고자 했던 문제

일반적인 리뷰 도구들은 린팅 (Linting) 에러와 스타일 제안을 제공합니다. 유용하지만 얕은 수준입니다. 그들이 말해줄 수 없는 것은 다음과 같습니다:

• "지난 3월에 이 싱글톤 (Singleton) 패턴을 거절했습니다. 인증 (Auth) 모듈에서 레이스 컨디션 (Race conditions)을 유발했기 때문입니다."
• "이 새로운 유틸리티 함수는 지난 분기에 운영 환경을 망가뜨렸던 동일한 데이터 파이프라인 (Data pipeline)을 건드립니다."
• "세 명의 개발자가 이와 동일한 캐싱 (Caching) 접근 방식을 구현하려고 시도했습니다. 왜 계속해서 되돌려졌는지 그 이유를 알려드립니다."

그러한 종류의 맥락 (Context)이 10배 개발자 (10x engineer)와 주니어 개발자를 구분 짓는 요소입니다. 그것은 인간의 기억 속에 존재하거나, 아니면 사라집니다. ReviewMind의 역할은 이를 포착하고, 저장하고, 모든 새로운 제출 시 자동으로 드러내는 것입니다.

아키텍처: 함께 작동하는 세 가지 계층

저는 각각 매우 구체적인 역할을 가진 세 가지 인프라 구성 요소를 중심으로 ReviewMind를 설계했습니다.

1. 벡터 데이터베이스 (Vector Database) — "이유"를 저장하기

이것은 메모리 시스템의 핵심입니다. 저는 Weaviate를 벡터 데이터베이스로 사용하여 다음의 의미론적 임베딩 (Semantic embeddings)을 저장했습니다:

• 과거의 코드 차이점 (Code diffs) 및 그와 관련된 리뷰 결과
• 프로젝트별 아키텍처 결정 사항 및 스타일 가이드 (Style guides)
• 과거 리뷰 피드백 ("X 때문에 거절됨", "Y가 변경된 후 승인됨")

새로운 PR (Pull Request)이 들어오면, 에이전트는 단순히 원시 코드 (Raw code)만 살펴보지 않습니다. 에이전트는 Weaviate에 쿼리를 날려 의미론적으로 유사한 과거의 변경 사항을 검색합니다. 이를 통해 겉보기에 코드가 다르더라도 제출된 내용과 일맥상통하는 아키텍처 패턴을 찾아냅니다.

# 의미론적으로 유사한 과거 리뷰를 위해 Weaviate에 쿼리하기
def retrieve_similar_reviews(code_diff: str, top_k: int = 5):
    embedding = embed(code_diff)
...

이것이 에이전트에게 "조직적 기억 (Institutional memory)"을 부여하는 핵심입니다. 에이전트는 단순히 당신의 코드를 아는 것이 아니라, 당신 팀의 결정 사항을 알고 있습니다.

2. Redis — 고속 컨텍스트 엔진 (High-Speed Context Engine)

ReviewMind에서 Redis는 두 가지 중요한 역할을 수행합니다:

의미론적 캐싱 (Semantic Caching): 개발자가 지난주에 리뷰된 것과 95% 이상 유사한 PR을 제출하면, Redis는 캐시된 리뷰를 즉시 제공하며 LLM 호출이 필요하지 않습니다. 이는 대규모 팀에서 비용을 크게 절감하고 지연 시간 (Latency)을 낮게 유지해 줍니다.

실시간 세션 상태 (Real-time Session State): 사용자가 탐색함에 따라 대화형 의존성 그래프 (Dependency graph)가 실시간으로 업데이트됩니다. Redis는 활성화된 그래프 상태를 메모리에 유지하므로, 저장소 (Repository)가 수백 개의 모듈로 확장되더라도 시각화 레이어가 신속하게 유지됩니다.

# LLM을 호출하기 전 의미론적 캐시 확인
def get_cached_review(diff_hash: str):
    cached = redis_client.get(f"review:{diff_hash}")
...

3. LLM — 컨텍스트를 활용한 추론 (Reasoning With Context)

LLM (저는 Anthropic API를 통해 Claude를 사용했습니다)은 추론 레이어 (Reasoning layer)입니다. LLM은 다음을 전달받습니다:

1. 현재 코드 차이점 (Code diff)
2. Weaviate에서 검색된 과거 컨텍스트
3. 변경된 파일들의 의존성 그래프 흔적 (Dependency graph footprint)

그 후 LLM은 이 세 가지를 종합하여 구조화된 리뷰를 생성합니다. 단순히 "이것은 잘못된 것 같습니다"라고 말하는 것이 아니라, "이 패턴은 PR #247에서 알림 서비스의 연쇄 장애 (Cascade failure)를 일으켰기 때문에 구체적으로 지적된 바 있으며, 이번 변경 사항이 해당 서비스에 직접적인 영향을 미칩니다"와 같이 답변합니다.

def generate_review(diff: str, history: list, dependencies: list):
    context = format_context(history, dependencies)
    prompt = f"""
...

시각화를 가능하게 하는 핵심 기능: 의존성 영향 그래프 (Dependency Impact Graph)

이 부분은 제가 가장 자랑스럽게 생각하는 지점입니다. 모든 코드 제출(submission)은 실시간으로 상호작용이 가능한 **시스템 마인드맵 (System Mind Map)**을 생성합니다. 이는 새로운 코드가 기존 저장소 아키텍처(architecture)에 미치는 관계적 발자국(relational footprint)을 매핑하는 시각적 그래프입니다.

이 그래프는 세 가지 역할을 수행합니다:

1. 의존성 매핑 (Maps dependencies) — 변경된 코드가 직접적으로든 전이적으로든(transitively) 건드리는 모든 파일이 하나의 노드(node)로 표시됩니다.

2. 리스크 플래그 표시 (Flags risk) — 변경 사항의 하류(downstream)에 있는 파일이나 모듈은 위험 수준에 따라 색상으로 구분됩니다. 안전하면 녹색, 잠재적 영향이 있으면 황색, 과거에 취약했던 모듈은 적색으로 표시됩니다.

3. 메모리의 시각적 인코딩 (Encodes memory visually) — 과거 리뷰에서 이미 설정된 규칙을 위반했던 컴포넌트들은 다르게 강조됩니다. 개발자는 그래프를 보고 즉시 다음과 같이 파악할 수 있습니다: "저 모듈은 이전 세 번의 리뷰에서 패턴 플래그(pattern flag)가 발생했었군."

이 단계에서 지속성 메모리(persistent memory)는 단순한 백엔드 개념을 넘어, 실제로 보고 상호작용할 수 있는 무언가가 됩니다. 텍스트의 벽을 일일이 읽는 대신, 그래프의 노드를 가리키는 것만으로도 변경 사항의 영향 범위(blast radius)를 몇 초 만에 이해할 수 있습니다.

엔드 투 엔드 데이터 흐름 (The Data Flow End to End)

전체 리뷰가 실행되는 과정은 다음과 같습니다:

1. 개발자가 PR 제출 → diff를 추출하고 해시(hash)를 생성합니다.
2. 캐시 확인 (Cache check) → Redis에서 거의 동일한 과거 리뷰가 있는지 확인합니다.
3. 메모리 검색 (Memory retrieval) → Weaviate가 의미론적으로 유사한 과거 리뷰와 아키텍처 결정 사항을 찾아냅니다.
4. 의존성 해결 (Dependency resolution) → 그래프 레이어가 어떤 모듈이 영향을 받는지 매핑합니다.
5. LLM 합성 (LLM synthesis) → Claude가 diff + 히스토리 + 의존성을 결합하여 구조화된 비평(critique)을 생성합니다.
6. 시각적 렌더링 (Visual render) → 프론트엔드가 메모리 플래그에 따라 색상이 지정된 상호작용형 의존성 지도를 그립니다.
7. 결과 캐싱 (Result caching) → Redis가 향후 유사한 PR을 위해 출력값을 저장합니다.

전체 파이프라인은 일반적인 PR (Pull Request) 크기에 대해 3초 미만으로 실행되며, 개발자의 흐름 (flow)을 방해하지 않을 만큼 충분히 빠릅니다.

이를 구축하며 배운 점

메모리 저장 (Memory storage)은 쉽습니다. 메모리 검색 (Memory retrieval)은 어렵습니다. Weaviate 쿼리가 단순히 표면적으로 유사한 코드가 아니라, 진정으로 유용한 역사적 맥락 (historical context)을 드러내도록 만드는 과정에는 임베딩 전략 (embedding strategy)과 청킹 (chunking) 방식에 대한 세심한 튜닝이 필요했습니다. 파일의 전체 디프 (diff)를 단일 임베딩으로 저장하는 것은 효과적이지 않았습니다. 이를 의미론적 단위 (semantic units, 함수 단위 또는 모듈 단위)로 나누는 것이 큰 차이를 만들었습니다.

Redis 의미론적 캐싱 (semantic caching)에는 정확한 일치 (exact matching)가 아닌 유사도 임계값 (similarity threshold)이 필요합니다. 순수하게 해시 (hash) 기반으로 이루어지는 캐싱은 너무 많은 캐싱 기회를 놓칩니다. 저는 캐시에서 제공할지 아니면 LLM (Large Language Model)을 호출할지 결정하기 전에, 임베딩 코사인 유사도 (embedding cosine distance)를 사용하여 가벼운 유사도 검사를 구현했습니다.

시각화 레이어 (visualization layer)는 엔지니어들이 실제로 참여하는 지점입니다. 텍스트 기반의 리뷰 출력물은 대충 훑어보게 되지만, 인터랙티브 그래프 (interactive graph)는 면밀히 검토하게 됩니다. 개발자들은 자연스럽게 플래그가 지정된 노드 (nodes)를 클릭하여 왜 빨간색으로 표시되었는지 이해하고 싶어 합니다. 그러한 참여가 이루어지는 곳에서 조직의 지식 (institutional knowledge)이 실제로 전달됩니다.

LLM 컨텍스트 윈도우 (context windows)는 이력 데이터로 인해 빠르게 채워집니다. 저는 LLM에 데이터를 보내기 전에 역사적 맥락을 요약하고 순위를 매기는 작업을 공격적으로 수행하는 법을 배웠습니다. 가장 최근의 리뷰 20개를 보내는 것보다, 의미론적으로 가장 관련성이 높은 과거 리뷰 5개를 보내는 것이 더 뛰어난 성능을 보였습니다.

점진적 아키텍처 (Incremental architecture)가 빅뱅 방식의 설계 (big-bang design)를 이깁니다. 저는 메모리나 그래프 없이 오직 LLM 리뷰만으로 시작했습니다. 그다음 Weaviate를 추가했고, 그다음 Redis 캐싱, 그리고 시각화 레이어를 추가했습니다. 각 단계는 독립적으로 유용했고 테스트 가능했습니다. 만약 처음부터 이 세 가지를 동시에 구축하려고 했다면, 저는 여전히 통합 (integration) 디버깅을 하고 있었을 것입니다.

향후 계획

다음 즉각적인 단계는 **교차 저장소 메모리 (cross-repository memory)**입니다. 즉, ReviewMind가 조직 내 여러 프로젝트에서 내려진 아키텍처 결정 사항들을 학습할 수 있도록 하는 것입니다. 현재 메모리는 단일 저장소 (repo) 범위로 제한되어 있습니다. 인프라는 이미 이를 지원하고 있으며, 적절한 격리 (isolation) 및 액세스 제어 (access control) 계층을 구축하는 문제만 남아 있습니다.

Hindsight 프레임워크는 에이전트가 에피소드 메모리 (episodic memory)를 유지하고 검색하는 방식을 구조화하는 데 결정적인 역할을 했습니다. 메모리 증강 에이전트 (memory-augmented agents)를 구축하려는 분들이라면 직접 구현하기보다 여기서부터 시작할 것을 권장합니다. Hindsight 문서는 핵심적인 유지/회상 (retain/recall) 프리미티브 (primitives)를 잘 다루고 있으며, Vectorize 에이전트 메모리 (Vectorize agent memory) 개요는 저장소 스키마 (storage schema)를 설계하기 전에 읽어볼 가치가 있습니다.

제가 계속해서 되새기는 점은 이것입니다: 코드 리뷰의 가치는 시간이 지남에 따라 복리로 증가한다는 것입니다. 코드베이스에 대한 열 번째 리뷰는 첫 번째 리뷰보다 훨씬 더 뛰어나야 합니다. 왜냐하면 그때쯤이면 에이전트가 무엇이 망가지는지, 무엇이 유지되는지, 그리고 팀이 실제로 무엇을 가치 있게 여기는지 확인했기 때문입니다. 그것이 바로 ReviewMind가 지향하는 목표입니다. 즉, 당신과 함께 일하는 시간이 길어질수록 더 나아지는 리뷰어를 만드는 것입니다.

Yug Patel, Team Code Warriors 제작.