문제를 겪었고, 이를 해결하기 위해 무언가를 만들었습니다.

만약 여러분이 현재 애플리케이션을 구축하기 위해 Cursor, Copilot, 또는 Claude를 사용하고 있다면, 개발 속도(developer velocity)가 워프 속도에 도달했다는 것을 알고 있을 것입니다. AI 에이전트에게 프롬프트를 입력하여 30초 이내에 여러 파일로 구성된 기능을 구축하거나, 모듈을 리팩터링(refactor)하거나, 복잡한 검증 스키마(validation schema)를 생성하도록 할 수 있습니다.

하지만 이러한 속도에는 거대하고 조용한 세금(tax)이 따릅니다: 가속화된 아키텍처 드리프트(architectural drift)와 컨텍스트 붕괴(context collapse)입니다.

AI 어시스턴트는 미시적 수준(micro-level)의 기능 생성에는 뛰어나지만, 거시적 수준(macro-level)의 시스템 일관성 유지에는 종종 어려움을 겪습니다. 그들은 깊게 중첩된 조건문(conditionals)을 신경 쓰지 않으며, 눈 하나 깜빡이지 않고 순환 검증 의존성(circular validation dependencies)을 만들어내고, 인간 팀이 편안하게 추적할 수 있는 것보다 더 빠르게 파일을 생성합니다. 하지만 팀에 새로운 인원이 합류하면 어떻게 될까요?

어느 순간, 여러분의 저장소(repository)에는 리뷰 주기(review cycle)를 완전히 벗어나 복잡성이 확장되고 있는 매우 휘발성 높은 "핫스팟(hot spots)"이 생겨나게 됩니다.

제가 관리하는 코드베이스의 이 문제를 해결하기 위해, 저는 repo-drift를 구축했습니다. 이는 설정이 필요 없는(zero-config), 100% 로컬 방식의 읽기 전용(read-only) Python CLI 도구로, 몇 초 만에 가장 큰 기술 부채(technical debt) 핫스팟을 격리해 줍니다.

⚙️ 내부 작동 원리

repo-drift는 전적으로 여러분의 워크스페이스 터미널(workspace terminal) 내에서 작동합니다. 코드를 클라우드 데이터베이스로 동기화하지 않으며, 외부 API로 데이터를 유출하지도 않고, 수천 개의 파일을 파싱(parse)하는 데 1초도 걸리지 않습니다.

이 도구는 세 가지 주요 운영 계층(operational layers)에 걸쳐 저장소의 상태를 매핑합니다:

1. Git Churn Filtering (Git 변경 빈도 필터링): 설정 가능한 시간 범위(예: 90일) 동안 로컬 .git 로그를 스캔하여 파일당 편집 빈도를 추적하며, lockfiles, 빌드 폴더, 에셋(assets)과 같은 노이즈 파라미터는 자동으로 무시합니다.
2. Structural Complexity Profiling (구조적 복잡도 프로파일링): 변경 빈도가 높은(high-churn) 파일을 대상으로 절대적인 코드 라인 수(LOC, Lines of Code)와 함께 최대 중첩 들여쓰기 깊이(maximum nesting indentation depth)(순환 복잡도(cyclomatic complexity)를 나타내는 가볍고 매우 빠른 대리 지표)를 분석하여 가중치가 적용된 **변동성 점수(Volatility Score)**를 생성합니다.
3. Knowledge Ownership Mapping (지식 소유권 매핑): 이러한 고변동성 파일들에 대한 과거의 라인 단위 작성자(authorship) 정보를 분석하여 정확한 기여자 코드 비율을 계산하며, 프로젝트에서 가장 위험한 구역의 암묵적인 인간 "컨텍스트 소유자(Context Owners)"를 즉시 식별합니다.

📈 프로덕션 모놀리스(Monolith)에서의 벤치마킹: Dub.co

단순한 보일러플레이트(boilerplate) 저장소에서만 테스트하고 싶지는 않았습니다. 저는 repo-drift V1 엔진을 Dub 팀이 구축한 거대한 오픈 소스 프로덕션 모놀리스(production monolith)로 향하게 했습니다.

로컬 실행 루프는 다음과 같았습니다:

dub 저장소를 대상으로 repo-drift CLI를 실행하여, 0.7초 만에 partner 및 program 모듈 내부의 주요 코드베이스 핫스팟(hot spots)을 식별하는 터미널 출력 결과.

VS Code 내부에서 생성된 REPO_DRIFT_INSIGHTS.md 마크다운 파일로, 고위험 저장소 경로의 구조적 분석 내용을 보여줍니다.

출력 요약

더 중요한 것은, 지표가 즉각적으로 들려주는 아키텍처적 서사(architectural story)를 살펴보는 것입니다. 지난 90일 동안 Dub 저장소는 /partners 및 /program 아키텍처를 중심으로 한 격렬한 기능 반복(feature iterations)을 겪었습니다. schemas/partners.ts와 types.ts가 변동성 지수(volatility index)의 최상단에 위치하기 때문에, 이는 엔지니어링 리드에게 핵심 데이터 검증 계약(data validation contracts)이 UI 수정과 동시에 변하고 있다는 경고를 보냅니다. 이는 빠르게 움직이는 AI 코드 삽입이 구조적 회귀(structural regressions)를 유발하여 시스템을 깨뜨릴 수 있는 바로 그 지형입니다.

이 stdout 요약과 함께, 스캔된 디렉토리 내에 명시적인 복잡도 분석(complexity breakdowns)과 작성자 소유권 비율(author ownership percentages)을 상세히 기술하는 풍부한 텍스트 형식의 REPO_DRIFT_INSIGHTS.md 보고서를 직접 생성합니다.

🛠️ 여러분의 코드베이스에 직접 적용해 보세요

repo-drift v1은 완전히 오픈 소스이며 Python으로 네이티브하게 작성되었습니다. 주말 동안 여러분 자신의 저장소에 있는 사각지대를 확인하고 싶다면, 2분 안에 실행할 수 있습니다:

1. 저장소 클론(Clone):

git clone https://github.com/shaunakmukherjee/repo-drift.git
cd repo-drift

2. 의존성 설치 및 실행:

pip install -r requirements.txt
python main.py --repo 'path/to/your/repository' --days 90

GitHub에서 확인해 보시고, 유용하다고 생각되시면 별(star)을 눌러주세요:
👉 GitHub: shaunakmukherjee/repo-drift

다른 개발자 및 엔지니어링 리드분들의 의견을 듣고 싶습니다. 기능 확장이 자동화(autopilot) 모드로 진행될 때, 코드 건강도(code health)를 추적하기 위한 여러분의 주요 전략은 무엇인가요? 여러분의 생각이나 실행 결과를 아래 댓글로 남겨주세요!