API 사양이 프롬프트입니다: 모든 AI에게 백엔드를 재설명하는 것을 멈추세요

월요일 아침입니다. 새로운 코딩 어시스턴트가 유망해 보여서, 새 채팅을 열고 의식을 시작합니다. API 문서를 붙여넣고, 인증 헤더(auth header)를 설명하고, 페이지네이션이 cursor를 사용한다고 경고하며, 돈은 정수 센트(integer cents)라고 언급하고, 리스트 페이로드(list payload)가 data.records가 아니라 data.items라는 것을 상기시킵니다.

오후까지는 잘 작동합니다. 2주 후에 도구를 바꾸거나, 계약직 직원에게 온보딩을 하거나, 컨텍스트 창(context window)이 넘어가면 누군가가 그 의식을 다시 거칩니다. 그 사이에 백엔드는 세 군데에서 변경되었고 붙여넣은 문서는 도착할 때 이미 구식이 되어 있습니다.

이것은 프롬프팅 문제가 아닙니다. 이것은 진실의 원천(source of truth) 문제입니다.

계약서가 머물 곳이 없다

대부분의 팀은 동일한 암묵적 지식 스택을 운영합니다:

• 지난 펀딩 라운드 동안 마지막으로 수정된 위키 페이지,
• 엔지니어 한 명이 수동으로 관리하는 Postman 컬렉션,
• 모두 localhost에 연결되는 세 개의 curl 예시가 담긴 README 파일,
• 그리고 실제로 실행 중인 서비스의 동작 방식, 이것만이 유일하게 중요합니다.

AI 도구들은 격차를 메우기보다는 증폭시킵니다. 채팅 모델은 API가 실제로는 limit을 사용함에도 불구하고 pageSize에 대해 확신하는 것처럼 들리는 데 놀라울 정도로 능숙합니다. 통합 버그(integration bug)로 인해 비난받지 않기 때문에, 가장 그럴듯한 형태를 생성하고 넘어갑니다.

해결책은 지루하며, 제 경험상 실제로 작동하는 유일한 방법입니다: 모든 워크플로우가 읽고 다시 쓰는 하나의 기계 판독 가능한 계약서(machine-readable contract). HTTP API의 경우 그 계약서는 버전 관리 시스템에 있는 디스크상의 OpenAPI 문서이며, 코드처럼 검토되어야 합니다.

여기서 'AI 네이티브'가 실제로 의미하는 것

이 문구는 사이드바에 붙여진 챗봇에게 사용되는 경우가 많습니다. 저는 더 좁은 것을 의미합니다. API 워크플로우는 동일한 사양(spec)이 라이프사이클의 모든 단계를 구동할 때 AI 네이티브입니다:

로컬 우선(Local first), 클라우드 우선(Cloud-first)이 아닙니다

제가 이해하는 데 시간이 오래 걸렸던 한 가지는, 스펙이 로컬이라는 점입니다. 그것은 설명하는 코드 옆의 리포지토리 안에 위치합니다. AI 지원은 단지 사용자가 제어하는 설정된 제공업체와 API 키일 뿐입니다. 워크플로우가 반대 방향으로 진행되어 — 기존 코드베이스를 스캔할 때 — 소스 코드는 절대로 기계를 떠나지 않습니다. 도움을 요청하여 간극(gap)을 채우는 경우에만 개별적이고 타입이 지정되지 않은 핸들러가 사용자가 설정한 모델로 전송될 수 있습니다.

이는 중요합니다. 왜냐하면 가장 가치 있는 계약들은 아무도 업로드하고 싶어 하지 않는 내부 시스템들을 설명하기 때문입니다: 가격 책정 로직, 내부 관리자 경로(admin routes), 미출시 제품 등. 로컬 우선은 이 워크플로우에서 사생활 보호 트릭이 아니라, 실제 코드를 도구에 신뢰하는 전제 조건입니다.

이 시리즈가 다루는 내용

저는 지난 몇 달 동안 바로 이 루프를 중심으로 구축하고 직접 사용해 본 Powerduck이라는 로컬 API 작업 공간을 만들면서 살았습니다. 이 7부작 시리즈는 실용적인 버전입니다 — 하루에 하나의 워크플로우, 그리고 실수들까지 포함하여 다룹니다:

– Day 2 — 코드가 존재하기 전에 AI와 함께 API를 설계하고, AI가 정직하게 작업하도록 검토 게이트(review gates)를 마련합니다.
– Day 3 — 수동으로 작성한 모의 JSON을 스펙으로부터 생성된 모의 서버로 대체합니다.
– Day 4 — 단일 200 응답에 만족하기보다 비즈니스 플로우 전체를 따라가는 시나리오 테스트를 작성합니다.
– Day 5 — AST 엔진과 정직한 격차 보고서(gap reports)를 사용하여 200 라우트의 코드베이스를 OpenAPI로 스캔합니다.
– Day 6 — 코딩 에이전트를 MCP 위에서 스펙에 연결하여 필드 이름을 추측하는 것을 방지합니다.
– Day 7 — 웹사이트 프로젝트가 되지 않도록 호스팅되는 문서와 MCP 엔드포인트를 게시합니다.

이 모든 과정은 AI가 백엔드 엔지니어를 대체할 것이라고 믿을 필요는 없습니다. 오히려 그 반대가 필요합니다. 즉, 계약(contract)이야말로 시니어 엔지니어링의 판단력이 존재하는 곳이며, AI는 그것에 대한 빠르고 지치지 않는 초안 작성자이자 검증기 역할을 하는 것입니다.

오늘 시도해 볼 한 가지

지금 통합하고 있는 어떤 API든 열어보고 스스로에게 질문을 던져보세요. 만약 새로운 에이전트가 처음부터 이 API를 올바르게 호출해야 한다면, 무엇 단일 아티팩트를 건네줄 것인가? 정직한 대답이