llms.txt가 손상되었을 때 CI를 실패하게 만드는 GitHub Action을 만들었습니다

만약 당신의 사이트에 llms.txt를 추가했다면, 불편한 점이 하나 있습니다. 바로 그것이 깨졌을 때 아무도 알려주지 않는다는 것입니다. 누락된 제목, 잘못된 형식의 링크, AI 페처 (AI fetcher)가 해결할 수 없는 상대 경로 URL 등이 있으면, 당신이 정성껏 큐레이션한 파일은 그냥 무시됩니다. 그것도 조용히 말이죠. 그래서 저는 매 푸시 (push)마다 llms.txt를 린트 (lint)하고, 내용이 잘못되었을 때 빌드를 실패하게 만드는 작은 GitHub Action을 만들었습니다.

간단한 복습: llms.txt란 무엇인가?

llms.txt는 사이트 루트에 위치한 작은 마크다운 (markdown) 파일로, 대규모 언어 모델 (LLM)에게 당신의 가장 좋은 페이지들에 대한 큐레이션된 지도를 제공합니다. 이는 robots.txt 및 sitemap.xml의 AI 검색용 사촌 격입니다. 크롤러 (crawler)가 추측하게 두는 대신, ChatGPT, Perplexity, Claude 그리고 Google AI Overviews에게 무엇을 읽고 인용해야 하는지 정확하게 알려줍니다.

형식은 의도적으로 단순합니다:

# Your Site

> 모델이 가장 먼저 읽는 한 줄 요약.
...

문제는 "단순함"이 "틀리기 어렵다"는 것과 같지는 않다는 점입니다. H1은 유일하게 엄격하게 요구되는 요소이며, 링크는 반드시 실제 마크다운 링크 불릿 (markdown link bullets) 형태여야 하고, Optional 섹션은 특별한 의미를 가집니다. 이것들이 바로 새벽 1시에 당신이 잊어버리기 딱 좋은 것들입니다.

CI 체크가 필요한 이유

저는 llms.txt를 다른 빌드 아티팩트 (build artifact)와 동일하게 취급합니다. 만약 손상된 사이트맵 (sitemap)이 CI를 실패하게 만든다면, 손상된 AI 가독성 파일도 그래야 합니다. 제가 강제하고 싶었던 규칙들은 다음과 같습니다:

• 에러 (빌드 실패): 파일이 존재하고 비어 있지 않아야 함, 정확히 하나의 H1 제목이 존재하며 가장 먼저 나와야 함, 모든 링크 불릿은 - [name](url): notes 형식을 잘 갖추어야 함, URL이 비어 있어서는 안 됨.
• 경고 (선택적 실패): 제목 바로 아래에 인용구 (blockquote) 요약이 있어야 함, 링크는 절대 경로인 https:// URL을 사용해야 함, 모든 링크에는 : description이 있어야 함, 섹션은 H2를 사용해야 함, 빈 섹션이 없어야 함, 중복된 URL이 없어야 함, 그리고 Optional 섹션이 존재해야 함.

Action

의존성(dependency)이 전혀 없고 순수 Python 표준 라이브러리만 사용하므로, 별도의 setup 단계 없이 기본 러너 (runner)에서 약 1초 만에 실행됩니다:

name: Validate llms.txt
on: [push, pull_request]

...

target을 파일 경로 또는 배포된 URL로 지정할 수 있습니다 (일반 사이트 URL의 경우 /llms.txt가 자동으로 추가됩니다). 엄격 모드(strict mode)를 사용하려면 fail-on-warning: true로 설정하세요. 실행할 때마다 H1 / 섹션 (sections) / 링크 (links) / 오류 (errors) / 경고 (warnings) 표가 작업 요약(job summary)에 생성되며, 각 라인별 메시지가 제공됩니다.

이 프로젝트는 MIT 라이선스를 따르며, 전체 검증기(validator)는 읽기 쉬운 단일 파일로 구성되어 있습니다: github.com/atlashey-collab/llms-txt-action.

로컬에서도 실행 가능합니다

curl -sO https://raw.githubusercontent.com/atlashey-collab/llms-txt-action/v1/validate_llms_txt.py
python3 validate_llms_txt.py llms.txt
python3 validate_llms_txt.py https://example.com --fail-on-warning

종료 코드 (Exit codes)는 CI 환경에 최적화되어 있습니다: 0은 유효함, 1은 검증 실패, 2는 사용법 오류를 의미합니다.

솔직한 주의사항

llms.txt는 아직 초기 단계의 규약 (convention)입니다. 주요 AI 엔진들의 채택 수준은 여전히 불균형하며, 파일이 유효하다고 해서 반드시 인용(citations)이 보장되는 것은 아닙니다. 하지만 이를 올바르게 유지하는 데 드는 비용은 이제 제로에 가깝고, 파일이 깨져 있다면 인용되는 것은 불가능합니다. 이 정도의 트레이드오프 (trade-off)는 충분히 가치가 있습니다.

아직 파일이 없다면, 먼저 사양 (spec)을 준수하는 파일을 작성한 다음 검사 과정을 연결하세요. 어떤 방식이든, 깨진 llms.txt를 배포하면서도 그 사실을 모르는 상태를 멈추시기 바랍니다.