Stripe의 llms.txt에 지침 섹션이 있습니다. 생각보다 큰 일입니다.

Source: Dev.to

왜 이것이 중요한가

This post is a follow‑up to [API Design Principles for the Agentic Era]. That article covered the broader shift in how APIs need to be designed for autonomous consumers. Here we dive deep into one specific mechanism: the llms.txt instructions section.

고유 지침 섹션

docs.stripe.com/llms.txt 내부에 다음과 같은 블록이 있습니다:

# Instructions for LLMs
You are an AI assistant that helps developers understand Stripe’s API.
When answering questions, you must:
1. Cite the official Stripe documentation.
2. Provide code examples in the language requested.
3. Avoid speculation; if the answer is unknown, say so.
4. Highlight any upcoming deprecations or beta features.

차별점

• 자체 설명 행동: 파일은 언어 모델에게 Stripe에 대해 무엇을 말할지뿐만 아니라 어떻게 말할지를 알려줍니다.
• 강제된 모범 사례: 인용, 코드 예시, 그리고 알 수 없는 경우를 명시적으로 처리하도록 요구함으로써 Stripe는 일관되고 고품질의 AI 생성 콘텐츠를 보장합니다.
• 미래 대비: 폐기 예정 기능이나 베타 기능을 언급함으로써 개발자에게 수동 업데이트 없이도 다가오는 변화를 알릴 수 있습니다.

API에 대한 시사점

1. AI 출력 제어 – 문서에 직접 지시문을 삽입함으로써 타사 LLM이 귀하의 서비스를 어떻게 표현할지 조정할 수 있습니다.
2. 지원 부담 감소 – 일관되고 정확한 AI 응답은 반복적인 지원 티켓의 양을 줄여줍니다.
3. 문서를 코드처럼 – 문서를 실행 가능한 아티팩트(예: LLM이 읽는 .txt 파일)로 취급하면 버전 관리되고 테스트 가능한 문서를 장려합니다.

요약

• 지침 섹션을 채택하세요 AI 기반 상호작용에 영향을 주고 싶다면 여러분의 API 문서에.
• 지침을 명시적이고 버전 관리하도록 하여 API와 함께 진화하도록.
• AI 사용을 모니터링하세요 가이드라인이 준수되는지 확인하고 시간이 지남에 따라 개선하기 위해.

Stripe의 방식을 따름으로써 AI 시대를 막연한 유행어에서 구체적이고 제어 가능한 개발자 경험의 일부로 바꿀 수 있습니다.

Source: (원본 링크는 그대로 유지됩니다)

대형 언어 모델 에이전트를 위한 Stripe 통합 모범 사례

• 레거시 Charges API보다 Checkout Sessions API를 항상 사용
• 최신 안정 버전 SDK를 기본값으로
• 레거시 Card Element 또는 Sources API를 절대 권장하지 않음
• PaymentIntents에서 Checkout Sessions로 마이그레이션을 권고
• 하드코딩된 payment_method_types보다 동적 결제 수단을 선호

Note: 이것은 문서가 아니라 프롬프트이며—Stripe 도메인의 루트에 정적 파일로 배포되어—개발자가 “Stripe를 어떻게 추가하나요?”라고 물어보기 전에 AI 코딩 어시스턴트에 로드되도록 설계되었습니다.

Stripe는 AI 도구가 Stripe에 대해 말하는 방식을 프로그래밍하고 있습니다. 개발자가 Cursor, Claude 또는 다른 어시스턴트에 결제 수단을 어떻게 구현하냐고 물을 때마다, 에이전트는 먼저 이 파일을 가져오고 그 지침이 답변에 반영됩니다. 이는 단순히 문서를 기계가 읽을 수 있게 만드는 것이 아니라, 대규모로 서드파티 AI 시스템의 동작을 형성하는 것입니다.

기원

Jeremy Howard (fast.ai, Answer.AI)는 2024년 9월에 이 표준을 제안했습니다. 해결하고자 하는 문제는 실제입니다:

• LLM은 제한된 컨텍스트 윈도우를 가짐.
• HTML은 잡음이 많음.
• 전체 문서 사이트를 프롬프트에 한 번에 넣을 수 없음.

그의 해결책은 의도적으로 저기술적입니다: /llms.txt에 위치한 Markdown 파일로, 내용은 다음과 같습니다:

1. H1 제목.
2. 선택적인 요약 블록인용문.
3. 선정된 링크가 포함된 H2 구분 섹션.

동반 파일인 /llms‑full.txt는 전체 문서를 하나의 파일에 담고 있습니다. 개별 페이지는 URL 뒤에 .md를 붙이면 깨끗한 Markdown 형태로 가져올 수 있습니다.

