AI 어시스턴트가 버그 수정을 환각(Hallucinating)하지 않도록 만든 방법

커버: 자체 스택을 대상으로 실행한 실제 qa-probe 실행 화면, 요약 부분만 크롭됨 - 내부 제품 상세 정보는 비공개 처리됨.

우리는 현재 활발하게 데모가 진행 중인 SIEM인 LightShield를 구축하고 있습니다. 우리는 이 시스템의 대부분을 MCP를 통해 연결된 AI 코딩 어시스턴트와 페어 프로그래밍(pair-programming)하며 구축했습니다. 어시스턴트는 우리의 스택을 실행하고, 에러를 읽고, 스스로 코드를 패치했습니다. 소규모 팀에게 이는 초능력과도 같습니다. 하나의 엔드포인트(endpoint)가 실패하기 전까지는 말이죠.

우리가 계속해서 맞닥뜨렸던 루프는 다음과 같습니다. 라우트(route)가 500, 404 또는 빈 []를 반환합니다. 어시스턴트는 상태 코드(status code)를 보고 매우 자신만만하게 원인을 발표합니다. 그러고 나서 전혀 문제가 없었던 핸들러(handler)를 다시 작성합니다. 상태 코드는 원인이 아니며, 어시스턴트에게는 참고할 다른 정보가 없었기 때문입니다. 그래서 추측했고, 잘못 추측했으며, 그 결과 생성된 디프(diff)는 상황을 더 악화시켰습니다.

문제는 그 빈 []에 최소 6가지의 가능한 원인이 있었다는 점입니다:

데이터베이스가 비어 있음 (시드 데이터 없음)
피처 플래그(feature flag)가 꺼져 있음
프론트엔드와 백엔드 간의 컨트랙트 불일치 (contract mismatch)
첨부되지 않은 인증 토큰 (auth token)
428 precondition (사전 조건 미충족)
스키마 드리프트 (schema drift)

증상은 동일하지만, 해결책은 6가지로 달랐습니다. 우리는 이분법적 탐색(bisect)을 통해 실제 원인을 찾아낼 수 있었지만, AI는 할 수 없었습니다. AI에게는 그라운드 트루스(ground truth, 정답)가 없었기에, 스스로 하나를 만들어냈습니다.

그래서 우리는 qa-probe를 구축했습니다

qa-probe는 앱을 분석하고, 라이브 엔드포인트를 조사하며, 각 실패를 근본 원인(root cause)과 수정 힌트(fix hint)로 분류합니다. 세 가지 분리되고 캐싱된 단계로 구성됩니다:

qa-probe analyze   # 소스 파싱 + OpenAPI -> 라우트 그래프 생성
qa-probe probe     # 라이브 엔드포인트 호출 (HTTP/SSE/WS), 증거 기록
qa-probe report    # 근본 원인 분류 -> HTML / Markdown / JSON / AI-context
...

FastAPI, Express, Next.js, tRPC, GraphQL을 위한 어댑터(adapter)와 일반적인 폴백(fallback)을 갖추고 있어, 사용자가 일일이 목록을 작성할 필요 없이 라우트를 자동으로 발견합니다.

실제로 문제를 해결한 부분: 모든 결과는 반증 가능해야 한다 (every result is falsifiable)

각 결과는 증거(실제 요청, 제한된 응답 샘플, 타이밍), 약 25개 카테고리 중 하나로 분류된 근본 원인(root cause), 그리고 high, medium, none으로 보정된 신뢰도(confidence)를 포함합니다. 시스템이 판단할 수 없을 때는 허풍을 떠는 대신 none을 반환합니다. 신경망(neural network)도, 블랙박스(black box)도 아닙니다. 투명한 규칙과 엔드포인트별 통계 메모리(stat memory)를 사용하여, 왜 해당 판정에 도달했는지 항상 읽을 수 있습니다. 이를 사용하는 AI는 느낌(vibe)을 믿는 것이 아니라, 주장을 검증해야 합니다.

AI에게 입력했을 때 무엇이 변했는가

