Sphinx가 AI가 짠 코드를 푸시 전에 질문으로 검증한다

AI 코딩 에이전트가 만든 코드를 그대로 원격 저장소에 올리기 전에, 개발자 본인이 그 변경을 제대로 이해했는지 물어보는 Git 훅이 나왔다. 이름은 Sphinx이며, npm 패키지 `sphinx-understand`로 배포된다. 슬로건은 생각은 맡겨도 이해까지 맡기지는 말자는 취지다.

동작은 단순하다. 보호 대상으로 지정한 브랜치에 푸시하려 하면 Git 흐름이 잠시 멈추고, Sphinx가 해당 커밋의 diff를 읽어 질문 하나를 던진다. 질문을 만드는 주체는 개발자의 대화 기록을 전혀 보지 못한 리뷰어다. 즉 에이전트와 나눈 채팅 맥락이 아니라, 실제로 바뀐 코드만 보고 "이 변경이 잘못됐을 때 무슨 일이 벌어지는가"를 묻는다.

원문에 실린 예시는 결제 로직이다. 웹훅 핸들러가 `charge()` 호출보다 이벤트 ID를 먼저 저장하도록 바뀐 상황에서, Stripe가 타임아웃 후 같은 이벤트를 다시 보내면 어떻게 되는지 묻는다. 개발자가 "두 번 청구된다"고 답하면 틀렸다고 알려주고, 저장된 ID 덕분에 재시도는 200을 반환하고 청구를 건너뛴다는 점, 다만 그 ID가 청구 성공 전에 기록되므로 `charge()`가 실패하면 다음 재시도에서 결제가 영영 누락될 수 있다는 점을 짚어준다. 여기서 정확히 답하면 푸시가 이어진다.

설치 환경은 Node 22.19 이상이며 macOS, Linux, WSL에서 돌아간다. `sphinx install`을 실행하면 Git과 코딩 에이전트를 연결하고, 리뷰를 담당할 모델을 고르는 절차가 시작된다. 질문 생성에는 기존에 쓰던 코딩 에이전트를 그대로 활용하거나 OpenRouter, 또는 OpenAI 호환 엔드포인트를 붙일 수 있다. 토큰을 최소한으로 쓰도록 설계됐다는 점을 내세운다.

호환 범위는 Codex, Claude Code, Cursor, OpenCode, Pi 같은 에이전트 도구와 일반 Git이다. 에이전트가 대신 답하게 할 수도 있지만, 어느 쪽이든 개발자의 답변이 코딩 에이전트 쪽으로 전달되지는 않는다. `.env` 파일이나 키가 담긴 파일은 열지 않는다고 명시한다.

배경에는 에이전트 보조 개발의 확산이 있다. 코드 생성 속도가 빨라질수록 사람이 감당해야 할 리뷰 양이 늘고, diff를 눈으로 훑는 것만으로는 변경의 부작용을 놓치기 쉬워진다. Sphinx는 검증을 문서나 체크리스트가 아니라 "말로 설명해 보기"라는 방식으로 되돌린다. 틀리면 왜 틀렸는지 배우고 다른 시나리오로 다시 시도하게 하는 구조다.

실무에서는 리뷰어가 붙기 전 단계에 이해도 관문이 하나 생기는 셈이다. 특히 결제, 인증, 데이터 마이그레이션처럼 실패 경로가 중요한 변경에서 효과가 클 것으로 보인다. 반대로 사소한 리팩터링까지 매번 질문을 받는 흐름이 부담스러울 수 있다.

주의할 점도 있다. 급할 때는 `sphinx yolo`로 푸시를 통과시킬 수 있지만, 건너뛴 기록은 모두 남는다. 즉 강제 차단 장치라기보다 기록이 남는 자율 규율에 가깝다. 또한 질문 품질은 연결한 모델과 diff 크기에 좌우되므로, 어떤 모델을 리뷰어로 붙이는지가 운영의 핵심 변수가 된다.