엔드포인트 75개는 다 살아 있는데 봉투가 틀렸다 — 에이전트용 지면 3개 전수 대조

칼라톤에는 사람이 읽는 지면과 기계가 읽는 지면이 따로 있다. 사람 쪽은 홈과 각 서비스 페이지이고, 검색엔진 쪽은 sitemap.xml과 robots.txt다. 그리고 2025년 이후 생긴 세 번째 독자층 — AI 에이전트 — 을 위해 우리는 파일 셋을 더 올려 두었다. /llms.txt(요약 카탈로그), /llms-full.txt(상세 레퍼런스), /.well-known/ai-plugin.json(기계가 읽는 서비스·인증 매니페스트)이다.

문제는 이 셋이 사람이 손으로 쓴 문서라는 점이다. 사이트맵은 리포트 생성기가 찍고, 페이지는 코드에서 나오지만, "우리 서비스에는 이런 엔드포인트가 있습니다"라는 문장은 운영자가 타자로 적는다. 손으로 적은 카탈로그는 반드시 낡는다. 그래서 질문은 하나다. 에이전트에게 보여 주는 지면은 사람 지면과, 그리고 실제 코드와 같은 것을 말하는가?

이번에는 그 셋이 나열한 URL·백엔드·엔드포인트를 전부 꺼내 ① 저장소의 실제 파일트리 ② sitemap.xml ③ 각 백엔드의 라우트 코드와 openapi.yaml ④ 라이브 HTTP 응답, 이렇게 네 군데와 대조했다. 결과를 미리 말하면 뼈대는 거의 다 맞았고, 틀린 자리는 아무도 안 볼 것 같은 한 줄이었다.

방법 — 세 지면이 적은 것을 세고, 네 군데와 맞춘다

모집단은 그 세 파일이다. 크기와 적어 둔 분량부터 보자. 대조군으로 같은 저장소의 사람·크롤러 지면 둘을 함께 올린다.

지면바이트줄사람 페이지 링크백엔드 호스트엔드포인트
llms.txt5,1657810624
llms-full.txt9,3091450775
.well-known/ai-plugin.json3,452—160
(대조) sitemap.xml24,8058261500
(대조) robots.txt1,66656000

세 지면의 성격이 수치로 갈린다. llms.txt는 사람 페이지 10개를 링크하는 안내문에 가깝고, llms-full.txt는 사람 페이지를 하나도 링크하지 않는 대신 엔드포인트 75개를 늘어놓는 API 레퍼런스다(도메인 주소 두 개만 적는다). ai-plugin.json은 엔드포인트를 적지 않고 서비스 베이스 URL과 라이선스 정책만 담은 매니페스트다. 세 파일이 각각 다른 일을 하고 있고, 같은 사실을 세 번 적는 자리는 백엔드 호스트 목록뿐이다. 바로 그 자리가 뒤에서 가장 많이 어긋난다.

엔드포인트 75개는 두 llms 파일의 합집합이다(llms.txt의 24개가 llms-full.txt의 75개에 모두 포함된다). 라우트 코드 대조는 각 백엔드의 router.get/post 선언을 마운트 접두와 합쳐 풀 경로로 복원한 뒤 맞췄고, 같은 수를 서로 다른 두 방식으로 세어 일치한 값만 적었다. 라이브 조회는 전부 두 차례 돌려 상태 코드와 success 값이 두 번 같았던 것만 쓴다.

결과 ① — 엔드포인트 75개 중 코드에 없는 것은 0개였다

가장 걱정했던 항목이 가장 깨끗했다. 손으로 적은 엔드포인트 75개를 라우트 코드와 맞추니 실재하지 않는 경로가 0개다. 두 방식(마운트 복원 파서, 상대 경로 그렙)이 처음부터 일치했다.

대조 항목대상일치어긋남
라우트 코드에 실재하는가75750
그 서비스의 openapi.yaml에도 있는가75714
경로 변수 이름이 라우트와 같은가24222
공개 선언 엔드포인트의 라이브 응답(2회)33330

두 번째 줄의 4개는 전부 스펙 쪽이 모자란 경우였고 카탈로그가 틀린 경우가 아니다. /gallery/public_images는 코어 라우트 코드에 있는데 코어 openapi.yaml에 없고, /openapi.yaml과 /docs 두 개는 모든 백엔드가 실제로 서비스하면서 11개 스펙 중 0개가 자기 자신을 문서화하지 않는다. 두 llms 파일이 "모든 백엔드가 <base>/openapi.yaml과 <base>/docs를 제공한다"고 약속한 것은 사실인데, 그 약속이 스펙 안에서는 어디에도 적혀 있지 않다. 참고로 /health는 11개 스펙 중 10개에 있다(코어만 없다).

