본문으로 건너뛰기

AI가 읽을 지도를 만들고, 설치 없는 API 예제로 직접 확인해 본 기록

FLOAT흐름팀

2026.11.03

안녕하세요. 플로트 주식회사(FLOAT)에서 개발자 플랫폼 흐름(HRUM)을 만들고 있어요. 저희 서비스로 해 본 사례라 소속부터 밝혀요.

소개

AI 코딩 도구에게 「사주 앱 만들어 줘」라고만 하면 계산 규칙을 지어내거나, API 키를 프런트엔드 코드에 넣어 버릴 위험이 있어요. 그래서 사람이 읽는 설명서와 따로, AI가 읽을 안내(llms.txt)와 AI용 전자책을 만들었어요. 링크를 받은 AI가 어떤 순서로 움직여야 하는지를 단계별로 적어 둔 지도예요.

진행 방법

안내에 적어 둔 순서는 이래요.

  1. 어떤 앱인지 사람에게 먼저 물어요. 운세 앱, 기억하는 캐릭터 채팅, AI 없는 회원제 웹앱, 토스 앱 안의 미니앱 중에서 고르게 하고, 애매하면 통합 운세 책으로 가요

  2. 고른 책의 지도 첫 페이지를 열고, 지금 단계의 페이지만 읽어요. 책 전체를 한 번에 넣지 않아요

  3. API 키는 사람이 콘솔에서 직접 발급해요. AI는 키 값을 채팅으로 달라고 하지 않고 「저장했는지」만 물어요

  4. API는 서버에서 불러요. 키는 저장소가 아니라 호스팅 앱의 환경변수에 들어가요

  5. GitHub 저장소를 연결하고 푸시하면 빌드되어 공개돼요

저희가 직접 해 본 것은 이래요.

설치 없는 예제를 AI 코딩 도구로 만들었어요. Claude Code로 만세력 API 예제 저장소를 만들어 MIT로 공개했어요. curl 스크립트, Node 내장 fetch만 쓰는 파일, Python 표준 라이브러리 urllib만 쓰는 파일, 예시 응답을 돌려주는 로컬 목 서버, 그 목 서버로 도는 테스트가 들어 있어요. 키는 환경변수에서만 읽게 했어요.

처음 검증은 얕았어요. 글 초안을 쓸 때는 진짜 키 없이 가짜 키로만 돌려 봐서, 인증 오류가 나는 경로만 확인됐고 성공 응답이나 저장본을 다시 쓰는 경로는 못 봤어요. 그래서 그 상태로는 올리지 않았어요.

실제 키로 다시 불러 봤어요. 테스트용 계정 키로 예제 저장소의 Node 파일, 블로그 글에 넣은 서버 연동 코드(Python·Node)를 실제 API에 붙여 원국 네 기둥을 받았어요. 서버 연동 코드는 결과를 저장해 두게 했는데, Python 쪽을 같은 입력으로 한 번 더 부르니 API를 또 부르지 않고 저장해 둔 결과를 썼어요.

문서와 실측이 다른 곳이 나왔어요. 문서에는 Python urllib의 기본 User-Agent가 보안 규칙에 막혀 403이 온다고 적혀 있었는데, 키 없이 기본 User-Agent로 불러 보니 403이 아니라 401(키 오류)이 왔어요. 그래서 글에는 「403이 올 수 있어요」로 낮춰 쓰고, User-Agent를 직접 넣으라는 권고는 그대로 뒀어요.

토스 미니앱을 실제로 만들면서 배운 걸 책에 옮겼어요. 미니앱은 서버 렌더링이 안 되고(정적 번들만), 토스 밖 화면을 앱 안에 띄울 수 없었어요. 또 「데모 수준」에서 멈추지 않으려고 본 앱 기능과 하나씩 맞춰 보는 전수표를 만들고, 따로 클릭해 확인한 뒤에야 번들을 올렸어요. 이런 것들을 토스 미니앱 책에 AI가 따라 할 순서로 적어 뒀어요.

결과와 배운 점

막히기 쉬운 곳(안내의 「자주 하는 실수」)은 이래요.

  • 키를 브라우저 코드에 넣기 — 키는 서버 환경변수에만 둬요

  • 헤더 이름을 다르게 쓰기 — X-Partner-Api-Key가 아니면 인증 오류가 나요

  • Python urllib 기본 User-Agent로 부르기 — 보안 규칙에 막힐 수 있어요. User-Agent를 직접 넣어요

  • 모르는 출생 시각을 아무 값으로 채우기 — 시각을 비우면 시주를 빼고 계산해요

  • 푸시하자마자 「배포됐어요」라고 말하기 — 실서버 상태 확인 주소의 커밋이 마지막 커밋과 같아진 뒤에 말하게 해요

느낀 점이에요.

  • AI가 쓴 문서 문장도 실제로 불러 봐야 맞는지 알 수 있었어요. 가짜 키로 돌린 확인은 확인이 아니었어요

  • 가입·이메일 인증·키 발급·결제 설정처럼 사람이 해야 할 일은 끝까지 사람에게 남겨 두는 쪽으로 안내를 썼어요

도움 받은 글

참고한 외부 글은 없어요. 비슷하게 「AI가 읽을 지도」를 주는 방식을 써 보신 분 있으면 어떤 구조가 잘 먹혔는지 듣고 싶어요.

  • AI용 안내: https://hrum.ai/llms.txt

  • 예제 저장소: https://github.com/float1122/hrum-manseryeok-example

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.11.03

FLOAT흐름팀님, 소속을 먼저 밝히고 시작해 주셔서 읽기 편했어요.

가짜 키로 돌린 첫 검증이 "인증 오류 경로만 확인된 얕은 검증"이라서 올리지 않고, 실제 키로 다시 불러 서버 연동 코드까지 확인하셨다는 대목이 특히 좋았어요. 저장해 둔 결과를 쓰는 경로를 같은 입력으로 한 번 더 호출해서 직접 확인하신 것도요.

문서에는 403이라 적혀 있었는데 실측은 401이어서 글에는 "403이 올 수 있어요"로 낮춰 쓰셨다는 부분도 기억에 남아요. AI가 쓴 문장도 실제로 불러 봐야 안다는 느낀 점이 글 전체에 일관되게 드러나요.

꼬리 탁! 치고 응원하고 갈게요 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기