TypeScript 기반 통합 Schema 설계를 통한 3,000개 API의 CLI 자동 생성 체계 구축

Context

100개 이상의 제품과 3,000여 개의 HTTP API를 보유한 방대한 API Surface 관리의 어려움 직면. OpenAPI 스키마만으로는 로컬 개발 환경과 API 요청이 결합된 복잡한 CLI 동작 및 Agent Skill 정의에 한계가 존재하며, 수동 업데이트로 인한 낮은 확장성과 잦은 휴먼 에러 발생.

Technical Solution

• OpenAPI의 표현력 한계를 극복하기 위해 API, CLI 명령어, 인자 및 컨텍스트를 통합 정의하는 자체 TypeScript Schema 도입
• TypeScript 기반의 타입 시스템, 린팅 및 가드레일을 적용하여 대규모 조직 내에서도 일관된 인터페이스 명명 규칙(예: info 대신 get 사용) 강제
• 단일 Source of Truth인 TS Schema로부터 CLI, SDK, OpenAPI 스키마, 문서 등을 자동 생성하는 Code Generation Pipeline 구축
• 로컬 리소스와 원격 리소스의 API 형상을 일치시킨 Local Mirror API 설계를 통해 --local 플래그만으로 동작하는 심리스한 환경 제공
• Agent의 예측 가능성을 높이기 위해 전역적으로 일관된 옵션(--json, --force 등)을 Schema 레이어에서 표준화