처음부터 에이전트를 고려해 설계한 사이트가 뒤늦게 개조한 블로그보다 낮은 점수를 받았습니다. 그런데 저자는 이걸 실패라고 부르지 않습니다.
WordPress 공동 창업자이자 Yoast SEO 개발자인 Joost de Valk가 칵테일 레시피 사이트 cocktail.glass를 처음부터 에이전트 친화적으로 설계한 과정을 공유했습니다. 기존 블로그는 뒤늦게 개조했고, cocktail.glass는 처음부터 에이전트를 염두에 두고 설계했습니다. 그런데 점수는 오히려 블로그가 더 높았습니다. 그 이유와 의미가 이 글의 핵심입니다.
출처: Building a site agents can use, from scratch – joost.blog
하나의 데이터, 모든 표현
블로그의 콘텐츠는 산문(prose)으로 존재합니다. 에이전트에게 Markdown을 제공하려면 MDX → HTML → Markdown 순으로 변환하는 파생 작업이 필요하고, 에이전트는 항상 그 체인의 끝에 있습니다.
cocktail.glass는 반대 방향으로 설계했습니다. 콘텐츠 자체가 처음부터 구조화된 JSON 데이터입니다. 레시피 500개가 cocktails.json에, 재료 정보가 ingredients.json에 있고, HTML 페이지·Markdown·JSON 피드·MCP 서버·schema.org 그래프가 모두 이 하나의 데이터에서 파생됩니다. 어떤 표현도 다른 표현의 복사본이 아닙니다. 데이터 하나를 수정하면 사람용 화면과 에이전트용 인터페이스가 동시에 바뀝니다.
저자는 이것을 “처음에만 할 수 있는 선택”이라고 표현합니다. 콘텐츠가 산문으로 이미 존재하는 사이트에서 이걸 하려면 마이그레이션이 필요하지만, 데이터부터 시작하면 HTML은 그저 가장 많은 장식이 붙은 렌더링 결과일 뿐입니다.
같은 URL, 다른 표현
블로그는 에이전트를 위한 Markdown 파일을 빌드 단계에서 미리 생성해 CDN 규칙으로 라우팅합니다. 작동하지만, 페이지마다 .md 파일이 생기고 CDN 설정이 따로 필요합니다.
cocktail.glass에는 .md 파일이 아예 없습니다. 대신 요청의 Accept 헤더를 확인하는 미들웨어 하나가 같은 URL에서 HTML과 Markdown을 구분해 응답합니다. 브라우저는 HTML을, Accept: text/markdown을 보내는 에이전트는 Markdown을 받습니다. 콘텐츠가 데이터로 존재하기 때문에 Markdown은 저장하는 것이 아니라 요청 시 렌더링하는 것이 됩니다. 응답 헤더에는 예상 토큰 수도 함께 실어서, 에이전트가 내용을 읽기 전에 비용을 가늠할 수 있습니다.
에이전트가 스스로 찾아오도록
에이전트가 사이트를 활용하려면 먼저 무엇이 있는지 알아야 합니다. cocktail.glass는 모든 페이지 응답 헤더에 세 가지를 연결해 놓았습니다.
- API 카탈로그: 기계가 사용할 수 있는 모든 엔드포인트 목록 (RFC 9727 표준)
- MCP 서버 카드: 연결 전에 서버의 이름·전송 방식·기능을 미리 알려주는 문서
- llms.txt: 언어 모델을 위한 사이트맵
어떤 URL에 접근하든 응답 헤더 하나만 따라가면 MCP 서버·JSON 피드·상태 확인 엔드포인트까지 도달할 수 있습니다. HTML을 파싱할 필요가 없습니다. 디스커버리는 사이트의 특정 페이지가 아니라 모든 응답의 속성입니다.
MCP 서버 자체는 무상태(stateless)로 설계했습니다. 세션 ID를 발급하지 않고, 모든 요청이 독립적으로 처리됩니다. 읽기 전용 카탈로그에서 상태를 유지할 이유가 없고, 인증도 없습니다. 공개 데이터를 보호한다는 명목으로 에이전트가 실패할 지점을 하나 더 만드는 것보다, 아예 없애는 편이 낫다는 판단입니다.
“에이전트 준비”는 한 번으로 끝나지 않는다
cocktail.glass는 처음부터 에이전트를 고려했지만 에이전트 준비도 평가 도구 isitagentready.com 초기 스캔에서 75점이었습니다. 개조한 블로그의 83점보다 낮았습니다. 이유는 간단합니다. cocktail.glass의 첫 커밋이 스캔 도구 출시보다 3주 앞섰고, 그 사이에 새로운 표준(Agent Skills)이 등장했기 때문입니다.
저자는 이것을 솔직하게 인정합니다. 표준보다 먼저 만들어진 사이트는 그 표준이 나오는 순간 개조가 필요해집니다. 그럼에도 처음부터 설계한 사이트가 유리한 이유는 점수가 아니라 적응 비용입니다. 새 표준이 생겼을 때, 처음부터 설계한 사이트는 기존 구조에 파일을 하나 추가하는 것으로 충분했습니다. 블로그는 구조적 한계 때문에 우회로를 만들어야 했습니다.
저자가 cocktail.glass의 한계도 명확히 짚는다는 점은 주목할 만합니다. 읽기 전용·소규모·공개 데이터라는 세 가지 조건이 설계를 단순하게 만들었고, 실제 프로덕션 환경은 그 가정들을 하나씩 포기해야 합니다. cocktail.glass는 그 패턴을 가장 깨끗하게 보여주는 교육용 사례입니다.
답글 남기기