Vercel Optimize

Vercel Optimize은(는) 무엇을 하나요?

관찰 가능성 우선 Vercel 최적화 감사를 실행합니다. signals.json이 존재하고 결정론적 게이트가 라우트, 파일 또는 프로젝트 설정을 가리킬 때까지 소스 파일을 검사하지 마십시오.

핵심 교리: 규칙이 명확하지 않은 경우 references/doctrine.md를 읽으십시오.

• 메트릭 우선. 권장 사항은 저장소 전체의 grep이 아닌 Vercel 프로덕션 신호에서 시작됩니다.
• 결정론적 게이트. scripts/gate-investigations.mjs가 무엇을 조사할 가치가 있는지 결정합니다.
• 후보 범위 내. 후보가 명명한 파일 또는 라우트-로컬 임포트 체인만 읽습니다.
• 버전 인식 인용. references/docs-library.json만 사용하십시오. 유효하지 않거나 버전이 일치하지 않는 인용은 제거됩니다.
• 고객 문체. 보고서 텍스트나 채팅 출력을 작성하기 전에 references/voice.md를 읽으십시오.

전제 조건

• Vercel CLI v53+ (vercel metrics, vercel usage, vercel contract, vercel api 명령어 필요).
• 인증된 CLI 세션: vercel login.
• 연결된 앱 디렉토리: vercel link. VERCEL_PROJECT_ID는 프로젝트 구성을 확인하는 데 도움이 될 수 있지만, vercel metrics는 여전히 디렉토리 연결이 필요합니다. 링크 또는 환경에는 의도한 프로젝트 조직/팀/사용자 범위가 포함되어야 수집기가 CLI-safe --scope를 확인하고 동일한 계정에서 vercel metrics, vercel usage, vercel contract를 유지할 수 있습니다.
• Node.js 20+.
• 라우트 수준 메트릭 기반 권장 사항을 위한 Observability Plus.

인증 토큰을 셸 명령어에 절대 넣지 마십시오. 채팅에 표시될 수 있는 명령어에 VERCEL_TOKEN=..., --token ... 또는 Authorization: Bearer ...을 입력하지 마십시오.

프레임워크 지원

사전 점검은 package.json을 읽고 메트릭 수집 전에 기대치를 설정합니다.

프레임워크	상태	비고
Next.js App Router	지원됨	가장 강력한 라우트 매핑, 스캐너, 플레이북, 인용
Next.js Pages Router	지원됨	감지 시 Pages Router 관용구로 범위 제한
SvelteKit	지원됨	src/routes 파일 및 SvelteKit 스캐너에 대한 라우트 매핑
Nuxt	지원됨	라우트 매핑 및 일반/플랫폼 검사; 프레임워크별 권장 사항 적음
Astro	제한적	라우트 매핑 및 일반 검사; 프레임워크별 권장 사항 적음
Hono / Remix / 알 수 없음	기본적으로 차단됨	사용자가 제한된 플랫폼/코드 전용 감사를 수락하는 경우에만 계속

지원되지 않는 경우 중단하고 스캔 또는 게이팅 전에 사용자에게 물어보십시오:

이 프로젝트는 <framework>을(를) 사용합니다. Vercel Optimize는 Next.js, SvelteKit 및 Nuxt에 대한 메트릭 기반 코드 권장 사항을 지원합니다. Astro 지원은 제한적입니다. <framework>의 경우 제한된 플랫폼/스캐너 감사를 실행할 수 있지만, 라우트 수준 Vercel 메트릭이 소스 파일에 매핑되지 않을 수 있습니다.

제한된 감사를 계속하시겠습니까, 아니면 여기서 중단하시겠습니까?

사용자가 계속하기로 선택한 경우 --continue-unsupported-framework 플래그와 함께 수집을 다시 실행하십시오.

실행 디렉토리

모든 감사마다 새로운 실행 디렉토리를 사용하십시오. 실행 간에 브리프, 하위 에이전트 출력 또는 보고서를 재사용하지 마십시오.

RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"

파이프라인

1. 신호 수집, 스캔 및 병합

연결된 앱 디렉토리에서 실행하거나 스크립트가 지원하는 경우 --cwd를 전달하십시오. stdout JSON을 stderr 로그와 분리하여 유지하십시오. 스트림을 결합하지 마십시오.