세 번째 줄의 2개는 경로 변수의 이름만 다르다. llms 파일은 /lotto/ticket_captures/{draw_no}라 적었지만 라우트와 스펙은 둘 다 target_draw_no이고, 숏폼 스튜디오 조회는 카탈로그가 {season_number}, 라우트는 :n이다. 위치 인자라서 에이전트가 값을 끼워 호출하면 그대로 작동한다 — 고장은 아니고 어긋남이다.

결과 ② — 라이브 33개 전부 200, 선언한 동작도 그대로였다

세 지면이 "키 없이 읽을 수 있다"고 선언한 공개 엔드포인트를 실제로 호출했다. 두 차례 모두 결과가 같았다.

서비스조회2004xx·5xx특이사항
로또770/health만 success 키 없음
유머550—
트레이딩990랭크 2종은 빈 배열
홀짝(마인드게임)550—
커플매칭(코어 경유)220구 경로로 안내 — 결과 ③
숏폼550/openapi.yaml·/docs 포함
합계333302회 조회 결과 동일

선언된 동작도 맞았다. llms.txt는 숏폼의 lane 매개변수를 두고 "제품 라인 넷(general·bible·bible_en·buddhist), 기본값 general, 시즌 번호는 레인 안에서만 유일해서 남의 레인 번호를 물으면 404"라고 적어 두었다. 네 값 모두 200, 없는 레인 값은 400, 레인을 빼면 응답이 general, 그리고 일반 레인에 없는 시즌 6번과 30번은 404인데 같은 번호가 성경 레인에서는 200이었다. 네 줄짜리 설명이 네 번 다 맞은 셈이다. 레인별 공개 시즌 수는 일반 8 · 성경 56 · 영문 성경 56 · 법의 바다 26이었다.

Accept-Language 안내도 실측했다. "ko 또는 en을 보내라, /lotto/stats는 현지화된다"는 문장대로 두 헤더의 응답 본문이 서로 달랐고(한글 토큰 26개 대 2개) 응답 해시도 갈렸다. 반면 트레이딩의 /trading/rank/orders·/trading/rank/snapshots 두 개는 비-SCALP 시즌 둘(시즌 1 VIRTUAL · 시즌 2 VIRTUAL_RANK) 모두에서 200과 함께 빈 배열을 돌려준다. 죽은 경로는 아니지만 에이전트가 이 주소에서 가져갈 것은 없다.

결과 ③ — 가동 중인 백엔드 11개 중 4개는 세 지면 어디에도 없다

여기서부터가 어긋난 쪽이다. 프런트엔드 설정(js/config.js)에 들어 있는 라이브 백엔드 주소는 11개인데, 세 지면이 이름을 적어 준 것은 많아야 7개다.

백엔드llms.txtllms-full.txtai-plugin.json비고
로또OOO셋 다
유머OOO셋 다
트레이딩OOO셋 다
홀짝(마인드게임)OOO셋 다
이미지편집OOO셋 다
코어(갤러리·결제)—OO둘
숏폼OO—매니페스트 누락
커플매칭———구 경로로만 안내
운영 관리(어드민)———없음
진지(게임)———없음
롱폼———없음
합계(11)676합집합 7

반대 방향은 깨끗하다. 세 지면이 적은 호스트 중 설정에 없는 것은 0개다 — 죽은 주소를 안내하지는 않는다. 누락만 있고 유령은 없다는 뜻이고, 손으로 쓴 카탈로그에서는 이쪽이 훨씬 다행인 모양이다.

커플매칭은 조금 다른 종류의 어긋남이다. 세 지면 모두 커플매칭을 설명하면서 "코어 백엔드의 /get_seasons로 읽으라"고 안내하는데, 커플매칭은 전용 백엔드로 독립한 모듈이고 실제 커플매칭 페이지는 그 전용 주소의 /matching/seasons를 호출한다. 구 경로는 이중 운영용으로 아직 코어에 남아 있어서 호출하면 200을 돌려주지만(위 표에서 확인했다), 에이전트는 지금 곧 걷힐 폴백 경로를 정식 입구로 안내받고 있다. ai-plugin.json의 비대칭도 같은 뿌리다 — 그 파일의 services에는 베이스 URL 6개가, service_notes에는 설명 5개가 있는데 겹치는 것은 4개뿐이다. matching은 설명만 있고 주소가 없으며, backend·lotto는 주소만 있고 설명이 없다.

