검증 가능한 가설로 디버깅하기

수정을 제안하기 전에 실패를 설명하세요

유용한 디버깅 요청에는 기대 동작, 관찰한 동작, 영향 범위가 들어갑니다. 버전, 관련 입력, 오류도 포함하세요. 로그를 AI 도구에 제공하기 전에 자격 증명과 비공개 기록을 제거하세요.

‘내보내기가 고장 났다’는 설명만으로는 조사 방향을 잡기 어렵습니다. 더 나은 설명은 다음과 같습니다. ‘로컬에서는 내보내기가 성공합니다. 스테이징에서는 최근 배포 후 같은 관리자의 요청이 403을 반환합니다. 다른 경로는 여전히 정상 작동합니다.’

이 설명으로 원인이 확정되지는 않습니다. 조사의 방향을 정하는 데 도움이 되는 차이를 제시합니다.

여러 설명의 가능성을 열어 두세요

에이전트에게 가능한 원인 몇 가지와 각 원인을 뒷받침하는 증거를 요청하세요. 처음 나온 그럴듯한 설명을 바로 확정하도록 요청하지 마세요.

이 가상의 내보내기 실패에서는 서비스 ID의 권한 누락, 역할 매핑 변경, 잘못된 환경으로 전송된 요청 등이 원인일 수 있습니다. 각 설명이 맞을 때 나타날 증거는 서로 다릅니다.

이 표는 조사의 출발점입니다. 403 응답은 여러 계층에서 발생할 수 있습니다. 애플리케이션의 인가 처리에 실패했다고 가정하기 전에 어떤 구성 요소가 응답을 생성했는지 확인하세요.

안전하게 관찰할 방법을 선택하세요

적은 비용으로 설명을 구분할 수 있는 관찰부터 시작하세요. 배포된 버전과 비밀 정보가 아닌 구성을 비교하세요. 관련 오류와 요청 식별자를 살펴보세요. 가능하면 허가된 테스트 환경에서 문제를 재현하세요.

오류가 사라지는지 확인하려고 광범위한 권한을 부여하지 마세요. 보안 경계가 바뀌고 실제로 누락된 권한이 무엇인지 가려질 수 있습니다. 민감한 정보를 제거한 오류와 요청 경로만으로 충분하다면 전체 프로덕션 로그를 모델에 붙여 넣지 마세요.

각 가설의 가능성을 낮출 증거가 무엇인지 명시하세요. 그러면 에이전트가 첫 답을 고수하는 대신 설명을 수정하는 데 도움이 됩니다.

한 번에 하나의 원인을 수정하세요

증거로 유력한 원인을 찾은 뒤에는 그 원인에 집중해 수정하세요. 권한 변경, 라이브러리 업그레이드, 핸들러 재작성을 한꺼번에 하지 마세요. 증상이 사라져도 어떤 변경이 영향을 줬는지 알 수 없게 됩니다.

처음 실패했던 조건을 검증하세요. 인접한 경계도 확인하세요. 관리자의 접근 문제를 수정했다면 권한 없는 사용자의 접근은 여전히 거부되는지 확인하세요.

반복되는 결함에는 이를 탐지할 수 있는 계층에 회귀 검사를 추가하세요. 단위 테스트로 모든 배포 구성 오류를 탐지할 수는 없습니다. 일부 실패에는 통합 검사나 통제된 배포 후 검증이 필요합니다.

새로운 증거 없이 시도를 반복하지 마세요

에이전트는 여러 수정안을 만들 수 있습니다. 시도 횟수가 늘어난다고 진단이 반드시 나아지는 것은 아닙니다. 같은 실패가 반복되면 다음 시도에서 어떤 새로운 관찰을 얻을 수 있는지 물어보세요.

불확실한 조사에는 시간이나 시도 횟수의 한도를 정하세요. 한도에 도달하면 현재 증거, 배제한 가설, 해결하지 못한 질문을 보고하세요. 다른 사람이 같은 실험을 반복하지 않고 조사를 이어갈 수 있습니다.

복구 후에는 원인과 함께 문제가 해당 환경에 도달하도록 허용한 조건을 기록하세요. 수정은 당장의 결함을 제거합니다. 유용한 후속 조치는 같은 실패가 재발할 가능성을 줄입니다.