node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"

node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"

수집 세부 정보, 스키마, 메트릭 ID 및 성능 저하 동작은 references/data-collection.md에 있습니다. 메트릭 레지스트리는 lib/queries.mjs에 있습니다. 모든 쿼리는 공유된 14일 기간을 유지하십시오.

collect-signals.mjs는 연결된 프로젝트 소유자를 commandScope.cliScope로 확인하고 확인된 계정이 확인된 프로젝트를 읽을 수 있는지 Observability Plus를 확인하기 전에 확인합니다. 다운스트림 스크립트는 --scope를 허용하는 모든 Vercel CLI 명령어에 대해 해당 범위를 재사용합니다. 동일한 범위 없이 수동으로 vercel usage, vercel metrics 또는 vercel contract를 실행하지 마십시오. 범위가 지정되지 않은 사용량은 사용자의 개인 조직을 보고하는 반면, 라우트 메트릭은 팀 프로젝트에서 가져올 수 있습니다.

프로젝트 또는 범위 확인이 모호한 경우 중단하고 사용자가 감사하려는 Vercel 프로젝트 및 팀/개인 범위를 물어보십시오. 현재 vercel whoami 팀에서 의도된 범위를 추론하지 말고, 링크, .vercel/repo.json의 정확한 프로젝트 일치 또는 VERCEL_PROJECT_ID + VERCEL_ORG_ID가 의도된 계정을 식별할 때까지 메트릭, 사용량 또는 계약 수집을 진행하지 마십시오.

PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED 또는 PROJECT_SCOPE_MISMATCH에 대해 다음 프롬프트를 사용하십시오:

아직 이 감사를 위한 Vercel 프로젝트와 계정을 안전하게 식별할 수 없습니다.

Vercel 프로젝트 이름 또는 ID와 팀 슬러그/이름을 확인해 주시거나 개인 계정에 속한 것임을 알려주십시오. 확인되면 메트릭을 확인하기 전에 정확한 범위에 대해 다시 연결하거나 수집을 다시 실행하겠습니다.

1.1 차단 요소에서 중지

게이팅 전에 차단 요소를 확인하십시오:

jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"

필요한 조치:

• frameworkSupportBlocker === "unsupported_framework": 위의 지원되지 않는 프레임워크 프롬프트를 사용하십시오.
• PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED 또는 PROJECT_SCOPE_MISMATCH: 중단하고 사용자가 감사하려는 Vercel 프로젝트와 팀/개인 범위를 물어보십시오. 팀 프로젝트의 경우 vercel link --yes --project <프로젝트-이름-또는-ID> --team <팀-슬러그> 후 다시 실행하고, 개인 프로젝트의 경우 의도된 사용자 계정으로 연결하거나 VERCEL_PROJECT_ID와 VERCEL_ORG_ID를 모두 설정한 후 다시 실행하십시오.
• observabilityPlusBlocker === null: 계속합니다.
• no_traffic: 라우트 메트릭이 부족하다고 사용자에게 알리고, 제한된 출력을 수락하는 경우에만 계속합니다.
• payment_required 또는 no_oplus_probe: references/observability-plus.md를 그대로 표시하고 물어보십시오.
• project_disabled: 사용자에게 프로젝트에 대해 Observability Plus를 활성화하거나 제한된 감사를 수락하도록 요청하십시오.
• daily_quota_exceeded: 중단하고 Observability 쿼리 할당량이 소진되었음을 사용자에게 알리고, 다음 UTC 자정 리셋 후 다시 시도하거나 제한된 코드 전용 감사로 계속할지 물어보십시오.
• not_linked: 앱 디렉토리를 연결한 다음 1단계를 다시 실행하십시오. 앱 경로와 프로젝트를 알고 있는 경우:

vercel link --yes --project <프로젝트-이름-또는-ID> --cwd <앱-디렉토리>
# 팀 ID 또는 슬러그를 알고 있으면 --team <팀-ID-또는-슬러그> 추가

• forbidden 또는 project_not_found: 인증/팀 범위를 수정하십시오. Observability Plus를 홍보하지 마십시오.
• all_failed_other: 원시 오류 코드를 표시하고 제한된 코드 전용 모드로 계속할지 물어보십시오.

