웹 개발 데일리 브리핑 — 2026-11-18
Soshy··조회수 —

기준 시점: 2026-11-18 06:00 KST
조사 범위: 전일 2026-11-17 06:00 ~ 당일 2026-11-18 06:00 KST
추천 글 범위: 기준 시점 당시 최근 7일
1️⃣ 프론트엔드
Vercel Preview Deployment, Pull Request가 있는 Branch만 빌드하는 설정 추가
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인. 게시 날짜가 KST 조사 범위와 겹쳐 포함
- 발표 주체: Vercel
- 안정화 단계: 정식 배포 설정 기능
- 적용 대상: Vercel의 GitHub·GitLab 연동 프로젝트
- 변경 내용: 열린 Pull Request가 없는 Branch의 Preview Build 자동 생략
- 원문: https://vercel.com/changelog/pull-request-only-preset-now-available-for-preview-builds
Vercel이 Preview Deployment의 실행 조건을 더 간단하게 관리할 수 있도록 새로운 Ignored Build Step Preset을 추가했다.
새로운 설정의 이름은 다음과 같다.
Only build previews for pull requests
이 설정을 활성화하면 열린 Pull Request가 존재하는 Branch에 대해서만 Preview Build를 실행할 수 있다.
기존에는 Branch에 새로운 Commit을 Push할 때마다 Preview Deployment가 생성되는 구성을 사용할 수 있었다.
이 방식은 개발자가 변경 사항을 빠르게 확인하는 데 편리하다. 하지만 실제로 모든 Commit마다 별도의 배포가 필요한 것은 아니다.
기존 Preview Build의 문제
예를 들어 하나의 Next.js 프로젝트에서 다음과 같은 개발 작업을 진행한다고 가정해 보자.
- 새로운 기능 Branch 생성
- 첫 번째 Commit Push
- 코드 정리 후 두 번째 Commit Push
- 테스트 수정 후 세 번째 Commit Push
- Pull Request 생성
- 코드 리뷰 이후 네 번째 Commit Push
기존 Preview 설정에서는 각 Push마다 빌드가 실행될 수 있었다.
따라서 Pull Request가 생성되기 전에도 여러 Preview Deployment가 만들어진다.
이러한 구조에서는 실제 개발자가 확인하지 않는 Preview에도 빌드 자원이 사용될 수 있다.
특히 Monorepo 또는 정적 페이지 수가 많은 프로젝트에서는 빌드 시간이 길어질 수 있다.
이번 기능은 이러한 불필요한 빌드 실행을 줄이기 위한 것이다.
새로운 동작
새로운 Preset을 활성화하면 다음과 같이 처리된다.
| 상황 | Preview Build |
|---|---|
| 열린 PR이 없는 Branch에 Push | 생략 |
| 열린 PR이 있는 Branch에 Push | 실행 |
| Production Deployment | 기존대로 실행 |
중요한 부분은 Production Deployment의 동작을 변경하지 않는다는 점이다.
이번 설정은 실제 운영 환경의 배포를 중단하는 기능이 아니라 Preview Build의 실행 조건을 제한하는 기능이다.
또한 GitHub와 GitLab을 사용하는 프로젝트에서 생략된 Preview Deployment는 빌드 CPU 시간이 소비되기 전에 취소된다.
따라서 단순히 빌드를 시작한 뒤 중간에 종료하는 방식과 구분된다.
설정 방법
Vercel Dashboard의 다음 위치에서 활성화할 수 있다.
Deployments > Configuration
이후 Ignored Build Step의 Behavior 메뉴에서 다음 항목을 선택한다.
Only build previews for pull requests
이번 Preset은 필요한 Ignore 명령을 자동으로 구성한다.
따라서 개발자가 직접 Shell Script를 작성해 현재 Branch에 열린 Pull Request가 존재하는지 확인할 필요가 줄어든다.
비용과 개발 경험의 트레이드오프
이번 변경은 빌드 CPU 사용량을 줄이는 데 도움이 될 수 있다.
하지만 모든 프로젝트에 적합한 것은 아니다.
예를 들어 개발자가 Pull Request를 생성하기 전에 실제 Preview URL에서 기능을 검증하는 작업 방식을 사용한다고 가정해 보자.
새로운 설정에서는 해당 Preview가 자동 생성되지 않는다.
따라서 기존 개발 프로세스와 충돌할 수 있다.
또한 이번 기능이 실제 Build의 실행 시간을 단축하는 것은 아니다.
실제로 필요한 Build 하나의 CPU 비용은 기존과 같을 수 있다.
변경된 것은 불필요한 Build의 실행 여부다.
공식 발표에는 전체 빌드 비용이 몇 퍼센트 감소했는지에 관한 Benchmark가 포함되지 않았다.
Pull Request를 중심으로 개발과 리뷰를 진행하는 팀이 실제로 필요하지 않은 Preview Deployment의 실행을 줄일 수 있도록 한 배포 정책 변경이다.
이번 조사 범위에서 React, Next.js, Vue, Nuxt, Angular, Svelte, SvelteKit, Astro, Remix의 이외에 포함할 만한 주요 신규 안정 기능을 확인하지 못했습니다.
각 프로젝트의 공식 블로그와 릴리스 채널을 확인했으며, 개발 브랜치의 Commit이나 Canary 변경만으로 새로운 안정 기능이 출시됐다고 판단하지 않았다.
이전 브리핑에서 다룬 Next.js 16.5 계열의 Turbopack 및 RSC 내부 변경, Angular 22.2.6·22.3.0 RC, Astro 7.4 계열 패치도 반복하지 않았다.
이번 추천 글에서는 Next.js의 Cache Components를 기존 캐시 구조와 비교한 상세한 마이그레이션 자료와 실제 1,093개 페이지의 내부 링크를 분석한 사례를 선정했다.
2️⃣ 웹 플랫폼·브라우저
WebKit, Spatial CSS 개발자 Preview 공개 — CSS로 여러 3D 모델의 배치·조명·상호작용 제어
- 공식 게시일: 2026-11-16
- 정확한 게시 시각: 미확인
- 조사 범위 판정: 공식 사이트에 날짜만 표시돼 있으며 시간대가 확인되지 않음. 11월 16일의 미국 현지 게시 시각에 따라 11월 17일 06:00 KST 이후에 해당할 가능성이 있어 조건부 포함
- 발표 주체: WebKit
- 기술 단계: Spatial CSS Developer Preview
- 지원 환경: Safari on visionOS 27.3
- 활성화 조건: CSS Portals Feature Flag
- 공식 원문: https://webkit.org/blog/18621/introducing-spatial-css-a-developer-preview/
- 관련 규격 초안: https://drafts.csswg.org/
WebKit이 Spatial CSS의 초기 구현을 공개했다.
이번 기능은 일반적인 웹페이지의 2D Layout을 변경하는 새로운 CSS 속성 하나를 추가한 것이 아니다.
브라우저 안에서 여러 3D 객체를 하나의 공간에 배치하고 기존 CSS와 비슷한 선언적인 방식으로 위치, 회전, 조명 및 상호작용을 관리할 수 있도록 하는 실험적 기능이다.
현재 구현은 HTML의 <model> 요소를 중심으로 한다.
하지만 장기적인 규격 제안은 웹의 다른 콘텐츠도 공간적인 표현에 활용할 수 있도록 하는 방향을 포함한다.
기존 3D 웹 콘텐츠의 구조
일반적인 웹사이트에서는 3D 콘텐츠를 표시하기 위해 다음 기술을 사용할 수 있다.
- Three.js
- WebGL
- WebGPU
- 별도의 3D Viewer
예를 들어 가구 판매 사이트를 생각할 수 있다.
사용자는 책상과 의자를 3D로 확인하고 싶어 한다.
두 객체를 같은 장면에 배치하고 위치를 조정하려면 일반적으로 3D Scene과 Camera, Transform을 관리해야 한다.
이번 Spatial CSS Preview는 이러한 구성의 일부를 CSS 방식으로 표현하는 접근을 제안한다.
다만 모든 기존 3D Rendering Engine을 대체하는 기술로 정식 출시된 것은 아니다.
현재는 제한된 개발자 Preview다.
spatial: portal
첫 번째 핵심 기능은 다음 선언이다.
spatial: portal
예를 들어 다음과 같은 HTML을 생각할 수 있다.
<div class="world">
이 요소 안에 여러 <model>이 존재한다.
각 모델은 다음과 같은 실제 3D 객체일 수 있다.
- 책상
- 의자
- 조명
부모 요소에 spatial: portal을 지정하면 여러 모델이 공유하는 공간을 정의할 수 있다.
따라서 모델 하나하나를 독립적으로 표시하는 방식에서 벗어나 같은 공간 안에서 여러 모델을 구성할 수 있다.
현재 Preview에서는 주로 <model> 요소에 초점을 맞춘다.
3D Transform
이번 기능에서는 기존 CSS의 transform을 공간적인 객체에 적용할 수 있다.
예를 들어 다음 표현이다.
transform: translateX(-50cm)
일반적인 CSS에서 사용하는 Pixel이나 Percentage와 달리 실제 공간에서 사용하는 길이 단위가 등장한다.
WebKit의 예제에서는 서로 다른 3D 블록을 왼쪽과 오른쪽으로 이동시킨다.
또한 회전과 크기 조정도 같은 방식으로 구성할 수 있다.
중요한 점은 같은 transform이라는 속성을 사용하더라도 일반적인 2D 요소의 변환과 실제 3D 모델의 공간 변환은 실행 환경이 다르다는 사실이다.
따라서 기존 브라우저에서 모든 Transform이 자동으로 공간적인 3D 변환으로 처리된다고 판단해서는 안 된다.
position-anchor
두 번째 핵심 기능은 3D 객체 사이의 배치 관계다.
예를 들어 책상 위에 조명을 올려놓는 상황을 생각할 수 있다.
조명의 위치를 임의의 숫자로만 지정하면 책상의 크기나 방향이 변경됐을 때 문제가 발생할 수 있다.
Spatial CSS에서는 Anchor를 이용해 객체의 상대적인 배치 관계를 표현할 수 있다.
대표적인 속성은 다음과 같다.
anchor-nameposition-anchorposition-context
WebKit의 예제에서는 다음과 같은 참조를 사용한다.
position-anchor: --board#octagon-position
이는 3D 모델 내부에 정의된 특정 Anchor 위치를 참조하는 방식이다.
예를 들어 Blender에서 조립 부품의 정확한 위치를 미리 정의할 수 있다.
이후 웹페이지에서는 해당 Anchor를 사용해 다른 모델을 배치한다.
이렇게 하면 3D 모델의 내부 구조와 웹페이지의 배치 규칙을 연결할 수 있다.
@environment-map
이번 Preview에는 조명 관련 기능도 포함됐다.
대표적인 선언은 다음과 같다.
@environment-map
Environment Map은 실제 3D 객체에 반사되는 주변 환경과 조명을 표현하는 데 사용된다.
예를 들어 같은 제품 모델을 다음 환경에 표시한다고 가정해 보자.
- 밝은 전시장
- 어두운 방
- 야외
3D 모델의 Geometry는 같더라도 실제 조명 환경에 따라 표면의 색과 반사가 달라질 수 있다.
이번 기능에서는 360도 HDR 이미지를 Environment Map으로 지정할 수 있다.
그리고 CSS에서 해당 Environment Map을 선택할 수 있다.
따라서 여러 3D 객체가 같은 조명 환경을 공유하도록 구성할 수 있다.
하지만 실제 물리 기반 렌더링의 정확성과 성능은 모델과 구현체에 영향을 받는다.
portal-action: orbit
3D 제품 Viewer에서는 사용자가 모델을 회전해 다른 방향에서 보고 싶어 할 수 있다.
이번 Preview에는 다음 기능이 포함됐다.
portal-action: orbit
이는 사용자가 3D Scene을 회전해 살펴보는 상호작용을 제공하기 위한 것이다.
기존 JavaScript 기반 3D Viewer에서는 이러한 상호작용을 직접 구현하거나 별도의 Control Library를 사용해야 할 수 있었다.
Spatial CSS는 이러한 행동을 선언적인 방식으로 표현하려는 방향을 보여준다.
다만 현재 Preview에서 지원하는 상호작용은 제한적이다.
복잡한 Physics나 Collision, 사용자 정의 Camera Control을 모두 대체하는 것은 아니다.
requestVolumetricScene()
이번 발표에는 다음 API도 포함됐다.
requestVolumetricScene()
이 API는 브라우저의 Portal 안에 표시한 3D 콘텐츠를 사용자 주변의 공간적인 장면으로 표시하도록 요청할 수 있다.
예를 들어 사용자가 가구의 3D 모델을 보고 있다고 가정해 보자.
사용자는 버튼을 눌러 해당 모델을 자신의 공간에 배치할 수 있다.
WebKit은 브라우저의 콘텐츠와 공간적인 장면 사이의 연결을 유지할 수 있다고 설명한다.
따라서 웹페이지에서 실제 모델을 변경하면 공간적인 장면에도 변경이 반영될 수 있다.
하지만 이 기능은 visionOS의 공간 컴퓨팅 환경에 의존한다.
일반적인 데스크톱 Chrome에서 동일한 API를 사용할 수 있다는 의미는 아니다.
활성화 방법
현재 개발자 Preview는 Vision Pro 또는 visionOS Simulator에서 테스트할 수 있다.
실제 설정 경로는 다음과 같다.
Settings > Apps > Safari > Advanced > Feature flags > CSS Portals
따라서 일반 사용자에게 기본 제공되는 안정 기능은 아니다.
개발자는 관련 Feature Flag를 활성화한 뒤 테스트할 수 있다.
표준화와 브라우저 호환성
이번 발표는 Spatial CSS의 규격 초안과 함께 제공됐다.
하지만 규격 초안이 존재한다는 사실은 해당 기능이 웹 표준으로 정식 확정됐다는 의미가 아니다.
또한 다른 주요 브라우저 엔진에서 같은 기능을 구현했다고 판단할 수도 없다.
현재는 특정 플랫폼과 브라우저에서 제공하는 Developer Preview다.
공식 발표에는 실제 3D Scene의 Frame Time과 GPU 사용량, JavaScript 기반 Renderer와의 성능 비교 결과가 포함되지 않았다.
따라서 Spatial CSS를 사용하면 모든 3D 웹 애플리케이션의 성능이 개선된다고 단정해서는 안 된다.
이번 발표는 기존 CSS의 선언적인 설계 방식과 HTML 기반 3D 모델을 결합해 공간적인 웹 콘텐츠를 구성하려는 초기 구현을 공개한 것이다.
이번 조사 범위에서 W3C, WHATWG, TC39, MDN, Chrome·Chromium, Firefox·Mozilla의 이외에 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
특히 표준화 기구의 규격 초안과 브라우저 개발 브랜치의 변경, 실제 안정 버전에서 기본 제공되는 기능은 구분했다.
Firefox 160의 WebTransport 변경과 기기 내 음성 인식, 보안 수정은 이전 브리핑에서 이미 다뤘으므로 반복하지 않았다.
3️⃣ 백엔드·인프라
Vercel Blob, 파일 자동 삭제를 위한 TTL 정식 지원 — 업로드부터 1~730일 후 삭제하고 기존 파일의 만료일도 변경
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: Vercel
- 안정화 단계: 정식 기능
- 적용 대상: Vercel Blob,
@vercel/blob2.9.0 이상, Vercel CLI 65.16.0 이상 - 주요 기능: 파일별 TTL 설정, 만료일 조회, 기존 파일의 TTL 변경·제거
- 원문: https://vercel.com/changelog/vercel-blob-now-supports-ttls-for-automatic-deletion
Vercel이 Blob Storage에 파일의 자동 삭제 시점을 설정하는 기능을 추가했다.
TTL(Time To Live)은 특정 데이터가 얼마나 오래 유효하게 유지되는지 나타내는 값이다.
이번 업데이트에서는 파일을 업로드할 때 TTL을 지정하면 해당 기간 이후 파일을 자동으로 삭제할 수 있다.
특히 임시 업로드와 다운로드용 파일을 관리하는 웹 애플리케이션에 영향을 줄 수 있다.
기존 파일 삭제 방식
예를 들어 사용자가 보고서를 생성하는 서비스를 운영한다고 가정해 보자.
사용자는 보고서 생성 버튼을 누른다.
서버는 CSV 파일을 생성한다.
이후 Vercel Blob에 파일을 업로드한다.
사용자는 다운로드 URL을 전달받는다.
문제는 다운로드가 완료된 이후다.
파일을 별도로 삭제하지 않으면 저장소에 계속 남을 수 있다.
기존에는 개발자가 다음과 같은 삭제 작업을 직접 구현해야 할 수 있었다.
- 파일 업로드
- 파일의 생성 시각 기록
- 일정 주기의 Cleanup 작업 실행
- 만료된 파일 검색
- 삭제 API 호출
- 실패한 삭제 작업 재시도
이러한 구조에는 별도의 데이터베이스나 Cron Job이 필요할 수 있다.
이번 기능은 파일 자체에 만료 기간을 지정하도록 한다.
ttlDays
새로운 설정은 다음과 같다.
ttlDays
허용 범위는 다음과 같다.
1~730일
예를 들어 7일 동안만 유지할 파일을 업로드할 수 있다.
ttlDays: 7
Vercel은 업로드 시점을 기준으로 만료일을 계산한다.
따라서 같은 파일을 업로드한 이후 7일이 지나면 자동 삭제 대상이 된다.
중요한 부분은 TTL의 기준 시점이다.
TTL은 파일을 마지막으로 조회한 시점이 아니라 업로드한 날짜를 기준으로 계산된다.
따라서 파일을 여러 번 다운로드했다고 해서 자동으로 만료 기간이 연장되는 것은 아니다.
지원 API
이번 기능은 다음 작업에서 사용할 수 있다.
put()copy()putImage()- Multipart Upload
- Presigned Upload URL
예를 들어 브라우저에서 직접 파일을 업로드하는 기능을 생각할 수 있다.
Presigned Upload URL을 사용하는 경우에도 TTL을 지정할 수 있다.
따라서 파일의 업로드 경로가 다르다는 이유로 별도의 삭제 정책을 작성할 필요가 줄어든다.
expiresAt
이번 업데이트에서는 파일의 만료일도 확인할 수 있다.
관련 필드는 다음과 같다.
expiresAt
이 값은 업로드 결과와 head() 응답에 포함된다.
예를 들어 사용자가 업로드한 파일을 관리하는 화면에서 다음 정보를 표시할 수 있다.
이 파일은 2026년 11월 25일에 삭제될 예정입니다.
하지만 실제 만료 시각과 해당 시각에 물리적인 데이터 삭제가 완료되는 순간을 동일하게 취급해서는 안 된다.
실제 삭제 처리에는 Storage 시스템의 실행 정책이 적용될 수 있다.
기존 파일의 TTL 변경
이번 기능에서는 이미 업로드한 파일의 TTL도 변경할 수 있다.
관련 API는 다음과 같다.
setTtl()
예를 들어 다음 작업이 가능하다.
- 7일에서 30일로 변경
- 30일에서 1일로 단축
- TTL 제거
TTL을 제거할 때는 다음 값을 사용한다.
ttlDays: null
중요한 점은 파일을 다시 업로드할 필요가 없다는 것이다.
이미 저장된 Blob의 만료 설정만 변경할 수 있다.
또한 한 번에 최대 1,000개 URL에 대해 TTL을 변경할 수 있다.
따라서 기존 파일에도 새로운 보관 정책을 일괄 적용할 수 있다.
CLI 지원
Vercel CLI 65.16.0 이상에서는 다음 옵션을 사용할 수 있다.
--ttl-days
대표적인 명령은 다음과 같다.
vercel blob put report.csv --ttl-days 7
기존 파일의 TTL을 변경할 때는 다음 명령을 사용할 수 있다.
vercel blob set-ttl
따라서 SDK 코드뿐 아니라 관리 Script에서도 파일 보관 기간을 설정할 수 있다.
실제 과금 방식
이번 기능에서 중요한 제한사항은 과금이다.
Vercel은 TTL을 설정할 때 Advanced Operation 비용이 발생한다고 명시했다.
기준은 다음과 같다.
시작된 60일마다 Advanced Operation 1회
예를 들어 다음과 같다.
| TTL | Advanced Operation |
|---|---|
| 7일 | 1회 |
| 60일 | 1회 |
| 61일 | 2회 |
| 730일 | 13회 |
이는 파일을 업로드하는 작업 자체의 비용과 별개다.
따라서 TTL을 설정하면 삭제 관리 코드는 줄어들 수 있지만 Storage 관련 작업 비용이 추가될 수 있다.
반면 TTL을 제거하거나 실제 만료로 파일이 삭제되는 작업에는 별도 비용이 발생하지 않는다고 설명한다.
따라서 파일 수와 보관 기간에 따라 실제 비용을 계산해야 한다.
실제 데이터 보관 정책과의 관계
이번 기능은 임시 파일을 관리할 때 유용할 수 있다.
예를 들어 다음 파일이다.
- 임시 보고서
- 사용자 업로드
- AI 대화 Export
- 일정 기간만 제공하는 다운로드 파일
하지만 TTL이 존재한다는 사실만으로 모든 개인정보 삭제 요구사항을 충족한다고 판단해서는 안 된다.
예를 들어 실제 데이터가 다음 위치에도 존재할 수 있다.
- 애플리케이션 데이터베이스
- 별도의 백업
- CDN Cache
- 분석 로그
Blob 파일의 만료 설정은 해당 Storage에 존재하는 파일에 관한 것이다.
다른 저장 위치의 데이터까지 자동으로 삭제하는 것은 아니다.
적용 범위와 한계
이번 발표에는 파일 조회 성능이나 삭제 처리 시간의 정량적인 Benchmark가 포함되지 않았다.
또한 TTL을 설정한다고 해서 저장된 파일의 접근 권한이 자동으로 제한되는 것은 아니다.
파일의 공개·비공개 설정은 별도로 관리해야 한다.
이번 업데이트는 일정 기간만 유지해야 하는 파일에 대해 별도의 Cleanup Scheduler를 구현하지 않고 Storage 자체의 만료 정책을 이용할 수 있도록 한 정식 기능이다.
Cloudflare AI Search, 파일 인덱싱 단계에서 자동 요약·주제·키워드 생성 지원
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: Cloudflare
- 안정화 단계: 기존 AI Search의 정식 설정 기능
- 적용 대상: AI Search, Workers AI, AI Gateway
- 신규 설정:
indexing_options.file_summary - 기본값: 비활성화
- 원문: https://developers.cloudflare.com/changelog/post/2026-11-17-file-summaries/
Cloudflare가 AI Search에서 파일을 인덱싱할 때 자동으로 요약과 주제, 키워드를 생성할 수 있도록 기능을 추가했다.
이번 업데이트는 새로운 검색 엔진을 출시한 것이 아니다.
기존 검색 인덱스를 구성할 때 문서의 의미를 설명하는 추가 Metadata를 생성하도록 하는 기능이다.
특히 긴 문서와 많은 기술 문서를 검색하는 RAG 애플리케이션에 영향을 줄 수 있다.
기존 문서 인덱싱
예를 들어 기술 문서 검색 서비스를 운영한다고 가정해 보자.
사용자는 다음과 같이 질문한다.
API Key가 만료되면 어떻게 갱신하지?
시스템에는 관련 기술 문서가 존재한다.
하지만 실제 문서는 매우 길 수 있다.
AI Search는 해당 문서를 여러 Chunk로 나눠 인덱싱할 수 있다.
Chunk는 실제 검색에 사용할 수 있도록 나눈 문서의 일부다.
문제는 일부 Chunk만으로 전체 문서의 의미를 이해하기 어려울 수 있다는 점이다.
예를 들어 한 Chunk에는 다음 문장만 존재할 수 있다.
이 작업은 관리자가 실행해야 합니다.
하지만 어떤 작업을 설명하는지 알기 어렵다.
실제 문서 전체의 제목과 목적을 함께 제공하면 검색에 도움이 될 수 있다.
파일 요약 생성
새로운 기능에서는 텍스트 문서를 인덱싱할 때 LLM을 사용해 추가 정보를 생성한다.
대상은 다음 조건을 충족하는 문서다.
최소 세 개 이상의 Chunk가 생성되는 텍스트 문서
Cloudflare는 다음 정보를 생성한다.
- Summary
- Topics
- Keywords
Summary는 문서 전체의 내용을 요약한다.
Topics는 문서의 주요 주제를 표현한다.
Keywords는 관련 검색어를 설명하는 데 사용할 수 있다.
Metadata 저장 방식
생성된 Summary와 Keywords는 파일의 context Metadata에 저장된다.
하지만 중요한 호환성 규칙이 있다.
개발자가 이미 context 값을 지정했다면 해당 값이 유지된다.
따라서 자동 요약을 활성화했다는 이유로 기존의 모든 사용자 정의 Context가 무조건 덮어써지는 것은 아니다.
생성된 Topics는 파일 Chunk의 Context Header에도 추가된다.
이렇게 하면 실제 Chunk를 검색할 때 문서 전체의 주제 정보를 함께 활용할 수 있다.
예를 들어 특정 Chunk에 토큰 갱신이라는 표현이 직접 포함되지 않았더라도 실제 문서가 API 인증에 관한 자료라는 정보를 제공할 수 있다.
다만 이러한 Context 정보가 모든 검색의 정확도를 반드시 높인다는 보장은 없다.
실제 생성된 Summary가 부정확할 가능성도 존재하기 때문이다.
활성화 방법
새로운 기능은 기본적으로 비활성화돼 있다.
개발자는 Dashboard 또는 API에서 다음 값을 설정할 수 있다.
indexing_options.file_summary = true
이렇게 하면 새로 인덱싱하는 문서에 대해 요약 생성을 활성화할 수 있다.
하지만 실제 기존 인스턴스의 설정을 변경할 때는 중요한 사항이 존재한다.
전체 재인덱싱
Cloudflare는 file_summary 설정이 변경되면 전체 재인덱싱이 발생한다고 명시했다.
예를 들어 이미 10만 개 문서를 인덱싱한 AI Search Instance가 있다고 가정해 보자.
개발자가 파일 요약 기능을 활성화한다.
이 경우 기존 데이터에 대해서도 재인덱싱이 발생할 수 있다.
따라서 설정 하나를 변경하는 작업이더라도 실제 처리 시간과 비용에 영향을 줄 수 있다.
또한 indexing_options는 부분적으로 병합되지 않는다.
설정을 업데이트할 때 전달한 객체가 기존 옵션 전체를 대체한다.
예를 들어 기존에 여러 옵션이 존재한다고 가정해 보자.
이번 요청에서는 file_summary만 전달했다.
이 경우 생략한 다른 옵션이 기본값으로 돌아갈 수 있다.
따라서 기존 설정을 유지하려면 현재 사용 중인 다른 옵션도 함께 전달해야 한다.
이는 실제 운영 환경에서 중요하다.
Workers AI 사용 비용
이번 기능은 LLM을 이용해 문서 요약을 생성한다.
따라서 실제 추론 비용이 발생할 수 있다.
Cloudflare는 이 비용을 Workers AI 사용량으로 청구한다고 설명한다.
또한 파일 요약 작업은 기존 AI Search Ingestion 할당량에 포함되지 않는다.
요약 모델은 해당 AI Search Instance에 설정한 AI Gateway를 통해 호출한다.
별도로 설정하지 않았다면 default Gateway를 사용한다.
따라서 다음 두 비용을 구분해야 한다.
- 검색 문서의 일반적인 인덱싱 비용
- 요약 생성에 사용하는 Workers AI 추론 비용
Cloudflare는 새로 생성하거나 변경된 파일을 각각 한 번 요약한다고 설명한다.
따라서 문서 변경이 빈번한 서비스에서는 요약 생성 비용도 증가할 수 있다.
RAG 검색에서의 한계
이번 기능은 문서 검색의 Context를 풍부하게 만들 수 있다.
하지만 실제 원문을 검증하는 과정을 대체하지는 않는다.
예를 들어 요약 모델이 문서에 존재하지 않는 내용을 Summary에 포함할 수 있다.
또는 실제 문서의 중요한 예외 조건을 생략할 수 있다.
따라서 AI Search가 반환한 요약만으로 실제 보안 정책이나 API의 정확한 동작을 확정해서는 안 된다.
또한 이번 발표에는 다음 결과가 포함되지 않았다.
- 검색 Recall 개선율
- 검색 Precision 개선율
- 실제 검색 지연 시간
- 문서당 요약 생성 시간
- 독립적인 RAG Benchmark
따라서 요약 기능을 활성화하면 검색 품질이 일정한 비율로 개선된다고 단정할 수 없다.
이번 업데이트는 긴 문서를 인덱싱할 때 문서 전체의 주제와 키워드를 Chunk에 추가해 검색에 활용할 수 있도록 한 AI Search의 인덱싱 기능 확장이다.
Google BigQuery, AI.RANK() 정식 출시 — SQL에서 검색 결과를 의미적 관련성으로 재정렬
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: Google Cloud
- 안정화 단계: Generally Available
- 적용 대상: BigQuery, Agent Search Ranking API
- 신규 기능:
AI.RANK() - 공식 발표: https://docs.cloud.google.com/release-notes
- 상세 공식 문서: https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-ai-rank
Google Cloud가 BigQuery에서 AI.RANK() 함수를 정식 제공한다고 발표했다.
이 함수는 SQL Query의 결과를 단순한 문자열 일치나 숫자 기준으로 정렬하지 않는다.
검색 질문과 실제 문서의 의미적 관련성을 평가해 결과를 재정렬한다.
특히 기존 SQL 기반 서비스에 자연어 검색을 추가하는 경우에 영향을 줄 수 있다.
일반적인 Keyword Search
예를 들어 고객지원 문서가 있다고 가정해 보자.
문서 제목은 다음과 같다.
Update your login information
사용자는 다음과 같이 검색한다.
비밀번호를 재설정하려면 어떻게 해야 하나요?
두 문장에는 정확히 일치하는 단어가 많지 않을 수 있다.
하지만 실제 의미는 관련돼 있다.
일반적인 Keyword Search는 문자열이 얼마나 일치하는지에 영향을 받는다.
반면 의미적 검색에서는 문장 전체의 의미를 비교할 수 있다.
이번 AI.RANK()는 검색 질문과 각 문서의 텍스트를 함께 평가한다.
따라서 단순한 문자열 일치와 다른 방식으로 관련성을 계산할 수 있다.
AI.RANK()의 입력
기본 구조는 다음과 같다.
AI.RANK(TABLE, column_to_rank, query)
예를 들어 다음 정보를 전달할 수 있다.
- 검색할 BigQuery Table
- 실제 텍스트가 저장된 Column
- 사용자의 검색 질문
추가로 다음 옵션을 지정할 수 있다.
modeltop_n
top_n은 실제로 반환할 최대 행 수를 제한한다.
예를 들어 상위 다섯 개 결과만 필요한 경우 다음 값을 사용할 수 있다.
top_n => 5
실제 SQL 예제
공식 문서는 다음 형태를 제공한다.
SELECT rank, score, title
FROM AI.RANK(
TABLE `bigquery-public-data.bbc_news.fulltext`,
'title',
'downward trends in the housing market',
top_n => 5
);
이 Query는 BBC News 데이터에서 검색 질문에 관련된 기사 제목을 찾는다.
반환 결과에는 다음 정보가 포함된다.
rankscore- 기존 Table의 Column
따라서 검색 결과를 가져온 뒤 원래 데이터를 다시 Join할 필요가 줄어든다.
rank와 score
rank는 검색 결과의 순위다.
1부터 시작한다.
score는 해당 질문에 대한 의미적 관련성을 나타내는 값이다.
범위는 다음과 같다.
0.0 ~ 1.0
하지만 중요한 제한사항이 있다.
score는 서로 다른 Query 사이에서 직접 비교하도록 보정된 값이 아니다.
예를 들어 첫 번째 질문에서 어떤 문서가 0.8점을 받았다고 가정해 보자.
두 번째 질문에서도 다른 문서가 0.8점을 받았다.
하지만 두 점수가 동일한 수준의 확률이나 관련성을 의미한다고 판단해서는 안 된다.
Google Cloud는 실제 결과를 선택할 때 고정된 Score Threshold보다 순위나 top_n을 활용하도록 설명한다.
또한 0점은 실제 관련성이 없다는 의미일 수도 있지만 평가되지 않은 결과와 관련될 수도 있다.
따라서 Score만으로 모든 결과를 해석하면 문제가 발생할 수 있다.
Vector Search와의 차이
BigQuery에서는 Vector Search를 사용할 수도 있다.
Vector Search는 텍스트나 다른 데이터를 Embedding으로 변환한 뒤 벡터의 유사도를 계산할 수 있다.
하지만 AI.RANK()는 다른 방식으로 동작한다.
검색 질문과 각 행의 텍스트를 함께 평가한다.
Google Cloud는 이러한 방식이 실제 질문에 대한 답변의 적합성을 더 정밀하게 평가할 수 있다고 설명한다.
다만 중요한 비용상의 차이가 존재한다.
Vector Search는 Index를 이용해 큰 데이터셋에서 관련 후보를 찾을 수 있다.
반면 AI.RANK()는 Index를 사용하지 않는다.
따라서 실제 입력으로 전달한 모든 행을 평가해야 한다.
입력 행이 증가하면 처리 비용도 증가할 수 있다.
두 단계 검색 구조
Google Cloud는 다음 방식의 조합을 권장한다.
- Keyword Search 또는 Vector Search로 후보 검색
- 후보 가운데 일부를
AI.RANK()로 재정렬
예를 들어 100만 개 문서가 존재한다고 가정해 보자.
모든 문서를 AI.RANK()로 평가하면 비용이 클 수 있다.
대신 Vector Search에서 먼저 50개 문서를 선택한다.
이후 50개 문서를 AI.RANK()로 평가한다.
이러한 구조에서는 실제 검색 범위를 제한할 수 있다.
대표적인 API 조합은 다음과 같다.
VECTOR_SEARCHAI.SEARCHAI.RANK
하지만 두 단계 검색이 모든 경우에 가장 정확한 결과를 보장하는 것은 아니다.
첫 번째 단계에서 실제 관련 문서를 놓쳤다면 두 번째 Re-ranking에서도 해당 문서를 복구할 수 없기 때문이다.
따라서 후보 검색의 Recall과 Re-ranking의 정확성을 함께 고려해야 한다.
실제 권한과 API
이번 함수를 사용하려면 Discovery Engine API가 활성화돼 있어야 한다.
또한 관련 Ranking API를 호출할 수 있는 IAM 권한이 필요하다.
대표적으로 다음 권한이다.
discoveryengine.rankingConfigs.rank
Google Cloud는 Discovery Engine Viewer 역할을 관련 권한을 제공하는 역할 가운데 하나로 안내한다.
따라서 BigQuery Table을 조회할 수 있다는 사실만으로 AI.RANK()를 사용할 수 있는 것은 아니다.
실제 Ranking API의 권한과 Quota도 필요하다.
과금과 제한사항
이번 함수는 Agent Search Ranking API를 호출한다.
따라서 해당 API의 요금과 Quota가 적용된다.
또한 실제 입력 텍스트가 모델의 Token 제한을 초과하면 초과 부분이 잘릴 수 있다.
검색 대상 Column에는 String 타입이 필요하다.
그리고 입력 데이터에는 rank 또는 score라는 이름의 Column이 존재해서는 안 된다.
해당 이름이 출력 Column에 사용되기 때문이다.
NULL 또는 빈 문자열을 가진 행은 Ranking 이전에 제외된다.
따라서 반환 결과의 행 수가 원본 입력보다 작을 수 있다.
공식 발표에는 새로운 함수와 기존 검색 방식의 정확도를 동일한 조건에서 비교한 독립적인 Benchmark가 포함되지 않았다.
이번 업데이트는 BigQuery SQL에서 의미적 Re-ranking을 직접 실행하고 기존 데이터 분석 및 검색 파이프라인에 자연어 관련성 평가를 결합할 수 있도록 한 정식 기능이다.
Google App Engine Standard, Java·PHP Push Queue의 Cloud Tasks 자동 마이그레이션 정식 지원
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: Google Cloud
- 안정화 단계: Generally Available
- 적용 대상: App Engine Standard의 Java 및 PHP Legacy Bundled Services
- 변경 내용: SDK 업데이트를 통한 Push Queue의 Cloud Tasks 이전
- 공식 발표: https://docs.cloud.google.com/release-notes
- Java 마이그레이션 문서: https://docs.cloud.google.com/appengine/migration-center/standard/java/migrating-push-queues-upgrade-sdk
Google Cloud가 App Engine Standard에서 사용하는 기존 Push Queue를 Cloud Tasks로 이전하는 방법을 정식 제공한다고 발표했다.
이번 기능은 새로운 작업 Queue 서비스를 출시한 것이 아니다.
기존 App Engine의 Legacy Task Queue API를 사용하는 애플리케이션이 최신 Cloud Tasks 기반으로 이전할 수 있도록 SDK 호환 계층을 제공하는 것이다.
기존 Push Queue
일반적인 웹 애플리케이션에서는 HTTP 요청 안에서 모든 작업을 처리하기 어렵다.
예를 들어 사용자가 주문을 완료했다고 가정해 보자.
서버는 다음 작업을 수행해야 할 수 있다.
- 주문 저장
- 확인 이메일 발송
- 외부 배송 API 호출
- 재고 동기화
이러한 작업을 하나의 HTTP 요청 안에서 모두 처리하면 사용자에게 응답하기까지 시간이 길어질 수 있다.
따라서 일부 작업을 Queue에 등록하고 나중에 실행하도록 구성할 수 있다.
App Engine의 기존 Push Queue도 이러한 용도로 사용됐다.
하지만 Google Cloud는 새로운 Cloud Tasks API를 제공하고 있다.
기존 애플리케이션을 이전하려면 API의 차이를 처리해야 할 수 있었다.
코드 변경 없이 이전
이번 GA 기능의 핵심은 SDK 업데이트다.
Google Cloud는 Bundled Services SDK를 최신 버전으로 업데이트하면 기존 Push Queue 호출을 Cloud Tasks API로 전달할 수 있도록 한다.
예를 들어 기존 애플리케이션이 다음 작업을 수행한다고 가정해 보자.
PushQueue에 새로운 작업 추가
새로운 SDK는 해당 작업을 내부적으로 Cloud Tasks Frontend API에 전달한다.
따라서 기존 애플리케이션 코드를 모두 새로운 Cloud Tasks Client Library로 변경하지 않아도 될 수 있다.
또한 기존 Queue와 Task를 유지하도록 설계됐다.
따라서 별도의 데이터 이전 작업을 수행하지 않고도 마이그레이션을 진행할 수 있다.
Batch Task 지원
Java 마이그레이션 문서에서는 기존 Task Queue의 기능을 유지하기 위한 호환성도 설명한다.
대표적으로 Batch Task 생성이다.
SDK는 하나의 Batch에서 최대 100개의 Task를 추가하는 기능을 지원한다.
따라서 기존 코드에서 여러 작업을 한 번에 등록하던 구조를 유지할 수 있다.
하지만 이번 기능이 모든 Legacy Task Queue 동작과 Cloud Tasks의 새로운 API가 완전히 같다는 의미는 아니다.
실제 프로젝트에서 사용하는 세부 기능과 제한사항은 마이그레이션 문서를 통해 확인해야 한다.
실제 운영 환경에서의 고려 사항
이번 변경은 코드를 대규모로 수정하지 않고 이전할 수 있도록 한다.
하지만 SDK를 교체했다는 사실만으로 실제 실행 환경의 모든 설정이 그대로 유지된다고 보장할 수는 없다.
특히 다음 항목을 확인할 필요가 있다.
- Queue 이름
- 실제 Task의 인증 및 권한
- 재시도 정책
- Task Timeout
- 작업 처리 Endpoint
- IAM
또한 Queue 기반 시스템에는 기본적으로 중복 실행 가능성이 존재할 수 있다.
예를 들어 작업이 실제로 성공했지만 완료 기록이 정상적으로 반영되지 않을 수 있다.
이후 재시도에서 같은 작업이 다시 실행될 수 있다.
따라서 결제와 이메일 발송, 재고 차감처럼 실제 상태를 변경하는 작업에는 Idempotency가 필요할 수 있다.
적용 범위와 한계
이번 GA 발표는 Java 및 PHP App Engine Standard의 관련 SDK 마이그레이션에 관한 것이다.
모든 App Engine Runtime의 모든 Queue 기능을 같은 방식으로 변경한다는 의미는 아니다.
또한 기존 Queue API를 새로운 Cloud Tasks 기능 전체와 동일하게 사용할 수 있다는 의미도 아니다.
이번 발표에는 처리량과 Task 실행 지연이 얼마나 개선되는지에 관한 Benchmark가 포함되지 않았다.
기존 App Engine 웹 애플리케이션이 Legacy Push Queue API를 유지하면서 Cloud Tasks 기반의 실행 환경으로 이전할 수 있도록 한 호환성 기능의 정식 출시다.
이번 조사 범위에서 AWS와 Azure의 이외에 포함할 만한 주요 신규 서버리스·데이터베이스 발표는 확인하지 못했습니다.
Cloudflare Images에서는 TIFF 원본 이미지를 입력으로 받아 다른 이미지 형식으로 변환할 수 있도록 지원 범위를 확대했다.
- 발표일: 2026-11-17
- 원문: https://developers.cloudflare.com/changelog/post/2026-11-17-tiff-input-support/
TIFF를 업로드한 뒤 브라우저에서 사용하기 쉬운 AVIF 또는 WebP 등의 형식으로 변환하는 경우에 활용할 수 있다.
다만 여러 페이지가 포함된 TIFF에서는 첫 번째 페이지만 처리한다는 제한이 있다.
이번 변경은 특정 이미지 입력 형식의 지원 확대이므로 주요 상세 항목보다는 짧게 기록했다.
4️⃣ 개발 도구 및 보안
Cloudflare CLI cf 1.0 Release Candidate 공개 — Vite 기반 개발·빌드·배포 명령 통합
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: Cloudflare
- 버전:
cf1.0.0-rc.1 - 안정화 단계: Release Candidate, 정식 1.0 아님
- 적용 대상: Cloudflare Workers, Vite, Wrangler, Deployment 및 Observability
- 원문: https://developers.cloudflare.com/changelog/post/2026-11-17-release-candidate/
Cloudflare가 새로운 CLI인 cf의 1.0 Release Candidate를 공개했다.
cf는 2026년 9월 말부터 Beta로 제공됐다.
이번 버전은 1.0 정식 출시 이전에 실제 프로젝트에서 검증하도록 권장하는 출시 후보 버전이다.
이번 발표에서 중요한 부분은 단순히 CLI 버전 번호가 1.0에 가까워졌다는 사실이 아니다.
프로젝트 생성부터 개발 서버 실행, 빌드, 배포 및 운영 로그 조회에 이르는 명령 구조가 정리되고 Build Output 형식이 1.0을 위한 형태로 안정화됐다는 점이다.
통합 CLI 구조
Cloudflare는 다음 명령을 제공한다.
cf initcf devcf buildcf deploycf previews deploycf workers versions create
예를 들어 새로운 Workers 프로젝트를 생성한다고 가정해 보자.
cf init으로 프로젝트를 생성한다.
이후 cf dev로 개발 서버를 실행한다.
cf build로 실제 배포 결과물을 생성한다.
마지막으로 cf deploy로 배포한다.
이러한 구조는 여러 배포 명령과 설정을 하나의 CLI 흐름으로 관리하도록 한다.
하지만 기존 Wrangler 명령이 모두 즉시 사용할 수 없게 되는 것은 아니다.
이번 RC는 새로운 CLI의 출시 후보이며 기존 프로젝트와의 마이그레이션 경로를 함께 제공한다.
cloudflare.config.ts
Cloudflare는 다음 설정 형식을 1.0까지 안정적으로 유지할 계획이라고 발표했다.
cloudflare.config.ts
이는 TypeScript 기반의 프로젝트 설정 파일이다.
예를 들어 다음 정보를 관리할 수 있다.
- 계정 정보
- 프로젝트 설정
- 배포 관련 구성
- 필요한 Binding
이번 RC에서 안정화 대상으로 안내한 또 다른 부분은 실제 Build Output이다.
새로운 결과물 위치는 다음과 같다.
.cloudflare/output/v1/
기존 Beta의 Build Output과 경로가 다르다.
따라서 기존 Beta에서 생성한 결과물에 의존하는 자동화 Script가 있다면 확인이 필요하다.
cf deploy는 해당 위치에서 처음 실행할 때 새로운 Build를 자동으로 생성할 수 있도록 한다.
Vite Plugin 요구사항
이번 RC는 관련 의존성의 최소 버전도 변경했다.
대표적인 요구사항은 다음과 같다.
| 구성요소 | 최소 버전 |
|---|---|
| Cloudflare Vite Plugin | 2.0.0-rc.0 |
| Wrangler | 4.163.0 |
Vite를 이용하는 프로젝트에서는 새로운 Plugin 버전이 필요하다.
반면 기존 Wrangler를 이용해 빌드하는 Legacy 프로젝트에서는 호환되는 Wrangler 버전이 필요하다.
따라서 cf만 업데이트한 뒤 기존 프로젝트의 모든 빌드가 정상적으로 동작한다고 가정해서는 안 된다.
실제 프로젝트의 Plugin과 Wrangler 버전도 함께 확인해야 한다.
API 명령 이름 변경
이번 업데이트에서는 일부 명령 이름이 변경됐다.
대표적인 예는 다음과 같다.
기존 명령:
cf workers secrets bulk
새로운 명령:
cf workers secrets bulk-edit
이번 RC에서는 기존 명령의 Alias를 제공하지 않는 경우가 있다.
따라서 기존 Beta의 명령을 사용하던 Shell Script는 수정이 필요할 수 있다.
또한 API의 camelCase 또는 snake_case 이름을 CLI에서는 kebab-case로 표현하도록 정리했다.
예를 들어 다음과 같은 형태다.
getCredits → get-credits
이는 실제 CLI의 일관성을 높이기 위한 변경이지만 기존 자동화와의 호환성에는 영향을 줄 수 있다.
표준 출력과 오류 출력의 분리
이번 CLI에서는 출력 Stream도 정리됐다.
대표적으로 다음과 같이 구분한다.
- stdout: 실제 명령 결과
- stderr: Prompt, 진행 상황, 상태 메시지
이러한 구조는 CLI의 출력 결과를 다른 프로그램으로 전달하는 상황에서 중요하다.
예를 들어 다음 작업을 생각할 수 있다.
cf ... | jq
개발자는 명령의 JSON 결과를 jq로 처리하고 싶을 수 있다.
하지만 stdout에 진행 상태와 사용자 안내 문구가 함께 포함된다면 JSON Parsing이 실패할 수 있다.
새로운 구조에서는 실제 결과와 상태 메시지를 분리한다.
다만 기존 Beta에서 stdout의 안내 문구를 직접 읽던 Script가 있다면 변경이 필요할 수 있다.
배포 명령의 동작
이번 RC에는 실제 배포 과정에 관한 변경도 포함됐다.
대표적인 기능은 다음과 같다.
cf deploy ./dist
이 명령은 기존에 생성된 정적 파일을 배포하는 데 사용할 수 있다.
Cloudflare는 별도의 Build를 다시 수행하지 않고 Assets-only Worker를 생성할 수 있다고 설명한다.
또한 다음 옵션을 제공한다.
cf deploy --dry-run
이는 실제 배포와 관련된 설정 변경을 미리 확인하는 데 사용한다.
따라서 실제 배포 환경에 영향을 주기 전에 필요한 리소스 생성과 설정 변경을 검토할 수 있다.
하지만 Dry Run이 성공했다는 사실만으로 실제 배포가 반드시 성공한다고 보장할 수는 없다.
실제 네트워크 및 권한과 실행 시점의 상태에 따라 결과가 달라질 수 있기 때문이다.
기존 Wrangler 설정 마이그레이션
cf dev, cf build, cf deploy는 기존 Wrangler 설정 파일을 발견하면 마이그레이션을 제안할 수 있다.
이러한 방식은 기존 프로젝트가 새로운 CLI로 이동하는 부담을 줄이기 위한 것이다.
하지만 실제 마이그레이션에는 설정의 차이가 존재할 수 있다.
따라서 자동으로 변환된 설정이 실제 프로젝트의 요구사항을 모두 유지하는지 확인해야 한다.
특히 다음 부분이 중요하다.
- 환경 변수
- Secret
- Binding
- 배포 대상
- 로컬 개발 설정
실시간 로그
이번 RC에서는 다음 명령으로 실시간 로그를 확인할 수 있다.
cf observability tail
이 명령은 로그와 관련 Observability Event를 NDJSON 형식으로 출력한다.
NDJSON은 한 줄마다 독립적인 JSON 객체를 출력하는 형식이다.
대표적인 필터는 다음과 같다.
--worker--zone--all--filters
예를 들어 특정 Worker의 로그를 확인할 수 있다.
cf observability tail --worker my-worker
또한 별도의 JSON 파일에서 필터 조건을 읽을 수 있다.
하지만 실제 Worker의 로그를 확인하려면 Workers Logs가 활성화돼 있어야 한다.
명령이 존재한다는 사실만으로 모든 Worker의 로그가 자동으로 제공되는 것은 아니다.
파괴적인 명령의 확인 정책
이번 CLI에서는 사용자가 확인할 수 있는 Terminal이 존재하지 않는 환경에서 파괴적인 명령을 실행하는 경우의 동작도 정리됐다.
예를 들어 CI에서 삭제 명령을 실행한다고 가정해 보자.
실제로 사용자가 확인 Prompt에 응답할 수 없는 환경이다.
새로운 CLI는 이러한 명령을 기본적으로 실패 처리한다.
명시적인 실행이 필요하다면 다음 옵션을 사용할 수 있다.
--force
따라서 자동화된 실행에서 의도하지 않은 리소스 삭제를 줄이도록 설계했다.
하지만 --force를 사용하면 해당 안전장치가 우회될 수 있다.
실제 CI에 적용할 때는 삭제 대상과 권한을 확인해야 한다.
RC의 제한사항
Cloudflare는 다음 부분을 1.0까지 안정적으로 유지할 계획이라고 설명한다.
cloudflare.config.ts- Build Output 형식
- 프로젝트 생성·개발·빌드·배포 명령
- 대부분의 API 기반 명령
하지만 일부 사용 빈도가 낮은 API 명령은 정식 1.0 이전에 변경될 수 있다.
따라서 이번 버전을 완전히 안정화된 1.0으로 취급해서는 안 된다.
또한 공식 발표에는 기존 Wrangler와 비교한 빌드 시간이나 배포 시간의 Benchmark가 포함되지 않았다.
이번 발표는 Cloudflare의 새로운 통합 개발·배포 CLI가 정식 출시를 앞두고 설정 및 Build Output 형식과 주요 명령을 안정화한 Release Candidate다.
GitHub Copilot Code Review, PR 복잡도별 Adaptive 검사·다른 Repository 참조·Secret 탐지 Preview 제공
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: GitHub
- 안정화 단계: Adaptive·Cross-repository Context·Secret Detection은 Public Preview
- 적용 대상: GitHub Copilot Code Review, Copilot CLI·App·SDK의 보안 검토
- 지원 요금제: Copilot Pro, Pro+, Max, Business, Enterprise
- 주요 발표: https://github.blog/changelog/2026-11-17-copilot-code-review-adaptive-effort-secret-detection-and-more/
- Secret Scanning 상세 발표: https://github.blog/changelog/2026-11-17-secret-scanning-on-demand-for-developers-and-agents/
GitHub가 Copilot Code Review의 검사 방식과 보안 기능을 확대했다.
이번 날짜에는 관련 발표가 두 개 존재했다.
첫 번째는 Code Review의 깊이를 자동으로 선택하는 기능과 다른 Repository의 Context를 사용하는 기능이다.
두 번째는 기존 GitHub Secret Scanning을 Copilot의 보안 검토 과정에서 실행할 수 있도록 하는 기능이다.
두 발표는 같은 코드 검토 Workflow와 관련돼 있으므로 하나로 묶었다.
기존 Code Review Effort
Copilot Code Review에서는 실제 코드 변경에 대해 여러 수준의 검토를 수행할 수 있다.
대표적인 수준은 다음과 같다.
- Lite
- Balanced
- Max
예를 들어 문서의 오탈자만 수정하는 Pull Request와 사용자 인증을 변경하는 Pull Request를 생각할 수 있다.
두 작업의 위험은 다르다.
문서 수정에서는 간단한 검토로 충분할 수 있다.
반면 인증 로직 변경에서는 더 자세한 분석이 필요할 수 있다.
하지만 기존에는 실제 사용자가 검토 수준을 직접 선택해야 하는 경우가 있었다.
Adaptive Review
새로운 기능은 다음과 같다.
Adaptive
Copilot은 실제 Pull Request의 복잡도와 위험을 분석한다.
그리고 다음 수준 가운데 하나를 선택한다.
- Lite
- Balanced
- Max
예를 들어 단순한 CSS 수정에서는 Lite를 선택할 수 있다.
반면 인증 관련 코드가 변경됐다면 더 높은 수준을 선택할 수 있다.
실제 Review 결과에는 Adaptive가 선택한 검토 수준도 표시된다.
따라서 사용자는 어떤 수준의 검토가 수행됐는지 확인할 수 있다.
하지만 Adaptive가 항상 가장 정확한 수준을 선택한다고 보장할 수는 없다.
실제 코드의 위험을 잘못 평가할 가능성도 존재하기 때문이다.
조직 정책과 최대 검토 수준
이번 기능에는 조직 정책에 관한 제한이 있다.
Adaptive는 Enterprise나 Organization, Repository에서 설정한 최대 Review Effort를 초과하지 않는다.
예를 들어 Organization이 최대 수준을 Balanced로 제한했다고 가정해 보자.
이 경우 Adaptive는 Max를 자동으로 선택하지 않는다.
따라서 자동 선택 기능이 상위 관리자의 사용량 및 정책 제한을 우회하지 않도록 설계됐다.
기본 Review Effort는 여전히 Balanced다.
Adaptive는 기본값으로 강제 활성화된 것이 아니라 선택할 수 있는 Preview 기능이다.
Cross-repository Context
두 번째 기능은 다른 Repository의 코드를 참조하는 것이다.
예를 들어 다음 구조를 생각할 수 있다.
- Repository A: 공통 TypeScript SDK
- Repository B: 웹 애플리케이션
개발자는 Repository A에서 함수의 인자를 변경했다.
하지만 실제 Repository B에서는 이전 함수 Signature를 사용하고 있다.
A만 검사하면 다른 Repository의 영향을 놓칠 수 있다.
새로운 Cross-repository Context에서는 Copilot이 관련 공개 Repository를 참조할 수 있다.
따라서 다른 Repository의 코드와 문서, Custom Instruction을 참고해 검토할 수 있다.
다만 이번 Preview에는 중요한 제한사항이 있다.
Cross-repository Context는 공개 Repository를 대상으로 한다.
모든 Private Repository 사이의 관계를 자동으로 분석할 수 있는 기능으로 취급해서는 안 된다.
GitHub Secret Scanning과 결합
이번 발표에서 중요한 보안 기능은 Secret Scanning이다.
예를 들어 개발자가 다음 값을 실수로 Commit했다고 가정해 보자.
- API Key
- Database Password
- Access Token
- Connection String
GitHub는 기존 Secret Scanning에서 알려진 Provider Pattern을 검사할 수 있다.
이번 기능에서는 Copilot Code Review와 보안 검토에 해당 탐지기를 연결했다.
지원하는 Pattern은 다음 규모다.
- 500개 이상의 Secret 유형
- 150개 이상의 Provider Partner
또한 정형화된 Token Pattern이 없는 Credential도 탐지할 수 있도록 Fine-tuned 모델을 사용한다.
예를 들어 Connection String 안의 Password처럼 명확한 Prefix가 없는 Secret을 주변 코드의 Context와 함께 분석할 수 있다.
하지만 모든 Secret 유형이 완벽하게 탐지된다는 의미는 아니다.
정적 Pattern과 AI 기반 분석 모두 오탐 및 누락 가능성이 존재한다.
검사 범위의 제한
이번 Secret Scanning은 실제 코드의 변경 부분을 검사한다.
Repository 전체의 과거 Git History를 검색하는 기능은 아니다.
예를 들어 1년 전에 Commit한 Secret이 현재 Repository에 남아 있다고 가정해 보자.
이번 코드 검토 기능을 활성화했다고 해서 기존 모든 Commit을 자동으로 검사하는 것은 아니다.
실제 전체 Repository의 Secret Scanning과 Pull Request 변경 사항 검사는 구분해야 한다.
또한 현재 공개된 기능은 Opt-in이다.
기본적으로 비활성화돼 있다.
Copilot CLI에서 실행
Copilot CLI에서는 다음 설정을 사용할 수 있다.
/settings aiSecretDetection on
이후 다음 명령으로 보안 검토를 요청할 수 있다.
/security-review
또한 security-review Specialist를 호출할 수 있다.
이렇게 하면 개발자가 Pull Request를 생성하기 전에 현재 변경 사항에 Secret이 포함돼 있는지 확인할 수 있다.
하지만 검토를 실행했다는 사실만으로 해당 코드가 안전하다고 보장할 수는 없다.
실제 보안 검토 결과를 확인하고 필요한 수정을 수행해야 한다.
Copilot SDK와 App
이번 기능은 Copilot App과 SDK에서도 사용할 수 있다.
Copilot App에서는 Experimental Settings에서 관련 기능을 활성화할 수 있다.
Copilot SDK에서는 다음 Feature Flag를 사용할 수 있다.
SECURITY_REVIEW_FINE_TUNED_MODEL=true
이후 관련 보안 검토 Agent를 실행할 수 있다.
따라서 자체 에이전트 Workflow에서 코드 변경을 반환하기 전에 Secret 검사를 수행하도록 구성할 수 있다.
하지만 실제 SDK가 변경한 파일의 모든 내용을 자동으로 검사한다는 의미는 아니다.
검사 대상과 호출 시점을 실제 Workflow에서 명확하게 지정해야 한다.
비용과 안정화 단계
이번 Secret Scanning은 기존 Copilot Security Review를 사용할 수 있는 환경에서 제공된다.
별도의 추가 요금제가 필요한 것은 아니다.
하지만 실제 검사는 Secret Protection AI Credit을 사용한다.
따라서 추가 요금제 계약이 필요 없다는 사실과 사용량 비용이 없다는 사실은 구분해야 한다.
이번 발표에는 다음 수치가 포함되지 않았다.
- Secret 탐지 Recall
- False Positive 비율
- Adaptive Review의 오류 발견율
- Cross-repository Context의 정확도 개선율
이번 업데이트는 코드 검토의 깊이를 변경 사항에 따라 선택하고 다른 Repository의 Context와 실제 Secret 탐지기를 결합해 Pull Request의 보안 문제를 더 넓게 검사하도록 한 Public Preview 확대다.
GitHub Copilot Evals 공개 Preview — Custom Agent·Skill·MCP 변경 전후를 반복 테스트로 비교
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: GitHub
- 안정화 단계: Public Preview
- 적용 대상: GitHub Copilot, Custom Agent, Agent Skill, MCP Tool
- 평가 엔진: Vally
- 지원 환경: VS Code, Copilot CLI, Copilot App
- 원문: https://github.blog/changelog/2026-11-17-github-copilot-evals-is-now-in-public-preview/
GitHub가 Copilot Evals를 Public Preview로 공개했다.
이번 기능은 AI 모델의 새로운 추론 API를 제공하는 것이 아니다.
AI 코딩 에이전트의 설정과 도구를 변경했을 때 실제 작업 수행 결과가 개선됐는지 반복해서 검증할 수 있도록 하는 평가 도구다.
특히 Custom Agent와 Skill을 사용하는 프로젝트에 영향을 줄 수 있다.
기존 AI 에이전트 테스트의 문제
예를 들어 팀에서 코드 리뷰를 수행하는 AI 에이전트를 만들었다고 가정해 보자.
에이전트에는 다음 지침이 존재한다.
- TypeScript 타입 오류 확인
- 인증 관련 변경 검토
- 불필요한 API 호출 발견
- 테스트 누락 확인
개발자는 지침을 수정한다.
그리고 같은 Pull Request에서 다시 실행한다.
두 번째 실행 결과가 더 좋아 보일 수 있다.
하지만 실제 AI 모델의 출력은 같은 입력에서도 달라질 수 있다.
따라서 한 번의 성공적인 실행만으로 새 지침이 기존보다 더 좋다고 판단하기 어렵다.
이번 Evals 기능은 이러한 문제를 다루도록 설계됐다.
Eval의 구성
Eval은 반복할 수 있는 테스트다.
개발자는 다음 정보를 정의한다.
- 에이전트가 수행할 실제 작업
- 기대하는 결과
- 실제 결과를 검사할 조건
예를 들어 다음 작업을 생각할 수 있다.
TypeScript 코드에서 SQL Injection 위험을 찾아라.
이후 평가 기준을 정의할 수 있다.
- 위험한 코드 위치를 발견했는가?
- 잘못된 API를 사용하지 않았는가?
- 실제 수정 코드가 테스트를 통과하는가?
에이전트는 해당 작업을 수행한다.
이후 Evals는 실제 결과와 평가 기준을 비교한다.
따라서 단순한 자연어 평가보다 반복 가능한 검증 구조를 만들 수 있다.
Custom Agent와 Skill
이번 기능은 다음 구성요소를 대상으로 한다.
- Skill
- Custom Agent
- MCP Tool
예를 들어 팀에서 새로운 MCP Tool을 추가했다고 가정해 보자.
해당 Tool은 실제 GitHub Issue를 읽는다.
에이전트가 새로운 Tool을 사용하면 작업의 정확성이 높아질 수 있다.
하지만 반대로 실제 API 호출이 불필요하게 증가하거나 잘못된 데이터를 사용할 수도 있다.
개발자는 동일한 Eval을 새로운 Tool 추가 전후에 실행한다.
그리고 결과를 비교할 수 있다.
이렇게 하면 에이전트의 기능 변경에 관한 회귀 테스트를 수행할 수 있다.
결과와 실행 과정의 검증
이번 Evals는 최종 출력뿐 아니라 실제 작업 과정을 확인하도록 설계됐다.
예를 들어 에이전트가 정답과 비슷한 내용을 생성했다고 가정해 보자.
하지만 해당 결과를 얻기 위해 허용되지 않은 파일을 읽었을 수 있다.
또는 불필요한 외부 API를 호출했을 수 있다.
따라서 실제 결과만 비교해서는 충분하지 않을 수 있다.
GitHub는 다음 정보를 확인할 수 있도록 한다.
- 어떤 검사가 통과했는가?
- 어떤 검사가 실패했는가?
- 실패한 이유는 무엇인가?
- 이전 실행과 무엇이 달라졌는가?
이러한 정보는 실제 Agent Harness를 수정할 때 활용할 수 있다.
실행 승인
이번 기능에서는 각 Eval 실행 전에 사용자의 승인을 받는다.
따라서 테스트를 정의했다는 사실만으로 모든 Eval이 자동으로 실행되는 것은 아니다.
이는 실제 에이전트가 파일을 변경하거나 외부 도구를 사용하는 상황에서 중요하다.
다만 승인 후 실제 실행하는 작업의 권한과 안전성은 별도로 확인해야 한다.
Vally
GitHub Copilot Evals는 Vally를 평가 엔진으로 사용한다.
Vally는 확장 가능한 로컬 평가 도구다.
따라서 실제 평가 작업을 개발자의 환경에서 실행할 수 있다.
하지만 로컬 평가 결과가 실제 운영 환경의 모든 실행 조건을 재현한다는 의미는 아니다.
예를 들어 실제 운영 환경에서는 다음 조건이 다를 수 있다.
- 네트워크
- API 권한
- 데이터베이스 상태
- 실제 사용자 입력
- 외부 서비스의 응답 시간
따라서 로컬 Eval과 운영 환경의 실제 모니터링을 구분해야 한다.
지원 환경
이번 Preview는 다음 환경에서 사용할 수 있다.
- Visual Studio Code Extension
- Copilot CLI Plugin
- Copilot App
Copilot App에서는 github/evals Marketplace를 추가해 관련 Plugin을 설치할 수 있다.
지원 요금제는 다음과 같다.
- Copilot Individual
- Copilot Business
- Copilot Enterprise
다만 Public Preview이므로 향후 API와 평가 기능이 변경될 수 있다.
또한 이번 발표에는 실제 Eval 사용으로 에이전트의 오류율이 얼마나 감소했는지에 관한 독립적인 Benchmark가 포함되지 않았다.
이번 업데이트는 AI 코딩 에이전트의 지침과 도구를 수정할 때 결과와 실행 과정을 반복적으로 검사해 회귀 문제를 발견할 수 있도록 평가 체계를 제공하는 기능이다.
GitHub Event Streams Preview — Webhook Server 없이 PR 리뷰·Commit·CI 상태 변경을 지속 연결로 수신
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: GitHub
- 안정화 단계: Preview, Waitlist
- 적용 대상: GitHub Pull Request Event, AI Coding Agent, 개발 자동화
- 주요 변경: Polling 없이 지속 연결을 통해 PR 이벤트 수신
- 원문: https://github.blog/changelog/2026-11-17-github-event-streams-is-now-in-preview/
GitHub가 Event Streams를 Preview로 공개했다.
이번 기능은 GitHub REST API의 일반적인 조회 방식을 대체하는 것이 아니다.
Pull Request에서 발생한 변경 사항을 반복적인 API Polling 없이 수신할 수 있도록 하는 이벤트 전달 기능이다.
특히 로컬에서 실행하는 AI 코딩 에이전트와 개발 자동화에 영향을 줄 수 있다.
기존 Polling 방식
예를 들어 AI 코딩 에이전트가 Pull Request를 생성했다고 가정해 보자.
이후 실제 사용자의 Code Review를 기다려야 한다.
에이전트는 다음 API를 주기적으로 호출할 수 있다.
PR에 새로운 Review가 달렸는가?
하지만 Polling에는 두 가지 문제가 존재한다.
첫 번째는 호출 빈도를 높이는 경우다.
이 경우 실제 변경이 없더라도 API 요청을 반복한다.
따라서 Rate Limit 사용량이 증가할 수 있다.
두 번째는 호출 빈도를 낮추는 경우다.
이 경우 새로운 Review가 등록됐더라도 에이전트가 실제로 확인하기까지 시간이 걸릴 수 있다.
이번 Event Streams는 이러한 문제를 줄이도록 한다.
이벤트 구독
기본적인 흐름은 다음과 같다.
- 특정 Pull Request 구독
- GitHub와 지속적인 연결 유지
- 새로운 이벤트 수신
- 이벤트에 따라 에이전트 또는 자동화 실행
지원하는 주요 이벤트는 다음과 같다.
- Review 제출
- 새로운 Commit Push
- Merge Conflict 발생
- Pull Request Merge
- Pull Request Close
- Check Suite 변경
- Check Suite 상태 변경
예를 들어 CI 테스트가 실패했다고 가정해 보자.
에이전트는 실제 Check Suite 상태 변경 이벤트를 받는다.
이후 해당 결과를 분석해 코드 수정 작업을 시작할 수 있다.
따라서 실제 작업이 발생할 때만 자동화를 실행하는 구조를 만들 수 있다.
Webhook과의 차이
GitHub Webhook은 특정 이벤트가 발생했을 때 미리 등록한 HTTP Endpoint로 요청을 보낼 수 있다.
하지만 로컬에서 실행하는 에이전트는 공개 HTTP Endpoint를 가지고 있지 않을 수 있다.
예를 들어 개발자가 MacBook에서 코딩 에이전트를 실행한다고 가정해 보자.
해당 노트북에는 외부에서 접근할 수 있는 Webhook Server가 존재하지 않을 수 있다.
이번 Event Streams는 이러한 상황에서 지속 연결을 통해 이벤트를 받을 수 있도록 한다.
따라서 개발자가 공개 Webhook Receiver를 별도로 배포할 필요가 줄어든다.
하지만 Event Streams가 모든 Webhook 기능을 그대로 대체하는 것은 아니다.
현재 Preview의 지원 이벤트와 연결 정책을 기준으로 사용해야 한다.
연결이 끊긴 경우
이번 방식에서는 실제 연결의 상태도 중요하다.
예를 들어 사용자의 노트북이 절전 모드로 이동했다고 가정해 보자.
그러면 Event Stream 연결이 종료될 수 있다.
이후 다시 연결해야 한다.
따라서 실제 서비스를 운영한다면 다음 상황을 고려해야 한다.
- 네트워크 단절
- 재연결
- 중복 이벤트
- 누락된 이벤트
- 처리하지 못한 작업의 재검사
GitHub가 Event Streams를 제공한다는 사실만으로 모든 이벤트를 정확히 한 번만 처리할 수 있다고 보장할 수는 없다.
실제 중요한 작업에는 상태 조회와 Idempotency 처리가 필요할 수 있다.
Preview의 제한사항
이번 기능은 현재 Waitlist를 통해 접근할 수 있다.
따라서 모든 GitHub 사용자가 즉시 사용할 수 있는 정식 기능은 아니다.
GitHub는 이번 발표에서 실제 이벤트 전달의 P95 지연과 연결당 최대 처리량, Polling 대비 절감률에 관한 Benchmark를 공개하지 않았다.
따라서 Event Streams가 모든 상황에서 Polling보다 특정 비율만큼 빠르다고 단정할 수 없다.
이번 업데이트는 GitHub Pull Request를 중심으로 개발자와 AI 에이전트, CI 시스템 사이의 상태 변경을 실시간에 가깝게 전달하기 위한 새로운 이벤트 인터페이스의 Preview다.
Vercel 신규 Pro·Enterprise Team, Standard Build도 사용량 기반 과금으로 변경
- 발표일: 2026-11-17
- 정확한 게시 시각: 미확인
- 발표 주체: Vercel
- 안정화 단계: 정식 과금 정책 변경
- 적용 대상: 2026년 11월 17일부터 생성하는 신규 Pro 및 Enterprise Team
- Pro Standard Build 요금: 빌드 1분당 0.014달러
- 기존 Team: 이번 정책 변경의 신규 적용 대상이 아님
- 원문: https://vercel.com/changelog/standard-build-billing-new-teams
Vercel이 신규 Pro 및 Enterprise Team의 Standard Build 과금 정책을 변경했다.
이번 발표는 새로운 빌드 엔진의 출시나 실제 빌드 성능의 개선이 아니다.
기존에 제공하던 Standard Build Machine의 요금을 다른 빌드 환경과 같은 사용량 기반 정책으로 통합한 것이다.
기존 Standard Build Slot
기존에는 일부 Team의 요금제에 Standard Build Slot이 포함돼 있었다.
따라서 실제 빌드 실행에 관한 비용 구조가 다른 Build Machine과 달랐다.
이번 정책부터는 새로 생성한 Pro 및 Enterprise Team에 기본 Standard Build Slot이 포함되지 않는다.
대신 실제 사용한 빌드 시간을 기준으로 과금한다.
Pro의 요금은 다음과 같다.
1분당 0.014달러
예를 들어 하나의 빌드가 10분 걸린다고 가정해 보자.
해당 빌드의 요금은 다음과 같이 계산할 수 있다.
10 × 0.014 = 0.14달러
실제로 한 달 동안 같은 빌드를 100번 실행하면 단순 계산으로 14달러가 된다.
다만 이 계산은 Standard Build의 실행 시간만 고려한 것이다.
실제 청구 금액에는 적용되는 월간 Credit과 다른 서비스의 사용량이 영향을 줄 수 있다.
월간 Credit
Vercel Pro의 기존 월간 Usage Credit은 Build 사용량에도 적용된다.
따라서 실제 과금은 해당 Credit을 고려해야 한다.
Enterprise는 계약에 따른 요금이 적용된다.
따라서 Pro의 분당 요금을 Enterprise에도 동일하게 적용해서는 안 된다.
Elastic에서 Standard로 변경
이번 정책에서 중요한 부분은 다음 조건이다.
신규 Team이 Elastic Build를 사용하다가 Standard Build로 변경하더라도 Standard Build는 사용량 기반 과금 대상이다.
따라서 Standard로 변경하면 기존의 포함 Slot을 자동으로 확보할 수 있다고 판단해서는 안 된다.
적용 범위의 제한
이번 발표는 신규 Team을 대상으로 한다.
따라서 이전에 생성한 모든 Pro 및 Enterprise Team의 과금 정책이 동일하게 변경됐다는 의미는 아니다.
또한 실제 빌드 속도나 Cache Hit Rate에 관한 새로운 Benchmark가 포함된 것은 아니다.
신규 Vercel Team의 Standard Build 비용을 사용량에 따라 계산하도록 변경한 과금 정책 업데이트다.
그 밖에 Node.js, Deno, Bun, Vite, webpack, Rollup, esbuild, Babel, Biome, ESLint, Prettier, npm, pnpm, Yarn, GitLab 및 주요 테스트·배포 도구의 공식 발표를 조사했다.
이번 조사 범위에서 이외에 포함할 만한 주요 신규 안정 버전이나 보안 수정은 확인하지 못했습니다.
Google Cloud SDK 594.0.0도 11월 17일 공개됐다.
이 버전에서는 일부 명령에서 Positional Argument와 --account, --project 옵션을 함께 지정했을 때의 우선순위가 변경됐다.
대표적으로 인증과 Billing, Shared VPC 관련 명령이 영향을 받을 수 있다.
이는 기존 CLI의 인자 처리 오류를 수정한 변경으로, 실제 자동화 Script에서 같은 명령에 여러 값을 함께 전달하는 경우 호환성을 확인할 필요가 있다.
다만 이번 브리핑에서는 새로운 API와 보안 검토, CI 및 개발 도구의 주요 변경을 우선해 별도의 상세 항목으로 선정하지 않았다.
또한 Cloud Logging Ops Agent 2.72.0에서는 기존 Logging Agent의 처리 경로를 Metric Agent로 변경하면서 업그레이드 직후 일시적으로 로그가 중복될 수 있다는 안내가 공개됐다.
이러한 중복은 기존과 새로운 처리 경로가 각각 이전 처리 위치를 별도로 관리하기 때문에 발생할 수 있다.
이번 변경 역시 웹 개발의 주요 신규 기능보다는 운영 호환성에 관한 사항으로 분류했다.
OWASP와 주요 공급망 보안 권고도 확인했으며, 이번 기간에 처음 공개된 중요한 취약점과 영향 버전, 실제 수정 버전을 공식 원문으로 함께 검증할 수 없는 항목은 제외했다.
📚 추천 글
宣言したものだけがキャッシュされる ── Next.js 16 Cache Components、4層モデルからの移行ガイド
- 원제: 宣言したものだけがキャッシュされる ── Next.js 16 Cache Components、4層モデルからの移行ガイド
- 저자: raruchan
- 매체: UPGRADE tech blog / Zenn
- 게시일: 2026-11-16, 11월 17일 수정
- 기술: Next.js 16, React Server Components, Cache Components, PPR,
use cache,cacheLife,cacheTag - 원문: https://zenn.dev/upgradetech/articles/ec6b304fe4c856
Next.js 16의 Cache Components를 이해하기 위해 기존 App Router의 네 가지 캐시 계층이 새로운 모델에서는 어떻게 변경되는지 분석한 상세한 기술 글이다.
이번 글은 새로운 Next.js 릴리스 발표를 반복하는 자료가 아니다.
이미 제공되는 Cache Components를 실제 애플리케이션에 적용할 때 기존 코드를 어떻게 변경해야 하는지 설명하는 마이그레이션 가이드다.
특히 캐시가 기본적으로 적용되는 구조에서 명시적으로 지정한 영역만 캐시하는 구조로 전환하는 과정의 의미를 자세하게 다룬다.
기존 Next.js의 네 가지 캐시 계층
기존 App Router의 캐시는 크게 네 종류로 설명할 수 있었다.
첫 번째는 Request Memoization이다.
동일한 서버 렌더링 작업 안에서 같은 데이터를 여러 번 요청하더라도 중복된 작업을 줄이는 기능이다.
두 번째는 Data Cache다.
서버에서 가져온 데이터를 다음 요청에서도 재사용할 수 있도록 저장한다.
세 번째는 Full Route Cache다.
정적으로 생성한 전체 Route의 렌더링 결과를 재사용한다.
네 번째는 Router Cache다.
클라이언트에서 이전에 가져온 Route 관련 데이터를 재사용한다.
이러한 네 계층은 서로 다른 목적을 가지고 있었다.
하지만 실제 개발자는 어떤 API가 어떤 캐시를 사용하는지 이해해야 했다.
예를 들어 다음 코드를 작성했다고 가정해 보자.
fetch(url)
실제로 해당 요청이 어느 수준에서 캐시되는지는 Next.js 버전과 Route의 설정, Fetch 옵션 등에 영향을 받을 수 있었다.
저자는 이러한 구조가 개발자에게 부담을 주었다고 설명한다.
새로운 Cache Components 모델
Next.js 16의 Cache Components에서는 캐시의 기본적인 사고방식이 변경된다.
기존에는 특정 데이터나 Route가 암묵적으로 캐시될 수 있었다.
새로운 모델에서는 개발자가 실제로 캐시할 영역을 명시한다.
대표적인 선언은 다음과 같다.
'use cache'
예를 들어 상품 목록을 가져오는 함수가 있다고 가정해 보자.
해당 함수에 'use cache'를 지정할 수 있다.
이후 Next.js는 해당 함수의 결과를 재사용할 수 있도록 처리한다.
따라서 캐시의 범위를 실제 함수나 컴포넌트 단위로 명확하게 표현할 수 있다.
하지만 이번 기능을 활성화했다고 해서 모든 서버 작업의 실행 결과가 자동으로 캐시되는 것은 아니다.
개발자가 어떤 작업을 캐시할지 결정해야 한다.
cacheComponents: true
실제 기능을 활성화하는 설정은 다음과 같다.
cacheComponents: true
Next.js 16.4에서는 관련 기능이 새 프로젝트의 권장 구성으로 확대됐다.
또한 다음 설정과 결합할 수 있다.
partialPrefetching: true
이러한 설정은 애플리케이션 전체의 렌더링 모델에 영향을 줄 수 있다.
따라서 특정 Route 하나에서만 기존 캐시 동작을 유지하고 나머지 Route에 새로운 모델을 적용하는 단순한 전환 옵션으로 취급해서는 안 된다.
실제 마이그레이션에서는 전체 애플리케이션의 캐시 전략을 검토해야 할 수 있다.
Request Memoization은 유지
저자는 네 가지 기존 캐시 가운데 Request Memoization은 기본적으로 유지된다고 설명한다.
이 기능은 React의 렌더링 과정과 연결된다.
예를 들어 서버 컴포넌트 A와 B가 같은 데이터를 필요로 한다고 가정해 보자.
두 컴포넌트가 같은 렌더링 작업 안에서 동일한 요청을 수행할 수 있다.
Request Memoization은 해당 작업의 중복을 줄이는 데 사용된다.
따라서 Cache Components를 활성화했다고 해서 이 기능을 새롭게 구현할 필요는 없다.
하지만 Request Memoization이 존재한다는 사실만으로 다음 HTTP 요청에서도 같은 데이터를 재사용할 수 있다는 의미는 아니다.
실제 요청 간 캐시와 하나의 렌더링 안에서의 Memoization은 서로 다른 기능이다.
Data Cache와 use cache
두 번째는 Data Cache다.
저자는 기존 Data Cache가 완전히 사라진 것은 아니라고 설명한다.
기존의 fetch 관련 캐시와 unstable_cache는 일정한 범위에서 계속 사용할 수 있다.
하지만 새로운 코드에서는 use cache를 중심으로 설계하는 방향을 권장한다.
여기에는 저장 위치와 수명에 관한 차이가 존재한다.
저자가 설명한 주요 차이는 다음과 같다.
| 방식 | 일반적인 저장 특성 |
|---|---|
| 기존 Fetch Data Cache | 배포 이후에도 유지되는 캐시 모델 |
기본 use cache | 서버 메모리 중심의 캐시 |
use cache: remote | 공유 외부 저장소를 이용하는 캐시 |
use cache: private | 사용자 브라우저의 메모리를 이용하는 캐시 |
다만 실제 캐시 저장소와 배포 간 유지 여부는 사용하는 Hosting 환경과 Cache Handler 구성에 따라 달라질 수 있다.
따라서 위 표를 모든 배포 플랫폼에서 절대적으로 동일한 동작으로 해석해서는 안 된다.
전체 Route 캐시에서 부분적인 캐시로
기존에는 하나의 Route 전체가 정적이거나 동적으로 처리되는 구성이 중요했다.
예를 들어 상품 상세 페이지를 생각할 수 있다.
해당 페이지에는 다음 정보가 존재한다.
- 공통 Navigation
- 상품 이름
- 상품 설명
- 사용자 장바구니
- 사용자별 추천 상품
이 가운데 일부는 모든 사용자에게 동일하다.
반면 장바구니와 추천 상품은 사용자마다 다를 수 있다.
기존에는 동적인 사용자 정보 때문에 전체 Route의 렌더링 방식이 달라질 수 있었다.
Cache Components에서는 정적 영역과 동적 영역을 더 명확하게 분리할 수 있다.
예를 들어 상품 이름과 설명은 캐시할 수 있다.
반면 장바구니는 실제 요청에 따라 생성한다.
그리고 정적인 Shell을 먼저 전달한 뒤 동적인 부분을 Streaming할 수 있다.
이러한 방식은 Partial Prerendering과 연결된다.
하지만 정적 영역이 존재한다고 해서 모든 페이지의 TTFB나 LCP가 자동으로 개선된다고 보장할 수는 없다.
실제 동적인 데이터의 로딩 시간과 Suspense Boundary의 구조도 중요하다.
use cache: remote
이번 글에서 중요한 부분은 원격 캐시다.
예를 들어 Next.js를 여러 서버리스 인스턴스에서 실행한다고 가정해 보자.
각 인스턴스가 자신의 메모리에만 캐시를 저장한다면 문제가 발생할 수 있다.
인스턴스 A에는 이미 필요한 데이터가 저장돼 있다.
하지만 다음 요청은 인스턴스 B로 전달된다.
이 경우 B에는 캐시가 존재하지 않을 수 있다.
따라서 같은 데이터를 다시 가져와야 할 수 있다.
use cache: remote는 외부 공유 저장소를 이용해 이러한 문제를 줄이도록 한다.
하지만 외부 저장소를 조회할 때마다 네트워크 작업이 발생할 수 있다.
따라서 캐시를 사용한 결과의 이점과 원격 저장소 접근 비용을 비교해야 한다.
저자는 특히 캐시를 사용하지 않았을 때 원본 API나 CMS에 큰 부하가 발생하는 상황에서 적합할 수 있다고 설명한다.
use cache: private
다른 방식은 다음과 같다.
use cache: private
이 방식은 사용자별 데이터를 처리할 때 사용한다.
일반적인 서버 캐시에서는 사용자마다 다른 데이터를 잘못 공유하면 위험할 수 있다.
예를 들어 다음 정보를 생각할 수 있다.
- 사용자 이름
- 로그인 상태
- 개인 설정
이러한 데이터는 사용자별로 달라질 수 있다.
use cache: private는 실제 사용자의 브라우저 메모리에서 결과를 재사용하도록 한다.
따라서 서버의 공용 캐시에 사용자별 결과를 저장하지 않는다.
하지만 서버의 계산량 자체가 줄어드는 것은 아니다.
실제로 서버가 여러 사용자의 요청을 처리할 때 같은 계산을 계속 실행해야 할 수 있다.
따라서 모든 사용자별 데이터를 무조건 Private Cache에 저장하는 것이 최적의 방법은 아닐 수 있다.
저자는 가능하면 Cookie에서 필요한 최소한의 정보를 읽어 캐시 함수의 인자로 전달하는 방식도 검토하도록 설명한다.
cacheLife
새로운 모델에서 캐시의 수명을 정의할 때는 다음 API를 사용할 수 있다.
cacheLife()
대표적인 사용 방식은 다음과 같다.
cacheLife('hours')
이는 실제 캐시의 수명 정책을 지정한다.
저자는 다음 세 값을 구분한다.
| 값 | 역할 |
|---|---|
stale | 클라이언트가 캐시를 재확인하지 않고 사용할 수 있는 기간 |
revalidate | 서버가 캐시를 갱신하는 정책 |
expire | 기존 결과의 사용을 중단하고 갱신을 기다려야 하는 경계 |
예를 들어 상품 가격은 자주 변경될 수 있다.
반면 서비스 소개 페이지의 내용은 거의 변경되지 않을 수 있다.
따라서 두 데이터의 Cache Life가 같을 필요는 없다.
개발자는 실제 데이터의 의미에 맞게 캐시 수명을 설정해야 한다.
기본 Cache Life의 함정
저자는 cacheLife()를 생략하면 기본 Profile이 적용된다는 사실을 설명한다.
해당 Profile은 다음 값을 포함한다.
- Stale: 5분
- Revalidate: 15분
- 만료: 명시적인 제한 없음
하지만 이러한 기본값이 모든 데이터에 적합한 것은 아니다.
예를 들어 실시간 재고 수량이 있다고 가정해 보자.
해당 데이터를 기본 Profile로 캐시하면 실제 사용자에게 이전 재고가 표시될 가능성이 있다.
따라서 저자는 캐시 수명을 명시적으로 지정하도록 권장한다.
이는 실제 시스템의 데이터 최신성 요구사항을 코드에 표현하기 위한 것이다.
캐시 무효화
이번 글에서는 다음 API의 역할도 설명한다.
cacheTag()
예를 들어 상품 상세 정보와 관련된 캐시를 생각할 수 있다.
해당 캐시에 상품 ID와 연결된 Tag를 지정한다.
이후 실제 상품 정보가 변경되면 관련 캐시를 무효화할 수 있다.
이러한 방식은 단순한 TTL 만료를 기다리지 않고 특정 데이터의 변경을 반영하는 데 활용할 수 있다.
하지만 실제 Cache Tag가 모든 CDN과 서버리스 인스턴스의 캐시를 자동으로 동일한 시점에 제거한다는 의미는 아니다.
실제 배포 환경의 Cache Handler와 무효화 정책을 함께 확인해야 한다.
실제 마이그레이션의 한계
저자는 다음 차이를 강조한다.
- 기존 Route 전체 캐시와 부분적인 캐시의 차이
- Request Memoization과 요청 간 캐시의 차이
- 서버 메모리 캐시와 원격 캐시의 차이
- 공통 데이터와 사용자별 데이터의 차이
- TTL과 이벤트 기반 무효화의 차이
이번 글은 실제 API와 공식 문서를 분석한 마이그레이션 가이드다.
하지만 기존 캐시 방식과 Cache Components의 LCP 또는 TTFB를 동일한 프로젝트에서 비교한 Benchmark는 포함하지 않았다.
따라서 새로운 캐시 모델이 모든 Next.js 프로젝트에서 반드시 더 빠르다고 단정해서는 안 된다.
이번 글은 Next.js의 새로운 캐시 구조를 단순한 API 문법의 변경이 아니라 데이터의 소유권과 수명, 사용자별 격리 및 배포 환경의 특성을 다시 설계하는 문제로 이해하도록 설명한 자료다.
TypeScript checker benchmark: 309 errors or none, on the same repo
- 저자: Aleksandr Argunov
- 매체: DEV Community / argbe.tech
- 게시일: 2026-11-17
- 기술: TypeScript 7, Bun, Rust 기반 Type Checker, Project References, Benchmark
- 원문: https://dev.to/argbetech/typescript-checker-benchmark-309-errors-or-none-on-the-same-repo-lne
여러 TypeScript Type Checker의 성능과 정확성을 비교하면서 실행 시간이 빠르다는 사실과 실제 같은 코드를 검사했다는 사실이 서로 다른 문제라는 점을 보여주는 기술 글이다.
저자는 여섯 개의 Type Checker를 같은 Repository에서 실행했다.
그리고 실제 Error Diagnostic과 Exit Code, 검사한 파일 수를 비교했다.
흥미로운 결과가 나타났다.
다섯 도구는 동일한 309개 오류를 보고했다.
반면 Bun의 Checker는 오류가 없다고 보고했다.
하지만 이러한 차이를 곧바로 Bun이 309개의 오류를 놓쳤다는 의미로 해석해서는 안 된다.
실제 원인은 Project References의 처리 방식과 빌드 순서에 있었다.
비교한 Type Checker
저자가 테스트한 도구는 다음과 같다.
| 도구 | 버전 |
|---|---|
| TypeScript | 7.0.2 |
| TypeScript | 7.1 Beta |
| tsc-rs | 0.8.0 |
| tsc-ts | 0.1.0 |
| tsrs | 0.20.1-ts7.1.0-beta |
| bun check | 1.4.4 |
이러한 도구는 모두 TypeScript 코드를 분석하는 데 사용할 수 있다.
하지만 내부 구현과 Project References의 처리 방식, 병렬화 전략은 서로 다를 수 있다.
따라서 단순히 하나의 코드베이스에서 실행 시간을 측정하는 것만으로 전체 성능을 비교하기 어렵다.
실제 테스트 환경
저자는 다음 환경에서 실험했다.
- Apple M1 Pro
- CPU 10개
- 메모리 16GiB
- macOS 27.0.1
- Node.js 26.13.0
실제 테스트는 2026년 11월 3일에 수행했다.
따라서 11월 17일은 해당 결과를 정리한 글의 게시일이다.
실험 시점의 TypeScript와 Bun 버전을 기준으로 해석해야 한다.
또한 저자는 테스트 머신이 완전히 Idle 상태가 아니었다고 명시했다.
따라서 실제 측정 결과의 일부는 다른 프로세스의 CPU 사용량에 영향을 받았을 수 있다.
date-fns의 Project References
저자는 date-fns Repository를 사용했다.
특정 Commit을 Checkout해 같은 Source 상태를 유지했다.
Commit은 다음과 같다.
a9739fb3e538
이후 TypeScript Checker를 실행했다.
첫 번째 결과는 다음과 같았다.
| 도구 | 오류 수 | Exit Code |
|---|---|---|
| TypeScript 7.0.2 | 309 | 1 |
| TypeScript 7.1 Beta | 309 | 2 |
| tsc-rs | 309 | 2 |
| tsc-ts | 309 | 2 |
| tsrs | 309 | 2 |
| bun check | 0 | 0 |
단순히 표만 보면 Bun이 오류를 놓친 것처럼 보일 수 있다.
하지만 실제 오류 내용을 분석하면 다른 설명이 가능하다.
309개 가운데 307개는 다음 오류였다.
TS6305
이 오류는 Project Reference에서 필요한 .d.ts 파일이 아직 빌드되지 않은 상황과 연결된다.
즉 실제 TypeScript 코드의 잘못된 타입 사용보다 프로젝트의 빌드 준비 상태에 관한 오류가 대부분이었다.
bun check의 다른 처리 방식
Bun은 Project References를 따라가는 방식을 다르게 처리한다.
저자는 bun check --help에서 관련 프로젝트를 별도로 먼저 빌드하지 않아도 된다는 설명을 확인했다.
따라서 Bun은 기존 TypeScript Checker와 다른 결과를 반환할 수 있었다.
이후 저자는 다음 명령을 실행했다.
tsc -b
즉 실제 Project References에 필요한 빌드를 먼저 수행했다.
그다음 여섯 Checker를 다시 실행했다.
결과는 다음과 같았다.
모든 Checker가 오류 없이 종료됐다.
따라서 최초 309개 오류의 대부분은 실제 소스코드의 잘못된 타입 선언 때문이 아니었다.
이번 결과는 Project References의 준비 상태와 실행 방식이 Type Checker의 결과에 영향을 줄 수 있다는 점을 보여준다.
검사한 파일 수의 차이
저자는 실제 검사 파일 수도 비교했다.
결과는 다음과 같았다.
- TypeScript 7.0.2: 2,287개
- bun check: 1,695개
따라서 두 Checker가 정확히 같은 범위의 파일을 검사했는지 확정할 수 없었다.
저자는 이러한 차이의 원인을 완전히 규명하지 않았다고 명시했다.
이는 Benchmark에서 중요한 제한사항이다.
두 도구가 같은 Repository를 입력받았다는 사실과 실제 동일한 파일 집합을 검사했다는 사실은 다르다.
따라서 실제 성능 차이를 비교할 때는 검사한 파일의 수와 종류도 함께 확인해야 한다.
오류를 의도적으로 생성한 실험
저자는 다른 Repository에서 일부러 TypeScript 오류를 추가했다.
대표적으로 다음과 같은 코드다.
const count: number = "three";
이 코드는 String을 Number 변수에 할당하므로 타입 오류가 발생한다.
또한 잘못된 함수 인자와 존재하지 않는 Property에 접근하는 코드를 추가했다.
결과는 다음과 같았다.
여섯 Checker 모두 같은 네 줄의 오류를 발견했다.
하지만 Exit Code는 서로 달랐다.
TypeScript 7.0.2와 Bun은 1을 반환했다.
반면 다른 Checker는 2를 반환했다.
따라서 CI Script에서 특정 Exit Code 하나만 실패로 처리하도록 작성했다면 문제가 발생할 수 있다.
실제 Checker를 교체할 때는 오류의 내용뿐 아니라 종료 코드의 의미도 확인해야 한다.
실제 실행 시간
저자는 각 Checker를 여러 번 실행한 뒤 중앙값을 비교했다.
일부 결과는 다음과 같았다.
| Checker | date-fns, 기본 Thread |
|---|---|
| TypeScript 7.0.2 | 0.72초 |
| TypeScript 7.1 Beta | 0.65초 |
| tsc-rs | 0.40초 |
| tsc-ts | 0.40초 |
| tsrs | 0.20초 |
| bun check | 0.27초 |
이 결과에서는 tsrs가 TypeScript 7.0.2보다 약 3.7배 빨랐다.
Bun은 약 2.7배 빨랐다.
하지만 이번 측정은 같은 코드를 완전히 동일한 범위로 검사했다는 사실이 보장되지 않는 조건에서 수행됐다.
또한 테스트 머신에 다른 CPU 부하가 존재했다.
따라서 해당 수치를 모든 TypeScript 프로젝트에 적용되는 속도 개선으로 취급해서는 안 된다.
외부 Benchmark와 비교
저자는 다른 개발자의 Benchmark도 함께 소개했다.
대표적으로 Apple M5에서 수행한 비교에서는 다음 결과가 보고됐다.
- tsrs: VS Code 기준 최대 5.8배
- bun check: VS Code 기준 약 3.3배
- tsc-rs: VS Code 기준 약 2.4배
하지만 이는 다른 머신과 다른 프로젝트에서 측정한 결과다.
따라서 저자의 M1 Pro 실험과 직접 합쳐 하나의 평균 성능으로 계산해서는 안 된다.
저자는 특히 CPU Thread 수에 따라 성능 비율이 크게 달라질 수 있다고 설명한다.
루트 tsconfig의 함정
이번 글에서 중요한 발견 가운데 하나는 루트 TypeScript Configuration이다.
저자가 사용한 프로젝트에서는 루트 tsconfig.json에 다음 설정이 존재했다.
"include": []
그리고 Project References가 정의돼 있었다.
이 상황에서 단순히 다음 명령을 실행했다고 가정해 보자.
tsc -p .
일부 Checker는 파일을 하나도 검사하지 않고 정상 종료할 수 있다.
실제로 Extended Diagnostics에서는 다음 결과가 나타났다.
Files: 0
즉 Checker가 성공적으로 종료됐지만 실제로는 검사한 파일이 없었다.
따라서 CI에서 Type Checker의 Exit Code만 확인한다면 문제가 발생할 수 있다.
저자가 제안한 검증 방법
저자는 Type Checker를 교체할 때 세 가지를 확인하도록 설명한다.
첫 번째는 실제 검사 파일 수다.
대표적으로 --extendedDiagnostics의 Files 값을 확인할 수 있다.
두 번째는 의도적인 타입 오류를 추가하는 것이다.
새 Checker가 해당 오류를 발견하는지 확인해야 한다.
세 번째는 동일한 조건에서 전체 검사 시간을 측정하는 것이다.
특히 CPU Thread 수와 실제 빌드 준비 상태를 통제해야 한다.
이러한 방식은 단순한 Benchmark 숫자보다 실제 도구의 호환성과 정확성을 검증하는 데 도움이 된다.
실험의 한계
이번 글은 실제 실행 명령과 버전, Repository Commit을 제공한다.
따라서 재현 가능한 부분이 존재한다.
하지만 다음 제한사항도 명확하게 존재한다.
- 테스트 머신이 완전히 Idle 상태가 아님
- 모든 Checker의 내부 동작이 동일하지 않음
- 검사 파일 수가 다름
- Project References의 처리 방식이 다름
- 일부 측정의 변동이 큼
따라서 이번 결과를 특정 Checker가 모든 프로젝트에서 가장 빠르거나 정확하다는 결론으로 사용해서는 안 된다.
이번 글은 TypeScript Checker의 성능을 비교할 때 처리 시간만 측정하지 않고 실제 검사 범위와 Diagnostic, 빌드 준비 상태 및 CI 종료 코드까지 확인해야 한다는 점을 구체적인 실험으로 보여준다.
I crawled all 1,093 of our pages: the 409 deepest now have 11 ways in, and the only stragglers are the 3 outside the registry
- 원제: I crawled all 1,093 of our pages: the 409 deepest now have 11 ways in, and the only stragglers are the 3 outside the registry
- 저자: Daniel Pertu
- 매체: DEV Community
- 게시일: 2026-11-17
- 기술: Next.js, TypeScript, SEO, Internal Linking, Sitemap, Registry 기반 Navigation
- 원문: https://dev.to/daniel_pertu/i-crawled-all-1093-of-our-pages-the-409-deepest-now-have-11-ways-in-and-the-only-stragglers-are-3a09
실제 Next.js 웹사이트의 1,093개 페이지를 모두 Crawling해 내부 링크의 연결 구조를 측정하고 특정 페이지들이 다른 페이지에서 얼마나 쉽게 발견되는지 개선한 과정을 설명한 글이다.
이번 글의 특징은 내부 링크를 추가했다는 사실만으로 작업이 성공했다고 판단하지 않았다는 점이다.
실제 사이트의 모든 URL을 방문했다.
그리고 각 페이지가 어디에서 링크를 받는지 계산했다.
그 결과 대부분의 페이지는 정상적으로 연결돼 있었지만 Registry 밖에 존재하는 세 페이지는 여전히 문제가 남아 있다는 사실을 발견했다.
기존 사이트의 구조
저자의 서비스는 CogniPrep다.
여러 기업의 채용 시험과 관련된 정보를 제공한다.
실제 URL 구조는 다음과 같다.
/games/<provider>/<test>
예를 들어 특정 기업이 사용하는 시험 종류를 설명하는 페이지가 존재할 수 있다.
이러한 페이지는 검색 엔진의 Long-tail Query와 연결될 수 있다.
사용자가 매우 구체적인 시험 이름을 검색하기 때문이다.
하지만 실제 사이트의 가장 깊은 페이지는 다른 콘텐츠에서 충분한 링크를 받지 못할 수 있었다.
예를 들어 다음 페이지가 존재한다고 가정해 보자.
- 기업별 시험 목록
- 특정 시험 설명
- 시험 준비 가이드
- 관련 블로그 글
실제로 이 콘텐츠들은 같은 시험을 다룬다.
하지만 각 페이지에서 다른 페이지로 이동할 수 있는 링크가 부족할 수 있다.
Registry 기반 링크 생성
저자는 실제 페이지 정보를 하나의 Registry에서 관리했다.
예를 들어 다음 정보를 가진다.
- 시험 ID
- 시험 Provider
- 실제 URL
- 검색에 사용하는 이름
그리고 이 Registry를 이용해 관련 시험의 링크를 생성했다.
중요한 부분은 링크 목록을 페이지마다 수동으로 작성하지 않는다는 것이다.
예를 들어 어떤 Provider에 17개의 시험이 존재한다고 가정해 보자.
해당 Provider의 설명 페이지에서는 Registry에서 17개 시험을 가져온다.
이후 실제 시험 페이지의 링크를 생성한다.
따라서 새로운 시험이 추가되면 Registry에 한 번 등록하는 것만으로 관련 페이지에서 링크를 생성할 수 있다.
여러 페이지에서 같은 컴포넌트 사용
저자는 하나의 공통 컴포넌트를 여러 페이지에서 사용했다.
대표적인 적용 위치는 다음과 같다.
- 시험 상세 페이지
- Provider별 가이드
- 관련 블로그 글
각 페이지는 같은 Registry를 참조한다.
따라서 실제 링크를 생성하는 규칙이 여러 곳에 흩어지지 않는다.
또한 링크의 Anchor Text에는 짧은 내부 코드가 아니라 실제 사용자가 검색할 만한 이름을 사용했다.
이러한 방식은 링크의 의미를 이해하기 쉽게 만든다.
하지만 Anchor Text를 변경했다는 사실만으로 검색 순위가 반드시 증가한다고 보장할 수는 없다.
실제 검색 엔진의 평가에는 다른 요소도 영향을 준다.
블로그 글에서 링크 생성
저자는 블로그 글이 특정 Provider의 시험만 다루는 경우를 구분했다.
예를 들어 어떤 블로그 글이 특정 기업의 시험을 여러 개 소개한다고 가정해 보자.
이 경우 해당 기업의 모든 관련 시험 페이지로 링크를 생성할 수 있다.
반면 한 블로그 글이 여러 기업의 시험을 함께 설명한다면 하나의 Provider에 속한 글로 판단하지 않는다.
따라서 특정 Provider의 모든 시험 링크를 무조건 표시하지 않는다.
이러한 방식은 관련성이 높은 콘텐츠에만 링크를 추가하기 위한 것이다.
하지만 실제 Registry의 데이터가 잘못됐다면 잘못된 링크가 여러 페이지에서 반복될 수 있다.
따라서 공통 데이터 구조의 정확성이 중요하다.
모바일에서 링크를 숨기는 방식
실제 Provider에 17개의 시험이 있다고 가정해 보자.
데스크톱에서는 17개 링크를 표시해도 큰 문제가 없을 수 있다.
하지만 모바일에서는 긴 링크 목록이 화면을 많이 차지한다.
저자는 이를 해결하기 위해 CSS로 일부 링크만 표시했다.
예를 들어 작은 화면에서는 네 개 링크만 보이도록 구성할 수 있다.
중요한 점은 나머지 링크를 실제 DOM에서 제거하지 않는다는 것이다.
모든 링크는 HTML에 존재한다.
하지만 CSS를 이용해 일부를 숨긴다.
저자는 이러한 구조가 검색 엔진의 Crawling에도 도움이 될 수 있다고 설명한다.
다만 CSS로 숨긴 링크가 존재한다는 사실만으로 검색 엔진이 모든 링크를 동일한 가치로 평가한다고 보장할 수는 없다.
실제 검색 엔진의 처리 방식과 페이지의 콘텐츠 관계도 영향을 준다.
또한 사용자에게 숨긴 링크를 실제로 어떻게 표시할지에 관한 접근성도 검토해야 한다.
전체 사이트 Crawling
저자는 실제 Sitemap의 URL을 모두 가져왔다.
그리고 각 페이지의 HTML을 요청했다.
측정 규모는 다음과 같았다.
| 항목 | 결과 |
|---|---|
| 전체 URL | 1,093개 |
| HTTP 200 응답 | 1,093개 |
| Crawling 시간 | 92초 |
| 내부 링크 인스턴스 | 58,030개 |
| 완전한 Orphan Page | 0개 |
이 결과는 실제 공개 페이지가 정상적으로 응답하고 내부 링크를 가지고 있었다는 사실을 보여준다.
하지만 모든 링크가 실제 사용자에게 의미 있는 연결이라는 뜻은 아니다.
예를 들어 공통 Header와 Footer에는 매우 많은 링크가 존재할 수 있다.
저자는 이러한 공통 Navigation을 별도로 구분했다.
공통 링크의 영향 제거
실제 측정에서는 36개 목적지가 전체 페이지의 95% 이상에서 링크를 받았다.
대표적으로 다음 종류의 페이지일 수 있다.
- 홈페이지
- 공통 Navigation
- Footer의 정책 페이지
이러한 링크는 사이트 전체에 반복적으로 존재한다.
따라서 모든 내부 링크를 단순히 합산하면 실제 콘텐츠 사이의 연결 관계를 정확하게 이해하기 어렵다.
저자는 공통 Navigation의 링크와 특정 콘텐츠의 링크를 구분했다.
이러한 구분은 실제 내부 링크 개선의 효과를 분석하는 데 중요하다.
409개 시험 페이지의 결과
저자는 가장 깊은 시험 페이지 409개를 별도로 분석했다.
결과는 다음과 같았다.
| 항목 | 결과 |
|---|---|
| 시험 페이지 | 409개 |
| 전체 유입 링크 | 4,755개 |
| 최소 유입 링크 | 5개 |
| 중앙값 | 11개 |
| 평균 | 11.6개 |
| 최대 | 25개 |
또한 링크가 어디에서 생성됐는지도 구분했다.
| 링크 출처 | 유입 링크 |
|---|---|
| 다른 시험 페이지 | 2,683개 |
| 블로그 글 | 595개 |
| 시험 유형 페이지 | 420개 |
| Provider Hub | 410개 |
| 준비 가이드 | 409개 |
| 기업 가이드 | 134개 |
| 정답 관련 페이지 | 69개 |
| Benchmark 페이지 | 28개 |
| 네덜란드어·독일어 페이지 | 6개 |
가장 많은 링크는 같은 시험 페이지 집단 내부에서 발생했다.
하지만 저자는 같은 페이지 집단이 서로 연결하는 것보다 다른 종류의 관련 콘텐츠에서 새로운 링크를 받는 것이 이번 변경의 중요한 부분이라고 설명한다.
실제로 다른 Page Family에서 들어오는 링크는 2,072개였다.
이는 기존 시험 페이지 집단이 다른 콘텐츠와 더 많이 연결되도록 변경됐다는 사실을 보여준다.
Registry 밖에 존재하는 세 페이지
이번 작업에서 가장 중요한 발견은 다음 문제다.
저자는 새로운 공통 컴포넌트가 모든 관련 시험 페이지에 링크를 제공한다고 생각했다.
하지만 실제 Crawling에서는 세 페이지가 예상한 범위에서 누락됐다.
이 세 페이지는 다음 URL 구조에 존재했다.
/games/<provider>/...
실제 URL만 보면 일반적인 시험 페이지처럼 보였다.
하지만 해당 페이지는 TEST_PAGES Registry에 등록되지 않은 Benchmark 관련 페이지였다.
따라서 Registry를 기준으로 생성하는 공통 링크 목록에서 제외됐다.
실제 해당 페이지의 유입 링크 수는 다음과 같았다.
- 1개
- 2개
- 2개
즉 Registry를 기준으로 링크를 자동 생성하면 Registry 안의 데이터는 일관되게 처리할 수 있지만, Registry 밖에 존재하는 데이터는 자동으로 발견하지 못할 수 있다는 문제가 나타났다.
자동화된 데이터 구조의 한계
이번 사례는 Registry 기반 설계의 장점과 한계를 함께 보여준다.
Registry를 사용하면 다음 작업이 쉬워진다.
- 새로운 페이지 추가
- 관련 링크 생성
- Anchor Text 관리
- 여러 페이지의 동일한 규칙 적용
하지만 Registry가 완전하지 않다면 문제가 발생할 수 있다.
예를 들어 새로운 개발자가 실제 페이지를 추가했다.
하지만 Registry에는 등록하지 않았다.
이 경우 해당 페이지는 정상적으로 배포될 수 있다.
그러나 공통 링크 생성 시스템에서는 발견되지 않을 수 있다.
따라서 실제 파일시스템의 Route 목록과 Registry를 비교하는 검증이 필요할 수 있다.
실제 SEO 성능과의 차이
이번 글은 내부 링크 구조를 실제로 측정했다.
하지만 다음 결과까지 검증한 것은 아니다.
- Google 검색 순위 상승
- Organic Search 유입 증가
- 검색 클릭률 증가
- 검색 엔진의 실제 색인 속도 개선
따라서 링크의 개수가 증가했다는 사실만으로 실제 SEO 성과가 개선됐다고 단정해서는 안 된다.
또한 내부 링크는 실제 사용자에게 유용해야 한다.
단순히 링크 수를 늘리기 위해 관련성이 낮은 페이지를 연결하는 것은 적절하지 않을 수 있다.
이번 글은 대규모 Next.js 사이트에서 내부 링크를 코드와 Registry로 관리하면서 실제 모든 페이지를 Crawling해 자동 생성 구조의 누락을 발견하는 방법을 보여주는 운영 사례다.
Invoice PDF page breaks: a row split in half, and the total alone on the last page
- 저자: Dudko Development
- 매체: DEV Community / ireceipt.pro
- 게시일: 2026-11-16
- 기술: HTML, CSS, Chromium, Playwright, PDF Printing, Pagination
- 원문: https://dev.to/dudko-dev/invoice-pdf-page-breaks-a-row-split-in-half-and-the-total-alone-on-the-last-page-28d1
HTML과 CSS로 작성한 송장을 PDF로 변환하면서 테이블 행이 페이지 중간에서 잘리거나 합계 정보가 별도의 마지막 페이지에 혼자 표시되는 문제를 분석한 글이다.
이번 글은 단순히 page-break-inside: avoid를 사용하라는 설명에서 끝나지 않는다.
실제로 Headless Chromium에서 여러 종류의 송장을 출력했다.
그리고 각 CSS 규칙이 어떤 상황을 해결하고 어떤 상황에서는 실패하는지 비교했다.
특히 웹페이지의 일반적인 Layout과 인쇄 페이지의 Pagination이 서로 다른 문제라는 점을 보여준다.
실제 문제
일반적인 송장에는 다음 정보가 존재한다.
- 상품 이름
- 수량
- 단가
- 금액
- 소계
- 세금
- 최종 합계
예를 들어 상품이 다섯 개만 존재한다고 가정해 보자.
모든 정보가 하나의 PDF 페이지에 들어갈 수 있다.
하지만 상품이 30개 또는 60개라면 여러 페이지가 필요할 수 있다.
문제는 브라우저가 실제 페이지를 나누는 방식이다.
예를 들어 하나의 상품 설명이 매우 길다고 가정해 보자.
해당 상품 행의 절반이 첫 번째 페이지에 표시된다.
나머지 절반은 두 번째 페이지에 표시된다.
이 경우 실제 송장을 읽는 사용자는 상품 정보의 관계를 이해하기 어려울 수 있다.
실제 Headless Chromium 테스트
저자는 Playwright를 이용해 PDF를 생성했다.
실험 조건은 다음과 같았다.
- Chromium 153
- Playwright 1.63
- US Letter
- 0.5인치 여백
먼저 상품이 60개 존재하는 송장을 출력했다.
실제 결과는 여러 페이지로 나뉘었다.
하지만 일부 행이 페이지 경계에서 잘렸다.
이러한 문제는 단순히 페이지의 높이를 고정하는 방식으로 해결하기 어렵다.
실제 콘텐츠의 길이가 달라질 수 있기 때문이다.
break-inside: avoid
저자는 다음 CSS를 사용했다.
tr {
break-inside: avoid;
}
이 속성은 가능한 경우 하나의 테이블 행을 페이지 사이에서 나누지 않도록 요청한다.
예를 들어 현재 페이지에 50px의 공간만 남아 있다고 가정해 보자.
하지만 다음 상품 행은 80px이다.
브라우저는 해당 행을 다음 페이지로 이동할 수 있다.
이렇게 하면 하나의 상품 정보가 두 페이지에 나뉘는 상황을 줄일 수 있다.
하지만 이 속성이 모든 상황을 해결하는 것은 아니다.
예를 들어 상품 설명이 너무 길어 하나의 행 높이가 전체 페이지보다 커진다면 문제가 발생한다.
실제로 브라우저는 해당 행을 하나의 페이지에 배치할 수 없다.
따라서 break-inside: avoid를 지정했더라도 행을 나누어야 할 수 있다.
테이블 Header 반복
저자는 다음 구조도 사용했다.
<thead>
Chromium의 인쇄 처리에서는 테이블의 Header가 여러 페이지에 반복될 수 있다.
예를 들어 두 번째 페이지에 다음 상품이 표시된다고 가정해 보자.
해당 페이지의 상단에도 다음 정보를 표시할 수 있다.
- 상품
- 수량
- 단가
- 금액
이렇게 하면 실제 사용자가 두 번째 페이지부터 읽더라도 각 Column의 의미를 이해하기 쉽다.
하지만 반복되는 Header 역시 실제 페이지의 사용 가능한 높이를 차지한다.
따라서 Pagination 결과에 영향을 줄 수 있다.
합계가 혼자 남는 문제
두 번째 문제는 합계 영역이었다.
예를 들어 상품이 13개인 송장을 생각할 수 있다.
상품 목록은 첫 번째 페이지에 거의 모두 들어간다.
하지만 실제 합계 영역은 페이지의 아래쪽 공간에 들어가지 않는다.
브라우저는 합계를 두 번째 페이지로 이동시킬 수 있다.
그 결과 첫 번째 페이지에는 상품 목록만 존재한다.
두 번째 페이지에는 다음 정보만 표시된다.
- 소계
- 세금
- 최종 합계
실제 문서의 내용은 모두 존재한다.
하지만 사용자 경험은 좋지 않다.
합계가 어떤 상품 목록에 관한 것인지 직관적으로 연결하기 어렵기 때문이다.
break-inside만으로는 부족
저자는 먼저 다음 설정을 사용했다.
.totals {
break-inside: avoid;
}
이렇게 하면 합계 영역 자체가 여러 페이지로 나뉘는 문제는 줄일 수 있다.
하지만 실제 합계 전체가 다음 페이지로 이동할 수 있다.
따라서 두 번째 페이지에 합계만 존재하는 문제는 계속된다.
저자는 이를 해결하기 위해 다음 규칙을 추가했다.
break-before: avoid
이 규칙은 해당 요소가 이전 콘텐츠와 분리되지 않도록 요청한다.
따라서 브라우저가 합계와 마지막 상품 행을 함께 다음 페이지로 이동시킬 수 있다.
실제 동작
저자가 사용한 CSS는 다음과 같다.
.totals {
break-inside: avoid;
break-before: avoid;
}
이후 Chromium에서는 마지막 상품 행과 합계가 같은 페이지에 표시됐다.
또한 테이블 Header도 다음 페이지에 다시 표시됐다.
저자는 다음 방법으로도 비슷한 결과를 얻었다.
tbody tr:last-child { break-after: avoid; }
즉 마지막 상품 행 이후에 페이지를 나누지 않도록 요청하는 방식이다.
두 방법은 실제 문서의 구조와 스타일에 따라 선택할 수 있다.
다만 CSS의 Pagination Hint가 모든 브라우저와 모든 콘텐츠에서 동일한 결과를 보장하는 것은 아니다.
실제 사용하는 PDF Renderer에서 테스트해야 한다.
<tfoot>를 사용하지 않은 이유
합계는 테이블의 Footer에 해당하는 정보처럼 보일 수 있다.
따라서 다음 요소를 사용할 수 있다고 생각할 수 있다.
<tfoot>
하지만 저자는 이 방법을 사용하지 않았다.
이유는 Chromium이 여러 페이지에 걸친 Table의 <tfoot>를 반복해서 표시할 수 있기 때문이다.
예를 들어 전체 송장이 세 페이지라고 가정해 보자.
최종 합계는 세 번째 페이지에 한 번만 표시해야 한다.
하지만 <tfoot>에 합계를 배치하면 각 페이지의 하단에 같은 합계가 반복될 수 있다.
따라서 실제 최종 합계에는 적합하지 않을 수 있다.
저자는 <tfoot>를 다음 정보에 사용하는 것이 더 적절할 수 있다고 설명한다.
다음 페이지에 계속
즉 반복해야 하는 Footer와 최종 문서의 합계를 구분해야 한다.
한 페이지보다 큰 행
저자는 매우 긴 상품 설명도 테스트했다.
특정 상품 행에 70줄의 설명을 포함했다.
이 경우 실제 하나의 행이 PDF 페이지보다 커졌다.
break-inside: avoid를 지정했더라도 브라우저는 해당 행을 하나의 페이지에 배치할 수 없었다.
실제로는 다음 문제가 발생했다.
- 해당 행을 새로운 페이지로 이동
- 이전 페이지에 많은 빈 공간 발생
- 새로운 페이지에서도 전체 행이 들어가지 않음
- 행이 다시 여러 페이지로 분리
따라서 CSS만으로 모든 Pagination 문제를 해결할 수 없다.
저자는 이러한 경우 긴 설명을 테이블에서 제한하고 별도의 Notes 영역에 표시하는 방법을 검토하도록 설명한다.
PDF Renderer의 차이
이번 테스트는 Chromium 기반으로 수행됐다.
하지만 실제 PDF 생성에는 여러 도구가 존재한다.
대표적으로 다음과 같다.
- Chromium
- Playwright
- Puppeteer
- wkhtmltopdf
이러한 도구가 같은 CSS Pagination 기능을 지원한다고 보장할 수 없다.
특히 wkhtmltopdf는 오래된 QtWebKit 기반이므로 Chromium과 다른 결과를 생성할 수 있다.
따라서 이번 CSS 규칙이 wkhtmltopdf에서도 동일하게 동작한다고 판단해서는 안 된다.
적용 범위와 한계
이번 글은 실제 PDF를 생성하면서 Pagination 문제를 검증했다.
하지만 모든 용지 크기와 Font, 브라우저 버전을 대상으로 한 독립적인 Benchmark는 아니다.
또한 break-before: avoid와 break-inside: avoid는 브라우저에 전달하는 Pagination Hint다.
실제 페이지의 높이보다 큰 콘텐츠를 반드시 하나의 페이지에 표시할 수 있도록 만드는 기능은 아니다.
이번 글은 HTML 기반 PDF에서 테이블 행과 합계 영역의 논리적인 관계를 유지하려면 단순히 요소의 분할을 금지하는 것뿐 아니라 앞뒤 콘텐츠의 페이지 분리 조건까지 함께 설계해야 한다는 점을 실제 테스트로 설명한다.
Zod-Validated LLM Output: The Repair Loop That Makes It Safe to Ship
- 저자: Muhammad Zain Ul Abidin
- 매체: DEV Community / zainvibes.com
- 게시일: 2026-11-17
- 기술: TypeScript, Zod 4, JSON Schema, LLM, Structured Output, 오류 복구
- 원문: https://dev.to/zforzain2000/zod-validated-llm-output-the-repair-loop-that-makes-it-safe-to-ship-3b00
AI 모델이 생성한 JSON을 실제 데이터베이스에 저장하는 과정에서 발생한 오류를 바탕으로 모델의 응답을 검증하고 일부 오류는 자동으로 복구하며 복구할 수 없는 결과는 별도로 처리하는 구조를 설명한 글이다.
이번 글의 핵심은 모델에게 JSON 형식으로 답변하라고 요청하는 것과 실제 JSON 데이터가 애플리케이션의 Schema를 만족한다는 사실이 서로 다르다는 점이다.
저자는 고객지원 Ticket을 자동으로 분류하는 기능을 구현했다.
처음에는 Prompt에 다음 지시를 포함했다.
JSON만 반환하세요.
초기에는 정상적으로 동작했다.
하지만 이후 한 응답에서 Markdown Code Fence와 잘못된 Category가 함께 생성됐다.
그 결과 실제 데이터베이스에 잘못된 분류 정보가 저장됐다.
저자는 이러한 문제를 해결하기 위해 Zod 기반의 검증 계층을 만들었다.
실제 데이터 구조
저자는 고객지원 Ticket을 다음 정보로 분류했다.
- Summary
- Category
- Priority
- Confidence
- 사람의 검토 필요 여부
- Tag 목록
대표적인 Zod Schema는 다음 조건을 포함한다.
| 필드 | 조건 |
|---|---|
summary | String, 10~200자 |
category | billing·bug·feature·account |
priority | low·medium·high·urgent |
confidence | 0~1 사이의 Number |
needsHuman | Boolean |
tags | 최대 5개의 String |
예를 들어 다음 값은 허용되지 않는다.
category: "refund"
실제 Schema에서 허용한 Category가 아니기 때문이다.
또한 다음 값도 잘못될 수 있다.
confidence: "0.92"
실제로는 숫자이지만 String으로 반환했기 때문이다.
이러한 오류는 JSON의 문법이 올바르더라도 발생할 수 있다.
따라서 JSON Parsing과 Schema Validation을 구분해야 한다.
여덟 가지 실패 유형
저자는 실제 운영에서 발생할 수 있는 여덟 종류의 모델 응답을 구성했다.
그리고 Zod로 검증했다.
| 응답 유형 | 원본 검증 | 간단한 복구 이후 |
|---|---|---|
| 정상 JSON | 통과 | 통과 |
| 설명 문장과 Code Fence 포함 | 실패 | 통과 |
| 존재하지 않는 Enum | 실패 | 실패 |
| 응답이 중간에서 잘림 | 실패 | 실패 |
| 숫자를 String으로 반환 | 실패 | 실패 |
| 필수 필드 누락 | 실패 | 실패 |
| 정의하지 않은 추가 필드 | 통과 | 통과 |
| 숫자가 범위를 초과 | 실패 | 실패 |
결과는 다음과 같았다.
- 원본 응답 통과: 2/8
- 간단한 복구 이후 통과: 3/8
- 추가 복구가 필요한 결과: 5/8
이러한 결과는 저자가 구성한 여덟 개의 테스트 입력에 관한 것이다.
실제 모델의 전체 오류율이 75%라는 의미는 아니다.
실제 운영 환경에서 모델이 어떤 비율로 오류를 생성하는지는 별도의 측정이 필요하다.
Code Fence 제거의 한계
예를 들어 모델이 다음과 같이 응답했다고 가정해 보자.
```json
{
"category": "refund"
}
```
개발자는 Code Fence만 제거할 수 있다.
그러면 JSON Parsing 자체는 성공할 수 있다.
하지만 refund는 실제 허용된 Category가 아니다.
따라서 Schema Validation에는 여전히 실패한다.
즉 Code Fence를 제거했다는 사실만으로 결과가 정상 데이터가 되는 것은 아니다.
저자는 이러한 문제를 구분하기 위해 다음 두 단계를 사용한다.
- 결정적인 문자열 정리
- Zod Schema Validation
첫 번째 단계에서는 명확하게 제거할 수 있는 불필요한 표현만 정리한다.
두 번째 단계에서는 실제 데이터 구조와 범위를 검사한다.
safeParse()
저자는 다음 API를 사용한다.
safeParse()
이 함수는 실제 입력이 Schema를 만족하는지 검사한다.
정상적인 결과라면 검증한 데이터를 사용할 수 있다.
반면 실패하면 실제 오류 목록을 확인할 수 있다.
대표적으로 다음 문제가 표시될 수 있다.
- 필요한 필드 누락
- Enum 불일치
- 잘못된 타입
- 최대 길이 초과
- 숫자 범위 초과
이러한 오류 목록은 실제 모델에 재시도를 요청할 때도 사용할 수 있다.
Zod의 알 수 없는 필드 처리
이번 글에서 중요한 부분은 Zod의 객체 처리 정책이다.
예를 들어 모델이 다음 필드를 추가했다고 가정해 보자.
internalNote
하지만 실제 Schema에는 이 필드가 존재하지 않는다.
기본 z.object()는 이러한 알 수 없는 필드를 제거할 수 있다.
따라서 Schema Validation이 통과하더라도 실제 반환 데이터에서는 해당 필드가 사라질 수 있다.
하지만 개발자가 이러한 동작을 원하지 않을 수 있다.
예를 들어 모델이 예상하지 못한 정보를 생성했다면 이를 오류로 처리하고 싶을 수 있다.
이 경우 다음 API를 사용할 수 있다.
z.strictObject()
반대로 추가 필드를 허용하려면 다음 API를 사용할 수 있다.
z.looseObject()
따라서 실제 Schema의 검증 정책을 명확하게 선택해야 한다.
숫자 문자열 변환
일부 모델은 다음 값을 반환할 수 있다.
"0.92"
하지만 실제 Schema는 Number를 기대한다.
이러한 경우 Zod의 다음 기능을 사용할 수 있다.
z.coerce.number()
이 기능은 실제 String을 Number로 변환할 수 있다.
하지만 모든 입력을 무조건 Coercion하는 것이 적절한 것은 아니다.
예를 들어 비정상적인 문자열이나 빈 값이 의도하지 않은 Number로 변환될 수 있다.
따라서 실제 입력의 출처와 허용 범위를 고려해야 한다.
재시도 구조
저자는 Schema Validation에 실패한 결과를 무조건 폐기하지 않았다.
실제 오류의 종류를 분류했다.
예를 들어 다음 상황이다.
- Category가 허용되지 않는 값
- 필수 필드 누락
- Summary 길이 초과
이러한 오류는 실제 모델에 검증 결과를 전달한 뒤 다시 생성하도록 요청할 수 있다.
하지만 응답이 Token 제한 때문에 중간에서 잘린 경우에는 다른 문제가 존재한다.
실제 출력 제한이 그대로라면 다시 요청해도 같은 위치에서 잘릴 수 있다.
따라서 단순한 재시도 대신 출력 Token Budget을 변경해야 할 수 있다.
저자는 이러한 오류의 종류를 구분해 처리하도록 설명한다.
무제한 재시도를 사용하지 않음
모델 응답이 계속 잘못될 수 있다.
이때 재시도를 무제한 반복하면 다음 문제가 발생할 수 있다.
- 추론 비용 증가
- 요청 지연 증가
- 동일한 오류 반복
- 실제 작업 실패의 은폐
따라서 저자는 재시도 횟수를 제한한다.
이후에도 정상적인 결과를 얻지 못한다면 별도 실패 처리를 수행한다.
대표적인 방법은 Dead-letter Queue다.
이 Queue에는 자동으로 처리하지 못한 결과를 보관한다.
이후 별도의 작업자나 사람이 해당 데이터를 검토할 수 있다.
따라서 실제 데이터베이스에 잘못된 결과를 억지로 저장하지 않아도 된다.
Structured Output과 최종 검증
이번 글에서는 여러 AI 제공업체의 Structured Output API도 비교한다.
대표적인 제공업체는 다음과 같다.
- OpenAI
- Google Gemini
- Anthropic
각 서비스는 JSON Schema를 이용해 출력 형식을 제한할 수 있다.
하지만 실제 지원하는 JSON Schema의 범위는 서로 다를 수 있다.
예를 들어 특정 Provider에서는 다음 제약이 제한적으로 지원될 수 있다.
- 최소 문자열 길이
- 최대 문자열 길이
- 숫자 범위
- 배열의 최대 길이
따라서 Provider에서 Structured Output을 사용했다는 사실만으로 모든 Zod 제약이 실제 모델 생성 단계에서 강제된다고 보장할 수 없다.
또한 실제 응답은 다음 이유로 Schema를 만족하지 못할 수 있다.
- Safety Refusal
- Token Limit
- 응답 중단
- Provider별 지원 차이
따라서 실제 모델의 출력 형식을 제한하는 기능과 애플리케이션의 최종 Runtime Validation은 별도로 관리해야 한다.
실제 Validation 성능
저자는 Zod safeParse()의 실행 비용도 측정했다.
동일한 Schema에 대해 20,000번 검증했다.
결과는 다음과 같았다.
- 총 실행 시간: 25.1ms
- 검증 1회: 약 1.3마이크로초
이 수치는 저자가 작성한 비교적 작은 Schema에서 수행한 자체 측정이다.
모든 Zod Schema가 같은 시간에 검증된다는 의미는 아니다.
특히 중첩 구조가 복잡하거나 많은 Refinement가 존재한다면 실행 비용이 증가할 수 있다.
하지만 실제 모델 호출에는 일반적으로 네트워크와 추론 시간이 발생한다.
따라서 이러한 단순 Schema에서는 Runtime Validation의 비용이 모델 추론보다 훨씬 작을 수 있다.
데이터 의미의 검증은 별개
이번 글에서 중요한 한계는 다음과 같다.
JSON Schema가 정상이라는 사실과 실제 모델의 판단이 올바르다는 사실은 다르다.
예를 들어 모델이 다음 결과를 반환했다고 가정해 보자.
category: "billing"
이는 허용된 Category다.
따라서 Schema Validation을 통과할 수 있다.
하지만 실제 고객의 질문은 기술적인 버그에 관한 것일 수 있다.
이 경우 데이터의 구조는 올바르지만 내용은 잘못된 것이다.
따라서 실제 비즈니스 판단의 정확성을 검증하려면 별도의 평가가 필요하다.
적용 범위와 한계
이번 글의 여덟 가지 테스트 결과는 저자가 구성한 실패 사례에 관한 것이다.
실제 모든 모델의 오류 발생 비율을 대표하는 Benchmark는 아니다.
또한 문자열 복구와 재시도가 모든 잘못된 응답을 정상 데이터로 바꾸는 것은 아니다.
실제 중요한 작업에서는 사람의 확인과 비즈니스 규칙 검증이 필요할 수 있다.
이번 글은 AI 모델의 JSON 출력을 실제 애플리케이션 데이터로 사용하기 전에 문법과 타입, 허용 범위, 의미적 정확성을 구분해 검증하고 복구할 수 없는 실패를 명시적으로 처리하는 방법을 설명한 실무 사례다.