계약 우선 접근법이 LLM 에이전트로부터 보호하는 방법: API 우선으로 프론트엔드와 백엔드 정렬 유지

저자는 두 개의 사이드 프로젝트에서 LLM 에이전트가 프론트엔드와 백엔드를 개발할 때 계약(contract)이 자주 어긋나는 것을 발견했습니다. 프론트엔드 에이전트는 응답을 Record<string, unknown>으로 타입 지정하고, 느슨한 객체나 JSON 노드를 사용하며, 필드 이름이 다른 DTO를 중복 생성하고, 때로는 존재하지 않는 백엔드를 로컬 데이터와 토스트 메시지로 시뮬레이션하기도 합니다. 이러한 오류는 컴파일러, 린터, 아키텍처 테스트에서 모두 잡히지 않습니다. 분석 도구가 코드베이스 간의 HTTP 요청을 보지 못하기 때문입니다. 해결책은 계약 우선(contract-first) 방식입니다. 단일 진실 공급원은 OpenAPI 사양(YAML)이며, 여기에서 서버 인터페이스(interfaceOnly 및 skipDefaultInterface 옵션 사용)와 클라이언트가 빌드 시 생성됩니다. 컨트롤러는 생성된 인터페이스를 구현하므로 시그니처 일치가 보장되며, 계약에서 벗어나면 컴파일 오류가 발생합니다. 저자는 이 접근 방식이 이미 gRPC와 GraphQL에서 사용되고 있으며, REST로 다시 돌아오고 있다고 지적합니다. 계약을 읽는 주체가 이제 인간이 아닌 LLM 에이전트이기 때문입니다. LLM 에이전트는 의도를 복원하지 않고 추측이라는 쉬운 길을 선택합니다.