형식은 의도적으로 단순합니다—특수 구문, 스키마, JSON 없이 순수 Markdown만 사용합니다. LLM은 이미 이 형식을 네이티브하게 이해하니까요. 핵심 통찰은 큐레이션에 있습니다: 문서를 가장 잘 아는 사람은 크롤러보다 AI에게 어떤 부분이 중요한지 알려줘야 합니다.

이는 잘 관리된 robots.txt와 유사합니다—제외가 아니라 우선순위 지정을 제공합니다. robots.txt는 크롤러에게 건너뛸 대상을 알려주고, sitemap.xml은 존재하는 페이지를 알려주며, llms.txt는 AI에게 먼저 읽어야 할 내용을 알려줍니다.

Source: …

현재 채택

• 주요 AI 제공업체 중 자동으로 llms.txt를 가져오는 훈련 크롤러를 확인한 곳은 없습니다.
• 오늘날 실제 가치는 추론 시점에 있으며, 개발자들이 프로젝트 컨텍스트를 위해 Cursor, Claude 등 에이전트에 수동으로 로드하거나 프레임워크가 시작 시에 가져옵니다.
• BuiltWith이 추적한 800 k+ “구현”은 대부분 WordPress 사이트용 Yoast SEO가 파일을 자동 생성한 것입니다. 직접 검증된 수는 784개 사이트에 가깝습니다.

예시

Stripe의 접근 방식이 돋보이는 이유

Stripe의 API 영역은 15 년에 걸쳐 성장했으며, 여러 세대에 걸친 사용 중단된 결제 원시 기능들을 포함하고 있습니다:

• Charges API는 여전히 작동합니다.
• Card Element도 여전히 존재합니다.

개발자와 그들을 돕는 AI 어시스턴트는 레거시 Stack Overflow 답변과 2022년 이전의 학습 데이터에 나타나기 때문에 이러한 오래된 API를 자주 사용합니다.

instructions 섹션은 Stripe가 다음과 같이 말하는 방식입니다:

AI가 개발자가 우리 서비스를 통합하도록 도울 때, 올바른 방향으로 이끌어 주세요. 오래된 학습 데이터가 개발자를 Charges API로 보내지 않게 하세요. 우리의 이전 호환성이 발목을 잡는 일이 없도록 해 주세요.

이는 정당한 엔지니어링 고민입니다. 파일 형식은 조정 없이도 모든 시스템에서 URL을 가져올 수 있기 때문에, AI 제공자와 별도의 협의 없이도 우아한 해결책을 제공합니다.

영향

• 트위터에서 273,800 회 조회 및 740 회 북마크.
• Stripe 엔지니어 Ian McCrystal: “AI 도구가 결국 우리 문서의 주요 독자가 될 것으로 기대합니다.”

Stripe의 지시는 명확합니다: 나쁜 엔드포인트를 직접 언급합니다 — “Sources API와 같은 사용 중단된 API 엔드포인트를 호출해서는 안 됩니다.” “레거시 Card Element를 절대 추천하지 마세요.” 이러한 구체성 덕분에 파일은 머신‑액션 가능합니다. LLM은 구체적인 금지를 따를 수 있지만, “최신 패턴을 선호한다”와 같은 모호한 지침은 적용하기 어렵습니다.

비교 통찰

• Cloudflare는 llms.txt를 서비스별(Agents, AI Gateway, Workers AI 등)로 구성하여, 에이전트가 전체 파일을 파싱하지 않고 관련 섹션만 가져올 수 있게 합니다. 다중 제품 플랫폼에서는 가져오기 시 노이즈를 줄여줍니다.
• Anthropic은 깔끔한 인덱스를 제공하지만 Stripe의 지시가 수행하는 적극적인 교정 작업이 부족합니다.
• LangChain / LangGraph가 이 형식을 채택한다는 것은 일상적으로 에이전트를 구축하는 팀들에게 실용적이라는 신호입니다.

요약

1. Curated Indexes는 가치가 있다: 전체 사이트를 크롤링하는 대신 에이전트에게 집중된 진입점을 제공한다.
2. Active Guidance(Stripe가 하는 것처럼)는 llms.txt를 수동적인 사이트맵에서 수정 메커니즘으로 전환하여 모델 드리프트를 완화하고 오래된 권고를 방지한다.
3. low‑tech, Markdown‑only 접근 방식은 맞춤 파서나 스키마 없이도 모든 LLM과의 호환성을 보장한다.

Bottom line: 대부분의 구현에서는 llms.txt를 문서 인덱스로 사용한다. Stripe는 이를 AI를 적극적으로 안내하도록 확장한 가장 강력한 사례이며, 파일을 API 제공자와 모든 하위 AI 어시스턴트 간의 진정한 기계가 실행 가능한 계약으로 만든다.

문제

