Sphinx: 푸시 전에 변경한 코드를 설명하게 하기

무엇이 문제인가

코딩 에이전트코딩 에이전트개발자 대신 코드를 읽고 고치고 명령을 실행하는 AI 프로그램. Claude Code, Codex 등이 있다.가 쓴 코드는 개발자가 읽지 않은 채 푸시될 수 있다. Sphinx 를 만든 Parth Bhagat 은 2026년 10월 18일 Hacker News 의 Show HNShow HN개발자 커뮤니티 Hacker News 에서 자신이 만든 프로덕트를 소개하는 글. 제목이 "Show HN:"으로 시작한다. 글에서 이 프로덕트를 "생각은 맡길 수 있어도 이해는 맡길 수 없다"는 한 문장으로 설명했다.

변경 사항을 브랜치에 병합하기 전에 승인을 요구하려면 흔히 GitHub 의 브랜치 보호 규칙을 쓴다. GitHub 공식 문서(docs.github.com 의 About protected branches 페이지)에 따르면, 저장소 관리자가 보호 브랜치에 "Require pull request reviews before merging" 을 설정하면 협업자는 풀 리퀘스트풀 리퀘스트한 브랜치의 변경을 다른 브랜치에 병합해 달라는 요청. 다른 개발자가 검토하고 승인한다.를 열어야 한다. 쓰기 권한이 있는 리뷰어가 정해진 수만큼 승인해야 그 브랜치에 변경 사항을 병합할 수 있다. 이 규칙은 다른 사용자의 승인을 확인한다. 작성자가 자신의 변경 사항을 이해했는지도, 리뷰어가 코드를 읽었는지도 확인하지 않는다.

어떻게 해결했나

Sphinx 는 Git 훅훅정해진 시점에 자동으로 실행되도록 등록해 둔 스크립트. Git 은 커밋이나 푸시 직전에 훅을 실행한다.으로 작성자에게 변경한 코드의 동작을 묻는다. sphinx install 이 사용자 전역 Git 설정의 core.hooksPath 를 바꿔, 모든 저장소에서 Sphinx 의 pre-push 훅이 실행되게 한다. 푸시할 때는 저장소의 기존 훅이 Sphinx 보다 먼저 실행된다. 설치 직후부터 모든 저장소에서 main 과 master 브랜치로 푸시할 때 검사한다. sphinx init 은 저장소마다 검사할 브랜치와 이벤트를 .sphinxconfig 에 적어 이 기본값을 바꾼다.

검사할 브랜치로 푸시하면 푸시가 멈춘다. 터미널에는 로컬 페이지 주소가 출력된다. 그 사이 리뷰어 모델이 질문을 만든다. 작성자와 코딩 에이전트의 대화는 리뷰어에게 보내지 않는다. 리뷰어는 커밋된 변경을 읽기 전용 Git 도구(파일 목록, diff, 검색)로 조사한 뒤 질문을 만든다. 질문에 답하려면 작성자는 변경한 코드가 어떤 조건에서 어떻게 동작할지 예측해야 한다. 질문은 리뷰어 모델이 한 번 더 검토한 뒤 페이지에 표시된다. 작성자가 답을 보내면 리뷰어가 맞음·틀림·모호함으로 판정하고, 틀리면 설명과 함께 새 시나리오를 제시한다. 맞으면 멈춰 있던 푸시가 이어진다.

리뷰어 모델은 로그인된 Claude Code 나 Codex CLI 의 요금제, OpenRouterOpenRouter여러 회사의 AI 모델을 API 하나와 계정 하나로 사용할 수 있게 하는 서비스., 또는 OpenAI 호환 엔드포인트OpenAI 호환 엔드포인트OpenAI API 와 같은 형식으로 요청을 받는 서버 주소. 다른 회사의 모델이나 직접 실행한 모델도 이 형식으로 연결한다. 가운데 사용자가 고른다. .env 파일과 개인 키, 흔한 자격 증명 파일은 기본으로 리뷰어에게 보내지 않는다. 더 제외할 경로는 .sphinxignore 에 추가할 수 있다. 프로젝트 설명을 .sphinxcontext.md 에 적어 두면 Sphinx 가 매번 리뷰어에게 보낸다.

무엇이 다른가

