Athena: 로컬 우선 코드 감사 및 검증된 릴리스 노트 작성 도구 (Open-Weight AI 활용)

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

제가 만든 것 (What I Built)

Athena는 Hacktoberfest 2026 - 사이드 허슬 챌린지를 위해 구축된, 오픈 소스 기반의 로컬 우선 Git 및 AST 변경 인텔리전스 엔진이자 Model Context Protocol (MCP) 서버입니다.

모든 개발자와 엔지니어링 팀은 릴리스 당일에 같은 공포를 느낍니다:

리팩토링 과정에서 SemVer(Semantic Versioning)를 올리지 않고 공개 함수 시그니처가 미묘하게 변경되었는가?
이 풀 리퀘스트가 병합되면 코드베이스의 어떤 하위 호출자들(downstream callers)이 깨질 것인가?
누군가 함수의 매개변수를 업데이트했지만, 이에 수반되는 docstring이나 마크다운 가이드 문서를 업데이트하지 않았는가?
150개의 커밋을 읽고 구조화되고 증거 기반의 릴리스 노트를 작성할 시간이 누가 있는가?

저는 Athena를 구축하여 원시 Git 히스토리와 다중 언어 구문 트리(syntax trees)를 폐쇄적인 제3자 클라우드 API로 코드를 전송하지 않고도, 구조화되고 수학적으로 검증된 변경 인텔리전스로 변환할 수 있게 했습니다.

Athena는 무엇을 하나요? (What Does Athena Do?)

AST 레벨 Breaking Change 감지: Git 커밋 범위를 가로질러 Python 및 TypeScript 구문 트리를 파싱하여 제거된 export, 변경된 매개변수 목록, 수정된 반환 유형을 정확히 찾아냅니다.
호출자 폭발 반경(Caller Blast Radius) 매핑: 저장소 전체를 자동으로 탐색하여 시그니처가 수정됨으로써 영향을 받는 모든 내부 파일, 호출 함수 및 가져온 심볼을 찾습니다.
문서화 드리프트 감지: 수정된 코드 심볼을 Markdown 가이드 및 docstring과 교차 참조하여 배포 전에 오래되거나 틀린 문서를 포착합니다.
증거 기반 릴리스 노트: 모든 글머리 기호가 정확한 커밋 해시와 파일 diff에 직접 연결되는 분류별 변경 로그를 생성합니다.
범용 모델 컨텍스트 프로토콜 (MCP): 표준 JSON-RPC 2.0 stdio 도구를 통해 Claude Desktop, Cursor, Zed 또는 모든 AI 코딩 어시스턴트에 네이티브하게 플러그인됩니다.
오프라인 우선 및 개인 정보 보호 중심: Ollama와 qwen2.5-coder:7b 같은 오픈 웨이트 모델을 사용하여 로컬 컴퓨터에서 완전히 실행됩니다. 귀하의 독점 코드베이스는 절대 컴퓨터를 벗어나지 않습니다.

누가 비용을 지불할까요?

Athena는 규제가 엄격한 환경에서 구축하는 엔지니어링 팀, 프리랜서 및 기업을 위해 만들어졌습니다:

프리랜서 및 개발 에이전시: 클라이언트 백엔드를 구축하는 프리랜서 개발자는 Athena를 병합 전(pre-merge)에 실행하여 고객 계약이나 NDA를 위반하는 breaking change를 절대 푸시하지 않도록 보장할 수 있습니다.
SaaS 및 엔터프라이즈 엔지니어링 팀: 공유 내부 라이브러리에서 발생하는 사소한 breaking change는 긴급 롤백과 고객 다운타임에 수천 달러의 비용을 초래합니다. Athena가 CI/CD에서 병합 전 검사를 자동화합니다.
개인 정보 보호를 중시하는 조직 (FinTech, HealthTech, 국방): 독점 코드 diff를 클라우드 LLM으로 보낼 수 없는 팀은 개발자 노트북이나 에어 갭(air-gapped) CI 러너에서 Athena를 완전히 오프라인 배포할 수 있습니다.

사이드 허슬 모델(The Side Hustle Model): 솔로 개발자를 위한 오픈 코어 CLI 및 MCP 서버이며, 모든 Pull Request를 감사하고 PR 리뷰에 폭발 반경 경고(blast-radius warnings)를 직접 게시하는 자동화된 GitHub Action 봇($19/월 솔로 / $79/월 팀)과 결합됩니다.

데모 (Demo)

Athena는 모든 로컬 Git 저장소를 검사할 수 있습니다(현재 디렉터리에는 .를 전달하거나 프로젝트 경로를 지정). 또한 python examples/create_demo_repo.py를 실행하여 샘플 커밋, 하위 호환성 깨짐 변경 사항(breaking changes), 문서 드리프트가 포함된 즉각적인 샌드박스 저장소를 생성할 수 있습니다.