조용히 코드 전용 모드로 폴백하지 마십시오. 사용자가 제한된 감사를 수락하는 경우 다음으로 수집을 다시 실행하십시오:

node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"

그런 다음 다시 스캔하고 병합하십시오.

2. 후보 게이팅

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"

출력 형태:

• toLaunch: 조사할 코드 범위 후보.
• platform: 프로젝트/계정 범위 권장 사항.
• gated: 건너뛰거나, 포함되었거나, 자격이 박탈된 후보로 보고서에 계속 표시되어야 합니다.
• budget: 후보 예산 및 선택 모드.

기본 예산은 다양성 보호 장치가 있는 6개의 코드 범위 후보입니다. 확장하려면:

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"

생성된 후보 문서: references/candidates.md.

2.1 필요한 경우 감사 범위 문의

심층 분석 전에 다음을 실행하십시오:

node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"

shouldAsk가 false이면 계속합니다.

shouldAsk가 true이면:

1. exactChatMessage.body를 반환된 그대로 정확히 출력하십시오. 요약, 자르기, 순서 변경 또는 다시 작성하지 마십시오.
2. 그런 다음 호스트가 구조화된 질문을 지원하는 경우 questionPayload를 사용하여 questionText를 물어보십시오.
3. 사용자가 다른 번호를 선택한 경우 --max-candidates <선택>으로 게이트를 다시 실행하십시오.

긴 미리보기를 질문 필드 안에 절대 넣지 마십시오. 미리보기와 질문은 별도의 영역입니다.

2.2 심층 분석 및 조정

node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <프로젝트-디렉토리> > "$RUN_DIR/investigation-evidence.json"

node scripts/reconcile-candidates.mjs "$RUN_DIR/investigation-evidence.json" \
  --gate "$RUN_DIR/gate.json" \
  --out "$RUN_DIR/reconciled-investigation.json"

--cwd는 연결된 프로젝트 디렉토리여야 deep-dive.mjs가 동일한 프로젝트 링크를 확인하고 후속 vercel metrics 호출을 위해 signals.json.commandScope.cliScope를 재사용할 수 있습니다.

조정은 결정론적으로 반증된 후보를 소스 조사 전에 관찰 결과로 변환합니다:

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 브리프 생성 및 조사

작업 목록:

node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"

briefs-manifest.json.briefs의 모든 항목에 대해 하나의 브리프를 생성하십시오. group은 toLaunch 또는 platform일 수 있습니다. toLaunch 브리프만 생성하지 마십시오.

mkdir -p "$RUN_DIR/briefs" "$RUN_DIR/sub-agent-outputs"
node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" \
  --group <brief.group> --index <brief.index> --out "$RUN_DIR/briefs/<brief.group>-<brief.index>.md"

표시 가능한 작업자 이름(예: toLaunch-7이 아닌 /docs/llm-digest/[...slug]의 낮은 캐시 적중률 라우트)에는 briefs-manifest.json.briefs[].label을 사용하십시오.

분할 규칙:

• 1-2개의 브리프: 인라인으로 조사합니다.
• 3개 이상의 브리프: 호스트가 지원하는 경우 브리프당 하나의 하위 에이전트를 생성합니다.
• 하위 에이전트가 없는 호스트: 직렬로 인라인 실행합니다.

하위 에이전트 계약:

• 브리프는 전체 프롬프트입니다.
• 브리프에 나열된 파일과 필요한 경우 라우트-로컬 임포트만 읽습니다.
• references/recommendations.md를 사용하여 하나의 JSON 권장 사항 또는 하나의 JSON 변경 없음 결과를 내보냅니다.
• 제공된 인용 하위 집합 외부의 URL을 인용하지 마십시오.
• 감지된 버전에서 사용할 수 없는 프레임워크 기능을 권장하지 마십시오.

하위 에이전트가 저장소 전체 grep에 도달하는 경우 후보가 잘못된 것입니다. 범위를 확장하는 대신 삭제하거나 기권하십시오.

2.4 출력 수집

각 원시 조사 결과를 $RUN_DIR/sub-agent-outputs/에 저장한 다음 수집합니다:

node scripts/collect-sub-agent-outputs.mjs \
  --manifest "$RUN_DIR/briefs-manifest.json" \
  --out "$RUN_DIR/recommendations.json" \
  "$RUN_DIR/sub-agent-outputs/"

