HTTP 콘텐츠 협상으로 에이전트 친화적 페이지 만들기

AI 에이전트가 웹 페이지를 크롤링할 때 HTML 전체를 받아 파싱하는 방식은 토큰 낭비가 크다. HTTP 표준의 콘텐츠 협상(Content Negotiation)을 활용해 에이전트에게는 마크다운 형식으로 직접 응답하면 동일 URL에서 브라우저와 에이전트가 각자 최적의 포맷을 받을 수 있다는 걸 Next.js 구현으로 보여준다. 500KB HTML을 3KB 마크다운으로 줄여 99.37% 페이로드를 감소시킨 실제 적용 사례다.

핵심 포인트

에이전트가 `Accept: text/markdown` 헤더를 보내면 서버가 HTML 대신 마크다운을 반환하는 콘텐츠 협상 방식이다.
Next.js `next.config.ts`의 rewrite 규칙에서 Accept 헤더를 검사해 마크다운 전용 엔드포인트(`/md/` 경로)로 라우팅한다.
라우트 핸들러에서 CMS 리치 텍스트를 마크다운으로 변환해 제공 — 코드 블록 문법, 제목 계층, 링크가 모두 보존된다.
500KB HTML → 3KB 마크다운(99.37% 감소)으로 토큰 제한 에이전트가 더 많은 콘텐츠를 처리하게 된다.
계층적 마크다운 사이트맵을 함께 제공해 에이전트가 사이트 구조를 파악하고 필요한 콘텐츠를 탐색하게 한다.

상세 정리

배경: AI 에이전트가 웹 페이지를 읽을 때 HTML 전체(CSS, JS, 광고 포함)를 파싱해야 해서 토큰 낭비가 심하고 맥락 창을 빠르게 채운다.
콘텐츠 협상 원리: HTTP `Accept` 헤더는 클라이언트가 선호하는 MIME 타입을 서버에 알리는 표준 메커니즘 — 브라우저는 `text/html`, 에이전트는 `text/markdown`을 요청한다.
Next.js 설정: `next.config.ts`의 `rewrites` 함수에서 요청 헤더를 검사해 `Accept`에 `text/markdown`이 있으면 같은 URL을 `/md/{slug}` 경로로 내부 재작성한다.
마크다운 라우트 핸들러: `/md/[slug]/route.ts`에서 CMS API를 호출해 리치 텍스트 데이터를 마크다운으로 변환, `Content-Type: text/markdown` 헤더와 함께 반환한다.
포맷 보존: 코드 블록의 언어 힌트(문법 하이라이팅), 제목 계층(`#`, `##`), 하이퍼링크가 마크다운에서도 그대로 표현된다.
성능 수치: 동일 글 기준 HTML 약 500KB vs 마크다운 약 3KB — 99.37% 페이로드 감소. 에이전트가 같은 컨텍스트 창에서 훨씬 많은 페이지를 처리할 수 있다.
마크다운 사이트맵: 전체 콘텐츠 트리를 계층적 마크다운 목록으로 노출해 에이전트가 사이트맵을 먼저 읽고 필요한 페이지만 선택적으로 크롤링하게 한다.
점진적 도입 가능: 기존 HTML 라우트는 그대로 두고 마크다운 엔드포인트만 추가하는 방식이라 브라우저 사용자 경험에 영향을 주지 않는다.