llms.txt와 문서 · 코드의 정합성
2026-11-09 ~ 10 세션에서 메인테이너가 물은 셋입니다. “다른 LLM에게 “https://ariadnensd.com 으로 버블소트 알고리즘을 nsd로 그려주세요”라고 했을 때 무엇을 준비해야 될까요?”, “시안에서 u, d, j등이 언급되는데 무슨 뜻인가요?”, 그리고 “작업이 커져서 앞으로 문서나 /llms.txt의 정합성이 안 맞을 것이 걱정됩니다. 다른 엔지니어들이 쓰는 방법이 있을 것 같군요.”
llms.txt
한 줄 요약
사이트 맨 위에 두는 LLM용 안내서입니다(https://사이트/llms.txt, 마크다운). llmstxt.org가 제안한 관례이고, 표준은 아닙니다.
왜 필요한가
AriadneNSD 같은 앱은 자바스크립트가 화면을 그립니다(SPA). LLM이 주소를 읽으러 오면 자바스크립트를 돌리지 않아 “불러오는 중…” 한 줄만 봅니다. 메인테이너가 ChatGPT에게 시켜 보니 실제로 “페이지가 로딩 화면으로만 확인되어”라고 답했습니다. 그래서 두 가지가 필요합니다.
- 사람용 화면과 따로, 글로 된 안내서(
/llms.txt) - 첫 화면 HTML 안에 그것을 가리키는 말과 짧은 요약. 링크를 따라가지 않는 도구도 있기 때문
백엔드로 비유하면
API 문서(OpenAPI)와 같습니다. 사람은 화면을 쓰고, 프로그램은 문서를 읽고 정해진 형식으로 요청을 만듭니다. 여기서 “요청”은 공유 링크입니다.
공유 링크의 꾸림 d · j · u
공유 링크는 https://ariadnensd.com/#ns1.d.…처럼 생겼습니다. # 뒤는 서버로 가지 않습니다.
| 글자 | 담는 법 | 길이 | 손으로 만들기 |
|---|---|---|---|
d | JSON을 deflate로 압축한 뒤 base64url | 가장 짧음 | 못 함(압축은 코드가 필요) |
j | JSON을 base64url로만 | 약 2배 | 어렵고 틀리기 쉬움 |
u | JSON을 퍼센트 인코딩({ → %7B) | 약 3배 | 됨 |
앱의 “공유 링크 복사”는 가장 짧은 d를 만들고, LLM은 u로 줍니다. 앱은 셋을 모두 읽습니다 → ADR-0043
문서와 코드의 정합성을 지키는 법
같은 사실이 여러 곳에 적히면 언젠가 어긋납니다. 엔지니어들이 흔히 쓰는 넷입니다.
| 방법 | 이름 | 예 |
|---|---|---|
| 원본 하나에서 뽑기 | single source of truth, 코드 생성 | OpenAPI 명세에서 클라이언트 코드를 만들기, 이 저장소의 테스트 목록 |
| 문서 속 예제를 테스트로 | doctest, executable examples | Python의 doctest, Rust의 문서 테스트 |
| 함께 바뀌는 곳의 짝 | co-change rule | CODEOWNERS, Danger(PR에서 “이 파일을 바꾸면 저 문서도”를 알림) |
| 사용자처럼 시험 | eval, 인수 테스트 | LLM 앱에서 프롬프트를 바꿀 때 시험 문제를 다시 돌리기 |
앞의 셋은 “문서가 코드와 맞는가”, 마지막은 “문서가 읽는 쪽에게 통하는가”를 봅니다. 이 저장소의 규칙은 13. 문서와 코드의 정합성에 있습니다.
화면의 응답 시간은 어떻게 재나
AT-05(블록 500개 문서에서 편집 응답 100ms 안)를 묻자 메인테이너가 “시계와 눈으로 하나?”라고 물었습니다. 100ms는 눈으로 잴 수 없습니다. 브라우저의 performance.now()는 1ms보다 잘게 재는 시계입니다. 키를 누른 때와, 바뀐 그림이 화면에 그려진 뒤의 프레임(requestAnimationFrame) 사이를 잽니다. 여러 번 재서 느린 쪽 5%의 값(p95)을 기준과 견줍니다. 백엔드의 응답 시간 p95와 같은 생각입니다.
hidden과 보이지 않는 글(visually-hidden)
Grok은 화면을 띄워 앱을 조작하려 했고, 첫 화면의 AI용 안내를 보지 못했습니다. 그 안내는 hidden 속성으로 숨긴 채 #root 안에 있어서, 앱이 뜨면 React가 지웠습니다.
| 숨기는 법 | 화면 | 화면을 읽는 도구 · 스크린 리더 |
|---|---|---|
hidden, display: none | 안 보임 | 없는 것으로 봄 |
visually-hidden(1px로 잘라 내는 CSS, clip-path: inset(50%)) | 안 보임 | 읽음 |
그래서 안내 한 줄을 #root 밖에 visually-hidden으로 두었습니다. 스크린 리더도 읽으므로 짧게 씁니다. 백엔드로 비유하면, 사람용 응답 본문은 그대로 두고 기계가 읽는 헤더를 하나 더 다는 것과 비슷합니다.
커밋을 막는 훅
Claude Code의 PreToolUse 훅은 Claude가 도구를 쓰기 직전에 돕니다. git commit을 실행하려 할 때 스테이지한 변경을 보고, 함께 바뀌어야 할 문서가 그대로면 exit 2로 막습니다. Git 자체의 pre-commit 훅과 비슷하지만, 사람이 터미널에서 하는 커밋에는 듣지 않고 Claude와 에이전트의 커밋에만 듣습니다. 사람의 커밋은 CI의 경고가 봅니다.