API 버그 보고서에 호출자(Caller) 정보가 누락된 경우

팀원이 실패하는 요청을 AI 채팅창에 붙여넣습니다. 제안된 수정 사항은 합리적으로 보입니다. 심지어 로컬에서는 작동합니다. 하지만 스테이징 환경에서는 여전히 실패합니다.

프롬프트에 코드를 더 추가하기 전에, 인계 과정에서 사라진 것들—호출자(caller), 환경(environment), 그리고 시작 상태(starting state)—를 확인해 보세요.

API 요청은 재현의 일부일 뿐입니다. 유용한 디버깅 인계는 실패하게 만든 조건을 보존해야 합니다.

버그 보고서에서 누락된 줄

워크스페이스 소유자가 생성하는 송장(invoice) 엔드포인트를 상상해 보세요. 워크스페이스 소유자가 보낸 요청은 송장을 반환합니다. 하지만 멤버가 같은 요청을 보내면 404 오류를 반환합니다. 누군가 AI에게 “누락된 송장을 수정하라”고 요청합니다.

여기에는 적어도 세 가지 다른 설명이 있습니다. 해당 환경에 송장이 존재하지 않거나, 다른 워크스페이스의 것일 수도 있고, 아니면 API가 호출자가 접근할 수 없는 리소스를 의도적으로 숨기고 있을 수도 있습니다. 응답 스키마를 변경한다고 해서 이들을 구별할 수는 없습니다.

수정 사항을 제안하기 전에 관찰된 내용을 기록하세요:

Operation: getInvoice
Environment: staging, build 8f2c1a
Caller: member of workspace A (no credentials attached)
...

이것은 가상의 디버깅 메모이며 Powerduck 설정 형식은 아닙니다. 예상 결과는 의도적으로 질문입니다. 정책이 불분명할 때 “200을 반환하도록 만들어라”는 임의로 만들 수 있는 안전하지 않은 요구사항입니다.

AI에게 제한된 조사를 제공하기

더 나은 프롬프트는 다음과 같습니다: “운영 계약(operation contract)과 이러한 관찰 내용을 사용하여 이 차이점을 설명해 주세요. 확인된 사실과 가설을 분리하세요. 가설들을 구별하는 가장 작은 추가 검사 항목을 식별하세요.”

관련 요청 및 응답 스키마, 정제된 응답, 그리고 계약 개정 사항을 포함하세요. 구현 컨텍스트가 가능하다면, 실제로 요청을 처리하는 권한 부여 경로(authorization path)도 포함하세요. 유용한 증거를 관련 없는 소스 파일 아래에 묻지 마세요.

자격 증명(credentials)은 전달 과정에서 제외하세요. 가능하다면 합성된 고정값 ID(synthetic fixture IDs)와 역할 설명(role descriptions)을 사용하세요. '작업 공간 A' 대 '작업 공간 B'와 같은 구분을 유지하는 것이 중요합니다. 모든 식별자를 동일한 플레이스홀더로 대체하면 버그의 원인을 지울 수 있습니다.

사람과 에이전트를 동일한 실험에 참여시키기

만약 에이전트가 MCP를 통해 작업을 호출한다면, 그 환경과 호출자(caller)의 신원도 확인해야 합니다. 같은 작업 이름이라고 해서 에이전트가 개발자와 동일한 조건을 테스트하고 있다는 것을 보장하지 않습니다.

제안된 수정 사항을 받아들이기 전에 이러한 비교를 명시적으로 수행하세요. 관리자 자격 증명을 가진 에이전트는 권한 관련 버그(authorization bug)가 사라진 것처럼 보이게 만들 수 있습니다.

Powerduck에서는 AI 기반 디버깅, MCP 도구, 문서화, 시나리오 테스트를 연결하는 로컬 API 계약을 중심으로 구축합니다. 이 공유된 기반은 논의 중인 작업이 일관되게 유지되도록 돕습니다. 환경, 신원, 그리고 테스트 고정값(test fixtures)은 여전히 의도적으로 선택되어야 합니다.

답변을 지속적인 검사로 전환하기

의도된 정책이 확인되면 두 가지 사례를 저장하세요: 허용된 호출자와 금지된 호출자. 각각에 대해 문서화된 결과를 단언(assert)하세요. 일회성 고정값(disposable fixtures)을 사용하고 응답이 다른 작업 공간의 데이터를 노출하지 않는지 검증하세요.

그런 다음 동작을 설명하는 데 실패한 부분이 있다면 문서를 업데이트하세요. 구현이 잘못되었다면, 그것을 수정하고 두 사례를 다시 실행하세요. 우연한 응답에 맞추기 위해서만 계약(contract)을 재작성하지 마세요.

가장 좋은 디버깅 전달 과정은 가장 긴 프롬프트가 아닙니다. 이는 다른 사람이 누가 무엇을, 어디서, 어떤 조건 하에서 호출했는지 추측할 필요 없이 반복할 수 있는 작은 실험입니다.