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

기준 시점: 2026-11-23 06:00 KST
조사 범위: 전일 2026-11-22 06:00 ~ 당일 2026-11-23 06:00 KST
추천 글 범위: 기준 시점 당시 최근 7일
1️⃣ 프론트엔드
이번 조사 범위에서 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
React, Next.js, Vercel, Vue, Nuxt, Angular, Svelte, SvelteKit, Astro, Remix의 공식 블로그와 릴리스 기록을 조사했다.
이번 기간에는 주요 프론트엔드 프레임워크의 새로운 안정 버전이나 중요한 사용자 API의 정식 출시를 확인하지 못했다.
Next.js에서는 16.5.0-canary.60이 공개된 사실을 확인했다.
- 버전: Next.js 16.5.0-canary.60
- 공개일: 2026-11-21 — 정확한 KST 게시 시각 미확인
- 안정화 단계: Canary Pre-release
- 공식 원문: https://github.com/vercel/next.js/releases/tag/v16.5.0-canary.60
해당 릴리스에서는 Turbopack의 파일시스템 탐색 순서와 내부 Route 작업 정보, 개발 문서 등을 수정했다.
예를 들어 파일시스템에서 App Directory의 진입점을 탐색할 때 파일의 실제 열거 순서에 영향을 받지 않도록 처리하는 변경이 포함됐다.
이러한 작업은 빌드 결과의 일관성과 내부 코드 유지보수에 관련된다.
하지만 이번 릴리스에서 일반 개발자가 새롭게 사용할 수 있는 주요 안정 API나 프레임워크의 새로운 렌더링 기능은 확인되지 않았다.
또한 관련 성능 수치도 공개되지 않았다.
따라서 Canary의 내부 변경을 새로운 주요 기능 출시로 취급하지 않았다.
다음 공식 릴리스 기록도 확인했다.
- React: https://github.com/facebook/react/releases
- Next.js: https://github.com/vercel/next.js/releases
- Vue: https://github.com/vuejs/core/releases
- Nuxt: https://github.com/nuxt/nuxt/releases
- Angular: https://github.com/angular/angular/releases
- Svelte: https://github.com/sveltejs/svelte/releases
- SvelteKit: https://github.com/sveltejs/kit/releases
- Astro: https://github.com/withastro/astro/releases
- React Router·Remix: https://github.com/remix-run/react-router/releases
이전 브리핑에서 다룬 Vue 3.5.46의 SSR·Hydration 수정, SvelteKit 3.4.0과 Cloudflare Adapter 9.0.0, Next.js 16.5 계열의 Turbopack 최적화도 반복하지 않았다.
이번 추천 글에서는 프레임워크 자체의 릴리스 대신 실제 Next.js 서비스에서 User-Agent별 HTML과 가격이 달라지는 문제, 브라우저에서 AI 모델을 실행하며 발생한 성능 병목을 분석한 자료를 선정했다.
2️⃣ 웹 플랫폼·브라우저
이번 조사 범위에서 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
W3C, WHATWG, TC39, MDN, Chrome·Chromium, Firefox·Mozilla, WebKit·Safari의 공식 자료와 JavaScript·TypeScript·CSS, 웹 성능 및 접근성 관련 발표를 조사했다.
이번 기간에 주요 웹 표준이 새롭게 정식 채택됐거나 일반 사용자에게 제공되는 안정 브라우저에서 중요한 신규 API가 기본 활성화됐다는 발표는 확인하지 못했다.
특히 다음 세 종류의 변경을 구분했다.
첫 번째는 웹 표준 문서의 변경이다. 규격 초안의 새로운 문장이 공개되거나 기존 기능의 정의가 수정될 수 있다.
두 번째는 브라우저 엔진의 구현 변경이다. Chromium 또는 WebKit의 개발 브랜치에 새로운 코드가 추가될 수 있다.
세 번째는 실제 안정 브라우저에서의 기본 활성화다. 일반 사용자가 특별한 설정 없이 기능을 사용할 수 있는 단계다.
이 세 단계는 서로 다르다.
예를 들어 특정 CSS 기능이 규격 초안에 존재하거나 Browser Engine에서 실험적으로 구현됐더라도 일반적인 웹서비스에서 바로 사용 가능한 안정 기능이라고 판단할 수는 없다.
관련 공식 자료는 다음과 같다.
- W3C: https://www.w3.org/news/
- WHATWG: https://github.com/whatwg
- TC39: https://github.com/tc39/proposals
- MDN: https://developer.mozilla.org/
- Chrome Developers: https://developer.chrome.com/blog/
- Firefox Release Notes: https://www.firefox.com/en-US/releases/
- WebKit: https://webkit.org/blog/
이번 조사 기간에 해당하는 중요한 안정화 발표를 확인하지 못했으므로 이전 날짜의 변경을 새롭게 소개하지 않았다.
특히 이전 브리핑에서 다룬 Firefox 160의 WebTransport 관련 수정과 WebKit의 Global Privacy Control API, W3C의 시간대 처리 가이드 초안은 반복하지 않았다.
이번 추천 글에서는 이미 널리 사용되는 HTTP의 ETag와 Cache-Control을 실제로 측정한 자료를 소개한다.
특히 304 Not Modified가 파일의 전송량을 얼마나 줄일 수 있는지, no-cache와 no-store의 차이가 무엇인지, Last-Modified만 사용했을 때 어떤 오류가 발생할 수 있는지 자세하게 살펴본다.
3️⃣ 백엔드·인프라
이번 조사 범위에서 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
Cloudflare, AWS, Google Cloud, Microsoft Azure의 공식 제품 변경 기록과 서버리스·엣지 플랫폼, 데이터베이스, API 관련 발표를 조사했다.
최근 주요 발표는 이전 영업일인 11월 20일에 집중돼 있었다.
대표적으로 다음 변경이 존재했다.
- Vercel Functions의 HTTP 요청 본문 최대 20MiB 지원
- Cloudflare Browser Run의 Custom Script API
- Cloudflare Workers·Pages의 과거 배포 버전 보관 정책 변경
- Google BigQuery의 AI Index Preview
- Amazon EventBridge Scheduler의 API Action 지원 확대
- Amazon VPC Lattice의 TCP Metric 확대
이러한 항목은 이전 브리핑에서 이미 다뤘으므로 반복하지 않았다.
또한 GitHub와 주요 오픈소스 프로젝트의 릴리스에서 발견한 내부 코드 변경을 AWS 또는 Cloudflare의 새로운 제품 기능으로 취급하지 않았다.
이번 조사의 주요 공식 출처는 다음과 같다.
- Cloudflare Changelog: https://developers.cloudflare.com/changelog/
- Vercel Changelog: https://vercel.com/changelog
- AWS What's New: https://aws.amazon.com/about-aws/whats-new/
- Google Cloud Release Notes: https://docs.cloud.google.com/release-notes/
- Azure Updates: https://azure.microsoft.com/en-us/updates/
일부 제품 문서는 계속 변경될 수 있지만, 문서의 최근 수정 날짜가 새로운 기능의 최초 발표일과 같다는 의미는 아니다.
따라서 실제 신규 발표 여부와 안정화 단계, 적용 범위를 공식 원문으로 확인하지 못한 항목은 포함하지 않았다.
이번 추천 글에서는 PHP·Nginx·SQLite 기반 웹사이트를 Cloudflare Workers와 D1으로 이전하면서 발생한 데이터베이스 호환성 문제를 자세하게 다룬다.
특히 SQLite와 D1이 같은 SQL 계열이라는 사실만으로 데이터 파일과 전체 Dump가 그대로 호환되는 것은 아니라는 점을 실제 사례로 설명한다.
4️⃣ 개발 도구 및 보안
pnpm 12.23.0·11.29.0 정식 출시 — Monorepo 관리 명령 추가, OTP 유출 방지 및 Lockfile 공급망 검증 강화
- 발표일: 2026-11-22 — GitHub 표시 시각은 12.23.0이 13:22, 11.29.0이 13:58. 표시 시간대가 명시되지 않아 정확한 KST 게시 시각 미확인
- 발표 주체: pnpm
- 버전: pnpm 12.23.0, pnpm 11.29.0
- 안정화 단계: 두 버전 모두 정식 릴리스
- 적용 대상: Node.js 프로젝트, JavaScript·TypeScript Monorepo, npm Registry, CI/CD, 패키지 배포
- 주요 변경:
pnpm edit,pnpm catalog migrate,pnpm link --hard, 플랫폼별 패키지 변형 제거, OTP 설정 차단, HTTPS 인증정보 전송 제한, Lockfile 검증 강화 - pnpm 12.23.0 원문: https://github.com/pnpm/pnpm/releases/tag/v12.23.0
- pnpm 11.29.0 원문: https://github.com/pnpm/pnpm/releases/tag/v11.29.0
pnpm이 두 개의 버전을 같은 날짜에 공개했다.
이번 업데이트에는 새로운 개발 편의 기능과 공급망 보안 관련 수정이 함께 포함됐다.
특히 pnpm 12.23.0에는 기존 Monorepo의 의존성 관리 방식을 정리하는 명령이 추가됐다.
반면 11.29.0에는 현재 11 계열을 사용하는 프로젝트에서도 주요 보안 수정을 사용할 수 있도록 여러 변경이 반영됐다.
따라서 두 릴리스의 공통적인 보안 수정과 12 계열에만 존재하는 신규 기능을 구분해야 한다.
pnpm edit — 설치한 패키지의 디렉터리 열기
pnpm 12.23.0에는 다음 명령이 추가됐다.
pnpm edit
이 명령은 이미 설치한 패키지의 디렉터리를 Editor에서 열 수 있도록 한다.
예를 들어 React 프로젝트에서 어떤 라이브러리의 내부 구현을 확인하려고 한다고 가정해 보자.
실제 패키지는 node_modules 안에 존재한다.
하지만 pnpm의 node_modules는 일반적인 평면 디렉터리와 다르게 Symlink와 별도의 패키지 저장 구조를 사용한다.
따라서 특정 패키지의 실제 설치 위치를 직접 찾기 번거로울 수 있다.
새로운 명령은 이러한 탐색 작업을 단순화한다.
다만 이 기능은 설치한 패키지를 수정한 결과를 자동으로 영구적인 패키지 Patch로 관리하는 기능과는 구분해야 한다.
실제 의존성을 수정한 내용을 재현 가능하게 유지하려면 별도의 Patch 관리가 필요할 수 있다.
pnpm catalog migrate — Monorepo 의존성 버전 중앙 관리
이번 릴리스에서 프론트엔드 Monorepo에 직접적인 영향을 주는 기능은 다음과 같다.
pnpm catalog migrate
pnpm Workspace에서는 여러 프로젝트가 같은 의존성을 사용할 수 있다.
예를 들어 다음 세 프로젝트가 있다고 가정해 보자.
- apps/web
- apps/admin
- packages/ui
세 프로젝트가 모두 같은 TypeScript 버전을 사용한다.
기존에는 각 package.json에 같은 버전을 반복해서 작성할 수 있었다.
예를 들어 다음과 같다.
"typescript": "^7.0.0"
문제는 버전을 변경하는 경우다.
실제 Workspace의 여러 package.json을 함께 수정해야 한다.
pnpm Catalog는 이러한 버전 선언을 Workspace 설정으로 이동할 수 있도록 한다.
예를 들어 다음 구조를 사용할 수 있다.
catalog:
typescript: ^7.0.0
그리고 개별 프로젝트에서는 다음 값을 사용한다.
"typescript": "catalog:"
이렇게 하면 실제 버전 선언을 한 곳에서 관리할 수 있다.
기존 프로젝트의 자동 마이그레이션
새로운 pnpm catalog migrate는 기존 의존성 선언을 분석한다.
그리고 같은 버전을 사용하는 의존성을 기본 Catalog로 이동한다.
하지만 중요한 제한사항이 존재한다.
모든 Workspace 프로젝트가 해당 의존성을 동일한 Version Specifier로 선언한 경우에만 이동한다.
예를 들어 다음 상황을 생각할 수 있다.
| 프로젝트 | TypeScript 선언 |
|---|---|
| apps/web | ^7.0.0 |
| apps/admin | ^7.0.0 |
| packages/ui | ^7.0.0 |
이 경우 Catalog로 이동할 수 있다.
반면 다음 상황에서는 다르다.
| 프로젝트 | TypeScript 선언 |
|---|---|
| apps/web | ^7.0.0 |
| apps/admin | ~7.0.0 |
| packages/ui | ^7.0.0 |
실제 Version Specifier가 서로 다르다.
따라서 명령은 이를 무조건 통합하지 않는다.
대신 변경하지 않은 의존성을 별도로 표시한다.
이러한 방식은 버전 범위의 의미를 유지하기 위한 것이다.
^와 ~는 허용하는 후속 버전의 범위가 다를 수 있기 때문이다.
pnpm link --hard — 파일을 Hard Link로 연결
또 다른 신규 기능은 다음과 같다.
pnpm link --hard
일반적인 개발 과정에서는 로컬 패키지를 연결해 테스트할 수 있다.
예를 들어 다음 두 프로젝트가 있다고 가정해 보자.
- 웹 애플리케이션
- 로컬 UI 라이브러리
개발자는 UI 라이브러리를 npm Registry에 배포하기 전에 웹 애플리케이션에서 테스트하고 싶다.
기존에도 pnpm link를 사용할 수 있었다.
새로운 --hard 옵션은 연결 방식을 변경한다.
이 옵션을 사용하면 연결한 패키지를 file: 의존성으로 기록한다.
그리고 실제 파일을 Hard Link로 node_modules에 연결한다.
따라서 단순한 Symlink와 다른 방식으로 파일을 공유할 수 있다.
또한 연결한 패키지의 Dependency와 Peer Dependency는 실제 대상 프로젝트를 기준으로 해결한다.
이는 React와 같이 Peer Dependency가 중요한 라이브러리를 개발할 때 영향을 줄 수 있다.
예를 들어 UI 라이브러리가 React를 Peer Dependency로 선언했다고 가정해 보자.
실제 웹 애플리케이션에서 사용하는 React 버전과 연결되도록 해야 할 수 있다.
새로운 옵션은 이러한 로컬 개발 상황을 지원하도록 한다.
다만 Hard Link는 운영체제와 파일시스템의 제약을 가진다.
모든 저장 장치와 파일시스템 사이에서 같은 방식으로 사용할 수 있다고 가정해서는 안 된다.
플랫폼별 Variant 기능 제거
이번 12.23.0에는 기존 기능을 제거하는 변경도 포함됐다.
대표적으로 다음 항목이 제거됐다.
publishConfig.variantspackage.json의variantpnpm pack --variantpnpm publish --upload-variantpnpm publish --variant-integritypnpm publish --no-variants
기존에는 같은 패키지 버전에 여러 플랫폼별 Variant를 연결하는 실험적인 구성이 존재했다.
하지만 이번 변경에서는 하나의 패키지 버전이 하나의 Archive를 가지는 구조로 돌아갔다.
예를 들어 다음 환경에서 서로 다른 Native Binary가 필요하다고 가정해 보자.
- macOS ARM64
- Linux x64
- Windows x64
pnpm은 이러한 환경을 지원하기 위해 각 플랫폼용 패키지를 별도로 배포하도록 안내한다.
그리고 메인 패키지에서 다음 항목으로 연결한다.
optionalDependencies
이렇게 하면 플랫폼별 의존성을 개별 패키지로 관리할 수 있다.
기존 Lockfile과의 호환성
Variant 기능의 제거는 실제 CI에 영향을 줄 수 있다.
예를 들어 기존 pnpm-lock.yaml에 Registry 패키지의 플랫폼 Variant 정보가 존재한다고 가정해 보자.
이후 pnpm 12.23.0으로 업데이트한다.
CI에서는 다음 명령을 실행한다.
pnpm install --frozen-lockfile
하지만 기존 Lockfile은 새로운 pnpm이 지원하지 않는 Variant 구조를 포함한다.
이 경우 다음 오류가 발생할 수 있다.
ERR_PNPM_BROKEN_LOCKFILE
pnpm은 해당 Lockfile을 다시 생성하도록 안내한다.
관련 작업은 다음과 같다.
pnpm install
따라서 이번 버전을 단순한 패치처럼 업데이트하기 전에 기존 Lockfile의 구조를 확인해야 할 수 있다.
특히 플랫폼별 Native Binary를 직접 배포하던 패키지 Maintainer에게 영향이 있다.
공개 패키지와 Private Workspace 의존성 검사
pnpm 12.23.0은 pnpm pack과 pnpm publish의 검증도 강화했다.
예를 들어 다음 구조를 생각할 수 있다.
- packages/ui: 공개 npm 패키지
- packages/internal-utils: Private Workspace 패키지
공개 UI 패키지가 Private 패키지를 일반 dependencies에 선언했다고 가정해 보자.
하지만 Private 패키지는 Registry에 공개되지 않는다.
이 경우 공개 UI 패키지를 설치하는 사용자는 해당 의존성을 다운로드할 수 없을 수 있다.
이번 변경에서는 이러한 상황을 배포 전에 오류로 처리한다.
다만 다음 종류의 의존성까지 모두 금지하는 것은 아니다.
- devDependencies
- optionalDependencies
- peerDependencies
- Bundled Dependencies
따라서 실제 공개 패키지의 설치 가능성을 검증하면서도 다른 종류의 의존성은 기존 규칙에 따라 처리한다.
OTP 설정 파일을 통한 Secret 유출 차단
이번 보안 수정 가운데 중요한 부분은 OTP 설정 처리다.
pnpm은 더 이상 설정 파일에서 otp 값을 읽지 않는다.
예를 들어 기존에는 다음 설정이 존재할 수 있었다.
otp: ${NPM_TOKEN}
문제는 Registry 설정도 같은 프로젝트 설정 파일에 존재할 수 있었다는 점이다.
공식 릴리스는 다음 상황을 설명한다.
- 공격자가 Repository의 설정 파일 수정
otp에 환경 변수 참조 작성- Registry URL을 공격자가 관리하는 주소로 변경
- 사용자가
pnpm publish실행 - 실제 환경 변수 값이
npm-otpHeader로 전송
이러한 방식에서는 원래 OTP로 사용하려던 설정이 실제 인증 Token을 외부에 전달하는 통로가 될 수 있었다.
특히 개발자가 신뢰하지 않는 Repository를 Clone한 뒤 자신의 Registry 인증 정보가 존재하는 환경에서 명령을 실행하는 경우가 문제가 될 수 있다.
이번 수정은 설정 파일에서 OTP를 읽는 경로를 차단했다.
새로운 OTP 전달 방식
이제 OTP는 다음 방법으로 전달할 수 있다.
첫 번째는 CLI 옵션이다.
--otp
두 번째는 환경 변수다.
PNPM_CONFIG_OTP
반면 다음 설정 파일에 기록한 OTP는 사용하지 않는다.
- pnpm-workspace.yaml
- Global config.yaml
또한 다음 명령은 오류를 반환한다.
pnpm config set otp
대표적인 오류는 다음과 같다.
ERR_PNPM_CONFIG_SET_NOT_A_FILE_SETTING
따라서 기존 자동화가 설정 파일에 OTP를 저장하는 방식으로 구성돼 있었다면 변경해야 한다.
이번 수정은 pnpm 11.29.0에도 반영됐다.
Registry 인증정보의 HTTPS 전송 제한
두 번째 중요한 보안 변경은 Registry 인증정보의 전송 조건이다.
pnpm은 이제 Registry Credentials를 HTTPS를 통해서만 전달한다.
예외는 Loopback HTTP다.
예를 들어 로컬 개발 환경의 다음 주소는 별도로 처리할 수 있다.
http://127.0.0.1
하지만 일반적인 외부 HTTP Registry로 인증정보를 전송하지 않도록 제한한다.
이러한 변경은 다음 작업에 적용된다.
- Package Metadata 요청
- Tarball 다운로드
- pnprServer 요청
또한 Redirect가 발생하는 경우에도 Registry 인증정보의 Path 범위를 확인하도록 수정했다.
예를 들어 특정 Registry 경로에만 적용해야 하는 Token을 같은 Host의 모든 경로에 전송해서는 안 된다.
이번 수정은 이러한 Credential Scope를 더 정확하게 처리하도록 한다.
Registry 패키지의 로컬 의존성 차단
다음 보안 수정은 Package Dependency에 관한 것이다.
이제 외부 Registry에서 다운로드한 패키지가 다음 종류의 로컬 의존성을 선언하면 거부할 수 있다.
- file:
- link:
- 경로 기반 workspace:
대표적인 오류는 다음과 같다.
ERR_PNPM_LOCAL_SUBDEP_NOT_ALLOWED
예를 들어 외부에서 다운로드한 패키지의 의존성 선언이 사용자의 로컬 파일시스템을 가리킨다고 가정해 보자.
이러한 선언을 그대로 처리하면 패키지의 실제 내용이 사용자의 로컬 환경에 따라 달라질 수 있다.
또한 악성 패키지가 예상하지 못한 경로를 참조하도록 시도할 수 있다.
이번 수정은 외부 Registry 패키지가 로컬 파일시스템의 의존성을 임의로 요구하는 상황을 제한한다.
하지만 모든 로컬 의존성을 금지하는 것은 아니다.
다음은 계속 허용된다.
- 패키지 Archive 내부의 상대적인 file 의존성
- Workspace의 overrides
- Workspace의 packageExtensions
- Workspace의 .pnpmfile.cjs에서 명시한 로컬 의존성
즉 외부 패키지가 임의로 선언한 로컬 의존성과 사용자가 직접 구성한 로컬 의존성을 구분한다.
Lockfile의 외부 의존성 검증 강화
pnpm에는 다음 설정이 존재한다.
blockExoticSubdeps
이 설정은 일반 Registry Dependency 이외의 외부 의존성을 제한하는 데 사용할 수 있다.
예를 들어 다음 종류의 의존성이다.
- Git Repository
- 직접 다운로드하는 Tarball URL
문제는 실제 Lockfile에 이러한 의존성이 기록돼 있는 경우였다.
기존에는 관련 설정이 활성화돼 있어도 일부 Lockfile의 Dependency를 그대로 설치할 수 있었다.
이번 수정에서는 다음 작업에도 해당 정책을 적용한다.
pnpm install --frozen-lockfile
따라서 Lockfile에 이미 기록된 의존성이더라도 현재 보안 정책에 위반된다면 거부할 수 있다.
이러한 방식은 실제 설치 정책이 package.json의 신규 의존성에만 적용되는 것이 아니라 기존 Lockfile에도 적용되도록 한다.
pnpm dlx와 pnpm create의 로컬 설정 무시
이번 릴리스에서는 일회성 실행 명령의 설정 처리도 강화됐다.
대상은 다음과 같다.
- pnpm dlx
- pnx
- pnpm create
이러한 명령은 현재 작업 디렉터리의 일부 로컬 설정을 더 이상 읽지 않는다.
대표적으로 다음 항목이다.
- .pnpmfile.cjs
- 로컬 .npmrc의 Proxy 및 TLS 설정
- 로컬 pnpm-workspace.yaml의 실행 및 설치 설정
예를 들어 개발자가 신뢰하지 않는 Repository에서 pnpm dlx로 외부 도구를 실행한다고 가정해 보자.
기존에는 해당 Repository의 설정이 일회성 도구 실행에 영향을 줄 수 있었다.
이번 변경은 이러한 영향을 줄이도록 한다.
다만 사용자의 Global 설정은 계속 적용된다.
따라서 모든 설정을 무시하는 완전히 독립적인 실행 환경이 되는 것은 아니다.
minimumReleaseAge의 일회성 설정
pnpm 12.23.0에는 패키지의 출시 시점을 기준으로 의존성 선택을 제한하는 옵션도 추가됐다.
대표적으로 다음과 같다.
- --minimum-release-age
- --minimum-release-age-exclude
지원하는 명령은 다음과 같다.
- pnpm install
- pnpm add
- pnpm update
- pnpm dlx
예를 들어 매우 최근에 공개된 패키지 버전을 바로 설치하지 않으려는 프로젝트가 있다고 가정해 보자.
새 버전이 배포된 직후에는 악성 패키지나 잘못된 배포를 발견할 시간이 부족할 수 있다.
Release Age 정책은 너무 최근에 공개된 버전을 설치 후보에서 제외하도록 할 수 있다.
이번 변경은 이러한 정책을 설정 파일을 수정하지 않고 한 번의 명령 실행에 적용하도록 한다.
또한 다음 설정이 추가됐다.
referenceTime
이 값은 RFC 3339 형식의 기준 시각이다.
Release Age와 일부 Trust Policy의 시간 계산을 해당 기준으로 수행할 수 있다.
따라서 CI에서 의존성 해결 결과를 특정 기준 시점에 맞춰 재현하는 데 도움이 될 수 있다.
하지만 Release Age가 오래됐다는 사실만으로 해당 패키지가 안전하다고 보장할 수는 없다.
실제 악성 패키지가 오랫동안 Registry에 존재할 수도 있기 때문이다.
pnpm doctor의 실행 환경 검사
개발 환경 진단 기능도 개선됐다.
pnpm doctor는 실제 Lifecycle Script가 실행되는 환경을 확인한다.
대표적으로 다음 항목이다.
- PATH에서 찾을 수 있는 Node.js 실행 파일
- 잘못된 Node.js 실행 파일
- Script를 실행하는 Shell
- 패키지 실행 파일의 Shim
예를 들어 개발자의 Terminal에서는 Node.js가 정상적으로 동작한다고 가정해 보자.
하지만 실제 pnpm run에서는 다른 Node.js 실행 파일이 선택될 수 있다.
또는 PATH의 순서 때문에 의도하지 않은 Node.js 버전이 사용될 수 있다.
이번 기능은 이러한 상황을 진단하도록 한다.
특히 다음 도구를 여러 개 사용하는 개발 환경에서 도움이 될 수 있다.
- Homebrew
- Corepack
- Volta
- npm
- Scoop
하지만 실제 진단 결과가 모든 PATH와 Shell 문제를 자동으로 수정하는 것은 아니다.
문제가 되는 실행 파일과 환경을 찾아내는 기능이다.
pnpm 11.29.0의 적용 범위
11.29.0에서는 12.23.0에 포함된 여러 보안 수정이 반영됐다.
대표적으로 다음과 같다.
- 설정 파일의 OTP 사용 중단
- 외부 Registry 패키지의 로컬 의존성 제한
- Release Age 옵션 추가
- CI와 같은 비대화형 환경에서 호환되지 않는 node_modules 자동 재생성
하지만 다음과 같은 12.23.0의 모든 신규 기능이 11.29.0에도 포함된 것은 아니다.
- pnpm edit
- pnpm catalog migrate
- pnpm link --hard
- 플랫폼 Variant 제거와 관련된 12 계열 변경
따라서 두 버전을 완전히 동일한 기능 구성으로 취급해서는 안 된다.
성능 수치와 한계
이번 릴리스에는 일부 설치 성능 개선도 포함됐다.
대표적으로 다음과 같다.
- macOS에서 여러 Peer Dependency Variant의 패키지 설치 최적화
- 대규모 Workspace의 Binary Link 생성 개선
- Hoisted 설치에서 발생하던 메모리 문제와 중단 문제 수정
- 변경이 없는 Frozen Lockfile 설치의 불필요한 Node.js 버전 검사 제거
공식 릴리스에서는 특정 Homebrew Node.js 환경의 변경 없는 Frozen Install이 약 3배 빨라질 수 있다고 설명한다.
하지만 이는 특정 조건에서의 자체 측정이다.
모든 pnpm 설치 작업이 3배 빨라지는 것은 아니다.
또한 해당 개선은 일반적인 새 패키지 다운로드 및 전체 의존성 재설치와는 다른 작업 경로에 적용된다.
이번 발표는 Monorepo 의존성 관리 명령을 확장하면서 Registry 인증정보와 Lockfile, 외부 의존성의 신뢰 경계를 강화한 정식 릴리스다.
그 밖에 Node.js, Deno, Bun, Vite, webpack, Rollup, esbuild, Babel, Biome, ESLint, Prettier, npm, Yarn, GitHub, GitLab 및 주요 테스트·배포 도구의 공개 기록을 확인했다.
이번 조사 범위에서 이외에 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
공식 릴리스 확인 대상에는 다음 저장소가 포함된다.
- Node.js: https://github.com/nodejs/node/releases
- Deno: https://github.com/denoland/deno/releases
- Bun: https://github.com/oven-sh/bun/releases
- Vite: https://github.com/vitejs/vite/releases
- webpack: https://github.com/webpack/webpack/releases
- Rollup: https://github.com/rollup/rollup/releases
- esbuild: https://github.com/evanw/esbuild/releases
- Babel: https://github.com/babel/babel/releases
- Biome: https://github.com/biomejs/biome/releases
- ESLint: https://github.com/eslint/eslint/releases
- Prettier: https://github.com/prettier/prettier/releases
- TypeScript: https://github.com/microsoft/TypeScript/releases
- GitHub Changelog: https://github.blog/changelog/
최근 릴리스 가운데 Bun 1.4.5는 11월 19일 공개된 항목이며 이번 기간의 신규 릴리스가 아니다.
Rollup과 다른 개발 도구에서도 이번 범위에 포함할 수 있는 중요한 신규 안정 기능은 확인하지 못했다.
OWASP와 주요 보안 권고 자료도 조사했다.
하지만 이번 기간에 처음 공개된 중요한 취약점과 영향 버전, 실제 수정 버전을 공식 원문으로 함께 검증할 수 있는 별도 항목은 선정하지 못했다.
취약점 데이터베이스의 최근 수정 날짜나 기존 권고의 갱신을 신규 취약점의 최초 공개로 취급하지 않았다.
또한 이전 브리핑에서 다룬 NGINX HTTP/2 취약점, Java4Shell, Next.js의 Binary Cache Key 관련 보안 문제는 반복하지 않았다.
📚 추천 글
20개의 User-Agent로 같은 Next.js 가격 페이지를 요청했더니 네 종류의 HTML이 반환된 이유
- 원제: I fetched our pricing page as 20 clients and got four different documents, because two regexes are arguing
- 저자: Daniel Pertu
- 매체: DEV Community
- 게시일: 2026-11-22 — 정확한 게시 시각 미확인
- 기술: Next.js 16, React Server Components, Streaming SSR, User-Agent, SEO, Structured Data
- 원문: https://dev.to/daniel_pertu/i-fetched-our-pricing-page-as-20-clients-and-got-four-different-documents-because-two-regexes-are-58e6
실제 Next.js 웹사이트의 가격 페이지를 서로 다른 User-Agent로 요청하면서 같은 URL이 네 종류의 HTML 응답을 생성하는 이유를 분석한 기술 글이다.
저자는 Pub Trivia라는 서비스를 운영한다.
해당 서비스의 가격 페이지는 요청한 사용자의 지역에 따라 다른 통화를 표시한다.
예를 들어 일반 사용자는 자신의 지역에 맞는 가격을 확인한다.
하지만 검색 엔진 크롤러에게는 서비스의 기준 통화인 GBP를 보여주도록 설계했다.
그 이유는 검색 엔진이 페이지의 Structured Data와 실제 화면의 가격을 서로 다르게 해석하지 않도록 하기 위해서였다.
문제는 이 과정에서 두 개의 독립적인 Bot 탐지 규칙이 서로 다르게 동작한다는 점이었다.
첫 번째 Regex: 애플리케이션의 통화 선택
저자의 애플리케이션에는 다음 파일이 존재한다.
lib/http/bots.ts
이 파일에서는 User-Agent 문자열에 특정 단어가 존재하는지 검사한다.
대표적인 패턴은 다음과 같다.
/vercel|bot|crawler|spider|googlebot|bingbot|slackbot|twitterbot|facebookexternalhit|linkedinbot|whatsapp|headless/i
총 12개 선택지가 존재한다.
이 가운데 실제 일부는 중복된다.
예를 들어 googlebot에는 이미 bot이라는 문자열이 포함돼 있다.
따라서 bot만으로도 해당 User-Agent를 탐지할 수 있다.
저자는 이러한 중복이 실제 탐지 범위를 넓히지는 않지만 개발자가 어떤 종류의 Bot을 의도했는지 설명하는 역할은 할 수 있다고 분석했다.
실제 이 Regex가 일치하면 GBP를 사용한다.
일치하지 않으면 요청 위치에 따라 다른 통화를 표시한다.
두 번째 Regex: Next.js의 HTML 생성 방식
문제는 Next.js에도 별도의 Bot 탐지 규칙이 존재한다는 사실이다.
저자가 사용한 Next.js 16.2.7에는 다음 파일이 존재했다.
next/dist/shared/lib/router/utils/html-bots.js
이 파일에는 다음 Regex가 존재한다.
HTML_LIMITED_BOT_UA_RE
해당 Regex에는 약 27개 항목이 포함돼 있다.
대표적인 대상은 다음과 같다.
- Chrome-Lighthouse
- Google-InspectionTool
- Bingbot
- FacebookExternalHit
- Slackbot
- SkypeUriPreview
이 Regex의 목적은 애플리케이션의 통화를 선택하는 것이 아니다.
실제 HTML의 Streaming 방식을 선택하는 것이다.
일부 크롤러와 Link Preview 도구는 Streaming HTML의 일부를 올바르게 처리하지 못할 수 있다.
따라서 Next.js는 특정 User-Agent에 대해 HTML을 완성한 뒤 전달하는 Blocking Rendering을 사용할 수 있다.
반면 일반 브라우저에서는 Streaming Rendering을 사용할 수 있다.
서로 다른 두 목적
두 Regex는 같은 User-Agent 문자열을 읽는다.
하지만 목적은 다르다.
| 구분 | 애플리케이션 Regex | Next.js Regex |
|---|---|---|
| 목적 | 통화 선택 | HTML 전달 방식 선택 |
| 일치 결과 | GBP 표시 | Blocking Rendering |
| 불일치 결과 | 지역 통화 표시 | Streaming Rendering |
| 관리 위치 | 애플리케이션 코드 | Next.js 내부 |
문제는 두 Regex가 서로 다른 Bot 목록을 가지고 있다는 점이다.
예를 들어 Googlebot은 애플리케이션의 기준 통화로 GBP를 볼 수 있다.
하지만 Google-InspectionTool은 애플리케이션 Regex에 일치하지 않을 수 있다.
따라서 실제 검색 엔진의 페이지 검사 도구와 일반 Googlebot이 서로 다른 통화를 볼 수 있다.
20개 User-Agent 실험
저자는 20개 User-Agent를 이용해 같은 URL을 요청했다.
테스트 지역에서는 일반 사용자에게 EUR 가격이 표시됐다.
반면 Bot으로 분류한 요청에는 GBP 가격이 표시됐다.
실제 결과는 네 가지 조합으로 나뉘었다.
| 통화 | HTML 방식 | 대표적인 User-Agent |
|---|---|---|
| GBP | Streaming | Googlebot, Headless Chrome |
| GBP | Blocking | Bingbot, Slackbot |
| EUR | Blocking | Google-InspectionTool, Chrome-Lighthouse |
| EUR | Streaming | 일반 Chrome, 일반 Scraper |
이러한 결과는 단순히 Bot과 일반 사용자를 구분하는 문제가 아니었다.
동일한 요청 Header가 서로 다른 시스템에서 독립적으로 해석되면서 네 종류의 문서가 생성된 것이다.
실제 가격 차이
저자가 공개한 가격은 다음과 같았다.
- 기준 통화: £30
- 지역 통화: €36.99
따라서 Googlebot과 Google-InspectionTool은 같은 URL에서 서로 다른 가격을 받을 수 있었다.
이는 SEO를 검증하는 과정에서도 혼동을 만들 수 있다.
예를 들어 실제 Googlebot이 수집하는 가격을 확인하기 위해 Search Console의 URL Inspection 도구를 사용할 수 있다.
하지만 해당 도구의 User-Agent와 일반 Googlebot의 User-Agent가 애플리케이션에서 서로 다르게 처리된다면 검사 결과가 실제 크롤링 결과와 다를 수 있다.
다만 이 사실만으로 Google이 실제 사이트에 패널티를 적용했거나 검색 결과의 가격을 잘못 표시했다는 의미는 아니다.
저자는 HTTP 응답의 차이를 확인한 것이며 검색 엔진의 최종 색인 결과까지 증명한 것은 아니다.
Streaming과 Blocking의 실제 HTML 차이
저자는 실제 HTML의 Byte 수도 비교했다.
대표적인 결과는 다음과 같다.
| 요청 | HTML 크기 |
|---|---|
| Bingbot | 약 101,703B |
| 일반 Chrome | 약 102,002B |
두 문서의 크기는 약 300바이트 차이가 났다.
또한 일반 Chrome의 Streaming 응답에는 React Suspense 관련 Marker가 추가됐다.
반면 Blocking 응답에는 해당 Marker가 존재하지 않았다.
저자는 실제 <title>의 위치도 확인했다.
두 응답에서 Title이 시작하는 위치는 같았다.
2730
따라서 이번 실험에서 Blocking Rendering이 Title을 HTML의 더 앞쪽으로 이동시킨 것은 아니었다.
실제 차이는 Streaming 과정에서 필요한 React의 추가적인 구조였다.
같은 URL이라는 가정의 한계
이번 글에서 중요한 부분은 다음 사실이다.
같은 URL을 요청했다는 사실만으로 동일한 HTML을 받는 것은 아니다.
실제로 다음 정보가 서버 렌더링에 영향을 줄 수 있다.
- User-Agent
- 국가 또는 지역 Header
- Cookie
- 인증 상태
- 언어
- Device 정보
따라서 웹사이트를 테스트할 때는 URL만 기록하는 것보다 실제 Request Context를 함께 기록하는 편이 적합할 수 있다.
특히 가격과 권한, 개인정보처럼 중요한 데이터가 다른 조건에 따라 변경되는 서비스에서는 더욱 중요하다.
User-Agent 기반 분류의 한계
이번 실험에서 User-Agent는 실제 문자열이다.
클라이언트가 해당 문자열을 임의로 지정할 수도 있다.
따라서 User-Agent만을 기준으로 사용자의 신원이나 권한을 확정해서는 안 된다.
예를 들어 일반 브라우저에서 Googlebot User-Agent를 지정할 수 있다.
그 결과 같은 페이지에서 다른 가격이 표시될 수 있다.
하지만 이는 실제 사용자가 Googlebot이라는 의미는 아니다.
따라서 User-Agent 분류는 콘텐츠 제공 방식의 힌트로 사용할 수 있지만 인증과 인가의 근거로 사용해서는 안 된다.
실험의 한계
이번 글은 저자가 운영하는 하나의 사이트에서 직접 측정한 결과다.
실제 20개 User-Agent에 관한 응답과 HTML 구조를 비교했다.
하지만 다음 내용은 검증하지 않았다.
- 검색 엔진의 실제 색인 결과
- Google의 최종 Structured Data 처리 결과
- 사용자별 실제 전환율
- Streaming과 Blocking의 성능 차이
- 다른 Next.js 버전에서의 동일한 동작
따라서 이번 결과를 모든 Next.js 사이트에 일반화할 수 없다.
이번 글은 하나의 HTTP 요청에 여러 단계의 User-Agent 분류가 존재하면 실제 각 시스템이 서로 다른 목적과 규칙으로 같은 Header를 해석할 수 있으며, 그 결과 콘텐츠와 렌더링 방식이 예상보다 복잡하게 분기할 수 있다는 점을 실제 응답 비교로 설명한다.
브라우저에서 실행하는 이미지 배경 제거 모델을 43.8초에서 6.4초로 단축한 과정
- 원제: I built a background remover that runs 100% in the browser. Here's how I made it 7x faster
- 저자: Manish Joshi
- 매체: DEV Community
- 게시일: 2026-11-21
- 기술: Astro, Cloudflare Workers, JavaScript, WebGPU, WebAssembly, ONNX Runtime Web, Canvas, HTTP Cache
- 원문: https://dev.to/manish_joshi_5453f51f4e5b/i-built-a-background-remover-that-runs-100-in-the-browser-heres-how-i-made-it-7x-faster-14lp
사용자의 사진을 서버로 업로드하지 않고 브라우저 안에서 배경을 제거하는 서비스를 구현하면서 실제 작업 완료 시간을 약 44초에서 6초대로 줄인 과정을 설명한 기술 글이다.
저자는 무료 이미지 배경 제거 서비스를 만들었다.
중요한 조건은 다음과 같았다.
- 사용자의 사진을 서버로 전송하지 않음
- 브라우저에서 AI 모델 실행
- 회원가입 없이 사용
- 전체 해상도의 결과를 다운로드
처음 구현은 정상적으로 동작했다.
하지만 실제 휴대전화에서 처리 시간이 길어 사용자가 결과를 보기 전에 이탈할 수 있었다.
저자는 이미지 처리 전체 과정을 단계별로 측정했다.
그리고 서로 다른 네 종류의 병목을 발견했다.
실제 기술 구성
서비스는 다음 기술을 사용한다.
| 구성요소 | 역할 |
|---|---|
| Astro | 정적 웹사이트 |
| Cloudflare Workers | 정적 파일 제공 |
| @imgly/background-removal | 배경 제거 라이브러리 |
| IS-Net fp16 | 이미지 분할 모델 |
| ONNX Runtime Web | 브라우저 내 모델 실행 |
| WebGPU | 데스크톱 GPU 실행 |
| WebAssembly | 모바일 및 CPU 실행 |
| Canvas | 결과 이미지의 후처리 |
모델의 크기는 약 88MB였다.
실제 ONNX Runtime 관련 파일까지 포함하면 첫 방문에서 약 100MB를 다운로드할 수 있었다.
이러한 크기는 일반적인 웹사이트의 JavaScript Bundle과 비교하면 매우 크다.
따라서 첫 번째 병목은 모델의 다운로드였다.
첫 번째 문제: 모델 파일이 Cache되지 않음
저자는 외부 CDN에서 모델 파일을 다운로드하고 있었다.
하지만 실제 HTTP 응답에는 적절한 Cache-Control이 존재하지 않았다.
Cloudflare의 응답에서는 다음 상태가 확인됐다.
cf-cache-status: DYNAMIC
따라서 같은 사용자가 서비스를 다시 방문해도 모델 파일을 다시 다운로드하는 경우가 발생했다.
이는 수십 MB의 모델을 사용하는 애플리케이션에서 큰 문제다.
저자는 이를 해결하기 위해 모델 파일을 직접 호스팅했다.
그리고 Build Script에서 필요한 모델 Chunk를 다운로드하도록 변경했다.
파일은 다음 구조로 저장했다.
public/ai/<version>/
Content Hash와 장기 Cache
모델 파일의 이름에는 Content Hash가 포함돼 있었다.
따라서 실제 내용이 변경되면 파일 이름도 달라진다.
저자는 다음 Cache-Control을 적용했다.
Cache-Control: public, max-age=31536000, immutable
이 설정은 브라우저가 해당 파일을 장기간 재사용할 수 있도록 한다.
실제로 내용이 변경되면 새로운 URL이 생성되므로 이전 파일과 구분할 수 있다.
그 결과 재방문 시 모델 파일의 네트워크 다운로드가 발생하지 않도록 개선했다.
하지만 이 설정은 파일 이름이 콘텐츠 변경을 정확하게 반영한다는 전제가 중요하다.
같은 URL의 파일 내용을 변경하면서 immutable을 사용하면 오래된 파일이 유지될 수 있다.
확장자가 없는 Chunk의 404 오류
모델을 자체 호스팅하는 과정에서도 문제가 발생했다.
일부 모델 Chunk 파일에는 확장자가 존재하지 않았다.
하지만 개발 서버와 Hosting 환경은 확장자가 없는 경로를 일반적인 웹페이지 Route처럼 처리할 수 있었다.
그 결과 모델 파일 요청이 404를 반환했다.
저자는 각 Chunk에 .bin 확장자를 추가했다.
그리고 실제 모델 파일 목록을 관리하는 resources.json의 경로도 변경했다.
따라서 브라우저가 해당 파일을 정적 Binary Asset으로 가져올 수 있도록 했다.
이는 모델의 추론 성능 문제가 아니라 정적 파일 제공 설정의 문제였다.
두 번째 문제: WebAssembly가 CPU 하나만 사용
휴대전화에서는 WebGPU 대신 WebAssembly를 이용해 모델을 실행할 수 있다.
하지만 기존 구현에서는 CPU Core 하나만 사용하는 상태였다.
저자는 다음 값을 확인했다.
crossOriginIsolated === false
WebAssembly의 다중 스레드 실행에서는 SharedArrayBuffer가 필요할 수 있다.
이를 사용하려면 페이지의 Cross-origin Isolation 설정이 중요하다.
저자는 다음 두 HTTP Header를 추가했다.
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless
이후 WebAssembly Runtime이 여러 CPU Thread를 사용할 수 있게 됐다.
CPU 추론 시간
저자가 공개한 측정 결과는 다음과 같았다.
| 상태 | 추론 시간 |
|---|---|
| 변경 전 | 22.7초 |
| 변경 후 | 7.9초 |
약 2.9배 빠른 결과다.
하지만 이는 특정 사진과 실행 환경에서의 자체 측정이다.
모든 모바일 기기에서 같은 결과가 발생한다고 보장할 수는 없다.
또한 Cross-origin Isolation은 다른 외부 리소스의 로딩에도 영향을 줄 수 있다.
저자는 credentialless를 사용해 외부 Font와 Analytics의 호환성을 유지하려고 했다.
하지만 실제 사용하는 브라우저와 외부 리소스에 따라 다른 문제가 발생할 가능성도 존재한다.
세 번째 문제: 추론은 빨라졌지만 PNG 생성이 느려짐
이번 글에서 가장 흥미로운 부분이다.
WebAssembly의 다중 스레드 실행을 활성화한 뒤 모델 추론은 빨라졌다.
하지만 전체 처리 시간은 기대만큼 줄어들지 않았다.
저자는 다음 단계별 시간을 기록했다.
| 단계 | 처리 시간 |
|---|---|
| 모델 추론 | 1.5초 |
| PNG 인코딩 | 5.5초 |
| 경계 후처리 | 4.4초 |
실제 AI 모델의 추론보다 이미지 저장과 후처리에 더 많은 시간이 필요했다.
하지만 일반적인 1200×800 이미지의 PNG 인코딩이 항상 5초 이상 걸리는 것은 아니다.
저자는 같은 Canvas 작업을 별도로 측정했다.
PNG 인코딩 비교
실험 결과는 다음과 같았다.
| 상태 | PNG 인코딩 |
|---|---|
| 일반 페이지 | 208ms |
| Cross-origin Isolation 적용, ONNX 실행 전 | 217ms |
| ONNX 실행 후 | 2,648ms |
Cross-origin Isolation 자체는 큰 문제가 아니었다.
문제는 ONNX Runtime을 실행한 이후였다.
라이브러리는 다음 값을 기준으로 WebAssembly Thread를 설정하고 있었다.
navigator.hardwareConcurrency
이 값은 실제 기기의 논리적인 CPU Core 수와 관련된다.
모든 Core를 사용하는 설정에서는 ONNX의 Worker Thread가 추론 완료 이후에도 계속 실행 자원을 점유할 수 있었다.
그 결과 브라우저의 PNG 인코딩 작업이 충분한 CPU 자원을 확보하지 못했다.
즉 AI 모델의 추론 속도를 개선하기 위해 CPU Thread를 늘린 결과, 오히려 다음 단계의 일반적인 브라우저 작업이 느려진 것이다.
CPU Thread 제한
저자는 ONNX Runtime이 사용할 Thread 수를 제한했다.
CPU 경로에서는 다음 기준을 사용했다.
- 논리 Core 수의 절반
- 최대 4개
- 최소 1개
GPU 경로에서는 Thread를 1개로 제한했다.
저자는 라이브러리를 로딩하기 전에 navigator.hardwareConcurrency를 재정의하는 방법을 사용했다.
이렇게 하면 라이브러리의 내부 Thread 선택에 영향을 줄 수 있다.
그 결과 PNG 인코딩과 후처리의 병목이 크게 감소했다.
하지만 중요한 한계가 존재한다.
navigator.hardwareConcurrency를 전역적으로 재정의하는 것은 특정 라이브러리에만 적용되는 설정이 아니다.
실제 다른 JavaScript 라이브러리도 해당 값을 읽을 수 있다.
따라서 이 방법을 모든 웹 애플리케이션의 권장 설정으로 취급해서는 안 된다.
이번 사례는 해당 라이브러리와 실행 환경에서 적용한 우회 방법이다.
네 번째 문제: WebGPU Shader의 첫 실행 비용
GPU 경로에서는 또 다른 문제가 발생했다.
실제 두 번째 이미지를 처리하는 시간은 약 2초였다.
하지만 첫 번째 이미지는 약 17초가 필요했다.
원인은 GPU Shader Compilation과 모델 Session 초기화였다.
처음 실행하는 과정에서 GPU에 필요한 코드가 준비돼야 했기 때문이다.
저자는 이를 해결하기 위해 사용자 의도에 따라 모델을 미리 준비하도록 변경했다.
대표적인 Trigger는 다음과 같다.
- 데스크톱: 업로드 영역 Hover
- 모바일: 업로드 영역 Tap
이후 다음 작업을 수행했다.
- 모델 파일 Prefetch
- ONNX Session Preload
- GPU 경로에서 작은 이미지로 Warm-up 실행
Warm-up에 사용한 이미지는 32×32 크기였다.
실제 모델의 입력 크기가 고정돼 있어 이 작은 이미지를 이용해 필요한 Shader를 준비할 수 있었다.
따라서 사용자가 실제 사진을 선택하는 동안 준비 작업을 진행할 수 있었다.
불필요한 데이터 다운로드 방지
하지만 모델이 약 100MB라는 점은 여전히 중요했다.
예를 들어 사용자가 페이지를 잠깐 스크롤했을 뿐인데 모델을 다운로드하면 모바일 데이터를 불필요하게 사용할 수 있다.
따라서 저자는 다음 환경에서 Prefetch를 생략했다.
- saveData 활성화
- 2G 연결
- 모바일에서 실제 업로드 영역을 누르지 않은 경우
또한 CPU 경로에서는 Warm-up 추론을 생략했다.
휴대전화에서 Warm-up을 실행하는 시간 자체가 실제 이미지 처리와 비슷하게 길어질 수 있기 때문이다.
따라서 GPU와 CPU에서 서로 다른 초기화 정책을 선택했다.
실제 최종 성능
저자가 공개한 결과는 다음과 같다.
| 항목 | 변경 전 | 변경 후 |
|---|---|---|
| 클릭부터 결과까지 | 43.8초 | 6.4초 |
| CPU 추론 | 22.7초 | 7.9초 |
| PNG 인코딩 및 후처리 | 약 10초 | 0.2초 |
| 재방문 모델 다운로드 | 종종 약 100MB | Disk Cache에서 재사용 |
전체 작업 시간은 약 6.8배 개선됐다.
하지만 해당 결과는 저자가 같은 노트북과 사진에서 직접 측정한 것이다.
독립적인 제3자의 Benchmark는 아니다.
또한 43.8초에서 6.4초로 감소했다는 결과를 모든 휴대전화의 처리 속도 개선으로 일반화해서는 안 된다.
모델 크기와 정확성의 트레이드오프
저자는 더 작은 Quantized Model도 테스트했다.
기존 모델은 약 88MB였다.
Quantized Model은 약 44MB였다.
따라서 다운로드 크기는 절반 정도로 감소했다.
하지만 인물 사진에서 배경의 일부가 제대로 제거되지 않는 문제가 나타났다.
저자는 해당 모델을 사용하지 않기로 결정했다.
이는 파일 크기와 실행 속도만으로 모델을 선택할 수 없다는 점을 보여준다.
실제 사용자에게 제공하는 결과물의 품질도 고려해야 하기 때문이다.
운영 결과와 한계
저자는 Analytics를 추가한 이후 배경 제거 작업의 약 98%가 성공했다고 설명한다.
또한 사진을 업로드한 사용자 가운데 절반 이상이 결과를 다운로드했다고 보고했다.
하지만 두 수치는 저자가 운영한 서비스의 자체 분석 결과다.
실제 사용자 수와 통계 기간, 기기별 실패율이 충분히 공개된 독립적인 연구는 아니다.
또한 다음 항목을 주의해야 한다.
- 첫 방문의 대용량 모델 다운로드
- WebGPU 지원 여부
- WASM의 메모리 사용량
- 모바일 브라우저의 실행 제한
- 외부 라이브러리의 라이선스
저자가 사용한 @imgly/background-removal은 AGPL-3.0 라이선스로 제공된다.
따라서 실제 서비스에 적용할 때 라이선스 조건을 확인해야 한다.
이번 글은 브라우저 안에서 AI 모델을 실행할 때 모델의 추론 시간만 최적화하는 것으로 충분하지 않으며, HTTP Cache와 WebAssembly Thread, GPU Shader 초기화 및 후처리까지 전체 실행 경로를 측정해야 한다는 점을 실제 운영 사례로 설명한다.
HTTP Caching: ETag, Cache-Control and 304, Measured — 180KB 응답을 조건부 요청으로 바꿨을 때 실제 전송 시간 비교
- 저자: t.labo
- 매체: t.laboratory / DEV Community
- 게시일: 2026-11-21
- 기술: HTTP, Cache-Control, ETag, Last-Modified, Conditional Request, PHP, curl
- 원문: https://dev.to/tlaboratory/http-caching-etag-cache-control-and-304-measured-2kll
HTTP Cache의 동작을 실제 작은 서버로 구현하고, 같은 데이터를 다시 요청했을 때 전체 응답을 보내는 방식과 304 Not Modified를 반환하는 방식의 차이를 직접 측정한 기술 글이다.
이번 글은 새로운 HTTP 표준 발표가 아니다.
이미 사용되고 있는 HTTP Cache 기능을 실제 코드와 Request Header, 응답 시간으로 설명한 자료다.
특히 자주 변경되는 JSON API와 정적 파일을 어떤 방식으로 캐시할지 이해하는 데 적합하다.
실험 데이터
저자는 1,500개 상품을 가진 JSON 파일을 생성했다.
전체 크기는 다음과 같았다.
179,500바이트
약 180KB다.
그리고 간단한 HTTP Server를 구성했다.
실험 환경은 다음과 같았다.
- Apple M1 Pro
- curl 8.7.1
- PHP 8.5.6
- Python 3.9.6
- 127.0.0.1 로컬 서버
실제 테스트에서는 같은 JSON 파일을 반복해서 요청했다.
Cache의 두 가지 질문
작성자는 HTTP Cache가 다음 두 가지를 판단한다고 설명한다.
첫 번째는 응답을 저장할 수 있는가 하는 문제다.
두 번째는 저장한 응답을 다시 사용할 수 있는가 하는 문제다.
예를 들어 다음 Header를 생각할 수 있다.
Cache-Control: no-store
이는 저장 자체를 제한하는 정책이다.
반면 다음 Header는 의미가 다르다.
Cache-Control: no-cache
이름만 보면 캐시를 사용하지 말라는 의미처럼 보인다.
하지만 실제로는 응답을 저장할 수 있다.
다만 저장된 결과를 재사용하기 전에 서버에 다시 검증해야 한다.
이러한 차이는 웹 개발에서 자주 혼동되는 부분이다.
ETag의 역할
ETag는 특정 응답의 버전을 식별하는 값이다.
예를 들어 JSON 응답이 있다고 가정해 보자.
서버는 실제 Body의 Hash를 계산할 수 있다.
그리고 다음 Header를 반환한다.
ETag: "41455fbfcdb6b7a0"
클라이언트는 해당 응답을 저장한다.
이후 같은 데이터를 다시 요청할 때 다음 Header를 포함할 수 있다.
If-None-Match: "41455fbfcdb6b7a0"
서버는 현재 데이터의 ETag를 계산한다.
그리고 기존 ETag와 비교한다.
실제 데이터가 변경되지 않았다면 서버는 다음 상태를 반환할 수 있다.
304 Not Modified
이 응답에는 기존 JSON 본문을 다시 포함할 필요가 없다.
클라이언트는 이전에 저장한 데이터를 계속 사용할 수 있다.
따라서 네트워크에서 전달해야 하는 데이터의 양이 감소한다.
실제 서버 구현
저자는 PHP의 간단한 HTTP Server를 사용했다.
실제 ETag는 응답 Body의 SHA-256 Hash로 생성했다.
대표적인 구조는 다음과 같다.
$body = file_get_contents($file);
$etag = '"' . substr(hash('sha256', $body), 0, 16) . '"';
이렇게 하면 실제 파일의 내용이 변경되면 다른 ETag를 생성할 수 있다.
다만 Hash를 계산하는 작업 자체에도 비용이 존재한다.
따라서 실제 대용량 응답에서는 ETag를 언제 생성하고 어떻게 재사용할지 고려해야 한다.
예를 들어 정적 파일이라면 빌드 시점에 Hash를 생성할 수 있다.
반면 동적으로 생성하는 JSON에서는 실제 데이터의 변경 시점에 ETag를 갱신할 수 있다.
ETag의 따옴표
이번 글에서는 작은 구현상의 차이도 설명한다.
ETag는 다음처럼 따옴표를 포함하는 형식을 가진다.
"41455fbfcdb6b7a0"
하지만 클라이언트가 다음처럼 따옴표를 제거해 보내면 결과가 달라질 수 있다.
41455fbfcdb6b7a0
저자의 단순한 서버에서는 이 값이 일치하지 않는 것으로 처리됐다.
따라서 전체 응답인 200을 반환했다.
즉 ETag의 실제 문법을 정확하게 처리해야 한다.
단순히 문자열에서 따옴표를 제거한 뒤 비교하는 방식은 적절하지 않을 수 있다.
Weak ETag
HTTP에서는 Weak ETag도 존재한다.
대표적인 형태는 다음과 같다.
W/"41455fbfcdb6b7a0"
Weak ETag는 실제 Byte가 완전히 같지는 않더라도 의미적으로 같은 표현이라고 판단할 수 있는 경우에 사용한다.
예를 들어 서버가 같은 콘텐츠를 다른 압축 방식으로 제공할 수 있다.
이 경우 실제 Byte는 달라도 콘텐츠의 의미는 같을 수 있다.
중요한 점은 If-None-Match 비교에서 Weak Comparison을 사용할 수 있다는 사실이다.
저자는 처음 작성한 단순한 PHP Server가 이러한 비교를 완전히 구현하지 못했다는 점을 설명한다.
그리고 관련 비교 로직을 추가하는 방법을 제공했다.
Last-Modified의 제한
ETag 외에도 다음 Header를 사용할 수 있다.
Last-Modified
예를 들어 다음 값이다.
Last-Modified: Thu, 12 Nov 2026 14:28:40 GMT
이후 클라이언트는 다음 Header를 전달할 수 있다.
If-Modified-Since
서버는 파일의 수정 시각을 비교해 변경 여부를 판단한다.
하지만 Last-Modified에는 제한사항이 존재한다.
일반적인 HTTP 날짜 표현은 초 단위다.
따라서 같은 1초 안에 파일을 두 번 수정할 수 있다.
이 경우 실제 파일 내용은 변경됐지만 수정 시각을 초 단위로 비교하면 같은 값으로 처리될 수 있다.
따라서 해당 응답이 변경되지 않았다고 잘못 판단할 가능성이 있다.
실제 콘텐츠 기반 ETag는 이러한 문제를 줄이는 데 도움이 될 수 있다.
실제 로컬 측정
저자는 세 가지 측정 그룹을 구성했다.
각 그룹에서 50회 요청을 실행했다.
로컬 서버에서 측정한 결과는 다음과 같았다.
| 그룹 | 200 응답 중앙값 | 304 응답 중앙값 |
|---|---|---|
| 1 | 1.57ms | 1.38ms |
| 2 | 1.43ms | 1.40ms |
| 3 | 1.47ms | 1.38ms |
이 결과는 흥미롭다.
실제로 304 응답은 Body를 전송하지 않는다.
하지만 로컬 서버에서는 응답 시간의 차이가 매우 작았다.
이유는 실제 네트워크가 거의 존재하지 않는 환경이기 때문이다.
서버와 클라이언트가 같은 머신에서 실행됐다.
따라서 180KB의 데이터를 전송하는 비용이 상대적으로 작았다.
이는 304가 네트워크 전송량을 줄인다는 사실과 모순되지 않는다.
느린 네트워크에서의 비교
저자는 약 1MB/s의 제한된 전송 환경도 실험했다.
결과는 다음과 같았다.
| 응답 | 실행 1 | 실행 2 |
|---|---|---|
| 200 | 173.29ms | 173.01ms |
| 304 | 1.43ms | 1.46ms |
이 경우 결과가 크게 달라졌다.
전체 Body를 다시 전송하는 요청에서는 약 173ms가 필요했다.
반면 304에서는 약 1.4ms가 필요했다.
따라서 제한된 전송 속도에서는 실제 데이터의 크기가 응답 시간에 큰 영향을 줄 수 있다.
하지만 이번 실험은 로컬에서 전송 속도를 제한한 것이다.
실제 모바일 네트워크의 지연과 패킷 손실, 연결 재사용 및 CDN의 동작을 모두 재현한 것은 아니다.
따라서 해당 수치를 실제 모든 모바일 사용자의 응답 시간으로 적용해서는 안 된다.
Cache-Control: private
저자는 다른 Cache-Control 설정도 비교했다.
대표적으로 다음과 같다.
Cache-Control: private
이 설정은 일반적인 공유 Cache에 응답을 저장하지 않도록 제한하는 데 사용할 수 있다.
예를 들어 로그인한 사용자의 개인화된 HTML을 생각할 수 있다.
해당 응답을 여러 사용자 사이에서 공유하는 CDN Cache에 저장하면 위험할 수 있다.
따라서 실제 개인화된 응답은 Cache 정책을 신중하게 설정해야 한다.
하지만 private를 지정했다는 사실만으로 응답이 브라우저의 로컬 Cache에 저장되지 않는 것은 아니다.
저장 자체를 막아야 하는 데이터라면 no-store를 고려해야 한다.
실제 운영에서 발견한 세 가지 오류
저자는 대표적인 Cache 문제를 세 가지로 설명한다.
첫 번째는 매번 ETag를 새롭게 생성하는 것이다.
예를 들어 ETag에 현재 시각을 포함한다고 가정해 보자.
실제 응답 Body는 변경되지 않았다.
하지만 ETag는 매 요청마다 달라진다.
따라서 서버는 항상 200을 반환할 수 있다.
두 번째는 Last-Modified만으로 모든 변경을 판단하는 것이다.
앞서 설명한 초 단위 해상도 때문에 일부 변경을 놓칠 수 있다.
세 번째는 CDN에서 Redirect 응답을 잘못 캐시하는 문제다.
실제로 오래된 Redirect가 Cache에 남으면 새로운 배포 이후에도 사용자가 이전 URL로 이동할 수 있다.
경우에 따라 Redirect Loop가 발생할 수도 있다.
이러한 문제는 실제 HTTP 응답의 Cache 정책을 확인해야 해결할 수 있다.
서버 내부 캐시와 HTTP 캐시
저자는 서버 내부에서 사용하는 Cache와 HTTP Cache도 구분한다.
예를 들어 실제 API가 데이터베이스를 조회해 JSON을 생성한다고 가정해 보자.
HTTP Cache를 사용하면 같은 JSON을 다시 전송할 필요를 줄일 수 있다.
하지만 서버는 실제 ETag를 계산하기 위해 데이터베이스 Query를 다시 실행할 수 있다.
이 경우 네트워크 사용량은 감소하지만 데이터베이스의 부하는 그대로일 수 있다.
따라서 서버 내부에서도 일정 시간 Query 결과를 캐시할 수 있다.
이렇게 하면 실제 데이터베이스 조회 횟수를 줄일 수 있다.
하지만 HTTP 캐시와 서버 내부 캐시의 수명 정책이 서로 다르면 오래된 데이터가 제공될 가능성이 있다.
따라서 두 계층의 Cache를 별도로 관리해야 한다.
측정상의 한계
이번 글은 HTTP Cache의 동작을 실제 코드와 명령으로 검증했다.
하지만 다음 제한이 존재한다.
- 로컬 서버 기반 측정
- 작은 JSON 파일 하나 사용
- 실제 글로벌 CDN의 P95 측정 없음
- 다수 사용자의 동시 요청 실험 없음
- 브라우저별 Cache 정책 비교 없음
따라서 304 응답을 사용하면 모든 웹서비스의 응답 시간이 특정 비율만큼 감소한다고 판단할 수 없다.
이번 글은 HTTP Cache를 설정할 때 단순히 파일을 저장하는지보다 재검증 정책과 ETag 생성 방식, 실제 네트워크 환경 및 서버 내부 캐시의 역할을 구분해야 한다는 점을 측정 결과로 설명한다.
PHP·SQLite 웹사이트를 Cloudflare Worker 하나로 이전하기 — D1의 FTS5·AUTOINCREMENT 호환성 문제
- 원제: Moving a PHP + SQLite site to one Cloudflare Worker on the free plan: what the D1 import didn't tell me
- 저자: Vincenzo Allocca
- 매체: DEV Community / HASTE Collective
- 게시일: 2026-11-21
- 기술: PHP, Nginx, SQLite, Cloudflare Workers, D1, KV, TypeScript, Vitest
- 원문: https://dev.to/vincenzoallocca/moving-a-php-sqlite-site-to-one-cloudflare-worker-on-the-free-plan-what-the-d1-import-didnt-35cb
실제 PHP·Nginx·SQLite 기반 사이트를 Cloudflare Workers와 D1을 사용하는 서버리스 구조로 이전하면서 발견한 데이터베이스 및 배포 호환성 문제를 설명한 기술 글이다.
저자는 이탈리아의 HASTE Collective 사이트를 운영한다.
기존 서버는 VPS였다.
구성은 다음과 같았다.
- PHP
- Nginx
- SQLite
- Cron Job
- 로컬 디스크의 이미지 파일
사이트에는 여러 종류의 기능이 존재했다.
대표적으로 다음과 같다.
- 온라인 매거진
- 공개 Petition
- Stripe 결제를 사용하는 작은 상품 목록
- 편집자용 내부 Portal
따라서 단순한 정적 블로그를 다른 Hosting으로 이동하는 작업과 다르다.
실제 API와 데이터베이스, 파일 업로드, 인증 및 정기 작업을 함께 이전해야 했다.
기존 프로젝트 규모
저자의 프로젝트에는 다음 코드가 존재했다.
- PHP 파일 200개 이상
- API Endpoint 140개 이상
- 서버 Cron Job
- SQLite 데이터베이스
- 로컬 이미지 Storage
새로운 구조에서는 TypeScript로 코드를 다시 작성했다.
전체 코드는 약 95개 Module로 정리했다.
그리고 하나의 Cloudflare Worker에서 필요한 동적 요청을 처리하도록 구성했다.
따라서 여러 PHP Endpoint를 각각 독립된 Worker로 배포하는 구조가 아니었다.
실제 하나의 Worker에서 다음 기능을 처리한다.
- Routing
- API
- Session
- 보안 Header
- 데이터베이스 접근
이러한 방식은 실제 배포 단위를 단순화한다.
하지만 하나의 Worker에 많은 책임이 집중될 수 있다는 트레이드오프도 존재한다.
정적 페이지와 동적 요청의 분리
이번 글에서 중요한 설계는 다음과 같다.
모든 웹페이지 요청에서 Worker의 JavaScript 코드를 실행하지 않는다.
Cloudflare Workers의 무료 사용량에는 제한이 존재한다.
따라서 일반적인 페이지 방문마다 Worker를 실행하면 사용량이 증가할 수 있다.
저자는 이를 해결하기 위해 정적 페이지와 동적 요청을 분리했다.
실제 데이터베이스 조회가 필요하지 않은 페이지는 빌드 시점에 HTML을 생성한다.
또한 다음 파일은 Static Assets로 제공한다.
- CSS
- JavaScript
- Font
- 이미지
- 정적 HTML
반면 데이터베이스가 필요한 페이지와 API는 Worker에서 실행한다.
이렇게 하면 일반적인 콘텐츠 열람 요청은 Worker의 JavaScript 실행 없이 처리할 수 있다.
따라서 무료 사용량 제한에 영향을 주는 요청을 줄일 수 있다.
하지만 실제 Worker 호출과 정적 자산 요청의 과금 및 사용량 정책은 Cloudflare의 현재 플랜을 기준으로 확인해야 한다.
SQLite와 D1의 차이
저자는 기존 SQLite 데이터베이스를 D1으로 이전했다.
D1은 SQLite 기반의 데이터베이스다.
따라서 처음에는 기존 SQLite Dump를 그대로 Import할 수 있을 것으로 예상했다.
하지만 실제로는 두 가지 문제가 발생했다.
첫 번째는 FTS5 Shadow Table이다.
두 번째는 AUTOINCREMENT Counter다.
이러한 문제는 단순한 SQL Query 문법의 차이보다 실제 데이터베이스 내부 구조의 호환성과 관련된다.
FTS5 Shadow Table
FTS5는 SQLite의 Full-text Search 기능이다.
예를 들어 매거진의 기사를 검색한다고 가정해 보자.
사용자는 다음과 같이 검색할 수 있다.
Cloudflare migration
FTS5는 텍스트 검색에 필요한 Index를 관리한다.
하지만 FTS5 Virtual Table은 내부적으로 여러 Shadow Table을 생성할 수 있다.
대표적으로 다음과 같다.
- _data
- _idx
- _content
- _docsize
- _config
이러한 Table은 실제 애플리케이션의 일반적인 비즈니스 데이터 Table과 다르다.
FTS5의 내부 Index를 관리하기 위한 구조다.
문제는 sqlite3 .dump가 이러한 Shadow Table을 일반적인 SQL 데이터로 Export할 수 있다는 점이었다.
저자는 해당 Dump를 D1으로 Import하려고 했다.
하지만 D1은 관련 Shadow Table의 Import를 거부했다.
따라서 단순히 파일 형식이 SQLite라는 이유로 전체 Dump가 호환되는 것은 아니었다.
FTS5 Index 재생성
저자는 데이터베이스 Dump를 변환하는 작은 Script를 작성했다.
이 Script는 실제 FTS5 Shadow Table을 Import 대상에서 제외했다.
이후 일반적인 콘텐츠 Table을 먼저 Import했다.
그리고 실제 FTS5 Index를 다시 생성했다.
대표적인 SQL은 다음과 같다.
INSERT INTO articles_fts(articles_fts)
VALUES ('rebuild');
이 명령은 기존 콘텐츠를 기준으로 FTS5 Index를 다시 생성한다.
따라서 실제 기사 데이터와 검색 Index를 분리해 처리할 수 있었다.
중요한 점은 Index의 내부 데이터를 그대로 복사하는 대신 실제 원본 콘텐츠에서 다시 생성했다는 사실이다.
이러한 방식은 검색 Index를 재생성할 수 있는 구조에서 활용할 수 있다.
하지만 실제 원본 콘텐츠가 완전하게 Import됐는지 먼저 확인해야 한다.
콘텐츠 데이터가 누락된 상태에서 Index를 재생성하면 검색 결과도 누락될 수 있기 때문이다.
AUTOINCREMENT Counter
두 번째 문제는 다음 Table이다.
sqlite_sequence
SQLite에서는 AUTOINCREMENT를 사용하는 Table의 마지막 ID 정보를 해당 Table에 저장한다.
예를 들어 다음 데이터가 있다고 가정해 보자.
- ID 1
- ID 2
- ID 3
이후 ID 3의 행을 삭제했다.
AUTOINCREMENT의 목적은 이전에 사용한 ID를 다시 사용하지 않도록 하는 데 있다.
하지만 데이터베이스를 이전하는 과정에서 실제 sqlite_sequence 정보를 누락하면 새로운 ID의 생성 방식이 달라질 수 있다.
예를 들어 외부 시스템이 이미 삭제된 ID 3을 기록하고 있다고 가정해 보자.
새로운 데이터에 같은 ID를 다시 사용하면 외부 참조의 의미가 잘못될 수 있다.
저자는 이를 방지하기 위해 기존 AUTOINCREMENT Counter를 명시적으로 복원하도록 했다.
즉 실제 행의 데이터뿐 아니라 데이터베이스가 새로운 ID를 생성할 때 사용하는 상태도 함께 이전한 것이다.
SQLite 호환성의 의미
이번 사례에서 중요한 부분은 다음 사실이다.
같은 SQL 엔진을 사용한다는 사실과 실제 데이터 파일 및 내부 Metadata가 완전히 호환된다는 사실은 다르다.
예를 들어 기존 Query가 D1에서 정상적으로 실행될 수 있다.
하지만 데이터베이스 Dump 안의 모든 내부 Table을 그대로 Import할 수 있는 것은 아닐 수 있다.
따라서 데이터베이스를 이전할 때는 다음 세 단계를 구분해야 한다.
- Schema 이전
- 실제 데이터 이전
- Index와 Counter 등 내부 상태 재구성
이러한 차이는 SQLite와 D1뿐 아니라 다른 데이터베이스 마이그레이션에서도 고려할 수 있다.
이미지 Storage 선택
저자는 이미지 파일을 Cloudflare R2로 이전하는 방식을 검토했다.
R2는 Object Storage다.
하지만 실제 사용하려는 무료 플랜에서는 R2를 활성화하기 위해 결제 카드 등록이 필요했다.
저자는 이를 피하기 위해 Workers KV를 사용했다.
실제 이미지 사용량이 제한적인 편집자용 이미지였기 때문이다.
KV는 Key-Value Storage다.
예를 들어 이미지의 경로를 Key로 사용하고 실제 데이터를 저장할 수 있다.
하지만 KV는 모든 종류의 데이터 저장에 적합한 것은 아니다.
특히 중요한 제한사항은 다음과 같다.
- 지역 간 데이터 일관성
- 값의 크기 제한
- 읽기와 쓰기의 동작 특성
따라서 실제 결제 상태나 주문 데이터처럼 즉시 일관성이 필요한 정보는 KV에 저장하는 것이 적합하지 않을 수 있다.
저자의 구조에서는 실제 관계형 데이터는 D1에 유지한다.
이미지와 같은 정적 파일은 KV로 분리한다.
Cron Job의 이전
기존 VPS에서는 Crontab을 사용하고 있었다.
새로운 구조에서는 Cloudflare Cron Trigger를 사용했다.
대표적인 작업은 다음과 같다.
첫 번째는 30분마다 실행하는 뉴스 Feed 동기화다.
두 번째는 매일 실행하는 만료된 Session 및 Rate-limit 기록 정리다.
따라서 별도의 Linux 서버를 유지하지 않아도 정기 작업을 실행할 수 있었다.
하지만 Cron Trigger가 존재한다는 사실만으로 모든 작업이 정확히 한 번만 실행된다고 보장할 수는 없다.
실제 데이터베이스를 변경하는 정기 작업에서는 재시도와 중복 실행 가능성을 고려해야 한다.
중복된 URL 방지
Cloudflare Worker는 기본적으로 다음과 같은 URL에서 접근할 수 있다.
*.workers.dev
또한 Preview Deployment에도 별도의 URL이 존재할 수 있다.
하지만 실제 사이트는 다음 도메인에서만 제공하고 싶었다.
haste.it
저자는 이를 위해 다음 설정을 사용했다.
{
"workers_dev": false,
"preview_urls": false
}
이렇게 하면 일반적인 Worker 개발 URL과 Preview URL을 비활성화할 수 있다.
따라서 같은 콘텐츠가 여러 공개 URL에서 제공되는 상황을 줄일 수 있었다.
하지만 이러한 설정만으로 모든 Canonical URL 문제가 자동으로 해결되는 것은 아니다.
실제 Domain과 Redirect, Sitemap의 설정도 확인해야 한다.
테스트와 보안 Header
저자는 다음 검증을 구현했다.
- Vitest
- TypeScript Type Check
- 입력 데이터 검증
- 데이터베이스 접근 테스트
- 보안 Header 검사
또한 정적 CSS와 JavaScript에는 Content Hash를 포함한 파일 이름을 사용했다.
따라서 브라우저에서 오래된 파일을 재사용하지 않도록 캐시 정책을 구성할 수 있었다.
실제 보안 Header에는 다음 종류가 포함될 수 있다.
- CSP
- HSTS
하지만 이러한 Header를 추가했다는 사실만으로 실제 모든 웹 보안 문제가 해결되는 것은 아니다.
특히 Stripe 결제를 사용하는 경우에는 실제 Webhook 요청의 검증과 이벤트 중복 처리도 중요하다.
원문에서는 전체 결제 관련 보안 구현과 독립적인 감사 결과를 공개하지 않았다.
따라서 마이그레이션 이후 모든 결제 흐름이 완벽하게 검증됐다고 단정해서는 안 된다.
적용 범위와 한계
이번 글은 실제 운영 중인 사이트의 마이그레이션 기록이다.
하지만 다음 수치는 제공하지 않았다.
- 기존 VPS와 Workers의 실제 월 비용
- API 응답 시간의 P95
- 데이터베이스 Query 처리량
- 실제 장애율
- Worker Memory 사용량
따라서 Workers와 D1으로 이전하면 모든 PHP 웹사이트의 비용과 성능이 개선된다고 일반화할 수 없다.
또한 무료 플랜의 사용량 한도는 실제 트래픽과 데이터 구조에 영향을 받는다.
이번 글은 서버리스 마이그레이션에서 실제 PHP 코드를 TypeScript로 다시 작성하는 작업뿐 아니라 데이터베이스의 내부 상태, 정적 자산의 실행 경로, 정기 작업과 데이터 일관성 정책까지 함께 이전해야 한다는 점을 구체적으로 설명한 사례다.
AI가 이미 결정한 아키텍처를 무시하는 문제 — ADR 인덱스를 Claude Code Hook으로 주입한 4개월간의 운영 기록
- 원제: AIが既存決定を無視する本当の理由 — ADR文脈自動注入hookの手法
- 저자: 上原正吉
- 매체: Zenn
- 게시일: 2026-11-21
- 기술: Claude Code, Agent Harness, Architecture Decision Record, Shell Hook, Context Engineering, AI 코딩 에이전트
- 원문: https://zenn.dev/chooser/articles/cp-009-ai-dev-process
AI 코딩 에이전트가 이미 결정된 기술 선택을 반복해서 무시하는 문제를 해결하기 위해 기존 아키텍처 결정 기록을 자동으로 에이전트의 Context에 전달하는 Hook을 구현하고, 실제 운영 과정에서 발생한 성능 및 정확성 문제를 분석한 글이다.
이번 글은 단순히 AI에게 문서를 잘 읽으라고 지시하는 방법을 설명하지 않는다.
오히려 그러한 지시가 실제로 지켜지지 않았던 사례에서 시작한다.
저자는 기존 ADR을 인덱스로 생성해 전달하도록 변경했다.
이후 수개월 동안 Hook의 실행 시점과 성능을 변경했다.
또한 실제 구현이 여전히 어떤 정보를 누락하는지까지 공개했다.
기존 아키텍처 결정
저자의 프로젝트에서는 문서 편집기를 구현하고 있었다.
기술 선택 과정에서 다음 라이브러리를 비교했다.
- BlockNote
- TipTap
이후 BlockNote를 사용하기로 결정했다.
그리고 해당 판단을 ADR에 기록했다.
ADR은 Architecture Decision Record의 약자다.
대표적으로 다음 정보를 기록할 수 있다.
- 어떤 기술을 선택했는가?
- 어떤 대안을 검토했는가?
- 왜 해당 기술을 선택했는가?
- 이후 어떤 제약을 유지해야 하는가?
따라서 ADR이 존재한다면 이후 개발자는 기존 판단을 참고할 수 있다.
하지만 실제 AI 코딩 에이전트는 그렇지 않았다.
실제 발생한 문제
저자는 BlockNote를 선택한 지 약 2주 뒤 AI에게 새로운 작업을 요청했다.
그런데 AI는 TipTap을 직접 도입하는 방법을 제안했다.
기존 ADR에는 TipTap을 직접 사용하지 않기로 결정한 이유가 기록돼 있었다.
하지만 실제 에이전트는 해당 기록을 참조하지 않았다.
즉 문서가 존재했다.
내용도 명확했다.
하지만 실제 작업 시점의 Context에는 관련 결정이 포함되지 않았다.
저자는 이 문제를 단순히 모델이 내용을 잊었다는 설명으로 끝내지 않았다.
다음 네 가지 원인을 구분했다.
- ADR 파일은 존재하지만 자동으로 읽는 작업이 없음
- 프로젝트 지침에 ADR 확인을 작성해도 실제 작업에서 참조하지 않을 수 있음
- 구체적인 구현 요청에서는 과거 결정 확인보다 새로운 제안이 먼저 생성될 수 있음
- 조건부 지침은 모델이 필요하지 않다고 해석할 가능성이 있음
하지만 이번 분석이 모든 AI 코딩 에이전트의 동작에 관한 과학적인 원인 규명은 아니다.
저자는 실제 구조에서 발견한 문제를 설명한 것이다.
ADR 인덱스 생성
저자는 다음 디렉터리를 읽는 Script를 작성했다.
docs/adr/
각 ADR에는 다음 정보가 존재했다.
- 번호
- 제목
- 상태
상태에는 다음 값이 존재할 수 있다.
- Draft
- Accepted
- Amended
- Rejected
- Superseded
실제 현재 적용해야 하는 결정은 Accepted와 Amended로 제한했다.
예를 들어 과거에 Rejected된 기술을 현재의 필수 정책으로 전달하면 문제가 발생할 수 있다.
따라서 모든 ADR을 무조건 에이전트에 전달하지 않았다.
실제 유효한 결정만 선택했다.
전체 문서가 아니라 제목과 상태만 전달
이번 설계에서 중요한 부분은 Context의 크기다.
ADR 전체 본문을 모두 전달하면 Token 사용량이 크게 증가할 수 있다.
특히 프로젝트의 규모가 커지면 수십 또는 수백 개 ADR이 존재할 수 있다.
저자는 실제 본문을 모두 전달하지 않았다.
대신 다음 정보만 포함했다.
- ADR 번호
- 제목
- 상태
초기 설계의 한도는 다음과 같았다.
- 최대 30개 ADR
- 약 750 Token
이렇게 하면 모델은 실제 어떤 결정이 존재하는지 확인할 수 있다.
이후 관련 ADR을 선택해 본문을 읽을 수 있다.
하지만 중요한 한계가 있다.
ADR의 제목을 전달했다는 사실과 실제 ADR 본문을 읽었다는 사실은 다르다.
모델은 목록을 보고도 관련 문서를 선택하지 않을 수 있다.
또는 본문을 읽었더라도 실제 결정에 맞지 않는 구현을 제안할 수 있다.
따라서 이번 Hook은 문서의 존재를 알리는 기능이며, 모든 결정의 준수를 보장하는 기능은 아니다.
첫 번째 Hook: UserPromptSubmit
초기 구현은 다음 Claude Code Hook을 사용했다.
UserPromptSubmit
이 Hook은 사용자가 Prompt를 전달할 때 실행할 수 있다.
따라서 매 사용자 요청마다 ADR 인덱스를 생성했다.
예를 들어 다음 요청을 생각할 수 있다.
문서 편집기의 Toolbar를 개선해 줘.
이 요청이 전달되면 Hook이 현재 프로젝트의 ADR을 읽는다.
그리고 관련 목록을 모델 Context에 추가한다.
따라서 모델이 자발적으로 파일을 검색해야만 과거 결정을 발견하는 구조보다 명시적인 전달 경로를 제공할 수 있었다.
하지만 매 Prompt마다 같은 목록을 전달한다는 점이 문제였다.
Hook 자체의 세 가지 오류
저자는 초기 구현의 Code Review에서도 실제 오류를 발견했다.
첫 번째는 필터링 순서였다.
기존 구현은 ADR 목록을 30개로 줄인 뒤 상태를 확인했다.
이 경우 처음 30개에 Rejected 문서가 많이 포함돼 있다면 뒤쪽의 유효한 ADR이 누락될 수 있다.
저자는 순서를 변경했다.
- 전체 ADR 분석
- Accepted 및 Amended만 선택
- 이후 최대 30개로 제한
두 번째는 프로젝트 Root 탐색이었다.
기존 Script는 필요한 환경 변수가 존재하지 않으면 Hook 파일이 설치된 디렉터리를 기준으로 탐색했다.
하지만 실제 ADR은 사용자가 작업 중인 Git Repository에 존재한다.
따라서 다음 순서로 변경했다.
- 환경 변수
- 현재 디렉터리의 Git Root
- 현재 디렉터리
세 번째는 문자열 구분자였다.
기존에는 번호와 제목, 상태를 | 문자로 구분했다.
하지만 제목 자체에 |가 포함될 수 있었다.
따라서 해당 구분자를 Tab으로 변경했다.
이러한 문제는 자동 Hook도 일반적인 프로그램과 마찬가지로 구현 오류를 가질 수 있다는 점을 보여준다.
매 Prompt에서 SessionStart로 변경
초기 구현은 매 사용자 요청마다 최대 750 Token을 추가했다.
예를 들어 사용자가 20번 요청을 전달한다고 가정해 보자.
같은 인덱스를 반복해서 전달하게 된다.
이러한 방식은 Token 사용량을 증가시킬 수 있다.
저자는 이를 해결하기 위해 Hook의 등록 시점을 변경했다.
기존:
UserPromptSubmit
변경:
SessionStart
이제 새로운 세션이 시작될 때 관련 ADR 목록을 전달한다.
따라서 매 사용자 요청마다 같은 목록을 반복해서 생성하지 않아도 된다.
하지만 새로운 트레이드오프가 발생한다.
세션 중간에 새로운 ADR이 추가돼도 기존 Context에 즉시 반영되지 않을 수 있다.
또한 긴 세션에서는 처음 전달한 인덱스와 현재 작업 사이의 거리가 멀어질 수 있다.
따라서 단순히 Token 사용량이 감소했다는 이유로 모든 면에서 더 좋은 구조라고 판단할 수는 없다.
ADR 파일 수 증가
프로젝트 규모가 커지면서 또 다른 문제가 발생했다.
저자의 프로젝트에는 121개 ADR 파일이 존재했다.
초기 Script는 각 파일의 제목과 상태를 확인하기 위해 여러 Shell 명령을 실행했다.
대표적으로 다음과 같다.
- grep
- sed
파일마다 여러 프로세스를 생성했다.
따라서 Session을 시작할 때 약 1,100개 프로세스가 실행되는 구조가 됐다.
이러한 방식은 실제 ADR 목록을 생성하는 데 불필요한 시간이 필요했다.
Shell Script의 성능 개선
저자는 기존 구현을 하나의 awk 실행으로 변경했다.
그리고 같은 입력을 10번 처리해 시간을 측정했다.
결과는 다음과 같았다.
| 구현 | 실행 시간 중앙값 |
|---|---|
| 여러 grep·sed 실행 | 3,842ms |
| 하나의 awk 실행 | 94.7ms |
약 40배의 차이다.
하지만 이 결과는 저자 자신의 환경에서 동일한 파일 집합을 처리한 자체 측정이다.
다른 운영체제와 Shell 환경에서 같은 개선율이 발생한다고 보장할 수 없다.
이번 결과에서 중요한 부분은 Context의 Token 수뿐 아니라 Hook이 실제 Context를 생성하는 데 필요한 실행 시간도 고려해야 한다는 점이다.
Context Compact 이후의 재실행
또 다른 문제는 긴 세션에서 발생했다.
Claude Code에서는 Context를 Compact할 수 있다.
오래된 대화와 정보를 압축해 사용 가능한 Context를 확보하는 기능이다.
하지만 Compact 이후에도 SessionStart Hook이 실행될 수 있다.
따라서 방금 줄인 Context에 3KB가 넘는 ADR 목록이 다시 추가될 수 있었다.
저자는 이를 해결하기 위해 실제 Hook이 실행된 이유를 확인했다.
대표적인 구분은 다음과 같다.
- Startup
- Resume
- Compact
- Fork
일반적인 시작에서는 ADR 목록을 전달한다.
하지만 Compact와 Resume에서는 짧은 Pointer만 전달하도록 했다.
예를 들어 다음 내용을 전달할 수 있다.
필요한 경우 docs/adr 디렉터리에서 관련 설계 결정을 확인하세요.
이렇게 하면 전체 목록을 다시 추가하지 않아도 된다.
Compact 이후 출력 크기
저자가 실제 측정한 결과에서 전체 인덱스는 약 3,510바이트였다.
반면 Compact 이후 전달하는 Pointer는 약 262바이트였다.
따라서 반복적인 Context 재주입의 크기를 줄일 수 있었다.
하지만 이 방식에서는 실제 ADR 목록이 전달되지 않는다.
모델이 필요하다고 판단해 관련 디렉터리를 탐색해야 한다.
따라서 Context 사용량이 감소하는 대신 자동으로 전달하는 정보량도 줄어든다.
144개 ADR 가운데 실제 표시되는 것은 30개
이번 글에서 중요한 부분은 실제 남아 있는 문제도 공개했다는 점이다.
2026년 9월 28일 기준 저자의 프로젝트에는 144개 ADR 파일이 있었다.
그 가운데 문서상 Accepted 또는 Amended인 파일은 135개였다.
하지만 Hook이 실제로 인식한 파일은 106개였다.
문제는 상태 표시 형식이었다.
예를 들어 일부 문서에는 다음과 같은 표현이 존재했다.
**Status**:
기존 Parser는 이러한 형식을 인식하지 못했다.
따라서 29개 파일이 누락됐다.
또한 인식한 106개 가운데 실제 Context에 전달하는 파일은 30개뿐이었다.
나머지 76개는 상한 때문에 제외됐다.
단순한 개수 제한의 문제
저자는 ADR 목록을 번호순으로 처리했다.
하지만 번호순으로 처음 30개를 선택하면 오래된 결정이 먼저 표시될 수 있다.
반대로 최근에 작성한 ADR은 목록에서 제외될 가능성이 있다.
이는 실제 에이전트의 작업에 중요한 영향을 줄 수 있다.
예를 들어 최근에 변경한 아키텍처 결정이 있다고 가정해 보자.
하지만 해당 ADR의 번호는 120번이다.
현재 Hook은 처음 30개만 전달한다.
따라서 해당 결정이 존재한다는 사실을 모델에 알리지 못할 수 있다.
저자는 다음 방법을 향후 개선 후보로 제시했다.
- Domain별 ADR 인덱스
- 최근 변경된 결정 우선
- 실제 작업 Keyword 기반 후보 선택
- 누락 여부를 확인하는 자동 테스트
하지만 이러한 방법은 이번 글에서 완성된 기능이 아니다.
향후 개선 방향이다.
실제로 검증하지 못한 결과
저자는 Hook의 효과를 과장하지 않는다.
다음 세 지표를 지속적으로 측정하지 못했다고 설명한다.
- 관련 Session에서 Hook이 실행된 비율
- 모델이 실제 ADR 본문을 읽은 비율
- 기존 설계 결정을 위반한 제안의 감소율
따라서 Hook을 적용한 이후 아키텍처 위반이 몇 퍼센트 감소했다고 주장하지 않는다.
이번 구현이 보장할 수 있는 범위는 더 좁다.
Hook이 정상적으로 실행되면 ADR 목록을 지정된 형식으로 Context에 전달할 수 있다.
하지만 모델이 실제 문서를 읽고 결정을 준수하는 것은 별도의 단계다.
적용 범위와 한계
이번 글은 한 개발 조직의 실제 Hook 구현과 운영 기록을 바탕으로 작성됐다.
따라서 모든 AI 에이전트의 오류 원인이 동일하다고 단정할 수 없다.
또한 ADR 문서를 자동으로 전달하는 방식 자체에도 새로운 유지보수 책임이 발생한다.
대표적으로 다음과 같다.
- Parser의 정확성
- 파일 수 증가에 따른 성능
- Context 상한
- Session 재시작 및 Compact
- 실제 ADR의 최신성
- 모델이 관련 문서를 읽었는지 검증
이번 글은 AI 코딩 에이전트에게 기존 프로젝트의 설계 결정을 전달하는 작업과 해당 결정을 실제로 준수하도록 검증하는 작업을 구분해야 하며, Context Engineering 자체도 성능과 정확성에 관한 테스트가 필요한 소프트웨어라는 점을 구체적인 운영 기록으로 설명한다.