AI 코드 이해도 묻는 Git 훅 ‘Sphinx’ 공개

AI가 작성한 코드를 개발자가 얼마나 이해했는지 확인한 뒤 Git 푸시를 이어가는 오픈소스 도구 ‘Sphinx’가 공개됐다. 프로젝트 공식 GitHub 문서에 따르면 별도의 검토 모델이 코드 변경을 읽고 동작과 실패 상황에 관한 질문을 낸다. npm 공식 배포 기록상 최신 버전은 18일 오후 1시 31분(한국시간) 올라온 0.1.4다.

Sphinx는 설정된 브랜치로 코드를 푸시할 때 Git 작업을 잠시 멈춘다. 사용자가 질문에 답해 통과하면 같은 푸시가 계속된다. 답이 틀리면 이유를 설명한 뒤 같은 개념을 다루는 새 상황을 제시한다. 개발자가 직접 푸시했든 코딩 에이전트가 실행했든 점검 절차가 적용된다.

질문을 만드는 검토 모델은 코드를 작성한 에이전트의 대화 내용을 보지 않는다. 대신 읽기 전용 Git 도구로 커밋된 변경과 관련 파일을 살펴본다. 함수 이름을 외웠는지보다 작업이 중복 실행되거나 중간에 실패했을 때 어떤 결과가 생기는지, 반드시 유지해야 할 조건이 무엇인지 묻는 방식이다. 질문에 답하는 동안 코드를 찾아보는 것도 허용한다.

답변은 로컬 브라우저 설문이나 터미널에서 진행한다. 공식 문서는 답변 내용이 코딩 에이전트에 전달되지 않고 점검 상태와 진행 상황만 보인다고 설명한다. Codex, Claude Code, Cursor, OpenCode, Pi와 연동할 수 있으며 일반 Git 환경에서도 동작한다.

설치에는 Node.js 22.19 이상과 Git이 필요하다. macOS, 리눅스, WSL을 지원하며 윈도 네이티브 환경은 아직 지원하지 않는다. MIT 라이선스로 배포되고 npm 패키지 이름은 ‘sphinx-understand’다. 기본 설치는 사용자 전역 Git 훅 경로를 변경해 여러 저장소의 main·master 푸시에 점검을 적용한다. 기존 훅은 먼저 실행되도록 연결하며, 저장소별로 대상을 조정할 수 있다.

소프트웨어가 공개돼 있다고 모델 사용까지 무료인 것은 아니다. 검토에는 로그인된 코딩 CLI의 이용 한도나 별도 모델 API가 쓰인다. 검토 제공자에게 변경 코드와 관련 파일, 답변, 프로젝트 설명이 전달된다. 기본적으로 .env와 일반적인 인증 파일 등을 제외하지만, 평범한 소스 파일에 적힌 비밀값까지 경로 제외 규칙이 찾아내지는 못한다고 문서는 안내한다.

프로젝트 측은 이 도구를 보안 관문으로 보지 말아야 한다고 강조했다. 로컬 접근 권한이 있는 사용자나 에이전트는 Git 훅을 우회할 수 있고, 점검을 건너뛰는 기능도 제공한다. 건너뛴 기록은 남지만 통과가 코드 작성자의 신원이나 독립적인 이해를 증명하는 것은 아니다. 질문과 채점을 담당하는 모델도 틀릴 수 있다.

현재 0.1 계열은 로컬 커밋과 푸시만 대상으로 하며 웹에서의 병합, CI 필수 검사, 배포 단계는 다루지 않는다. 코드의 결함을 찾아내는 감사 도구라기보다, AI에 구현을 맡긴 뒤에도 개발자가 변경의 의미를 설명하도록 유도하는 보조 장치에 가깝다.

출처: Sphinx 공식 프로젝트 https://sphinx-six-theta.vercel.app/
Sphinx 공식 GitHub 저장소·문서 https://github.com/parthh01/sphinx
npm 공식 패키지 배포 기록 https://registry.npmjs.org/sphinx-understand