Sphinx로 AI가 짠 코드를 push 전에 퀴즈로 확인하기 — 설치부터 건너뛰기까지

AI가 짠 코드를 그대로 push하면, 나중에 그 코드가 왜 그렇게 동작하는지 설명하지 못하는 때가 옵니다. Sphinx는 그 질문을 push 앞으로 가져오는 무료 오픈소스 git 훅입니다. main 같은 브랜치에 push하면 Git이 잠깐 멈추고, 바뀐 코드에 대해 1~3개 질문을 던집니다. 맞히면 같은 push가 그대로 이어지고, 틀리면 왜 틀렸는지 설명한 뒤 다른 상황으로 다시 묻습니다.

2026년 10월 25일에 v0.1.17을 설치해서 작은 결제 재시도 코드를 push해 봤습니다. 아래에 설치 순서, 실제로 받은 질문, 코드가 어디로 나가는지, 급할 때 건너뛰는 방법을 적었습니다.

Sphinx가 하는 일

항목	내용
걸리는 시점	보호 브랜치(기본 main·master)로 push할 때
질문 수	작은 변경 1개, 중간 2개, 큰 변경 최대 3개 (기본 깊이)
질문 만드는 모델	로그인해 둔 Claude Code나 Codex CLI, 또는 OpenRouter 키
가격	도구는 무료(MIT). 모델 사용량은 내 요금제나 API에서 나감

질문은 함수 이름이나 파일 이름이 아니라 동작을 묻습니다. “이 상황에서 무엇이 반환되고, 상태는 어떻게 되는가” 같은 식입니다. 코드를 열어 보면서 답해도 됩니다.

질문을 만드는 쪽은 코드를 짠 대화를 보지 않습니다. 커밋된 변경만 읽기 전용 git 도구로 읽고 질문을 만들기 때문에, 코딩 에이전트가 “이렇게 짰다”고 한 설명이 그대로 정답이 되지 않습니다.

설치

Node.js 22.19 이상과 Git이 필요하고, macOS·Linux·WSL에서 됩니다. 윈도우 기본 환경은 아직 안 됩니다.

npm install -g sphinx-understand
sphinx install

sphinx install은 어떤 코딩 에이전트를 쓰는지, 질문을 어떤 모델로 만들지 묻습니다. 묻지 않고 바로 설치하려면 이렇게 합니다.

# Claude Code 요금제로 질문 만들기 (Haiku)
sphinx install --yes --preset claude-economy --agents claude

# Codex 요금제로
sphinx install --yes --preset codex-economy --agents codex

알아 둘 점이 하나 있습니다. 설치하면 이 컴퓨터의 모든 저장소에 적용됩니다. 전역 Git 설정의 core.hooksPath를 Sphinx 쪽으로 바꾸기 때문입니다. 원래 쓰던 훅은 Sphinx보다 먼저 그대로 돕니다. 저는 평소 쓰는 전역 설정을 건드리지 않으려고 임시 전역 설정 파일(GIT_CONFIG_GLOBAL)을 따로 두고 시험했습니다.

저장소마다 설정하기

cd 내-저장소
sphinx init --yes --branches main
sphinx doctor

sphinx init은 파일 세 개를 만듭니다.

• .sphinxconfig · 어느 브랜치, 어떤 이벤트(push·commit)를 검사할지
• .sphinxignore · 절대 읽지 않을 경로. .env, 개인 키, 흔한 인증 파일은 따로 적지 않아도 빠집니다
• .sphinxcontext.md · 이 프로젝트가 무엇을 하는지 짧게 적는 파일. 질문을 만들 때마다 같이 보냅니다

sphinx doctor가 ✓ Configured integrations are in place.로 끝나면 준비가 된 겁니다.

실제로 받은 질문

시험용 저장소에서 결제 함수에 재시도를 넣었습니다. 타임아웃이면 최대 두 번 더 시도하고, 마지막에도 실패하면 주문 상태를 failed로 바꾸고 에러를 던지는 코드입니다.

export async function charge(order, gateway, { retries = 2 } = {}) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      const receipt = await gateway.pay(order.total, { idempotencyKey: order.id });
      order.status = 'paid';
      return receipt;
    } catch (err) {
      if (err.code !== 'TIMEOUT' || attempt === retries) {
        order.status = 'failed';
        throw err;
      }
    }
  }
}

git push origin main을 하자 Git이 이렇게 멈췄습니다.

Sphinx: understanding check needed for refs/heads/main (small change).
Sphinx: Git is waiting for your answers in the local Sphinx questionnaire.
Sphinx questionnaire: http://127.0.0.1:53066/…
Sphinx: questionnaire opened in a background browser tab.

