Sphinx - AI가 작성한 코드를 이해했는지 푸시 전에 퀴즈로 확인하는 도구

GitHub README의 앞부분(소개, 요구 사항, 주의 사항, 설치)을 읽고 옮겼어요. 설정 세부 절은 읽지 못했어요.

한 줄 소개

생각은 외주로 맡길 수 있어도, 이해는 맡길 수 없어요.

Claude Code, Codex, Cursor, OpenCode, Pi 또는 그냥 git push와 함께 쓰고, 리뷰는 Claude Code·Codex 요금제, OpenRouter, OpenAI 호환 엔드포인트로 돌려요.

어떻게 작동하나요

보호 브랜치로 푸시하면 Git이 기다리는 동안 Sphinx가 변경이 무엇을 할지 예측해 보라고 물어요. 놓친 게 있으면 설명해 주고 보통 새 시나리오로 다시 기회를 줘요. 통과하면 같은 푸시가 이어져요. 사람이 푸시하든 코딩 에이전트가 푸시하든 똑같아요.

질문은 별도 리뷰어 모델이 만들어요. 읽기 전용 Git 도구로 커밋된 변경만 읽고, 코드를 만든 대화는 보지 않아요. 질문은 파일·함수 이름이 아니라 동작, 실패 모드, 불변식을 다뤄요. 코드를 보거나 에이전트에게 보여 달라고 하면서 답해도 되는 오픈북이에요.

예시(백그라운드 작업 큐를 추가하는 변경):

질문: 워커가 작업을 커밋했지만 확인(ack) 전에 죽었어요. 재전달되면 작업이 두 번 실행될 수 있나요? 답: 아니요, 커밋할 때 완료 표시가 돼요. Sphinx: 아니에요. 완료 표시는 커밋 뒤의 ack가 해요. 그 사이에 죽으면 미확인 상태라 큐가 다시 보내고 두 번 실행돼요.

알아 둘 점

• 요구 사항: Node.js 22.19 이상, Git, macOS·Linux·WSL(네이티브 Windows 미지원).
• 이 컴퓨터의 모든 저장소에 적용돼요. sphinx install이 전역 core.hooksPath를 설정하고, 기존 훅은 먼저 실행돼요. 설치 직후 모든 저장소의 main·master 푸시가 검사 대상이고, sphinx init으로 저장소별 조정이 돼요.
• Git을 막아요. 통과·일시정지·건너뛰기 전까지 최대 25분 기다리고, 에이전트 셸은 더 빨리 타임아웃될 수 있어요.
• 리뷰어 모델 계정이 필요해요. 로그인된 Codex·Claude Code CLI(요금제 사용량 사용), OpenRouter API 키(무료 모델에도 필요), OpenAI 호환 엔드포인트 중 하나예요. Sphinx 자체 계정이나 호스팅 서비스는 없어요.
• 코드가 밖으로 나가요. 리뷰어 제공자는 변경 코드와 관련 파일, 답변, .sphinxcontext.md를 받아요. 무시된 파일, .env, 개인 키, 흔한 자격 증명 파일은 기본 제외이고 .sphinxignore로 더할 수 있지만, 일반 소스에 붙여 넣은 비밀은 못 걸러요.
• 모델 호출 상한이 기본으로 없어요. 검사 한 번에 보통 5–8회 요청과 답변당 약 1회가 들고, 유료 제공자라면 지출 한도를 걸라고 권해요.
• 보안 게이트가 아니라 연습이에요. 로컬 접근 권한이 있으면 에이전트를 포함해 누구나 훅을 우회할 수 있고, 통과가 누가 코드를 썼는지나 혼자 이해했는지를 증명하지 않아요. 채점자도 LLM이라 틀릴 수 있어요.

설치

npm install -g sphinx-understand
sphinx install --yes --preset claude-economy --agents claude

안내형 설정은 쓰는 에이전트와 리뷰어를 묻고, Claude Code의 Haiku나 Codex의 GPT-6 Luna를 추천해요. Codex는 --preset codex-economy, 에이전트를 안 쓰면 --agents none이에요.