qa-probe mcp   # Claude, Cursor, 모든 MCP 클라이언트에 8개의 도구를 노출합니다

어시스턴트는 상태 코드(status code)를 바탕으로 추론하는 것을 멈추고, 증거를 바탕으로 추론하기 시작했습니다: "데이터베이스가 비어 있음, 높은 신뢰도, 이를 증명하는 응답은 다음과 같습니다." 어시스턴트는 핸들러(handler)를 다시 쓰는 대신 DB에 데이터를 심었습니다(seeded). 올바른 레이어(layer)를 수정했습니다. 추측은 기본적으로 중단되었습니다.

이는 우리가 더 빠르게 디버깅할 수 있도록 도왔습니다. 또한 AI에게 더 큰 도움이 되었습니다. 왜냐하면 AI의 성능은 당신이 제공하는 증거만큼만 발휘되기 때문이며, "엔드포인트가 실패하고 있다"는 것은 증거가 아니기 때문입니다.

파이프라인에 도입된 후 추가로 포착한 것들

보안 점검 (읽기 전용) - 인증 우회(auth-bypass), 권한 상승(privilege-escalation), 개인정보(PII) 유출
응답 단언(response assertions)을 통한 로직 버그
엔드포인트가 자체 이력에서 벗어나는 것을 플래그로 표시하는 적응형 베이스라인(adaptive baselines)
쓰기 흐름(Write-flows) - 보장된 정리(cleanup)가 포함된 선택적(opt-in) CRUD 체인, 기본값은 비활성화(off by default)
피드백 루프 - 판정에 한 번 라벨을 붙이면 기억함

활용 분야

단순히 숫자만 보여주는 것이 아니라 이유와 함께 빌드를 실패시키는 CI 게이트(CI gate)
스테이징(staging) 환경에 대한 릴리스 전 스모크 테스트(smoke test)
AI 어시스턴트가 환각(hallucinating)하는 대신 디버깅을 수행하도록 지정하는 대상

시도하고, 깨뜨리고, 기여하세요

초기 단계이며 오픈 소스입니다. 도움을 주는 가장 빠른 방법은:

자신의 API에 직접 실행해 보고 발견한 내용을 알려주세요 - 특히 근본 원인(root cause)을 잘못 파악했을 경우 더욱 그렇습니다. 증거가 첨부된 잘못된 판정은 제가 받을 수 있는 가장 유용한 버그 리포트입니다. 분류기(classifier)는 단순히 규칙(rules)에 기반하므로, 저는 그 규칙을 수정할 수 있기 때문입니다.
문제가 있거나 혼란스러운 부분이 있다면 이슈(issue)를 등록해 주세요: https://github.com/LS-SIEM-LLP/qa-probe/issues
PR(Pull Request)을 보내주세요. 좋은 첫 기여는 새로운 프레임워크 어댑터(Hono, NestJS, Fastify), 새로운 근본 원인 규칙(root-cause rules), 그리고 새로운 MCP 도구들입니다. 어댑터 및 규칙 인터페이스는 CONTRIBUTING.md에 문서화되어 있으며, 모든 PR에는 체크리스트가 포함되어 있습니다.

한 가지 정리해 드릴 사항이 있습니다: 기여는 서명 기반(DCO, Developer Certificate of Origin)으로 이루어집니다. 프로젝트의 라이선스를 깨끗하게 유지할 수 있도록 git commit -s를 사용하여 커밋해 주세요. 이것이 유일하게 거쳐야 할 관문입니다.

가져오기

저희 자신을 위해 이 도구를 만들었습니다. 충분히 잘 작동했기에 코드를 정리하여 Apache-2.0 라이선스로 공개했습니다.

npm i -g qa-probe

GitHub: https://github.com/LS-SIEM-LLP/qa-probe
npm: https://www.npmjs.com/package/qa-probe

LS-SIEM LLP에서 제작했습니다. 만약 여러분의 API에 직접 실행해 보신다면, 무엇을 발견했는지 진심으로 알고 싶습니다. 그러한 피드백이 규칙을 더욱 날카롭게 만드는 방법입니다.