제가 계속해서 마주쳤던 버그가 하나 있습니다. AI 어시스턴트에게 특정 라이브러리 — Prisma, Vercel AI SDK, Zod 등 — 를 사용하여 코드를 작성해 달라고 요청하면, 코드는 완전히 올바르게 보입니다. 깔끔하고, 관용적이며, 정확히 제가 기대했던 형태입니다. 하지만 막상 실행해 보면 컴파일이 되지 않습니다.

이유는 항상 같았습니다. 라이브러리는 새로운 메이저 버전(major version)을 출시했는데, 모델은 기억에 의존하여 이전 메이저 버전의 API를 작성하고 있었던 것입니다. inputSchema 대신 parameters를 사용하거나, error 대신 required_error를 사용하는 식입니다. 더 이상 존재하지 않는 new PrismaClient({ datasources }) 호출도 있었습니다. 사소한 것들이지만, 첫 시도에서 빌드를 깨뜨리기에는 충분했습니다.

모델은 학습 중단 시점(training cutoff)에 고정되어 있습니다. 하지만 라이브러리는 그렇지 않습니다. 따라서

중요한 설계 세부 사항 하나는 다음과 같습니다. 프롬프트(prompt)는 함수 이름은 명시하지만, 옵션 이름은 절대 명시하지 않습니다. 저는 “inputSchema를 사용하세요”라고 요청하는 대신, “설명과 입력 스키마(input schema)를 가진 도구(tool)”를 요청합니다. 그렇게 함으로써 모델이 제가 이미 건네준 이름을 단순히 따라 하는지(echo back)가 아니라, 모델이 자연스럽게 무엇을 선택하는지를 측정할 수 있습니다.

발견한 내용

세 가지 SDK를 대상으로 claude-opus-4-8을 실행한 결과입니다:

다음은 대표적인 실수 사례입니다. AI SDK를 사용하여 도구 정의(tool definition)를 요청하면 다음과 같은 결과를 받게 됩니다:

import { tool } from 'ai';
import { z } from 'zod';

...

맞아 보입니다. 하지만 ai v7에 대해 tsc(TypeScript compiler)는 다음과 같이 말합니다:

error TS2353: Object literal may only specify known properties,
and 'parameters' does not exist in type 'Tool<...>'.

옵션 이름이 inputSchema로 변경되었기 때문입니다:

const weatherTool = tool({
  description: 'Get the weather for a city',
  inputSchema: z.object({ city: z.string() }), // ✓ v5+
...

코드의 다른 모든 부분은 괜찮습니다. 단 하나의 변경된 키 때문이며, 이는 대충 읽었을 때는 그냥 지나치기 쉽지만 빌드(build)를 완전히 중단시켜 버리는 바로 그런 종류의 문제입니다.

패턴: 준비도(readiness)는 드리프트 창(drift window)을 추적한다

흥미로운 점은 개별 점수 자체가 아니라, 점수가 왜 다른가 하는 점입니다.

가장 최근의 파괴적 변경 사항(breaking change)이 가장 낮은 점수를 기록한다는 점에 주목하십시오. Vercel AI SDK와 Zod는 2025년에 이름 변경을 배포했습니다. 현재 모델은 이를 대부분 흡수하여 대부분 정확하게 작성합니다 (90/100). Prisma 7은 더 최근의 것이며, 모델이 아직 따라잡지 못했습니다 (80/100). 모델은 여전히 삭제된 설정 호출을 작성합니다.

이것이 전체 논지입니다. SDK에 대한 모델의 "준비도(readiness)"는 해당 SDK가 얼마나 최근에 변경되었는지를 추적합니다. 이는 이것이 일회성 감사(audit)가 아니라는 것을 의미합니다. 그 격차는:

• 라이브러리가 새로운 메이저(major) 버전을 출시할 때마다 다시 열리고,
• 모델이 재학습(retrained)될 때마다 이동합니다.

따라서 이것은 한 번 측정하고 끝내는 것이 아니라, _모니터링(monitor)_해야 하는 대상입니다. 오늘 95점을 받은 라이브러리가 다음 버전(v-next)을 출시하는 주에는 70점으로 떨어질 수 있으며, 이후 다음 세대의 모델이 이를 학습함에 따라 다시 상승할 수 있습니다.

솔직한 한계점

수치를 과장하기보다는 여러분이 그 수치를 신뢰할 수 있도록 한계를 명확히 밝히고자 합니다.

• 타입 체크(Type-check)만 수행합니다. 이 도구는 코드가 실제 현재의 API 표면(API surface)을 사용하는지 측정할 뿐, 코드가 올바르게 실행되는지 여부는 측정하지 않습니다. 깨끗하게 컴파일된다고 해서 버그가 없다는 뜻은 아닙니다.
• 현재는 단일 모델만 지원합니다. 시간이 지남에 따라 모델 간의 성능을 비교하는 것이 계획이며, 단일 모델은 시작점일 뿐 전체를 대변하지 않습니다.
• 스냅샷(Snapshot)입니다. 모든 점수는 특정 패키지 버전 및 모델 버전과 결합되어 있습니다. 두 요소 모두 계속 변합니다.

이러한 한계가 신호(signal) 자체를 훼손하는 것은 아니며, 단지 그 범위를 규정할 뿐입니다. "모델이 여전히 존재하는 API 표면을 호출하는가?"는 실질적이고 유용한 질문이며, 컴파일러는 주관 없이 이에 답합니다.

이것이 중요한 이유

• AI를 사용하여 코드를 작성한다면: 라이브러리가 메이저(major) 업데이트를 출시한 직후에 가장 회의적인 태도를 유지하십시오. 바로 그때가 "맞아 보이는 것"과 "컴파일되는 것"이 갈라지는 시점입니다. 버전을 고정(pin)하고 차이점(diff)을 확인하십시오.
• SDK를 유지 관리한다다면: 파괴적 변경(breaking change)이 포함된 메이저 버전을 출시하는 날, AI의 도움을 받는 사용자들은 모델이 따라잡을 때까지 첫 시도부터 깨진 코드를 마주하게 됩니다. 이는 현재 눈에 보이지 않는 지원 및 인식 비용입니다. SDKProof는 이를 가시화합니다.

오픈 소스입니다 — 여러분의 SDK를 추가하세요

SDK를 추가하는 데는 오후 시간 정도면 충분합니다. 패키지를 설치하고, tsconfig를 추가하고, 태스크(tasks) 파일을 작성하고, 등록하기만 하면 됩니다. 테스트 하네스(harness)가 생성, 타입 체크 및 점수 산출을 처리합니다.

• 대시보드 + 전체 분석: sdkproof.dev
• 코드: github.com/Kalpitrathore/sdkproof

저는 점수를 매길 다음 SDK들을 찾고 있습니다. 라이브러리의 마지막 메이저 업데이트 이후, AI 어시스턴트가 잘못 작성하는 것을 목격한 라이브러리가 있나요? 알려주시면 제가 실행해 보겠습니다.