인물생성은 전용 백엔드가 없고 코어가 서비스하므로 위 표에는 줄이 없다. 그런데 모듈 단위로 보면 누락의 규모가 가장 크다. 공개 시즌 리포트 국문 182편 가운데 152편이 인물 모듈이라 다섯 모듈 중 가장 큰데도, 세 지면에 Character라는 낱말이 나오는 횟수는 llms-full.txt 단 1회이고, 그마저 숏폼 출연진을 설명하는 줄 안의 ‘character season link’라는 구절이다. 그러면서 코어 스펙에는 인물 공개 엔드포인트 4개(/get_character_seasons, /get_character_season_detail/{n}, /get_character_sheet/{n}, /get_person_appearances/{id})가 문서화되어 있고, 네 개 모두 두 차례 조회에서 200을 돌려줬다. 작동하는 공개 API 4개가 에이전트 카탈로그에만 없다.

결과 ④ — 두 파일이 선언한 응답 봉투는, 29개 응답 중 0개에 있었다

이 글에서 유일하게 "틀렸다"고 쓸 수 있는 항목이다. llms.txt는 "응답은 JSON: { success, data, ... }", llms-full.txt는 "공통 봉투: { "success": boolean, "data": ..., "message"?, "error"? }"라고 적는다. 실제 응답 29개를 파싱해 최상위 키를 셌다.

최상위 키29개 응답 중선언
success28일치(/health만 예외)
data0어긋남
엔드포인트별 고유 키29선언 없음

본문은 data가 아니라 그 엔드포인트만의 이름을 쓴다. 회차 목록은 results, 최신 회차는 result, 통계는 stats, 시즌 목록은 seasons, 리더보드는 leaderboard, 캔들은 candles30m과 candles1m… 이렇게 서로 다른 키 이름 67가지가 나왔다(총 84칸). 그중 57가지는 딱 한 엔드포인트에만 등장한다. 두 엔드포인트 이상에서 공유되는 이름은 season(6회)·seasons(5회)를 포함해 10가지뿐이다.

이 한 줄이 왜 중요한가. 사람은 "{success, data} 꼴"이라고 읽고 응답을 열어 본 다음 키 이름을 고쳐 쓴다. 에이전트는 문서를 믿고 response.data를 읽는 코드를 바로 쓴다. 우리 지면에서 가장 기계적으로 소비될 문장이, 유일하게 사실이 아닌 문장이었다.

결과 ⑤ — 페이지 목록은 사이트맵의 부분집합이고, 주소 모양은 사이트맵보다 낫다

사람 페이지 쪽은 포함 관계가 깔끔했다. 저장소 최상위 HTML 페이지는 38개, 사이트맵에 오른 페이지는 15개, llms.txt가 링크한 페이지는 10개다.

집합편수내용
파일트리 최상위 페이지38관리자 전용·로그인·결제·인증 파일 포함
사이트맵 페이지15공개 페이지만
llms.txt 페이지 링크10기능 6 + 안내 4
사이트맵에 있고 llms.txt에 없음5홈 · 회사소개 · 인물생성 · 영문 약관 2
llms.txt에 있고 사이트맵에 없음0—
파일로 존재하지 않는 선언 URL1/openapi.json(라이브 404, 2회)

딱 하나 죽은 주소가 /openapi.json이다. 세 지면 중 둘이 이 주소를 적는데(llms.txt의 'Optional' 절, ai-plugin.json의 api.url 필드) 둘 다 "(planned)"라고 정직하게 달아 두었고, 라이브 조회는 두 번 다 404였다. 다만 ai-plugin.json의 api.url은 매니페스트 규격에서 에이전트가 스펙을 가져가려고 바로 받는 자리라서, 괄호 안의 "planned"를 읽을 파서는 많지 않다.

예상 밖의 소득도 있었다. 주소 모양은 에이전트 지면이 사람 지면보다 낫다. llms.txt의 페이지 링크 10개는 전부 확장자 없는 주소(/humor)이고 10개 모두 리다이렉트 없이 바로 200이다. 반면 사이트맵 162개 중 145개는 .html로 끝나 확장자 없는 주소로 308 리다이렉트된다(표본 조회 3건 모두 308). 이건 사이트맵 URL 전수 대조에서 143개로 셌던 바로 그 수이고, 그 뒤 아티클 2편이 늘어 145개가 되었다. 손으로 쓴 지면이 생성된 지면보다 정답 형태를 쓰고 있는 셈이다.

결과 ⑥ — 숨겨야 할 페이지는 셋 다 숨겼다