첫째, 묻는 대상이 다르다. GitHub 의 브랜치 보호 규칙은 다른 사용자의 승인 수를 확인한다. Sphinx 는 작성자 본인에게 변경한 코드의 동작을 예측하게 한다. 그래서 혼자 작업하는 저장소에서도 게이트가 작동한다. 트레이드오프는 판정의 주체다. GitHub 의 승인은 사람 리뷰어가 하지만 Sphinx 의 판정은 LLMLLM대규모 언어 모델. 많은 글로 학습해 글을 이해하고 생성하는 AI 모델이다.이 한다. README 에도 리뷰어 모델이 틀릴 수 있다고 적혀 있다. 오늘은 리뷰어 모델 대신 스텁스텁시험할 때 실제 구성 요소 대신 정해진 응답만 반환하는 가짜 구현.을 사용했으므로 실제 모델의 질문이 얼마나 날카로운지는 확인하지 못했다.

둘째, 게이트의 위치가 다르다. GitHub 의 규칙은 서버가 병합 시점에 적용한다. Sphinx 는 작성자의 컴퓨터에서 푸시 시점에 적용한다. 그래서 한 번 설치하면 모든 저장소에서 작동한다. 트레이드오프는 강제력이다. 로컬 훅은 --no-verify 로 건너뛸 수 있다. README 에도 Sphinx 는 연습 도구이지 보안 게이트가 아니라고 적혀 있다. 서버에서 강제하려면 GitHub 의 규칙을 써야 한다.

셋째, 외부로 전송되는 데이터가 다르다. GitHub 의 리뷰에서는 코드가 이미 GitHub 에 있다. Sphinx 는 리뷰어 모델에 커밋된 변경과 관련 파일, 프로젝트 설명, 작성자의 답을 보낸다. 오늘 스텁 엔드포인트가 기록한 요청에는 .env 와 개인 키 파일 key.pem 의 내용이 없었다. 소스 파일에 붙여 넣은 가짜 토큰은 그대로 들어 있었다.

무엇이 편해지나

• 에이전트에게 코드를 맡기고 main 에 직접 푸시하는 1인 개발자. 푸시 전에 변경한 코드의 동작을 자신의 말로 설명해야 하므로, 읽지 않은 코드가 그대로 올라가는 일이 줄어들 수 있다. 오늘 푸시는 답하기 전까지 멈췄고, 통과 뒤 그대로 이어졌다.
• 동료가 리뷰하기 전에 작성자의 이해부터 확인하고 싶은 팀. 리뷰어 모델이 커밋된 변경을 읽고 질문을 만든다. 오늘 요청에는 커밋 diff 와 프로젝트 설명, 작성자의 답이 들어 있었다.
• 시크릿 파일이 든 저장소에서 외부 모델을 쓰는 사용자. Sphinx 는 .env 파일과 개인 키 파일을 리뷰어에게 보내지 않는다. 오늘 Sphinx 는 질문을 만드는 데 요청 2건, 답을 채점하는 데 2건을 리뷰어에게 보냈다. 이 4건에는 .env 와 key.pem 의 값이 없었다.

어떻게 만들었나

• 커밋 78개가 2026-10-14 부터 닷새 동안 쌓였다. 제작자는 Parth Bhagat 혼자다. 커밋 54개의 메시지 끝에는 Claude Opus 5.5 와 함께 작성했다는 Co-authored-by 트레일러가 있다.
• 저장소의 .itervox 디렉토리에 에이전트 운영 설정이 들어 있다. 구현자, 리뷰어, 병합 봇 같은 역할별 지침 파일과 2026-10-17 의 인수인계 기록, 화면 캡처다.
• JavaScript 9,736줄(src 모듈 33개), 테스트 파일 56개. 직접 의존하는 외부 패키지는 Pi SDKPi SDK코딩 에이전트 Pi 를 다른 프로그램 안에서 쓰게 하는 라이브러리. 에이전트 세션과 도구 호출의 반복을 맡는다. 의 두 패키지뿐이다. 리뷰어 세션은 이 SDK 위에서 실행된다.

실행해 보니

설치한 뒤 아래 순서로 시험했다.

