AI 시대의 개발자 문서는 어떠해야 하는가 (feat. 공공 API 유감)

8주간 진행했던 넷플연가 교육의 초반부는 주로 기본적인 AI 활용 방법 및 DB/API 등 기본적인 개발 개념을 잡는 데 집중한 반면, 후반부는 매주 2시간 이상을 '코칭'에 쏟았습니다. 각자 수준이 다르고 만들고 싶은 게 다른 만큼, 제가 문제 해결을 위해 어떻게 접근하는지 Think Aloud 하며 투명하게 보여드리는 게 학습 효과가 크리라고 생각했기 때문이죠. 실제로 코칭을 보며 정말 많이 배웠다는 분이 다수 있었습니다.

제 교육의 핵심은 '본인의 불편함을 푸는 작은 프로그램 만들기'였습니다. 각자 배경이 다른 24명이 모였다 보니 이런 코칭이 아니었다면 제가 관심을 뒀을 가능성이 희박했던 문제도 고민할 수 있었던 게 재미있었어요. 이런 코칭을 최소 10번은 해드렸던 것 같은데, 그중에서도 '낙뢰 특보'를 활용한 프로그램과 '부동산 실거래가' 정보를 활용하는 프로그램을 구현하고자 했던 분들을 코칭했던 케이스가 가장 기억에 남습니다.

다만 기억에 남은 이유가 '재미'보다는 '고통'이었던 건 좀 아쉽습니다. 둘 다 공공 API를 활용해야 했는데, API 연동 과정이 너무나 고통스러웠기 때문입니다. 그래서 어떻게 하면 이 고통이 줄어들지 한번 생각해봤어요.

AI 시대의 개발자 문서가 갖춰야 할 조건

바이브 코딩이 보편화되면서 '개발'이 점차 민주화되고 있습니다. 하지만 바이브 코딩으로, '프롬프트 딸깍'만으로 만들어지는 프로그램이 장난감 프로젝트라는 오명을 벗고 실질적인 유용성을 가지려면 API가 연결되어야 합니다.

제가 개발자로서 하나의 프로그램에 외부 API 하나를 연결하기까지 거치는 과정은 대략 다음과 같습니다.

1. 필요한 데이터/기능을 제공하는 API 제공자의 개발자 문서를 찾는다.
2. 개발자 문서 내에서 API가 제공하는 기능, 비용, 제한 조건(Rate Limit 등)을 읽고 사용 여부를 결정한다.
3. API 호출시 어떤 인자를 어떤 형식으로 넣어야 하는지, 어떻게 응답이 돌아오는지, 어떤 종류의 에러들이 생기는지 이해한다.
4. API Key를 발급받아 직접 호출하며 가볍게 테스트해본다.
5. 내 프로그램에 API를 연결하기 위한 코드를 넣고, 실제로 실행하며 테스트한다.

그런데 AI 시대에는 이 모든 과정을 반드시 개발자가 하는 게 아닙니다. 오히려 비개발자가, AI 에이전트와 함께 할 일이 더 많습니다. 즉 이제는 웹상에 존재하는 모든 문서가 LLM의 컨텍스트로 들어갈 수 있음을, 에이전트가 개별 문서와 인터랙션할 것을 전제해야 합니다.

따라서 저는 개발자 문서가 AI 시대에 진정 유용해지려면, 발견과 활용 측면에서 다음과 같은 조건을 만족해야 한다고 생각합니다.

발견 측면

사용자가 필요한 기능/데이터를 자연어로 묘사하면 그러한 API 제공자의 웹페이지를 AI가 발견해서 제안할 수 있어야 합니다. 또한 그렇게 발견한 API 문서 내에서 API의 기능, 비용, 제한 조건, Key 발급 방법 등을 쉽게 찾고 이해하여, 인간이 AI와 함께 의사결정하기 쉬워야 합니다. 이를 위해선...

• llms.txt가 존재하며, SEO 및 GEO가 잘 되어 있을수록 좋습니다.
• 주요 페이지들이 모두 별도의 URL로 구성되어있는 게 좋습니다.
• 각 페이지가 텍스트만으로 모든 내용을 이해할 수 있도록, 예를 들어 마크다운 문서 형태로 작성되어 있는 게 좋습니다.

