dev.to

The Data Was Public. The Agent Path Wasn't. So His Mock Became My Documentation.

데이터는 공개됐지만 에이전트 경로는 아니었습니다 — 기여자의 목업이 문서가 된 과정

Sanity 데이터셋은 인증 없이 조회할 수 있지만, 에이전트가 쓰는 Context MCP 경로에는 조직 토큰이 필요했습니다. 접근할 수 없는 실행 경로를 대신해 기여자가 만든 목업 스키마가 도구 설명에 들어가면서 실제 데이터와 다른 문서가 될 뻔한 과정을 짚고, 실제 스키마에서 생성한 계약 픽스처를 대안으로 제안합니다.

AI 요약

Sanity 데이터셋은 API 키나 계정 없이 조회할 수 있지만, 에이전트가 실제로 사용하는 경로는 공개되지 않았습니다. 글쓴이는 공개 쿼리 API에서 문서 120개를 확인한 뒤, 같은 데이터 소스를 가리키는 Context MCP 엔드포인트를 호출해 401 응답을 받습니다. MCP 경로에는 프로젝트 토큰이 아니라 조직 API 토큰이 필요합니다. 저장소를 복제한 외부 기여자 Pouya에게 조직 접근 권한을 주지 않았으므로, 그는 README에 적힌 데이터를 읽을 수는 있어도 에이전트가 쓰는 경로를 실행할 수 없었습니다.

공개 데이터와 실행 경로의 차이

첫 외부 기여자인 Pouya는 에이전트가 GROQ 쿼리를 만들 때 문서 유형과 쿼리 문법을 잘못 추측한다고 진단했습니다. 모델이 실제 데이터 구조를 참고하도록 도구 설명에 스키마와 예제를 넣는 PR을 보냈습니다. 방향은 합리적이었지만, 글쓴이가 PR의 예제를 실제 데이터에 실행하자 오류가 드러났습니다.

claim 예제에는 결과 선택자 [0] 뒤에 불필요한 점이 있어 HTTP 400 오류가 났습니다. 점을 제거한 쿼리는 정상 동작했고, claim-ledger-population 문서에서 status는 standing, expiryStatus는 no_expiry_set을 반환했습니다. patch 예제는 findingRef라는 필드를 찾았지만 실제 필드는 배열인 findings였고, ID 대소문자도 달랐습니다. finding-B1을 사용해 findings[]._ref를 조회하자 sha는 dd1a654, inMain은 false로 나왔습니다.

목업 스키마가 문서가 될 때

PR은 예제 쿼리뿐 아니라 도구 설명에 넣을 스키마도 잘못 적었습니다. claim.subject는 실제 데이터에 없고, claim.statement는 text였습니다. finding.finders 대신 foundBy가 있었으며, patch.findingRef 대신 findings 배열을 사용했습니다. patch.commitHash에 해당하는 실제 필드는 sha였습니다. verifiedReceipts도 단순한 이름 차이가 아닙니다. 기록에 따라 commentId 또는 commentIds가 있으며, 댓글 ID만으로는 해당 댓글이 검증됐다고 말할 수 없습니다.

Pouya는 실패 원인을 설명하며, 당시 Context MCP 설정 전체를 재현할 수 없어 401을 받았고 LM Studio에서 오프라인 목업 스키마로 쿼리 생성 로직을 시험했다고 밝혔습니다. 그는 모델이 이해하기 쉽도록 commitHash, verifiedReceipts, finders처럼 의미가 분명한 이름을 골랐습니다. 설계 관점에서는 더 읽기 좋은 이름이지만, 실제 스키마와 다르다는 사실을 모른 채 도구 설명에 들어가면 모델은 이를 권위 있는 정보로 받아들입니다. 실행 중 모델이 추측한 내용은 추측으로 드러나지만, 문서에 적힌 잘못된 스키마는 공식 계약처럼 보입니다.

재현 가능한 계약을 제공하기

글쓴이는 README가 공개 데이터 조회 방법은 안내하면서 에이전트의 실제 경로는 재현하지 못했다고 지적합니다. 기여자가 접근할 수 없는 경계를 만났을 때 목업을 만드는 일 자체가 문제는 아닙니다. 저장소가 기준이 될 목업을 제공하지 않아 기여자가 계약까지 직접 설계해야 했다는 점이 문제입니다. 글쓴이는 실제 스키마에서 생성해 저장소에 넣는 계약 픽스처를 제안합니다. 흐름을 운영 스키마에서 생성된 계약 픽스처로, 다시 기여자 테스트 환경으로 이어지게 하면 조직 자격 증명을 공개하지 않고도 같은 인터페이스를 검증할 수 있습니다.

이 문제는 Sanity나 에이전트에만 국한되지 않습니다. 외부 기여자가 실행할 수 없는 비공개 API, 결제 샌드박스, 내부 큐, OAuth 서비스도 같은 상황을 만들 수 있습니다. 글쓴이는 저장소를 복제한 사람이 README에 적힌 경로가 아니라 시스템이 실제로 쓰는 경로를 실행할 수 있는지 확인하라고 제안합니다. PR은 두 차례 수정 끝에 병합됐으며, 세 커밋에 걸쳐 파일 한 개를 수정했습니다. 작업은 약 36시간이 걸렸습니다.

dev.to 반응

  • @octyn — 여기서 유용한 해결책은 생성된 픽스처입니다. 스키마 버전을 눈에 보이게 하고, 공개된 계약과 더는 맞지 않으면 기여자 테스트가 실패하게 하겠습니다. 그렇지 않으면 오늘의 기준 픽스처가 내일은 아주 그럴듯한 오래된 목업이 됩니다. 단수형 commentId와 복수형 commentIds 사례는 회귀 테스트에 좋습니다. 깔끔한 이름으로 바꾸면 실제 차이가 조용히 사라질 수 있기 때문입니다.

원문: dev.to / 번역·요약: Trawling

원문 보기 ↗토론 보기 ↗