맥에서는 질문 페이지가 브라우저 뒤쪽 탭으로 열립니다. 작은 변경이라 질문은 하나였습니다.

게이트웨이가 매번 TIMEOUT을 돌려주면, 호출한 쪽은 무엇을 받고, gateway.pay는 몇 번 불리고, order.status는 어떻게 되는가?

일부러 “성공할 때까지 계속 재시도하고 상태는 그대로”라고 틀리게 답했습니다. Sphinx는 반복이 retries(기본 2)까지만 돌아서 pay가 세 번 불리고, 마지막 시도에서 상태를 failed로 바꾼 뒤 에러를 던진다고 설명했습니다. 그리고 같은 개념으로 상황만 바꿔 다시 물었습니다.

retries: 0으로 부르고 매번 TIMEOUT이면, pay는 몇 번 불리고 결과는 어떻게 되는가?

“한 번 불리고, 첫 시도가 곧 마지막이라 failed로 바뀌고 에러가 던져진다”고 답하자 통과했고, Continue push를 누르자 멈춰 있던 push가 이어졌습니다.

Sphinx: understanding check complete. Continuing this Git operation.
   bcb61c8..19aef42  main -> main

질문을 만들고 채점하는 데 Claude Code Haiku로 약 3만 7천 토큰이 들었고, 페이지 위쪽에 사용량이 표시됩니다.

코드가 어디로 나가는지

Sphinx는 자체 서버가 없습니다. 대신 질문을 만드는 모델 쪽으로 바뀐 코드와 관련 파일, 내 답, .sphinxcontext.md가 나갑니다. Claude Code를 고르면 Anthropic, Codex를 고르면 OpenAI 쪽입니다.

• .sphinxignore에 적은 경로와 무시된 파일은 읽지 않습니다
• 경로로 거르는 방식이라, 일반 소스 코드 안에 붙여 넣은 비밀값은 못 거릅니다
• 내 답은 페이지에서 Sphinx로 바로 가고, 코딩 에이전트는 통과했는지만 봅니다

Claude Code로 쓸 때는 요금제 사용량으로 돌리기 위해 환경 변수의 API 키를 무시합니다. 저는 처음에 설정을 격리하느라 홈 폴더를 바꿨더니 Claude Code가 로그인 안 된 상태로 보여서 “Claude 요금제로 로그인되어 있지 않다”는 안내가 떴습니다. 평소처럼 로그인된 환경에서는 이 단계가 없습니다.

건너뛰는 세 가지 방법

방법	범위	기록
페이지의 Skip this time	이번 push 한 번	남음 (통과로 치지 않음)
페이지의 Stop push	이번 push를 보내지 않음. 진행 상황은 저장	—
sphinx yolo	이 저장소 검사를 끔. 다시 실행하면 켜짐	남음

sphinx yolo는 한 번만 건너뛰는 게 아니라 다시 켤 때까지 그 저장소 검사를 끄는 명령입니다. 저장소 밖에서 실행하면 전체가 꺼집니다. 이유를 같이 남길 수 있습니다.

sphinx yolo --reason "운영 장애 대응"
sphinx status   # 최근 건너뛴 기록 확인

sphinx status에는 yolo-on · 운영 장애 대응처럼 시간과 이유가 남습니다.

쓰기 전에 알아 둘 것

• push가 최대 25분 기다립니다. 코딩 에이전트가 push를 실행했다면 에이전트 쪽 셸이 먼저 시간 초과로 끊길 수 있습니다. 그럴 땐 같은 push를 한 번 더 하면 이어서 진행됩니다. 기다리는 push가 있는데 하나 더 띄우면 안 됩니다
• 통과 기록은 24시간 유지됩니다. 코드·목적지·정책이 바뀌지 않으면 같은 변경을 다시 push할 때 질문 없이 진행 여부만 묻습니다
• 보안 장치가 아닙니다. 훅은 로컬에서 끌 수 있고, 채점하는 모델이 틀릴 수도 있습니다. 공식 문서도 연습용이라고 적고 있습니다
• 모델 호출 횟수에 기본 상한이 없습니다. 한 번 검사에 보통 5~8번 부르고, 답할 때마다 한 번씩 더 부릅니다. 유료 API를 쓴다면 sphinx config --max-model-calls 30처럼 상한을 거는 게 안전합니다
• 웹에서 하는 머지, CI, 배포는 검사하지 않습니다. 로컬 commit과 push만 봅니다

지우고 싶으면 sphinx uninstall로 훅과 연동 설정을 걷어 냅니다.

참고

• Sphinx GitHub 저장소 (README)
• Sphinx 설정 문서

AI가 짠 코드를 서버에 올리는 쪽은 GitHub Actions와 Watchtower로 집 서버에 접속하지 않고 배포하는 방법에 적었습니다.