활용 측면

사용자가 AI에게 특정 API 문서의 URL을 제공하면 호출 테스트를 위한 코드를 완벽하게 작성할 수 있어야 합니다. 이를 위해선...

• API 호출 인자의 구조/의미/형식, 정상 응답 형식과 예시, 에러코드와 예시 등이 하나의 마크다운 문서로 존재하면 좋습니다. (OpenAPI 스펙을 따른다면 모두 충족됩니다) 이런 마크다운 문서를 버튼 클릭 한 번으로 클립보드에 복사할 수 있으면 더 좋습니다.
• 직접 복사할 필요 없이 API별로 개별 문서 URL이 부여되어, fetch 만으로 모든 내용을 가져올 수 있으면 좋습니다. fetch 로 마크다운 문서가 아닌 HTML을 받을 수도 있을테니 Semantic HTML과 접근성을 최대한 준수하는 게 좋습니다. (<a> 태그에는 href 속성이 존재해야 한다 등) 이러면 Comet 같은 브라우저-유즈 에이전트가 작업하기에도 훨씬 유리해집니다.

API 문서가 이러한 조건을 만족한다면 비개발자라도 (프롬프트 딸깍 만으로) 수월하게 API 연동이 가능해질 거라고 봅니다. 사실 API뿐 아니라, SDK를 비롯해 어떤 개발 문서든 기본 원리는 일맥상통해요. 그리고 이렇게 하면 AI에게만 좋은 게 아니라 대개 사람이 이해하기도 더 쉬워집니다.

Anthropic의 개발자 문서는 이 모든 조건을 만족합니다. llms.txt가 있고, API별로 개별 URL이 부여되어 있고, 입출력 형태와 예시가 표현되고, 클릭 한 번에 모든 내용을 마크다운으로 복사할 수 있죠. (공식 OpenAPI 스펙 문서는 없긴 합니다)

그리고... 안타깝게도 한국의 공공 API 문서는 이런 이상적 그림과는 거리가 한참 멀었습니다.

한국 공공 API 문서의 현실

사례 1: 기상청 API 허브

넷플연가 교육 참여자 중 공항에서 근무하시는 분이 있었습니다. 이분은 맡은 업무상 낙뢰 특보가 발생하면 이를 수기로 기록해야만 했는데요. 낙뢰 정보를 알려주는 공항기상 어플이 이미 있었지만 사용하기가 여러모로 불편했죠. 그래서 기상청 API를 활용해 시간대별/지역별 낙뢰 특보를 목록화, 시각화하는 걸 시도하셨습니다.