수집기는 JSON을 추출하고, 미리 확인된 레코드를 앞에 추가하고, 매니페스트 순서를 적용하며, 누락, 중복, 알 수 없거나 일치하지 않는 candidateRef 값이 있으면 실패합니다.

3. 권장 사항 확인

node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
  --signals "$RUN_DIR/signals.json" \
  --repo-root <프로젝트-디렉토리> \
  --out "$RUN_DIR/verify.json"

이 스크립트는 클레임을 추출하고, 파일/인용/버전 적합성을 확인하고, 품질을 평가하고, 살균기를 적용하고, verifiedRecommendations, withheldRecommendations, renderableRecommendations를 내보내고, 실패했거나 안전하지 않은 권장 사항에 대한 regenPlan을 생성합니다.

권장 사항 스키마, 작성 규칙, 살균기 순서 및 등급 규칙: references/recommendations.md. 확인 규칙: references/verification.md.

각 regenPlan 항목에 대해 topFailures를 나열하는 이전 시도에서 다음 검사가 실패했습니다 섹션과 함께 동일한 브리프를 다시 실행하십시오. 인용을 손상시키지 않고 확인이 개선되는 경우에만 다시 생성된 출력을 유지하십시오.

4. 보고서 및 최종 메시지 렌더링

node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
  --project <이름> \
  --out "$RUN_DIR/report.md" \
  --message-out "$RUN_DIR/final-message.json"

스킬을 개발할 때만 --debug-out "$RUN_DIR/debug.json"을 사용하십시오. 고객용 Markdown 및 채팅 출력에는 passRate, quality, 살균기 추적, 원시 하위 에이전트 이름 또는 기타 구현 필드가 노출되어서는 안 됩니다.

렌더링 후 final-message.json.body를 있는 그대로 출력하고 중단하십시오. 하이라이트, 디버그 노트, 원시 개수, 하위 에이전트 요약 또는 추가 설명을 추가하지 마십시오. 렌더링 시간 중복 제거, 플랫폼 상한 및 하드-세이프티 드롭으로 인해 고객에게 표시되는 개수가 변경될 수 있으므로 원시 verify.json에서 요약하지 마십시오.

보고서 구조 및 영향 프레이밍: references/scoring.md.

권장 사항 규칙

모든 권장 사항은 다음을 따라야 합니다:

• 실행된 후보, 플랫폼 후보, 사전 확인된 관찰 결과 또는 확인된 트래픽 독립적 스캐너 결과로 추적 가능해야 합니다.
• signals.json 또는 evidence.deepDive의 관찰된 메트릭 증거를 포함해야 합니다.
• 코드와 관련된 경우 줄 번호와 함께 확인된 파일을 인용해야 합니다.
• 감지된 프레임워크/버전에 적용되는 하나 이상의 허용된 인용을 포함해야 합니다.
• 정확한 관찰된 성능 수치를 사용해야 합니다.
• 비용 규모 구문만 사용하고 고객에게 직접적인 $N 절감액을 표시하지 마십시오.
• Vercel Workflow 런타임 엔드포인트(/.well-known/workflow/v1/*)에 대한 기간 감소를 권장하지 마십시오. 이들은 내구성 있는 단계/흐름 실행을 위한 생성된 오케스트레이션 라우트이므로 조사 전에 하드 게이트되어야 합니다.
• Workflow 권장 사항은 변경되는 경계를 명명해야 합니다. 유효한 예: 완료를 기다리는 대신 내구성 있는 작업을 큐에 넣고 실행 ID 반환, 스트림 재생/종료/잠금 수정, 또는 확인된 초과 Workflow 단계/초/실행 시간 감소.
• Vercel Workflow 런타임 엔드포인트에 대한 권장 사항은 Workflow 호출 비용 대신 실행 단계/지연/시간 초과를 대상으로 해야 합니다.

문서 구조

모든 핵심 규칙과 목적: references/doctrine.md

데이터 수집 세부 정보: references/data-collection.md

후보 문서: references/candidates.md

Observability Plus 교육: references/observability-plus.md

권장 사항 스키마 및 작성: references/recommendations.md

보고서 점수 및 심각도: references/scoring.md

확인 규칙: references/verification.md

고객 문체 가이드: references/voice.md