Claude Files·Skills API beta header 제거 대응법: SDK 업그레이드 전에 깨질 지점을 찾는 방법

Claude Files API와 Skills API를 쓰는 팀은 2026년 8월 27일 release notes를 꼭 봐야 한다. Anthropic은 Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0, C# SDK 12.44.0에서 client.beta.files와 client.beta.skills가 더 이상 files-api-2025-04-14, skills-2025-10-02 beta header를 보내지 않는다고 밝혔다. 결과 shape도 정식 client.files, client.skills와 같아진다.

요약하면 “beta 네임스페이스를 계속 호출해도 예전 beta 응답 모양을 기대하면 깨질 수 있다”는 뜻이다. 특히 client.beta.skills.delete()가 Skill과 모든 version을 함께 삭제하고, beta Messages 타입 BetaSkill이 container Skill reference를 뜻하는 BetaContainerSkill로 바뀌는 부분은 코드 영향이 있다.

왜 이 마이그레이션이 위험한가

API 마이그레이션에서 가장 무서운 변화는 컴파일 에러가 아니라 조용한 의미 변화다. 함수 이름은 그대로인데 응답 shape가 바뀌거나 delete 동작 범위가 달라지면 테스트가 빈약한 코드에서 뒤늦게 터진다. 이번 Claude Skills API migration도 그 부류다.

예를 들어 관리 콘솔에서 skill version 하나만 지우는 UI를 만들었다고 하자. 내부에서 client.beta.skills.delete()를 호출하고 있었다면, SDK 업그레이드 후 “container Skill 전체와 모든 version 삭제” 의미로 바뀔 수 있다. 이건 단순 호환성 문제가 아니라 데이터 손실로 이어질 수 있는 운영 사고다.

Files API도 마찬가지다. 8월 19일 release notes에는 Files API가 Claude API에서 beta를 벗어나며 /v1/files 요청과 Messages API의 file reference가 더 이상 beta header를 요구하지 않는다고 되어 있다. 새 응답 형식에는 file expiration, expires_in_seconds, expires_at, pagination, ids[] filter 같은 요소가 들어간다. 기존 코드가 예전 list 응답 구조만 가정하면 페이지 누락이나 만료 처리 누락이 생길 수 있다.

영향 범위를 찾는 순서

첫 단계는 SDK 버전을 고정해서 보는 것이다. package lock, requirements, go.mod, pom.xml, Gemfile, csproj를 확인한다. release notes에 명시된 버전 이상으로 올라가는 순간 동작이 바뀔 수 있다. 특히 caret range나 renovate 자동 merge를 쓰는 팀은 이미 올라갔을 가능성이 있다.

두 번째 단계는 beta namespace 사용처를 grep하는 것이다. client.beta.files, client.beta.skills, BetaSkill, files-api-2025-04-14, skills-2025-10-02 문자열을 찾는다. 단순 호출뿐 아니라 타입 정의, mock, fixture, API gateway 변환 코드도 봐야 한다.

세 번째 단계는 delete와 list를 분리해서 검토하는 것이다. delete는 피해가 크고, list는 조용히 누락될 수 있다. Skill 삭제 기능이 있다면 “version 삭제”인지 “container 삭제”인지 UI와 API 의미를 다시 맞춘다. Files list는 pagination과 expiration을 테스트에 넣는다.

테스트 케이스는 기능보다 계약을 검증해야 한다

마이그레이션 테스트는 “파일 업로드가 된다” 수준이면 부족하다. 응답 계약을 검증해야 한다. 예를 들어 파일 업로드 후 expires_at이 존재하는지, list pagination이 next_page를 반환할 때 다음 페이지를 가져오는지, ids[] filter가 기대한 파일만 반환하는지 확인한다.

Skills API는 더 조심해야 한다. 테스트 workspace에 container Skill 하나와 version 두 개를 만든다. 그런 다음 삭제 함수가 어떤 범위를 지우는지 dry-run UI 또는 staging에서 확인한다. production에서 바로 delete를 검증하면 안 된다. 삭제 API 앞에는 가능하면 confirmation token이나 soft-delete 계층을 둔다.

타입스크립트에서는 BetaSkill 타입 이름 변경이 컴파일 에러로 드러날 수 있다. 하지만 Python이나 Ruby에서는 런타임까지 숨어 있을 가능성이 있다. 따라서 mock 응답도 최신 shape로 바꿔야 한다. 오래된 fixture를 유지하면 테스트가 거짓 안정감을 준다.

배포 전략: 한 번에 올리지 않는다

SDK 업그레이드와 API 의미 변경을 같은 PR에 묶으면 리뷰가 어렵다. 먼저 현재 버전에서 사용처를 정리하고, beta header 의존 여부를 로그로 확인한다. 다음 PR에서 SDK를 올리고 fixture를 바꾼다. 마지막으로 beta namespace를 정식 namespace로 이동한다.

운영 중인 시스템이라면 feature flag를 둔다. 파일 처리 경로와 skill 관리 경로를 각각 새 client로 보내고, 실패율과 응답 shape 오류를 본다. 특히 background job이 Files API를 쓰는 경우 queue 재시도 정책을 확인해야 한다. 만료된 파일을 무한 재시도하면 비용과 로그가 불어난다.

관리자 콘솔에는 삭제 동작 설명을 명확히 써야 한다. “이 Skill과 모든 version을 삭제합니다” 같은 문구가 없으면 운영자가 예전 의미로 착각할 수 있다. API 변화는 코드만의 문제가 아니다. 내부 운영 문서도 같이 바뀌어야 한다.

기존 beta header를 계속 보내야 하는 경우

release notes는 요청이 여전히 beta header를 보내면 beta shapes를 계속 받는다고 설명한다. 즉 즉시 전환이 어렵다면 명시적으로 header를 유지하는 임시 전략을 쓸 수 있다. 하지만 이것은 시간 벌기다. SDK가 beta namespace에서 더 이상 header를 자동 전송하지 않는다면, 커스텀 client나 raw request 계층이 필요할 수 있다.

장기적으로는 정식 API shape로 이동하는 게 맞다. beta header에 남아 있으면 새 기능, 문서, SDK 타입의 기준과 어긋난다. 다만 삭제 의미처럼 위험한 부분은 별도 migration window를 잡아야 한다.

실행 체크리스트

• 사용 중인 Claude SDK 버전이 release notes의 변경 버전 이상인지 확인한다.
• client.beta.files, client.beta.skills, BetaSkill, beta header 문자열을 전부 검색한다.
• Skill 삭제 기능이 version 삭제인지 container 삭제인지 UI 문구와 API 호출을 맞춘다.
• Files list 코드는 pagination, next_page, ids[] filter를 처리하는지 확인한다.
• 파일 만료 필드 expires_in_seconds, expires_at을 테스트 fixture에 반영한다.
• mock 응답을 최신 정식 shape로 갱신한다.
• SDK 업그레이드 PR과 namespace 정리 PR을 분리한다.
• production 삭제 API에는 confirmation, soft-delete, 감사 로그를 붙인다.

출처: Claude Platform release notes, 2026년 8월 19일 및 8월 27일 Files·Skills API 업데이트.