API 설계, 이제 "사람이 읽는 설명"을 넘어 "에이전트가 검증할 수 있는 계약"으로

Об этом предложении

한 줄 요약 최신 API 기능을 빠르게 붙이는 것보다, 사람과 AI 에이전트가 함께 이해하고 검증할 수 있는 계약·문서·에러·비용 구조를 설계하는 것이 중요해지고 있다. 왜 지금 이 주제인가 최근 공개된 Build APIs Like This and You'll Fail the Interview 에서는 단순히 REST API를 구현하는 것과, 왜 그렇게 설계했는지를 설명하고 방어하는 것 사이에는 큰 차이가 있다고 지적한다. 영상에서는 간단한 상품 조회·등록 API를 만드는 과정에서 API 버저닝, 대량 데이터 조회, Entity의 직접 노출, 입력값 검증, HTTP 상태 코드, 멱등성, Rate Limiting, Controller에 비즈니스 로직을 두는 문제 등을 차례로 짚는다. 핵심은 코드를 작성하는 것 자체보다 설계의 트레이드오프를 설명할 수 있는가 에 있다는 것이다. 이 문제는 AI 시대에 한 단계 더 확장될 수 있다. 과거 API의 주요 소비자는 사람이 사용하는 웹·모바일 애플리케이션이었다. 하지만 이제는 LLM 기반 코딩 에이전트, RAG 파이프라인, MCP 기반 도구, 자동화 시스템 등도 API와 그 문서를 직접 소비한다. 따라서 API는 단순히 사람이 읽고 이해할 수 있는 문서만으로 충분하지 않다. 스키마, 예제, 에러 코드, 버전 정보, 사용 제약과 같은 구조화된 정보까지 포함해 기계가 해석하고 검증할 수 있는 계약으로 설계할 필요가 있다. 핵심 주장 이 글에서 이야기하고 싶은 핵심은 다음과 같다. API의 가치는 "얼마나 빠르게 만들 수 있는가"만으로 판단하기 어렵다. 사람과 AI 에이전트가 함께 검증할 수 있는 명확한 계약을 얼마나 잘 만들었는가도 중요한 판단 기준이 된다. 따라서 API를 설계할 때 다음과 같은 질문이 먼저 나와야 한다. 리소스 모델이 실제 비즈니스 개념과 일치하는가? 요청과 응답의 스키마가 명확한가? 에러 응답이 기계적으로 해석 가능한 형태인가? 멱등성 정책이 필요한 API에 명확하게 정의되어 있는가? API 버전과 Breaking Change 정책이 명시되어 있는가? 문서가 사람이 읽기 쉬울 뿐 아니라 AI 에이전트도 활용하기 쉬운 형태인가? AI가 생성하거나 수정한 코드를 사람이 리뷰하고 테스트할 수 있는가? 토큰 비용, Rate Limit, 캐시, 장애 시 Fallback 등을 고려했는가? API가 왜 현재와 같은 형태로 설계되었는지를 설명할 수 있는가? 이 질문에 답할 수 없다면 API는 단순히 "동작하는 코드"에 머물 가능성이 있다. API를 만드는 것에서 API의 설계를 설명하는 것으로 여기서 중요한 변화는 "API 면접에서 잘 답해야 한다"는 기술적인 팁에 그치지 않는다. 핵심은 API가 하나의 계약 자산이라는 점 이다. 사람은 API를 호출하고 문서를 읽는다. AI 에이전트는 API의 스키마와 문서를 참고해 호출 방법을 추론하고, 그 결과를 다음 작업의 입력으로 사용하기도 한다. 따라서 API 설계는 코드만의 문제가 아니다. API = Endpoint + Schema + Documentation + Error Contract + Versioning + Observability 라는 관점으로 확장해서 볼 필요가 있다. 이를 사람 중심 API와 AI 에이전트 소비 환경으로 나누어 보면 다음과 같다. 판단축 전통적인 API 소비 환경 AI 에이전트 소비 환경 문서 사람이 읽고 이해하는 설명 사람이 읽으면서 에이전트도 활용할 수 있는 구조화된 문서 계약 API 사용법과 설명 중심 스키마, 예제, 에러 코드, 멱등성, 버전 정보까지 명확하게 정의 리뷰 개발자 중심 코드 리뷰 AI 생성 결과에 대한 사람의 설계·코드 리뷰 비용 API 요청 및 인프라 비용 API 비용 + 모델 추론 및 토큰 비용 실패 모드 애플리케이션의 예외 처리 잘못된 해석에 따른 반복 호출과 연쇄적인 오류 관찰 가능성 로그와 시스템 지표 API 호출 패턴, 오류, 재시도, 비용까지 함께 관찰 여기서 중요한 것은 AI를 사용한다고 해서 기존 API 설계 원칙이 사라지는 것이 아니라는 점이다. 오히려 기존의 좋은 API 설계 원칙이 더 중요해진다. 명확한 리소스 모델, 일관된 스키마, 적절한 상태 코드, 입력 검증, 권한 관리, 멱등성, 버저닝, 관찰 가능성 같은 요소가 AI 에이전트 환경에서도 기본적인 안전장치가 된다. 문서는 사람이 읽는 페이지에서 에이전트가 활용하는 지식 자산으로 AI 시대의 API 설계에서 특히 눈여겨볼 부분은 문서의 형태 다. Mastra는 AI 에이전트가 프로젝트와 라이브러리를 더 정확하게 이해할 수 있도록 문서를 구조화하는 방식을 실제 프로젝트에 적용하고 있다. Mastra의 공식 자료에서는 패키지 내부에 SKILL.md 와 Markdown 기반 reference 문서를 제공하고, 패키지와 관련 문서를 연결하기 위한 구조화된 정보와 SOURCE_MAP.json 을 사용하는 방식을 설명한다. 또한 문서를 에이전트가 필요한 범위만 찾아 사용할 수 있도록 구성하는 접근도 소개하고 있다. 이 방식의 중요한 의미는 단순히 "문서를 Markdown으로 바꾼다"는 것이 아니다. 에이전트가 필요한 지식을 필요한 범위에서 찾아 사용할 수 있도록 문서 자체를 구조화한다는 것 이다. 예를 들어 다음과 같은 정보가 명확하게 제공될 수 있다. Package ├── API ├── Schema ├── Example ├── Version ├── Related Source └── Constraints 이렇게 하면 AI 에이전트가 프로젝트 전체를 무작정 읽는 대신 필요한 정보에 접근할 수 있다. 결과적으로 문서 품질은 단순히 "설명이 친절한가"라는 문제를 넘어선다. 정확성, 구조화 정도, 버전 일치 여부, 필요한 정보에 대한 접근성 도 중요한 품질 기준이 된다. AI 코딩 에이전트에서는 컨텍스트가 곧 품질이 된다 AI 코딩 에이전트를 사용할 때도 같은 문제가 발생한다. AI가 코드를 생성할 수 있다는 사실 자체는 이제 특별한 기능이 아니다. 더 중요한 질문은 다음과 같다. AI가 어떤 컨텍스트를 제공받고 코드를 생성하는가? 예를 들어 API를 변경해야 한다고 생각해 보자. 에이전트가 단순히 Controller와 Service 코드만 읽는 것과 다음 정보를 함께 제공받는 것은 결과가 달라질 수 있다. API 스키마 기존 호출 예제 에러 코드 데이터 모델 인증·권한 정책 버전 정책 관련 테스트 Breaking Change 정책 실제 사용 중인 클라이언트 코드 결국 AI 코딩의 품질은 모델의 생성 능력만으로 결정되지 않는다. 정확한 컨텍스트를 얼마나 잘 제공하고, 생성 결과를 어떻게 검증하는가 가 중요하다. 이 관점에서 API 문서는 단순한 개발자 문서가 아니라 AI 에이전트가 사용할 수 있는 프로젝트 지식의 일부가 된다. 토큰 비용도 API 설계의 새로운 고려사항이 된다 AI 에이전트가 API 문서를 반복적으로 읽고 호출한다면 기존에는 없었던 비용 구조도 등장한다. 예를 들어 문서가 지나치게 길거나 중복되어 있다면 에이전트가 필요한 정보를 찾는 데 더 많은 컨텍스트를 사용하게 될 수 있다. API 호출이 잘못 설계되어 불필요한 재시도가 반복되면 모델 추론 비용과 API 비용이 함께 증가할 수도 있다. 따라서 다음과 같은 요소도 함께 고려할 필요가 있다. 필요한 정보만 제공하는 문서 구조 명확한 에러 코드 재시도 가능 여부 Rate Limit Cache Pagination Timeout Fallback 요청 및 응답 크기 모델 컨텍스트 사용량 API 호출 로그와 비용 지표 특히 에러 메시지가 모호하면 에이전트가 잘못된 방법으로 재시도할 가능성이 있다. 반대로 에러 코드와 재시도 가능 여부 등이 명확하다면 에이전트가 실패 상황을 보다 일관되게 처리할 수 있다. 즉, API의 계약 품질이 곧 에이전트의 실행 품질에 영향을 줄 수 있다. AI 중심 설계에도 반론은 필요하다 그렇다고 모든 API를 AI-first 방식으로 다시 설계해야 한다는 의미는 아니다. 오히려 여기에는 몇 가지 중요한 트레이드오프가 있다. 1. AI 친화적인 문서가 항상 사람에게 친절한 것은 아니다 LLM이 처리하기 좋은 구조와 사람이 빠르게 이해하기 좋은 구조가 항상 동일한 것은 아니다. 따라서 사람을 위한 설명과 에이전트가 활용하기 위한 구조화된 정보가 서로 충돌하지 않도록 설계해야 한다. Markdown, Schema, Example 등을 적절하게 조합하는 방법도 하나의 선택지가 될 수 있다. 2. 문서 구조화는 운영 복잡도를 증가시킬 수 있다 문서를 별도의 구조로 관리하거나 패키지에 포함하고, 버전별로 관리하고, 소스와 문서를 연결하는 것은 추가적인 관리 비용을 만든다. 따라서 모든 프로젝트에 동일한 수준의 복잡성을 적용할 필요는 없다. AI 에이전트가 API를 반복적으로 사용하고 있거나, 문서와 실제 구현 사이의 차이가 자주 발생하는 시스템이라면 이런 구조화의 가치가 커질 수 있다. 반면 소규모 내부 도구라면 기존 README와 통합 테스트만으로도 충분할 수 있다. 3. AI가 생성한 코드는 사람의 검증이 필요하다 AI가 더 많은 코드를 빠르게 만들어준다고 해서 설계 검증까지 자동으로 끝나는 것은 아니다. 특히 다음과 같은 영역은 사람이 반드시 확인해야 한다. 권한 인증 멱등성 데이터 무결성 개인정보 및 보안 에러 처리 Breaking Change 트랜잭션 경계 성능 특성 AI가 생성한 코드가 동작한다는 사실과, 그 코드가 시스템의 설계 원칙에 맞는다는 사실은 서로 다르다. 4. 모든 API를 복잡하게 만들 필요는 없다 모든 API를 거대한 계약 자산으로 만드는 것도 좋은 접근은 아니다. 먼저 다음과 같이 영향도가 큰 API부터 정교하게 관리할 수 있다. 외부에 공개되는 핵심 API 여러 서비스에서 공통으로 사용하는 API AI 에이전트가 반복적으로 호출하는 API 데이터 변경의 영향도가 큰 API 버전 호환성이 중요한 API 중요한 것은 복잡성을 추가하는 것 자체가 아니라, 추가된 복잡성이 실제 문제를 해결하는가 다. 판단 프레임: 도입, PoC, 유지, 보류 자신의 시스템에 적용할 때는 다음과 같은 방식으로 판단할 수 있다. 판단 조건 도입 API를 LLM이나 에이전트가 반복적으로 호출하고 있으며, 문서·스키마·에러 계약을 체계적으로 관리할 필요가 있다. PoC 에이전트의 API 사용이 시작되었지만 실제 비용과 품질 개선 효과가 아직 불분명하다. 작은 범위에서 문서 구조화, Schema, MCP 등의 방식을 검증한다. 유지 API 트래픽이 낮고 사람 중심 문서와 테스트가 충분하며 현재 방식이 안정적으로 운영되고 있다. 보류 리소스 모델, 권한, 멱등성, 에러 계약 등 API의 기본 설계부터 명확하지 않다. 먼저 기본적인 API 계약을 정리한다. 이때 가장 중요한 것은 특정 기술을 도입하는 것이 아니다. 현재 발생하고 있는 문제가 무엇인지 먼저 확인하는 것 이다. 실무 체크리스트 API를 AI 에이전트가 소비할 가능성이 있다면 다음 항목을 점검해 볼 수 있다. 리소스 모델이 실제 비즈니스 개념과 일치하는가? URL, Entity, DTO, Response Schema에서 동일한 개념이 일관되게 표현되는가? 대량 조회 API에 Pagination이 적용되어 있는가? 변경 요청에 필요한 경우 멱등성 정책이 정의되어 있는가? 에러 응답에 기계가 해석할 수 있는 코드와 필요한 메시지가 포함되어 있는가? 재시도 가능한 오류와 재시도하면 안 되는 오류가 구분되어 있는가? API 버전과 Breaking Change 정책이 명확한가? 문서와 실제 API 구현의 버전이 일치하는가? Schema와 실제 요청·응답 예제가 일치하는가? AI 에이전트가 필요한 문서를 효율적으로 찾을 수 있는가? AI가 생성하거나 수정한 API 코드를 사람이 리뷰하는가? 인증과 권한 정책이 API 계약과 함께 관리되는가? Rate Limit, Cache, Timeout, Fallback 등을 고려했는가? API 호출 실패와 재시도 패턴을 관찰할 수 있는가? "왜 이렇게 설계했는가?"라는 질문에 설명할 수 있는가? 결론 Build APIs Like This and You'll Fail the Interview 가 던지는 핵심적인 질문은 단순히 "API 코드를 잘 작성할 수 있는가?"가 아니다. 왜 이 API를 이렇게 설계했는지를 설명할 수 있는가? 영상에서도 API 버저닝, 데이터 조회량, DTO, validation, HTTP status, idempotency, rate limiting, business logic의 위치 등 다양한 설계 요소를 코드와 함께 검토하면서, 단순히 동작하는 API와 설계 의도를 설명할 수 있는 API 사이의 차이를 보여준다. AI 시대에는 이 문제가 더욱 중요해질 수 있다. LLM과 에이전트는 잘 정의된 API와 구조화된 문서를 바탕으로 작업할 수 있지만, 모호한 계약은 잘못된 해석과 반복적인 시행착오로 이어질 가능성이 있다. Mastra가 보여주는 문서 구조화 사례 역시 이러한 변화를 보여준다. 문서를 단순한 웹 페이지가 아니라 에이전트가 필요한 정보를 찾아 사용할 수 있는 지식 자산으로 구성하는 방식이다. 따라서 앞으로 API 설계에서 중요한 질문은 다음과 같이 확장될 수 있다. 사람이 이 API를 이해할 수 있는가? AI 에이전트가 이 API를 오해하지 않고 사용할 수 있는가? 그 과정에서 발생하는 비용과 복잡도를 감당할 수 있는가? 실패했을 때 원인을 관찰하고 검증할 수 있는가? 그리고 왜 이렇게 설계했는지를 설명할 수 있는가? 이 질문에 답할 수 있을 때 API는 단순한 엔드포인트의 집합을 넘어, 사람과 AI가 함께 사용하는 기술적 계약이자 의사결정 자산 이 될 수 있다. 댓글로 의견을 나눠보고 싶은 질문 팀에서 LLM이나 AI 에이전트가 API 문서와 Schema를 직접 소비하도록 설계한 경험이 있으신가요? AI가 생성한 API 코드를 리뷰할 때 가장 먼저 확인하는 항목은 무엇인가요? API 문서를 사람 중심으로 관리하는 것과 에이전트가 활용하기 좋은 형태로 구조화하는 것 사이에서 어떤 방식을 사용하고 계신가요? 참고 자료 Amigoscode, Build APIs Like This and You'll Fail the Interview , 2026-08-25. Mastra, How to Structure Projects for AI Agents and LLMs . Mastra, Introducing Mastra Skills . Mastra, Introducing File-Based Agents for Mastra .