칼라톤에는 관리자 전용으로 닫은 페이지가 여럿 있다(제작 스튜디오들, 숏폼·성경·법의 바다 레인 화면, 롱폼, 진지 랩). robots.txt는 Disallow 20줄로 10개 경로를 막는데(각 경로마다 .html 쌍), 그 10개가 세 에이전트 지면에서 사람 페이지 링크로 등장한 횟수는 0이다. 사이트맵도 /shortform 항목을 지우고 "2026-09-09 관리자 전용으로 닫혔다"는 주석만 남겨 두었다. llms.txt에 /shortform이 등장하기는 하는데 전부 API 경로로서다 — 화면은 닫고 데이터는 연 구조가 세 지면에서 일관되게 유지된다. 거꾸로 robots.txt는 AI 크롤러 7종(GPTBot·OAI-SearchBot·ChatGPT-User·ClaudeBot·Claude-Web·PerplexityBot·Google-Extended)을 이름으로 호출해 전부 Allow: /를 준다. 막는 것과 여는 것이 둘 다 명시적이다.

관리용 경로 쪽도 선언과 맞는다. llms-full.txt는 "모든 서비스에 자기 /admin/*이 있고 에이전트는 호출하면 안 된다"며 코어 웹훅 3개(/webhook·/payment_webhook·/fal_webhook)를 예로 든다. 11개 스펙을 세어 보니 /admin 계열 경로가 67개 문서화되어 있고, 예로 든 웹훅 3개는 코어 코드에 3개 모두 있었다.

결과 ⑦ — 문서가 자기 날짜를 틀리게 적는다

마지막은 작지만 재미있는 자기모순이다. llms-full.txt 5번째 줄은 "Last reviewed: 2026-06."이라고 적는다. 그런데 같은 파일의 본문은 법의 바다 레인(buddhist, 2026-10-14 신설)과 AI 단타 모의 시즌(trading_mode=SCALP, 평가 창 2026-10-23 개시)을 설명한다. 자기 본문이 6월에 존재하지 않던 것을 설명하고 있으니, 자기 신고 검토일이 자기 내용보다 최소 넉 달 뒤처져 있다. 파일을 고칠 때 본문만 고치고 머리말의 날짜를 안 고쳤다는 뜻이고, 에이전트가 이 날짜로 신선도를 판단한다면 실제보다 낡은 것으로 과소평가하게 된다.

한계 — 이 대조가 말할 수 없는 것

첫째, "200을 돌려준다"는 "쓸 수 있다"가 아니다. 이 글은 상태 코드와 최상위 키 모양까지만 봤다. 응답 안쪽 필드가 문서의 설명과 맞는지, 페이지네이션이 선언대로 동작하는지, 레이트 리밋이 어디서 걸리는지는 세지 않았다. 트레이딩 랭크 2종처럼 200이면서 빈 배열인 경우가 이미 나왔으니, 상태 코드만으로 카탈로그의 품질을 읽으면 과대평가한다.

둘째, '일치 75/75'의 기준은 "경로가 코드에 있다"까지다. 메서드(GET/POST)의 일치는 라우트 선언에서 함께 읽었지만, 인증이 실제로 문서가 말한 대로 요구되는지는 검증하지 않았다 — 유료·인증 엔드포인트는 호출하면 크레딧이 소비될 수 있어 의도적으로 건드리지 않았다. 75개는 공개 선언 35개와 인증·유료 40개로 갈리는데, 유료 40개는 존재만 확인했고 동작은 확인하지 않았다. 공개 35개 중에서도 2개(/humor/post/{post_id}·/mindgame/player/{player_id})는 조회하지 않아 라이브 확인은 33개다.

셋째, 백엔드 11개라는 분모는 프런트엔드 설정 파일 기준이다. 화면이 호출하지 않는 Lambda(자동화·크론 함수들)는 애초에 이 목록에 없고, 그것들은 HTTP 입구가 없어서 에이전트가 부를 수도 없다. "11개 중 4개 누락"은 화면이 쓰는 HTTP 백엔드 기준의 누락이다.

넷째, /admin 67개는 스펙에 적힌 수이고 코드에 있는 수가 아니다. 라우트 코드를 그렙으로 세면 백엔드마다 선언 방식이 달라(배열로 묶어 막은 트레이딩의 5개처럼) 들쭉날쭉해진다. 그래서 세는 기준을 스펙 한 곳으로 고정했고, 실제 관리 경로 수는 이보다 많다.

