AI가 짠 코드가 이해되지 않을 때, Sphinx로 푸시 전 점검하기

AI가 구현한 변경을 사람이 예측하게 한다

parthh01/sphinx는 에이전트와 함께 개발하는 사람이 자신의 코드 변경을 이해했는지 묻는 도구다. 검사 대상인 Git 푸시를 잠시 멈추고, 변경이 어떻게 동작할지 질문한다. 코드를 만들었던 대화는 질문 모델에 전달하지 않는다.

문제는 함수 이름을 외웠는지보다 실패 상황에서 어떤 결과가 생기는지에 가깝다. 프로젝트가 제시한 예시는 작업 큐에서 처리를 끝낸 워커가 완료 응답을 보내기 전에 죽었을 때, 같은 작업이 다시 실행될 수 있는지를 묻는다. 이는 설명용 예시이며 모든 저장소에 같은 질문을 내는 방식은 아니다.

틀린 답에는 설명과 후속 문제가 이어진다. 코드를 보면서 답해도 되는 방식이므로 암기 시험과도 다르다. 구조 문서에 따르면 질문 모델은 변경 부분과 관련 소스·테스트를 읽고 근거를 마련한다. 완료 기록은 해당 변경과 목적지, 정책 등에 묶여 다시 확인된다.

설치는 전역 훅, 검사 조건은 저장소 정책이다

설치 범위는 현재 열어 놓은 프로젝트 하나보다 넓다. Sphinx 설치는 사용자 전역 Git 설정인 core.hooksPath를 설정한다. 기본적으로 여러 저장소에서 main이나 master로 보내는 푸시가 대상이 되며, 기존 훅은 먼저 실행되도록 연결한다.

저장소 정책에서는 브랜치, 원격 저장소, 검사 이벤트와 질문 깊이를 정할 수 있다. 푸시 검사의 브랜치 조건은 현재 로컬 브랜치 이름이 아니라 목적지 브랜치를 기준으로 판단한다.

따라서 작은 프로젝트에서 시험하더라도 설치 영향은 다른 저장소까지 살펴야 한다. 질문을 더 자세히 받고 싶은지와 어떤 Git 작업을 기다리게 할지는 별개의 설정이다.

질문창은 로컬이지만 코드 검토에는 모델이 필요하다

질문창을 내 컴퓨터에서 연다고 코드까지 항상 내 컴퓨터 안에만 머무는 것은 아니다. 선택한 검토 모델 제공자는 커밋의 변경 코드와 관련 파일, 사용자 답변, 프로젝트 설명을 받는다. 푸시 검사의 코드 근거는 작업 중인 파일이 아니라 Git 커밋에서 읽는다.

기본 제외 대상에는 환경 변수 파일과 개인 키, 흔한 자격 증명 파일이 들어간다. 프로젝트별 민감 경로는 .sphinxignore에 추가할 수 있다. 다만 이 규칙은 경로를 거르므로, 포함된 일반 소스 파일 안에 붙여 넣은 비밀 문자열까지 찾아내지는 않는다.

모델 호출 횟수에도 기본 상한이 없다. 선택적으로 호출 수를 제한할 수 있지만 그 수가 곧 결제 금액의 상한은 아니다. 팀이 도입할 때는 질문의 유용성뿐 아니라 어떤 파일을 보내고 어느 모델의 사용량을 쓰는지도 함께 정해야 한다.

GitHub 체크로 연결해도 통과의 뜻은 바뀌지 않는다

Sphinx의 핵심은 이해를 확인하는 연습이다. 로컬 접근 권한이 있는 사람이나 에이전트는 훅을 우회하거나 외부 도움을 받을 수 있고, 질문·채점 모델도 틀릴 수 있다. 통과를 코드에 오류가 없다는 판정으로 읽을 근거는 없다.

상세 설정 문서는 GitHub Action의 필수 설정과 브랜치 보호를 연결하는 방법을 제공한다. 동시에 상태는 푸시한 컴퓨터가 보고하는 값이며, 암호학적으로 이해도를 증명하는 장치가 아니라고 명시한다.

Sphinx를 도입할 이유는 개발자가 자신의 변경을 설명하는 시간을 확보하는 데 있다. 팀의 코드 검토와 테스트에 이 질문을 더할 수는 있다. 통과 표시 하나로 그 절차를 끝내는 것은 도구가 확인하는 범위를 넘어선다.

자주 묻는 질문