대부분의 API에는 다음과 같은 것이 있습니다:

• 폐기된 엔드포인트가 여전히 작동합니다.
• 레거시 패턴이 훈련 데이터에 남아 있습니다.
• 함정이 있어 경험 많은 개발자들은 피해야 한다는 것을 알지만, 신입 개발자들(그리고 오래된 Stack Overflow 답변으로 학습된 AI 어시스턴트)도 계속 사용합니다.

instructions 섹션은 그 격차를 메우기 위해 존재하지만, 거의 아무도 사용하지 않습니다.

왜 Stripe 문서가 중요한가

2012년경부터 Stripe의 개발자 경험은 업계 표준이 되었다. 그들의 성공은 우연이 아니다:

doc_url 훅

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

• doc_url은 문서 페이지의 Markdown 버전을 가리킨다.
• 400 오류를 받은 AI 에이전트는 해당 페이지를 가져와 가이드를 파싱하고 스스로 수정할 수 있다.
• 이는 단순히 좋은 DX가 아니라 자율적인 소비자를 위한 인프라이다.

John Collison의 “llms.txt” 베팅을 평이하게 표현하면:
“요즘 Stripe Docs를 읽으려면 RAM에 많이 올려야 하지만, LLM에게는 사소한 일이다.”

실제로 유용한 것 (카고 컬트와 대비)

✅ 유용한 실천법

1. 모든 오류 응답에 documentation_url (또는 doc_url) 필드를 포함하고, Markdown 페이지를 가리키게 합니다.
   비용: 거의 없음.
   가치: 터미널에서 디버깅하는 사람 및 스스로 교정할 수 있는 AI 에이전트 모두에게 즉시 도움이 됩니다.

2. 시맨틱 매칭을 위한 OpenAPI 설명 작성 – 단순히 사람이 읽기 위한 것이 아니라.
   에이전트가 여러분의 설명을 대상으로 최근접 이웃 검색을 수행합니다.
   좋은 설명 예시:

   “Returns a paginated list of invoices filtered by status, sorted by created_at descending. Requires accounting:read scope.”

   나쁜 설명: “Gets the data.”

3. 고품질 OpenAPI 스펙 유지: 모든 필드, 열거형, 엔드포인트에 명확하고 완전한 설명을 달아야 합니다.
   계약 테스트용 스펙이 형편없다면, 에이전트에게도 형편없습니다.

4. llms.txt 파일 추가 (오후 한 번이면 충분).

   • 가장 중요한 페이지 10개를 각각 한 문장으로 설명합니다.
   • 첫 날에 350개의 링크를 가진 Stripe‑스타일 구현을 만들 필요는 없습니다.

5. 폐기된 API에 대한 instructions 섹션 활용.
   알려진 함정들을 문서화하고 AI에게 피해야 할 점을 알려줍니다.

6. 마케팅 효과 활용:

   • 구조화된 기계‑읽기 가능한 문서는 AI 답변 엔진(Perplexity, ChatGPT 등)이 “어떤 API가 X에 가장 좋은가?” 라는 질문에 답할 때 참고하는 자료입니다.
   • llms.txt는 에이전트 및 검색 가능성을 동시에 높여줍니다.

⚠️ 아직은 크게 가치가 없을 수 있는 항목

새로운 개발자‑경험 패러다임

15년 동안 “developer experience”는 인간을 위한 최적화, 즉 읽기 쉬운 오류 메시지, 명확한 문서, 좋은 SDK, 인터랙티브한 플레이그라운드를 의미했습니다. 그때의 사고 모델은 터미널 앞에 앉은 개발자였습니다.

현재: API 소비자 중 점점 더 많은 비중을 차지하고 있는 자율 시스템은 다음과 같이 동작합니다:

• 문서를 읽는다.
• 인간의 검토 없이 스스로 결정을 내린다.
• 실패 시 자동으로 재시도한다.

문제는 이러한 설계를 해야 하는가가 아니라, 이미 일어나고 있는 상황을 의도적으로 설계하고 있는가입니다.

Stripe의 llms.txt 지침 섹션은 기계가 읽을 수 있는 문서를 만들고, 기계가 해당 문서에 대해 말하는 방식을 제어하려는 기업의 가장 명확한 사례입니다.

요약

구식 프리미티브와 상당한 개발자 기반을 가진 모든 API 회사는 Stripe가 해결한 동일한 문제에 직면합니다. 그 격차는 아직도 크게 남아 있습니다—다음으로 메우세요:

• doc_url in errors.
• Semantic‑rich OpenAPI specs.
• A concise llms.txt.
• Thoughtful use of the instructions section.

지금 바로 실행하면 인간 개발자 와 API 사용의 미래인 자율 에이전트 모두에게 서비스를 제공하게 됩니다.