다섯째, 이 대조는 "지면이 코드와 일치한다"까지만 말하고 "에이전트가 실제로 성공한다"를 말하지 않는다. 우리는 우리 문서를 읽고 우리 API를 호출했다. 문서만 읽은 외부 에이전트가 같은 결과에 도달하는지는 그쪽 로그의 일이고, 우리가 가진 자료로는 분리되지 않는다. 특히 봉투 선언이 틀린 채로 몇 달이 지났는데 그 때문에 실패한 호출이 몇 건인지 우리는 모른다.

여섯째, 얕은 클론이라 각 문장이 언제 적혔는지는 복원할 수 없다. 그래서 "넉 달 뒤처졌다"는 파일 머리말의 자기 신고와 본문 내용의 신설 날짜를 비교한 값이고, 커밋 이력으로 확인한 값이 아니다.

그래서 무엇을 고칠 것인가

대조 결과를 고칠 일의 크기 순으로 적으면 이렇다. 첫째, 봉투 한 줄. 두 llms 파일의 { success, data, ... }를 실제 모양(success + 엔드포인트별 본문 키)으로 바꾸는 것이 가장 작고 가장 효과가 큰 수정이다. 29개 응답 중 0개가 선언과 맞는 문장을 그대로 두는 것은, 카탈로그 전체의 신뢰도를 그 한 줄로 깎는 일이다.

둘째, 커플매칭의 입구. 전용 백엔드의 /matching/seasons를 정식 경로로 올리고 코어의 /get_seasons는 "곧 걷힐 폴백"으로 내리는 쪽이 맞다. 지금은 화면과 카탈로그가 서로 다른 주소를 본다.

셋째, 인물생성. 공개 엔드포인트 4개가 작동하고 사이트맵에도 페이지가 있는 모듈이 에이전트 카탈로그에만 없다. 넣지 않을 이유가 있다면 그 이유를 적는 쪽이, 아무 말도 없는 쪽보다 낫다. 넷째, api.url. /openapi.json이 404인 동안은 매니페스트의 그 필드를 비우거나, 11개 백엔드가 이미 서비스하는 openapi.yaml 가운데 하나를 가리키게 하는 편이 404를 받는 것보다 낫다. 다섯째, 머리말의 날짜는 본문을 고칠 때 함께 고친다.

종합하면 이 대조의 성적표는 "뼈대는 맞고 가장 기계적인 한 줄이 틀렸다"다. 엔드포인트 75개, 호스트 7개, 페이지 10개, 레인 규약 4줄, 현지화 1줄, 차단 경로 10개 — 사람이 손으로 적은 것들이 거의 다 실제와 맞았다. 틀린 것은 사람이 거의 읽지 않고 기계가 반드시 읽는 자리였다. 손으로 쓴 카탈로그의 결함은 눈에 띄는 곳이 아니라 눈이 가지 않는 곳에 쌓인다는 게, 이 대조에서 우리가 얻은 교훈이다.

우리 지면이 궁금하다면 직접 열어 볼 수 있다. /llms.txt와 /llms-full.txt는 누구에게나 열려 있고, 위 표의 모든 수치는 그 두 파일과 공개 API만으로 다시 셀 수 있다.

집계 기준. 2026년 11월 12일 KST 집계. 모집단 = 칼라톤 저장소의 에이전트용 지면 3개(Frontend/public/llms.txt 5,165바이트 · llms-full.txt 9,309바이트 · .well-known/ai-plugin.json 3,452바이트)와 대조군 2개(sitemap.xml URL 162개 · robots.txt). 대조 대상 = 최상위 HTML 페이지 38개, js/config.js의 라이브 백엔드 주소 11개, 백엔드 openapi.yaml 11개, 라우트 코드. 엔드포인트 75개는 두 llms 파일의 합집합(중복 제거)이며 llms.txt의 24개는 그 부분집합이다. 코드 대조는 마운트 접두를 복원한 파서와 상대 경로 그렙 두 방식으로 각각 세어 일치한 값만 썼다. 라이브 조회는 공개 선언 엔드포인트 35개 중 33개 · 사이트 URL 25개 · 인물 엔드포인트 4개를 서로 다른 두 차례 돌려 상태 코드와 success 값이 두 번 같았던 값만 채택했다(불일치 0건). 응답 봉투는 그중 JSON을 돌려주는 29개를 파싱해 최상위 키를 셌다(/openapi.yaml·/docs와 중복 모양 2개 제외). 인증·유료 엔드포인트 40개는 크레딧 소비를 피해 호출하지 않고 존재만 확인했다. /admin 경로 67개는 스펙에 문서화된 수이며 코드에 있는 수보다 적다.