/.well-known 디렉토리는 에이전트(agents)가 사이트에서 제공하는 기능에 대한 기계 판독 가능한(machine-readable) 설명을 찾기 위해 사이트 루트(root)에서 확인하는 표준 위치입니다. 페이지를 크롤링하고 추측하는 대신, 에이전트는 예측 가능한 경로를 가져와 다른 모든 것을 가리키는 매니페스트(manifest)를 읽습니다.

이 아이디어는 오래된 웹 관습에서 유래되었으며, 이제 에이전트가 관심을 갖는 파일들을 담고 있습니다. RFC 9727에 의해 정의된 well-known 경로의 API 카탈로그(API catalog)를 통해 에이전트는 단일 URL로부터 사이트의 공개 API를 열거할 수 있습니다. 서버 카드(server card)는 MCP 서버와 그곳에 접속하는 방법을 설명합니다. OAuth 메타데이터는 인증(authenticate) 방법을 설명합니다. 결제 및 에이전트 결제 매니페스트(Payment and agent-payment manifests)는 거래 방법을 설명합니다. security.txt는 문제를 보고할 곳을 알려줍니다.

이것의 가치는 발견(discovery)이 검색(search)이 아닌 조회(lookup)가 된다는 점에 있습니다. 이 관습을 알고 있는 에이전트는 하나의 예측 가능한 질문을 던지고 지도를 얻을 수 있으며, 이는 렌더링된 HTML에서 구조를 추론하는 것보다 훨씬 빠르고 훨씬 더 신뢰할 수 있습니다. 완전한 well-known 표면(surface)을 게시하는 사이트는 에이전트가 이미 사용하는 언어로 자신의 역량을 선언하는 것입니다.

well-known 디렉토리가 누락되거나 빈약하다고 해서 사람들에게 사이트가 깨지는 것은 아니지만, 에이전트가 추측하게 만들며, 대부분의 에이전트는 그냥 지나쳐 버릴 것입니다. 에이전트가 기대하는 매니페스트를 게시하는 것은 존재하는 기능과 에이전트가 찾을 수 있는 기능 사이의 차이를 만듭니다.

turva.dev는 /.well-known 아래에 API 카탈로그, 서버 카드, OAuth 메타데이터, 결제 매니페스트, 그리고 보안 연락처를 게시합니다. 사이트의 발견 표면(discovery surface)에 대한 감사가 필요하면 info@turva.dev로 문의하세요.

관련 항목

• MCP 서버 카드 설명
• 에이전트가 인증하는 방법
• 사이트맵, robots.txt 및 에이전트 액세스

원문 게시 위치: https://turva.dev/guides/well-known-for-agents