1. 설치와 테스트. npm install 이 패키지 118개를 5초에 받았다. 테스트 697개가 42초에 모두 통과했다. sphinx install 은 0.14초에 끝났다. 전역 Git 설정의 core.hooksPath 가 바뀌었다.
2. 스텁 리뷰어. 리뷰어 모델 대신 로컬 HTTP 서버를 OpenAI 호환 엔드포인트로 지정했다. 이 서버는 받은 요청을 전부 기록하고, 조사 도구 호출 없이 정해진 질문 한 개와 "맞음" 판정을 반환한다.
3. 저장소 준비. 새 저장소에 sphinx init 을 실행하자 .sphinxconfig, .sphinxignore, .sphinxcontext.md 가 생겼다. 커밋에 가짜 시크릿이 든 .env, 가짜 개인 키 key.pem, 가짜 토큰 문자열이 든 src/signup.js 를 넣었다. 저장소에는 기존 pre-push 훅도 미리 만들어 두었다. 이 훅은 실행되면 확인용 파일을 만든다.
4. 푸시. git push origin main 이 "understanding check needed" 와 로컬 페이지 주소를 출력하고 멈췄다. 기존 훅의 확인용 파일이 먼저 생겼다. 페이지에는 변경 파일 5개와 "2 changed files excluded by privacy or ignore rules" 가 표시됐다.
5. 리뷰어가 받은 데이터. Sphinx 는 질문을 만드는 데 요청 2건, 답을 채점하는 데 2건을 리뷰어에게 보냈다. 6단계의 실패한 시도에서 보낸 요청은 이 수에 넣지 않았다. 첫 채점 응답은 스텁의 형식 오류로 거절돼 한 번 더 요청했다. 요청 본문은 모두 합쳐 60.8 KB 였다. 이 4건 어디에도 .env 와 key.pem 의 값은 없었다. src/signup.js 의 가짜 토큰과 .sphinxcontext.md 의 문장은 그대로 들어 있었다.
6. 실패 경로. 스텁이 형식에 어긋나는 응답을 세 번 반환하자 페이지에 "Review did not finish" 가 표시됐다. Git 은 계속 대기했다. 일시 정지 버튼을 누르자 푸시가 "progress is saved" 를 출력하고 중단됐다. 다시 푸시하자 Sphinx 는 리뷰어에 새 요청을 보내지 않고 저장된 질문을 다시 사용했다.
7. 통과. 답을 보내자 채점 요청 뒤 "Passed" 가 표시됐다. 멈춰 있던 푸시는 "Continuing this Git operation" 을 출력하고 원격 저장소에 커밋 3개를 올렸다.

$ git push origin main
Sphinx: understanding check needed for refs/heads/main (medium change).
Sphinx: Git is waiting for your answers in the local Sphinx questionnaire. It will continue automatically after you pass.
Sphinx questionnaire: http://127.0.0.1:32875/9VaP6pNPvCosJSRYGcGF6S3IwCeSVZv-qkz0aA2eKKo
Sphinx: open the local URL above to answer. No application was brought to the foreground.
Sphinx: understanding check complete. Continuing this Git operation.
To /tmp/run/remote.git
 * [new branch]      main -> main

확인하지 못한 것

• 실제 리뷰어 모델의 질문 품질과 호출 수. 다음에는 OpenRouter 의 무료 모델(openrouter-free 프리셋)을 리뷰어로 지정하고 같은 커밋을 다시 푸시하자.
• 코딩 에이전트 연동. Sphinx 는 Claude Code 와 Codex 에 MCPMCPModel Context Protocol. AI 모델을 외부 도구와 데이터에 연결하는 방식을 정의한 규격이다. 서버와 훅을 설치한다. 두 CLI 가 설치된 컴퓨터에서 sphinx install --agents codex,claude 로 확인하면 된다.

판정

작동한다. 질문에 답할 때까지 푸시가 멈췄고, 통과 뒤 그대로 이어졌다. 다만 리뷰어 모델 대신 스텁을 사용해 실제 모델의 질문이 얼마나 날카로운지는 확인하지 못했다. 에이전트가 쓴 코드를 혼자 main 에 올리면서 최소한 자신의 말로 설명할 수 있는지 확인하고 싶고, 리뷰어 모델 비용을 감수할 수 있는 경우에 써 볼 만하다. 팀의 코드 리뷰를 대신하거나 보안 게이트로 쓰려는 경우에는 적합하지 않다.

얻어갈 것

• 에이전트가 만든 코드는 누가 승인했는지와 별도로 작성자가 설명할 수 있는지도 확인하자. Sphinx 는 푸시를 멈추고 작성자에게 변경한 코드의 동작을 예측하게 했다.
• 외부 모델에 보내는 데이터는 요청 기록으로 확인하자. 오늘 스텁 엔드포인트의 기록에서 .env 는 빠지고 소스 안의 토큰은 그대로 전송된 것을 확인했다.
• 리뷰어가 실패하면 기본으로 푸시를 멈춘 상태로 두자. 리뷰어가 형식에 어긋나는 응답을 세 번 반환하자 Sphinx 는 푸시를 통과시키지 않고 결정을 사용자에게 넘겼다.