Sphinx: AI가 짠 코드를 push하기 전에 이해했는지 퀴즈로 확인하는 Git hook

Who Should Read

코딩 에이전트가 쓴 코드를 제대로 읽지 않고 push하게 되는 것이 걱정인 개발자

Core Mechanics

• push 직전에 질문을 던진다
  • Sphinx는 에이전트 개발용 Git hook이다.
  • 코드가 나가기 전에 그 코드가 실제로 뭘 하는지 묻는다.
• 질문은 diff에서 나온다
  • 채팅 내용을 보지 못한 리뷰어 모델이 diff만 읽고 질문한다.
  • 문제가 생겼을 때 어떻게 동작하는지를 묻는다.
• 틀리면 이유를 알려 주고 새 시나리오로 다시 묻는다
  • 맞히면 push가 이어진다.
  • 예시는 Stripe 웹훅 재시도 시 charge() 실패 상황이었다.
• 모델과 에이전트를 가리지 않는다
  • 기존 코딩 에이전트, OpenRouter, OpenAI 호환 엔드포인트에서 돌아간다.
  • Codex, Claude Code, Cursor, OpenCode, Pi 또는 순수 Git과 함께 쓴다.
• 프라이버시와 우회 수단을 둔다
  • 답변은 코딩 에이전트에 전달되지 않고 .env와 키 파일은 열지 않는다.
  • sphinx yolo로 통과시킬 수 있고 건너뛴 기록은 로그에 남는다.

Community Reactions

• PR 설명을 직접 쓰는 방식이 비슷한 효과라는 경험
  • why, what, how를 나눠 쓰다 보면 LLM이 내린 숨은 결정과 버그를 발견한다는 의견이다.
• 퀴즈 스킬을 직접 만들어 써 봤다는 경험
  • 커밋이 아니라 PR 또는 브랜치 전체를 기준으로 퀴즈를 내게 했더니 질문이 좋았다는 반응이다.
  • 1500줄 PR 리뷰에 도움이 되지만 잘못된 엔드포인트 호출 같은 나쁜 결정은 못 잡는다는 경험도 있다.
• 코드 작성 전에 걸어야 한다는 의견
  • 객관식은 이해 없이 찍게 만든다는 구현 경험이 함께 나왔다.
• 만들어 써 보다 포기했다는 경험
  • 마법처럼 일하길 기대하는 도구에게 질문받는 게 싫어 그만뒀다는 의견이다.
  • 확인 피로가 쌓이고 결국 에이전트가 대신 답할 거라는 회의론도 있다.
• PR 제출 전에 걸면 좋겠다는 의견
  • 다른 사람의 시간을 쓰기 전에 걸러 주면 낭비가 줄 것이라는 주장이다.
  • OSS 메인테이너에게 유용하겠다는 반응도 있다.

How to Apply

• 오늘 내 브랜치로 퀴즈를 받아 보기
  • 아래 프롬프트를 Claude나 Claude Code에 붙여 diff와 함께 실행하라.
  • 설치 전에 질문 품질이 쓸 만한지 먼저 확인하라.
• 보호 브랜치 push에만 Sphinx를 걸기
  • npm install -g sphinx-understand 후 sphinx install을 실행하라.
  • 리뷰할 모델을 고르고 main에 push해 흐름을 확인하라.
• PR 올리기 직전 셀프 퀴즈를 팀 규칙으로 만들기
  • PR 템플릿에 why, what, how 세 칸을 넣어라.
  • how는 LLM 도움 없이 본인이 직접 쓰게 하라.

Try It

# Claude 또는 Claude Code에 붙여넣기 (Sphinx 방식의 간이 버전)

너는 이 대화를 본 적 없는 코드 리뷰어다. 아래 diff만 읽고 퀴즈를 낸다.
규칙:
- 한 번에 질문 하나만 한다.
- 정상 동작이 아니라 실패·재시도·경계 상황에서 코드가 어떻게 되는지 묻는다.
- 내가 답하면 맞는지 판단하고, 틀리면 이유를 설명한 뒤 새 시나리오로 다시 묻는다.
- 3문제를 연속으로 맞히면 "Understood"라고 말한다.

{{git diff 결과}}

이어서 해 볼 것: 답을 일부러 틀려 보고 설명이 납득되는지 확인하라.

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://sphinx-six-theta.vercel.app/
• https://substack.com/@jeffksmithjr/p-195763168