사이트 배포
Next.js 마케팅 사이트(web/site/)를 Vercel 프로덕션에 배포하되, 단일 명령어가 아닌 목표로 취급하세요: 모든 사이트 관련 수정 사항을 main에 반영하고, 배포하고, 프로덕션에서 모든 페이지와 이메일 캡처 흐름이 데스크톱 및 모바일에서 제대로 작동하는지 증명한 후, 모든 것이 정상이 될 때까지 수정 및 재배포를 반복합니다.
목표 계약
이 스킬을 폐쇄 루프로 실행하세요. 단순히 Vercel 배포가 성공했다고 해서 성공으로 선언하지 마세요. 배포는 성공했지만 페이지가 500 오류를 반환하거나, 모바일에서 레이아웃이 깨지거나, 대기자 명단 쓰기가 조용히 실패할 수 있습니다.
- 완료(DONE) 조건: 모든 사이트 관련 수정 사항이 커밋되어
main에 푸시되었고, 프로덕션 배포가 성공했으며, 아래 모든 경로가 데스크톱 및 모바일에서 200을 반환하고 콘솔/네트워크 오류 없이 올바르게 렌더링되며, 이메일 캡처 흐름이 제출을 수락하고 저장(관리자 읽기로 증명)하며, 테스트 행이 남아 있지 않습니다. - 미완료(루프 재실행) 조건: 경로 렌더링 실패, 뷰포트에서 레이아웃 깨짐, 콘솔 오류 표시, 이메일 캡처가 라운드트립되지 않음. 소스에서 수정하고, 다시 반영하고, 다시 배포하고, 다시 확인합니다.
- 차단됨(중단 및 보고) 조건: 수정에 필요한 자격 증명/결정이 없는 경우(예: KV 저장소 다운, 관리자 토큰 누락, Vercel 인증 만료) 또는 동일한 실패가 3번의 수정 시도에도 지속되는 경우. 정확한 실패 내용과 시도한 방법을 보고하세요. 무한 루프에 빠지지 마세요.
각 반복에 대한 간단한 실행 로그(무엇이 실패했는지, 무엇을 변경했는지, 재확인 결과)를 유지하여 루프를 감사 가능하게 만드세요. 사용자가 이를 지속적인 /goal로 원하는 경우, 이 스킬을 목표로 지정하고 동일한 DONE/BLOCKED 조건을 사용하세요.
루프
단계 0 범위 지정 및 반영 사이트 수정 사항 수집 -> 로컬 확인 -> 커밋 -> main 푸시
단계 1 배포 빌드 -> npx vercel@latest --prod (저장소 루트에서 실행)
단계 2 확인 (프로덕션) 워크플로우 팬아웃: 경로 x 뷰포트 + 이메일 캡처
단계 3 분류 빨간색 있음? 소스에서 수정 -> 단계 0으로 돌아가기
모두 녹색? -> 완료
컨텍스트
- 프로젝트: Vercel의
opentraces(범위jayfareis-projects) - 프레임워크: Next.js 16 (App Router)
- 루트 디렉토리: Vercel은 루트를
web/site/로 설정함 - 도메인: opentraces.ai (프로덕션: https://opentraces.ai)
- 빌드:
next build(web/site/에서 실행) - 버전: 빌드 시
next.config.ts를 통해src/opentraces/__init__.py에서 자동 읽기 - 이메일 캡처:
EarlyAccessForm이/api/waitlist로 POST (프로덕션에서 Upstash/KV 사용)./(HubTeaser통해) 및/hub에서 렌더링. 참조 섹션에서 선택자 및 관리자 읽기 확인.
단계 0 — 범위 지정 및 사이트 수정 사항 반영
-
사이트 관련 및 미반영 사항 찾기. 작업 트리에는 종종 사이트 + 비사이트 변경 사항이 섞여 있습니다. 여기서는 사이트 수정 사항만 반영합니다(나머지는 별도 문제).
git status --short web/site/ git status --short -- ':!web/site/' # 비사이트 변경 사항, 보통 그대로 둠 git log --oneline origin/main..HEAD -- web/site/ # 아직 푸시되지 않은 사이트 커밋 -
반영 전 로컬 확인 (게이트). 이미 실행 중인 개발 서버에 대해 사이트를 실행하고 agent-browser로 변경된 표면을 확인합니다: 라이트 + 다크, 데스크톱 + 모바일, 변경한 특정 상호작용, 콘솔/네트워크 클린 상태. 이것이 반영 전 게이트입니다. 시각적 회귀를 커밋하지 마세요. (개발 서버가 실행 중이지 않은 경우,
cd web/site && npm run dev를 여분의 포트에서 실행하고, 확인한 후 중지하세요.) -
로컬 빌드 (개발 서버가 숨기는 타입/빌드 오류 포착):
cd web/site && npm run build계속하기 전에 빌드 실패를 수정하세요.
-
main에 커밋하고 푸시. 프로젝트 규칙에 따라
main에 직접 커밋합니다(요청하지 않는 한 기능 브랜치를 자동 생성하지 마세요). 커밋은 사이트 수정 사항에 한정하며, 저장소 바닥글 규칙에 따라 공동 작성자를 추가합니다.git add web/site/ # 확인한 사이트 수정 사항만 스테이징 git commit -m "fix(site): <변경 사항>" git push origin main
단계 1 — 빌드 및 배포
저장소 루트에서 배포하세요(web/site/가 아님). Vercel이 프로젝트 설정에서 루트 디렉토리를 확인하기 때문입니다(rootDirectory=web/site). web/site/ 내에서 실행하면 경로가 이중 중첩됩니다. 항상 최신 CLI(npx vercel@latest)를 사용하세요.
cd /path/to/repo/root
rm -rf web/site/.next kb/app/.next # 오래된 빌드 출력물; 업로드를 부풀림
npx vercel@latest --prod --yes
--archive=tgz를 사용하지 마세요 (2026-06-26 측정, CLI 54.x). --archive=tgz는 전체 작업 트리를 tar로 묶고 .vercelignore를 우회하므로 .git-minus-nothing-else 외에 kb/, .otbox/, web/site/.next-test/ 등을 함께 올립니다. — 약 3 GB / 1998개 파일 업로드로 몇 분이 걸리며 한 번은 빌드 머신에서 "Extracting deployment files"에서 ~20분 동안 멈췄습니다 (실제 프로덕션 중단). vercel@latest의 기본 파일별(file-by-file) 경로는:
.vercelignore를 존중하여 → ~628개 파일 / ~40 MB,- ~2초에 업로드하고 ~60초 내 READY 도달,
--archive=tgz가 원래 회피하려고 했던Error: Upload aborted가 발생하지 않습니다 (그것은 brew 41.x 엔드포인트 버그였으며,vercel@latest에서 수정되어 이제는 순손실).
향후 CLI가 파일별 경로를 퇴보시켜 --archive=tgz로 대체해야 하는 경우, ~3 GB 아카이브와 수 분(가끔 중단되는) 추출을 예상하세요 — 추출 중 멈추면 배포를 재시도하세요.
출력에서 배포 URL/id를 캡처하세요. 확인 보고서에서 참조합니다.
팁: 먼저 Vercel 프리뷰 배포를 확인(
--prod생략)하고, 프리뷰 URL에 대해 단계 2를 실행한 후 프로모션할 수 있습니다. 이렇게 하면 이메일 캡처 테스트가 완전히 프로덕션 목록에 반영되지 않습니다.
단계 2 — 프로덕션 확인 (Workflow / ultracode를 통한 JIT 하네스)
라이브 사이트가 작동하는지 증명합니다. 이 단계는 적시(JIT) 하네스입니다: 플래너(당신)가 이 배포에 대한 실행 범위를 지정하고, Workflow 도구(결정론적 런타임)가 실행하며, 임시 브라우저 워커가 각각 타입이 지정된 스키마에 대해 결과를 반환합니다. 중간 상태는 하네스의 변수에 저장되므로 전체 매트릭스가 컨텍스트를 채우지 않고 실행됩니다. 이 스킬은 명시적으로 Workflow 오케스트레이션(ultracode)을 선택합니다.
하네스는 이 스킬 옆에 번들로 고정되어 있습니다: verify-site-deploy.workflow.js. 스크립트를 인라인으로 붙여넣지 말고 파일을 실행하세요.
확인할 사항
- 경로 (각각 200 + 렌더링, 콘솔/네트워크 오류 없음):
/,/explorer,/hub,/schema,/docs, 그리고 딥 페이지 스팟 체크:/schema/0.6.0,/docs/getting-started/installation,/docs/cli/commands,/docs/schema/trace-record. - 뷰포트: 데스크톱
1440x900및 모바일390x844(iPhone급). 수정 사항이 테마를 건드린 경우 라이트 + 다크도 확인. - 페이지별: HTTP 200, 기본 콘텐츠 표시, 뷰포트에서 레이아웃 오버플로우/클리핑 없음, 콘솔 클린, 실패한 네트워크 요청 없음, 내비게이션 작동.
- 이메일 캡처 (자체 에이전트, 아래 참조).
이메일 캡처 확인 (프로덕션 목록 오염 금지)
/api/waitlist는 라이브 저장소에 쓰며 DELETE 엔드포인트가 없습니다. 신중하게 진행하세요:
- 실제 라운드트립 (한 번, 데스크톱):
deploy-verify-<타임스탬프>@opentraces.ai와 같은 태그된 주소를 제출하세요. HTTP 200{ok:true}와 버튼이 성공 상태로 전환되는 것을 예상하세요. 관리자 읽기(GET /api/waitlist+Authorization: Bearer $WAITLIST_ADMIN_TOKEN)로 저장되었는지 확인하고, 이전/이후 개수를 기록하세요. 그런 다음 정리하여 저장소에서 해당 행을 제거(UpstashZREM)하고, 개수가 돌아왔는지 다시 읽으세요. 목록을 깨끗하게 유지하세요. - 중복 경로: 동일한 주소를 두 번 제출하고, "이미 목록에 있습니다" 메시지와 개수가 변경되지 않음을 확인하세요.
- 모바일 + 쓰기 없는 반복 UI 확인: 숨겨진 honeypot(
input[name=company])을 제출 시 작성하세요. 엔드포인트는 조용한 가짜 성공을 반환하고 행을 저장하지 않으므로, 모바일에서 쓰레기를 추가하지 않고 성공 UI를 확인할 수 있습니다. (성공이 보이지만 개수가 움직이지 않는다면, honeypot이 작동하는 것이지 버그가 아닙니다.) - 엔드포인트가 503("waitlist is not configured")을 반환하면, KV 저장소가 해당 배포에 연결되지 않은 것입니다. 이는 차단(BLOCKED) 상태입니다(환경/저장소 문제). 코드 수정 사항이 아닙니다. 보고하세요.
하네스 실행
Workflow 도구로 번들된 아티팩트를 호출하세요. args로 배포별로 범위를 지정하세요(이것이 JIT "플래너" 단계입니다):
Workflow({
scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
args: {
baseUrl: "https://www.opentraces.ai", // 표준 호스트; 또는 이메일을 프로덕션에서 보호하기 위한 프리뷰 URL
changed: ["/hub", "/"], // 이 배포가 건드린 경로 -> 심층 확인; 나머지는 스모크 테스트
pagesOnly: false // true = 이메일 쓰기 건너뜀 (읽기 전용 유효성 검사만 실행)
}
})
{ base, scoped, failures, allGreen }을 반환합니다. allGreen: true는 단계 2가 통과했음을 의미합니다. 그렇지 않으면 failures에 단계 3에서 수정할 내용이 정확히 나열됩니다.
하네스가 JIT 프리미티브를 적용하는 방법 (kb/docs/concept-jit-harnesses-generic.md 참조):
- 분류 및 라우팅:
changed를 전달하면 해당 경로는 전체 브라우저 검사(콘솔, 오버플로우, 스크린샷)를 받고, 다른 모든 경로는 저렴한curl상태만 확인합니다. 런타임이 소유한 일반 JS 제어 흐름으로, 모델이 개입하지 않으므로 범위가 지정된 배포는 저렴하게 유지됩니다. - 뷰포트당 하나의 결정론적 스윕 워커 (2개 워커, ~18개 아님): 각 워커는 하나의 고정된 bash 배치(경로당
curl+ 제한된 agent-browser 호출 세트)를 저렴한 모델(haiku)에서 실행하고 구문 분석된 JSON을 반환합니다. "모든 것을 확인"하라는 개방형 프롬프트가 없으므로 모델이 루프에 빠질 수 없습니다. 각 배치는 하나의 브라우저 세션을 열고close --all로 종료하므로 Chrome 프로세스가 쌓이지 않습니다. (2026-06-09 검증: 전체 심층 뷰포트 스윕에 ~16초, 남은 프로세스 1개, 원래 셀별 설계의 54개 프로세스 / 15분+ 대비) - 독립적 적대적 확인: 스윕이 실패로 플래그한 모든 경로는 깨끗한 세션(기본 모델)을 가진 별도의 워커에 의해 재확인되어 재현을 시도합니다. 실패는 확인도 실패할 경우에만 생존하므로, agent-browser의 실수가 사이트 버그로 위장되지 않습니다.
- 타입이 지정된 계약: 모든 워커는
PAGE_VERDICT/EMAIL_VERDICT에 대해 결과를 반환하므로, 결과가 기계적으로 병합됩니다. - 이메일 캡처는 독립적인 관리자 읽기를 통해 쓰기를 증명하고 테스트 행을 정리하는 자체 워커를 얻습니다(위의 오염 금지 규칙 참조).
매트릭스, 깊이 정책 또는 판결 스키마를 변경하려면 .js 파일을 편집하세요. 이것이 단일 진실 공급원입니다. 변경 사항이 한 페이지이고 오케스트레이션이 필요하지 않은 경우, 주 세션에서 agent-browser 스킬을 사용하여 해당 페이지의 검사를 순차적으로 실행할 수 있습니다.
단계 3 — 분류 및 반복
워크플로우의 failures를 읽으세요:
- 비어 있음 -> 목표가 달성되었습니다. 보고: 배포 id/URL, 확인된 경로, 뷰포트, 이메일 라운드트립 증명 및 정리됨. 완료.
- 비어 있지 않음 -> 각 실패에 대해
web/site/소스에서 근본 원인을 찾고, 수정한 후 단계 0으로 돌아가세요(로컬 확인 -> 커밋 -> 푸시 -> 배포 -> 재확인). 먼저 실패한 경로에 범위를 지정하여 확인을 재실행하고, 녹색이 되면 전체 패스를 실행하세요. - 동일한 실패에 대해 3번의 시도가 실패하거나, 자격 증명/저장소/인증 차단제가 발생하면 중지하고 정확한 오류와 시도한 내용을 **차단됨(BLOCKED)**으로 보고하세요.
각 반복을 실행 로그에 기록하여 루프를 감사 가능하게 만드세요.
.vercelignore
위치가 중요합니다: 실제 파일은 저장소 루트의 .vercelignore입니다. 프로젝트의 Root Directory가 web/site이더라도, 전체 저장소가 업로드되며(빌드가 ../../src/opentraces/__init__.py 및 ../../skill/SKILL.md을 읽음), 파일별 업로드가 존중하는 유일한 .vercelignore는 저장소 루트에 있는 것입니다 — 패턴은 저장소 루트를 기준으로 일치합니다. web/site/.vercelignore는 무시됩니다. 추가하지 마세요(2026-06-26 npx vercel@latest --debug로 검증됨).
이는 긍정적 무시 목록입니다(명시적으로 열거된 디렉토리, * 캐치올 + ! 부정이 아님 — 부정은 깨지기 쉽고 CLI 버전 간에 깨집니다). 이것 없이 업로드하면 무거운 저장소 트리가 포함됩니다. 제외해야 하는 주요 항목(각각 우리가 수정한 실제 누수):
kb/(~2.4 G),.claude/(~1.5 G),tests/(~1.4 G),.venv*/(~0.8 G).otbox/(~613 M 스냅샷 tarball)web/site/.next-test/(~98 M / 1000+ 파일 —**/.next/는-test접미사와 일치하지 않으므로.next-test/는 자체 규칙이 필요함)web/viewer/,web/coming-soon/,web/metrics-worker/
주의:
.vercelignore는 파일별 업로드 경로만 필터링합니다.--archive=tgz플래그는 이를 우회합니다(단계 1 참조 — 사용하지 말아야 하는 또 다른 이유).
.vercelignore를 편집한 후 무엇이 업로드될지 점검하려면, 저장소 루트에서 npx vercel@latest --debug를 실행하고 Found N files … M required to upload 줄을 읽은 후 Ctrl-C를 누르세요. 전체 배포가 필요하지 않습니다. 정상적인 사이트 배포는 ~628개 파일, 약 ~2000개가 아닙니다.
무시해서는 안 되는 파일(빌드 시 읽음):
| 파일 | 읽는 위치 | 목적 |
|---|---|---|
src/opentraces/__init__.py | next.config.ts | version.json을 위한 버전 감지 |
skill/SKILL.md | lib/docs.ts (getSkillContent()) | 문서 페이지의 머신 뷰 콘텐츠 |
사이트가 빌드 시 ../../foo와 같은 상대 경로로 읽는 새 파일을 추가하는 경우, .vercelignore에서 제외되지 않았는지 확인하세요.
참조
경로 (단계 2 매트릭스): /, /explorer, /hub, /schema,
/schema/[version], /docs, /docs/[[...slug]] (~36개의 문서 슬러그,
lib/doc-nav.ts 출처). API: /api/waitlist (POST 추가, GET 관리자 읽기),
/api/stars.
이메일 폼 선택자 (EarlyAccessForm.tsx): 이메일 입력
input[type=email] / aria-label="email address" / .ea-input; 제출
button.ea-btn ("get early access" -> 로딩 -> 성공); 숨겨진 honeypot
input[name=company] (작성 시 조용한 가짜 성공, 저장되지 않음).
대기자 명단 관리자 읽기: GET /api/waitlist + Authorization: Bearer $WAITLIST_ADMIN_TOKEN 헤더. JSON { count, emails: [{ email, timestamp }] } 반환. 엔드포인트는 503을 반환하면 WAITLIST_KV_REST_API_URL / WAITLIST_KV_REST_API_TOKEN이 설정되지 않은 것입니다.
환경 변수:
| 변수 | 어디서 사용 | 필수? |
|---|---|---|
WAITLIST_ADMIN_TOKEN | 관리자 읽기 헤더 | 확인 시 예 |
WAITLIST_KV_REST_API_URL | /api/waitlist (업스트림) | 배포 시 예 |
WAITLIST_KV_REST_API_TOKEN | /api/waitlist (업스트림) | 배포 시 예 |
이 스킬은 Workflow 도구(ultracode)를 명시적으로 선택하여 확인 단계를 조정하지만, 하네스는 필요에 따라 플래너가 직접 agent-browser 세션을 실행하는 것을 금지하지 않습니다. 가벼운 확인에는 순차 실행으로 충분합니다.