1. AST를 통한 하위 호환성 깨짐 변경 사항 감지 (Detecting Breaking Changes via AST)

python -m athena breaking-changes . --base v1.0.0 --target v2.0.0

검토가 필요한 하위 호환성 깨짐 변경 사항 1개 발견:

[CRITICAL] calculate_metrics (함수)
...

2. 호출자 폭발 반경 평가 (Assessing Caller Blast Radius)

python -m athena analyze . --base v1.0.0 --target HEAD

분석 요약:
  - 분석된 커밋: v1.0.0과 HEAD 사이의 12개 커밋
  - 수정된 파일: 8개 (Python: 5, TypeScript: 2, Markdown: 1)
...

3. 증거 기반 검증된 릴리스 노트 생성 (Generating Evidence-Verified Release Notes)

python -m athena release-notes . --base v1.0.0 --target v2.0.0 --version "v2.0.0"

# 릴리스 노트 - v2.0.0

## 잠재적 하위 호환성 깨짐 변경 사항
...

4. 대화형 AI 에디터 통합 (MCP 서버) (Interactive AI Editor Integration)

Athena를 claude_desktop_config.json 또는 Cursor 설정에 추가하세요:

{

**로컬 우선, 증거 기반의 Git 및 AST 릴리스 준비 및 변경 지능 MCP 서버**

Athena는 **검증 가능하고 근거에 충실한 코드 변경 지능**을 제공하는 오픈 소스 로컬 우선 Model Context Protocol (MCP) 서버이자 개발자 CLI입니다. 결정론적(deterministic) Git diff 분석, Python Abstract Syntax Tree (`ast`) 및 TypeScript/JavaScript 구조 시그니처 비교, 다운스트림 호출자 폭발 반경 추적(caller blast-radius tracing), 문서 드리프트 감지 기능을 결합하여, Athena는 기존 AI 릴리스 노트 생성기의 환각 현상과 피상성을 제거합니다.

## 주요 차별점 (Key Differentiators)

1. **결정론 우선 코어 (Deterministic-First Core) (LLM 독립성 100%)**: Athena는 Ollama, 외부 AI API 또는 네트워크 연결 없이도 완전히 오프라인으로 작동합니다. 모든 Git 검사, AST 심볼 델타, 호출자 폭발 반경 그래프, 문서 드리프트 경고 및 릴리스 노트는 LLM 대기 시간 0ms로 결정론적으로 실행됩니다.
2. **근거 기반 증거 인용 (Ground-Truth Evidence Citations)**: 보고되는 모든 변경 스토리와 잠재적인 하위 호환성 깨짐(breaking change)은 40자 길이의 커밋 SHA, 커밋 제목, 파일 경로, 정확한 베이스/타겟 라인 범위, 통합 diff hunk 등을 포함하는 검증된 `EvidenceRecord` 항목에 바인딩됩니다.

[GitHub에서 보기](https://github.com/aaryanrwt/athena)

-   **33 / 33 실제 자동화 테스트 통과**: (위치 전용 `/` 마커, staticmethods, Windows NTFS 스트림 보호 및 TypeScript 멀티라인 인터페이스를 포함하여 커버함)
-   **클라우드 API 요구사항 없음**: 결정론적 AST 폴백을 통해 100% 오프라인 우선 구현.

## 구축 과정 (How I Built It)

Athena는 엄격한 하이브리드 아키텍처를 중심으로 설계되었습니다:

[ Git 히스토리 및 Diff 엔진 ]
|
[ 다국어 AST 파서 (Python + TypeScript) ]
...


### 핵심에 있는 오픈 소스 AI

Athena는 오픈-웨이트(open-weight) `qwen2.5-coder:7b` 모델을 [Ollama](https://ollama.com/)를 통해 소비자 하드웨어에서 로컬로 구동하여 사용합니다 (6GB VRAM의 NVIDIA RTX 4050 Laptop GPU에서 테스트됨). 이 모델은 여러 커밋(multi-commit diffs)을 합성하고, 분산된 변경 사항들을 응집력 있는 비즈니스 내러티브와 기술적 릴리스 테마로 그룹화합니다.

### 결정론 우선 엔지니어링이 중요한 이유

LLM은 존재하지 않는 코드를 만들 수 있습니다. Athena는 이를 2단계 파이프라인으로 해결합니다:

1.  **결정론 규칙 엔진(Deterministic Rule Engine)**: AST 구문 분석 및 폭발 반경 추적(blast-radius tracing)은 전적으로 Python의 네이티브 `ast` 모듈과 TypeScript 문법 토크나이저를 통해 실행됩니다. 하위 호환성 파괴(breaking-change) 판정은 100% 수학적 진실입니다.
2.  **증거 기반 접지(Evidence Grounding)**: 로컬 AI가 생성하는 모든 요약은 실제 커밋 SHA와 파일 경로를 인용해야 합니다. Athena의 검증기(verifier)는 각 인용을 실제 Git 로그와 대조하며, 환각된 주장(hallucinated claims)은 자동으로 제거됩니다.
3.  **결정론적 폴백(Deterministic Fallback)**: Ollama가 오프라인이거나 설치되지 않은 경우, Athena는 결정론 모드로 원활하게 전환되어, 어떠한 AI 런타임 없이도 100% CLI 및 MCP 서버의 신뢰성을 보장합니다.

## 오픈 혁신이 중요한 이유

Athena와 같은 개발자 도구에게 있어 오픈 혁신은 전체 비즈니스 활성화 요소입니다:

-   **클라이언트 프라이버시 및 제로 NDA 위반**: 기업 코드를 다루는 프리랜서나 에이전시는 클라이언트의 지적 재산(IP)을 OpenAI, Anthropic 또는 외부 클라우드 엔드포인트로 서면 동의 없이 전송할 수 없습니다. 오픈-웨이트 모델을 노트북에서 로컬로 실행하면 100% 데이터 주권(data sovereignty)이 보장됩니다. 클라이언트 코드는 기기를 벗어나지 않습니다.
-   **사이드 허슬에 적합한 단위 경제학**: 하루에 20개의 풀 리퀘스트(pull requests)를 통해 5만 라인 분량의 변경 사항(diffs)을 독점 클라우드 API로 전송하는 것은 매달 수백 달러의 토큰 비용을 발생시켜 마진을 파괴할 것입니다. 오픈-웨이트 모델을 소비자 하드웨어에서 실행하면 감사당 단위 비용은 $0.00입니다.
-   **오프라인 및 에어 갭 자율성**: 개발자들은 비행기, 통근 열차, 보안이 유지되는 에어 갭(air-gapped) 기업 인트라넷에서 코딩합니다. Athena는 네트워크 호출이 전혀 없습니다 - 원격 측정(telemetry), 인터넷 확인, 클라우드 의존성이 없습니다.
-   **벤더 종속성 없음**: Athena가 오픈 표준(Git, 표준 ASTs, 그리고 오픈 Model Context Protocol)을 기반으로 구축되었기 때문에, 사용자는 로컬 모델을 Qwen에서 Llama 3 또는 Gemma 2로 언제든지 교체할 수 있습니다.

## 저의 첫 사용자

Athena를 실제 환경에서 테스트하기 위해, 저는 리테일 클라이언트를 위한 마이크로 서비스 청구 API(billing API)를 유지 관리하는 프리랜서 백엔드 개발자에게 이를 공유했습니다.

**테스트 내용**: 
저희는 38개의 커밋을 포함하는 다가오는 `v2.0.0` 리팩토링 브랜치에 대해 Athena를 실행했습니다.

**발견된 문제**: 
Athena는 즉시 **심각한(CRITICAL) 호환성 파괴 변경 사항(breaking change)**을 플래그 지정했습니다: 헬퍼 메서드 `format_tax_rate`가 `@staticmethod`로 변경되었고, 기본값이 없는 새로운 위치 인자(positional argument)를 받게 되었습니다. 작성자의 새 단위 테스트는 통과했지만, Athena의 **폭발 반경(Blast Radius)** 도구는 다른 파일에 있는 3개의 레거시 웹훅 프로세서가 이전의 1개 인자 시그니처를 호출하고 있음을 식별했습니다. 해당 PR을 병합하면 실제 고객 청구서 생성이 중단될 수 있었습니다.

**그들의 피드백**:

클라이언트가 보기 전에 그걸 잡아냈다는 게 제 평판을 살렸어요. 프리랜서로 일하면서 웹훅(webhook)이 고장 나면 화난 이메일과 계약금 손실을 의미하거든요. 클라이언트 리포지토리 전체에 걸쳐 이걸 자동화해 주는 도구라면 월 $29 정도는 기꺼이 지불할 거예요.

**다음으로 요청받은 것:** 
풀 리퀘스트(pull request)에 블래스트 반경 보고서(blast radius report)를 자동으로 댓글로 달아주는 네이티브 GitHub Action.

## 수상 부문

-   **2주 차: 사이드 허슬(Side Hustle)** - 프리랜서, 에이전시, 마이크로 SaaS 팀을 위한 명확한 상업적 경로를 가진 로컬 우선 변경 인텔리전스 및 릴리스 관리 엔진.
-   **최우수 오픈소스 AI 애플리케이션 (Best Open-Source AI Application)** - Ollama를 통해 오픈 웨이트 모델(`qwen2.5-coder:7b`)과 결정론적 AST 정적 분석을 결합하여 검증 가능하고 사적인 개발자 도구를 제공함.