첫번째로 눈에 띈 건 URL입니다. 좌측의 '레이더' 메뉴를 클릭하든, 페이지 내의 '낙뢰관측' 탭을 클릭하든 브라우저 주소창의 URL이 변경되지 않았어요. 비개발자라면 아마도 주소창에 보이는 대로 (즉 https://apihub.kma.go.kr/를) 프롬프트를 입력하여 API를 연동해달라고 할 가능성이 높은데, 당연히 이것만으로는 낙뢰 관측 API에 대한 정보를 AI가 추출할 수 없습니다. 그래도 llms.txt 가 있다면 훨씬 탐색하기 수월했겠지만, https://apihub.kma.go.kr/llms.txt 에 접근하면 아래와 같은 404 HTML 코드만 뜨더군요.

그리고 요청인자, 출력 변수 등이 표시되어있긴 했지만 어떤 HTTP Method인지, 무엇이 필수인자인지, 오류는 어떻게 처리하는지, 그래서 응답이 어떻게 나오는지 등은 알 수 없었습니다. 테스트 방법도 명시되어있지 않아서 예시 API URL을 보며 시행착오를 겪으며 테스트해볼 수밖에 없었죠.

사례 2: 서울 열린데이터광장

또 다른 참여자분은 서울시에서 제공하는 공공 API를 이용해 특정 지역의 부동산 실거래가 목록을 확인하고 싶어하셨습니다. 매매할만한 부동산을 더 쉽게 찾는 게 목표였죠.

부동산 실거래가 API 문서가 개별 URL을 가지고 있어서 기상청 API보다는 나았지만, 문제는 참여자 분이 이 API를 활용하기 위해 사용한 프롬프트에는 그 URL이 담겨있지 않았다는 점입니다.

https://data.seoul.go.kr 에서 제공하는, open API 정보를 이용해서, 아래 공공데이터를 활용하여,

1. 서울시 부동산 실거래가 정보
2. 서울시 개별공시지가 정보
3. 서울시 건축물대장 표제부

input : 내가 시군구 명, (주지번/부지번) 입력하면
output :
(1) 매칭되는 주소지의 3 서울시 건축물대장 표제부 의 output값 정보를 다 보여주고,
(2) 매칭되는 주소지의 2 서울시 개별공시지가 정보 최근 3개년치를 알려줘

(당연히) llms.txt는 존재하지 않았기 때문에 이런 요청에서 AI가 정확한 API 문서를 발견할 가능성은 매우 낮습니다. 게다가 API를 호출하기 위한 정보는 'OpenAPI' 라는 탭에 들어있었는데 이게 첫번째 탭이 아니었을뿐더러 동적으로 로딩되며, 탭에 부여된 URL도 없었습니다. 그러니 URL을 제대로 제공했더라도 (브라우저-유즈 에이전트가 아니라면) fetch 만으로 제대로 된 정보를 가져오기 어렵죠. 그리고 OpenAPI라고는 되어있었지만 실제로 OpenAPI 스펙을 따르는 것으로 보이지도 않았습니다.

실제로 Cursor(Grok Code 모델)에게 요청해보니, 상당히 그럴듯한 응답을 줬지만 출력값 예시는 환각이 굉장히 많았습니다. 아래 이미지에서 보듯 ACC_YEAR 나 STD_YM, BJDONG_CD 등 존재하지 않는 값들을 자신있게 표시하더군요.

게다가 요청인자를 object 형태가 아닌 위치 형태로 받았기 때문에 API URL 구성의 난도가 높았습니다. 필수값이 아닌 인자는 모두 빈 값 (%20)으로 넣어야 했습니다. API URL Builder를 따로 구현해서 차근차근 테스트해보면서 겨우 원하는 동작을 완성할 수 있었어요. 한마디로, 참 힘들었습니다.

맺으며

새로운 기술이 더 효과적으로 쓰이려면, 효과적으로 쓰이기 위한 인프라를 마련해줘야 합니다. 기지국이 없다면 통신 기술은 무의미하고, 전기차 충전소가 없다면 전기차는 무용지물이죠. 집안일을 돕는 가정용 로봇이 본격적으로 판매되기 시작했지만 집안 구조가 로봇이 일하기에 적절하게 되어있지 않다면 효용이 줄어들 겁니다.

AI도 마찬가지입니다. LLM 에이전트가 효과적으로 인간을 도와주려면 웹사이트와 API 문서들이 LLM 친화적으로 작성되어야 합니다. 사실 구현하기 아주 어려운 것도 아닙니다. Semantic HTML과 접근성은 10년도 전부터 저시력자를 위해서라도 꼭 지켜야 했던 것이고, llms.txt 도 서비스의 정보 구조가 잘 설계되어 있다면 '프롬프트 딸깍'만으로도 쉽게 만들어지니까요.

요즘 국가 차원에서 AI 시대를 따라가기 위한 거시적 과제(e.g., 소버린 AI, GPU 확보 등)들이 착착 진행되고 있습니다. 그런데 사소하다면 사소할 수 있지만, 저는 국가가 제공/관리하는 웹사이트들을 AI 시대에 맞게 개편하는 일도 함께 진행되었으면 합니다. 오히려 이런 사소한 '기본'을 지킴으로써 진정 이 나라가 AI에 진심임을 보여줄 수 있지 않을까 싶어요. 그래서 비개발자가 공공 API를 활용해 창의적인 서비스들을 손쉽게 만드는 사례가 여럿 공유된다면 '전 국민의 개발자화'가 마냥 허황된 말만은 아니게 될 거라고 생각합니다.

앞으로 '높으신 분'들을 만날 일이 만약 생긴다면 이런 이야기를 꼭 꺼내볼 생각입니다. 제가 말한다고 얼마나 효과가 있을지는 모르겠지만요. (혹시 이미 진행되고 있는 프로젝트를 아신다면 알려주세요!)