convert-site
오케스트레이터. 한 번의 인테이크 질문을 한 후, 중단 없이 다른 모든 스킬을 순서대로 실행하고, 사용자가 병합하는 풀 리퀘스트와 사용자가 실행하는 런북으로 마무리됩니다.
황금 규칙
- 인테이크 메시지 한 번, 이후 중단 없음. 모든 질문에는 기본값이 있습니다. 이후에 계정, 로그인 또는 가지고 있지 않은 토큰이 필요한 항목은 "사용자 필요" 목록(
state.needsYou및docs/LAUNCH.md섹션 A)에 추가되고 실행은 계속됩니다. - 라이브 사이트는 읽기 전용. 다음만이 이 사이트를 일정한 속도로 읽습니다: 캡처 스크립트,
shoot.mjs및styles.mjs(라이브에서),css-coverage.mjs,launch-audit --old-url및pre-launch --predecessor-url. 라이브 페이지 로드 시 분석은 차단되므로 방문이 집계되지 않습니다. 폼을 제출하거나, 로그인하거나, 갭을 채우기 위해 수동으로 페이지를 가져오지 마십시오. - 기본 빌드는 라이브와 동일하며, 결함도 포함. 콘텐츠는 캡처된 마크업에서 이동되며, 다시 입력하거나 정리하지 않습니다. 모든 특이사항은 "기본적으로 라이브를 재현"한다는 결정 행입니다. 강제된 차이는 예외이며, 개선 사항은 제안입니다(
PROPOSALS=on인 경우에만). - 모든 커밋에 게이트 적용, 절대 완화하지 않음.
baseline/을 편집하여 통과시키지 마십시오(baseline/scripts.json의keep플래그만 허용). 건너뛰기는 통과가 아닙니다. "Not covered"는 결코 통과가 아닙니다. main은 스캐폴드 커밋만 보유. 새 빈 저장소에서init-site는main에 하나의 커밋을 만듭니다. 이는 "main에 커밋하지 않음" 규칙의 예외입니다. PR에는 베이스가 필요합니다. 이후의 모든 작업은astro-rebuild브랜치, 하나의 PR에서 이루어집니다. 강제 푸시, 병합, DNS, 이전 호스트 또는 대시보드 설정을 절대 건드리지 마십시오.- 채팅이나 저장소에 비밀 정보 없음. 사용자에게 토큰을 붙여넣도록 요청하지 마십시오. 자격 증명은 환경 또는 CLI 자체 로그인에서 가져옵니다.
아래에서 사용되는 이름
KIT는 이 키트의 절대 경로입니다(skills/ 및 package.json이 있는 폴더).
LIVE는 라이브 오리진입니다.
SITE는 새 사이트 저장소의 절대 경로입니다(기본값 <current folder>/<slug>). 처음부터 캡처와 실행 상태가 여기에 기록되며, init-site.mjs가 이를 기준으로 스캐폴딩합니다. 모든 명령을 SITE에서 실행하십시오. 모든 스크립트는 --help를 출력하므로, 소스를 읽는 대신 그것을 실행하십시오. 새 셸의 모든 Node 명령은 source ~/.nvm/nvm.sh && nvm use 22.23.4로 시작합니다(또는 .nvmrc를 읽는 셸에서 실행).
0a단계: 실행 가능한 키트
스크립트는 키트의 node_modules에서 parse5, playwright 등을 가져옵니다. $KIT/package.json 또는 $KIT/node_modules가 없는 경우(스킬 폴더만 복사한 설치), 키트를 클론하고 설치한 다음 클론을 KIT로 사용하십시오:
git clone https://github.com/ethanplusai/astro-conversion-kit <folder>/astro-conversion-kit
npm install --prefix <folder>/astro-conversion-kit
0단계: 사전 점검 및 지문 인식 (인테이크 메시지 전)
node $KIT/skills/convert-site/scripts/preflight.mjs --json
node $KIT/skills/capture-site/scripts/fingerprint.mjs $LIVE
묻지 않고 직접 설치할 수 있는 누락된 항목을 설치하십시오: playwright.chromium이 false인 경우 npx playwright install chromium; vercel과 wrangler는 npx를 통해 실행합니다. 존재하지만 로그인되지 않은 CLI는 사용자가 로그인해야 합니다: 인테이크 메시지에 명령어 이름(gh auth login, npx vercel login, npx wrangler login)을 명시하고 스캐폴드에서 다시 확인하십시오.
experience는 말투를 설정하며, 수행하는 작업에는 영향을 미치지 않습니다. new: 각 단계가 무엇을 하고 왜 하는지에 대한 한 문장, 모든 용어는 한 번 설명, 설치는 조용히 수행. some: 단계당 한 줄. experienced: 명령과 결과만. Shopify 지문은 스토어입니다: 중단하고 그렇게 말하십시오.
1단계: 인테이크 (한 번의 메시지)
references/intake.md의 템플릿을 사전 점검과 지문이 찾은 내용으로 채워서 보내십시오: 모든 질문과 기본값, 그리고 "무엇이 누락되었고 어떤 일이 발생하는지" 목록. 사용자가 응답하지 않으면 기본값이 적용됩니다. 두 번째 질문 메시지를 절대 보내지 마십시오.
단계들
순서는 docs/process.md에 따릅니다. references/phases.md에는 모든 명령과 각 증명이 있습니다. 각 경계에서 node $KIT/skills/convert-site/scripts/state.mjs --dir $SITE phase <name>을 실행하십시오. 이전 단계의 증명이 유효할 때까지 다음 단계를 시작하지 마십시오. state.mjs 호출은 한 번에 하나씩 실행하며, &&로 연결하지 마십시오. 각 호출은 state.json을 다시 쓰며, 체인이 중간에 실패하면 단계가 맞지 않게 됩니다.
| # | 단계 (<name>) | 수행 작업 | 완료 조건 |
|---|---|---|---|
| 1 | intake | 사전 점검, 지문 인식, 한 번의 메시지 | 응답하거나 기본값 적용 |
| 2 | capture | capture-site -> $SITE/capture/, CSS 커버리지 | 모든 URL이 저장되거나 상태와 함께 기록됨; 노트 작성됨 |
| 3 | plan | 호스팅, URL 형식, 미디어 모드, 템플릿 결정; 상태에 결정 저장; .conversion/ 아래 초안 | 모든 템플릿, 개수, 특이사항 및 범위 외 기능에 대한 결정 존재 |
| 4 | scaffold | 저장소, 캡처 기반 init-site.mjs, 그 다음 docs/plan.md 및 docs/media-plan.json | 빈 상태로 빌드됨; main은 하나의 스캐폴드 커밋 보유 |
| 5 | baseline | npm run baseline (templates.json이 이미 존재함) | build-baseline.mjs --check가 0을 반환 |
| 6 | build | 레이아웃 및 공유 부분, 템플릿당 한 페이지, 템플릿 디자인 잠금, 그 다음 모든 페이지 | npm run build 통과; 템플릿 게이트가 경로별로 통과 |
| 7 | gates | 전체 게이트 | npm run verify가 0을 반환 |
| 8 | visual | 390, 768, 1440에서 모든 템플릿; 390 및 1440에서 모든 페이지 | 모든 쌍 통과 |
| 9 | components | 선택 사항, 기본적으로 꺼짐 (references/components-optional.md) | 게이트와 diff가 여전히 통과, 하나의 별도 커밋 |
| 10 | prelaunch | pre-launch, 스테이징 배포, verify-live, launch-audit, 한 번의 테스트 제출 | prelaunch-reconcile.mjs가 0을 반환 (references/phases.md §10); 감사 차단 항목 수정 또는 목록화 |
| 11 | suggestions | suggest-improvements with gates.json 및 review/ | docs/suggestions.md 및 "From the review" 섹션 |
| 12 | pr | 런북, 푸시, PR, 최종 보고서 | PR은 게이트 출력과 모든 "Not covered" 섹션을 인용 |
| 13 | launch | 사용자가 docs/LAUNCH.md에서 실행 | post-launch가 전환을 확인하고 30일 관찰 |
각 단계에서 사용하는 스킬과 자체 규칙: capture-site (2), parity-gates (5 to 7), visual-review (6, 8), pre-launch and launch-audit (10), suggest-improvements (11), post-launch (런북 내). 해당 단계 전에 각 스킬의 SKILL.md를 읽으십시오.
빌드, 한 문단으로
references/build-rules.md는 바인딩됩니다. 레이아웃과 공유 헤더, 내비게이션 및 푸터는 항상 컴포넌트입니다. 콘텐츠 블록은 스크립트에 의해 이동된 캡처된 마크업입니다. 미디어는 원래 경로에, 폰트는 자체 호스팅, CSS는 커버리지 정리(css-coverage.mjs 다음 css-prune.mjs), 절대 재작성하지 않습니다. 폼은 references/forms.md, 서드파티 스크립트는 references/third-party.md에 따릅니다. redirects.csv는 단일 리디렉션 소스입니다: 새 리디렉션은 source가 decision이고 note가 결정 ID를 명명하는 행이며, 그 다음 npm run redirects:build; 생성된 규칙을 수동으로 편집하지 마십시오. 템플릿당 하나의 커밋(feat: <template> template, 경로 범위 게이트가 통과하면), 전체 빌드에 대해 하나의 커밋을 사용하지 마십시오. 디자인은 모든 페이지로 롤아웃되기 전에 템플릿(시각 검토)에서 잠깁니다. 서브 에이전트를 사용하는 경우 템플릿 또는 게이트 수정당 하나의 구현자, 두 명이 하나의 파일을 작업하지 않음; 각 브리핑에는 절대 경로와 build-rules.md가 포함되며, 다음 단계 전에 커밋을 검토합니다.
결정, 예외, 제안
이 섹션이 규칙입니다. 참조는 여기를 링크합니다.
- 결정. 라이브 사이트가 특이하게 동작하는 모든 것, 그리고 적용하는 모든 기본값에 대해
state.mjs decision '{"topic":…,"choice":…,"default":…,"reason":…,"costIfWrong":…}'을 수행합니다. 이는 ID(d1,d2, …)를 출력합니다. 유일한 원장은docs/plan.md의 결정 테이블입니다: ID, 날짜, 주제, 선택, 기본값, 이유, 잘못되었을 때의 비용. 스캐폴드 전에 결정은.conversion/state.json에 있습니다. 계획 테이블은init-site직후에 이 결정으로부터 작성됩니다. 기본값은 항상 "라이브 재현"입니다. - 예외 (
exceptions.json,{ path, field, from, to, reason, approvedBy, date }): 정적 빌드가 피할 수 없는 차이; 게이트는 해당 경로의 해당 필드에 대해from대신to를 대체합니다.approvedBy는 사람이 PR에서 승인할 때까지"default, <decision id>"입니다. 폼과 스크립트는 예외 필드가 아닙니다(자체 플래그가 있음).routes는: 캡처가 읽을 수 없는 경로:from은 상태 문자열,to는"skip"또는 빌드된 대체 경로입니다. - 제안 (
proposals.json, 동일한 형태에id, 결정 ID, 및approvedBy: "proposed"추가; 여러 레코드가 하나의 ID를 공유할 수 있음): 개선 사항입니다. 코드는proposalOn(id)으로 전환합니다.PROPOSALS=on빌드에서만 제공되며,npm run verify:proposals로 게이트됩니다. 어떤 게이트도 측정하지 않는 변경(다시 작성된 hrefs)은field: "markup"이며, 비교되지 않습니다. 사람이 승인하면 레코드는exceptions.json으로 이동합니다(approvedBy업데이트).
호스팅
기본적으로 Vercel, 요청 시 Cloudflare Pages: references/hosting-vercel.md 및 references/hosting-cloudflare.md. 프로덕션 빌드가 PUBLIC_INDEXABLE=true를 설정하지 않는 한 모든 페이지는 noindex를 유지합니다. 미디어는 repo, store (media-upload.mjs) 또는 live-temporary(스테이징 전용, DNS 이동 전에 제거됨), media-plan.mjs가 결정합니다(references/phases.md §3).
계획 후 한 번의 메시지
3단계 후, 한 번의 짧은 상태 메시지(질문 아님)를 보내십시오: 플랫폼, 페이지 및 템플릿 수, 미디어 결정, 범위 외 기능 및 옵션, 기본적으로 취해진 결정, 그리고 현재까지의 사용자 필요 목록. 비대화형 실행(대답이 고정되어 있고 아무도 응답하지 않음)에서도 필수입니다: 진행 라인이 이를 대체하지 않습니다. 그런 다음 기다리지 않고 계속 진행하십시오.
풀 리퀘스트 (12단계)
astro-rebuild를 푸시하고(main은 스캐폴드에서 푸시됨), 그 다음 gh pr create --base main --head astro-rebuild --title "Astro rebuild of <host>" --body-file .conversion/pr-body.md를 실행하십시오. pre-launch가 placeholders.form-id(아직 폼 ID 없음)에서 실패하는 동안 --draft를 추가하고, 최종 보고서에서 이를 차단 항목으로 명명합니다. gh 로그인이 없으면 본문은 해당 파일에 남아 있고 "push and open the PR"이 사용자 필요 목록에 추가됩니다. 본문 순서:
## What changed 한 문단: 플랫폼, 변환된 내용, 호스트, 미디어 모드
## Counts 페이지, 템플릿, 리디렉션, 미디어 파일 및 크기, 폼, 유지/제거된 벤더
## Exceptions applied 모든 exceptions.json 항목: 경로, 필드, 이유, 결정 ID
## Proposals open 모든 proposals.json ID: 경로, 내용, 이유 (PROPOSALS=on에서만 제공)
## Decisions docs/plan.md 결정 테이블 및 모든 기본값이 아닌 선택
## Gate output `npm run verify` 출력, 그대로, 코드 블록, 모든 건너뛰기 라인 포함;
그 다음 prelaunch-reconcile이 수락한 모든 행, "reproduced from live (dN)" 형식
## Visual review `npm run review:check` 출력, 모든 docs/visual-overrides.json 항목
(경로, ID, 임계값, 이유), 모든 bannerClosed 및 heightMismatch; 연락처 시트는
review/index.html 및 review/all.html (로컬; npm run review:sheet)
## Staging 스테이징 URL, verify-live 결과, launch-audit 차단 항목 및 상태
## Suggestions 카테고리별 개수, 중간 및 높은 위험 항목, 적용 가능한 ID
## Not covered pre-launch 및 launch-audit의 "Not covered" 섹션, 그대로, 각각
자체 제목 아래; 그 다음 capture-site, visual-review 및 suggestions
## Waiting on you 모든 state.needsYou 항목, 런북 순서
최종 보고서 (사용자에게)
PR 링크로 시작하고(초안인 경우 "draft: waiting on the form id" 추가), 그 다음: 변환된 내용(개수), 게이트 및 시각 검토를 각각 한 줄로, 스테이징 URL, Waiting on you 아래의 사용자 필요 목록(state.mjs --dir $SITE get needsYou에서 읽음, 각 항목은 정확한 명령 또는 클릭, 런북 순서), 그 다음 모든 "Not covered" 섹션을 그대로. "PR open, waiting on your merge"라고 말하고, "done" 또는 "live"는 사용하지 마십시오. 시작한 리뷰 서버를 중지하고(npm run review:serve -- --stop, 미리보기를 사용한 경우 npx astro preview stop), 그 다음 중지하십시오.
재개
새 세션에서 node $KIT/skills/convert-site/scripts/state.mjs --dir $SITE get을 읽고 phase에서 계속하십시오: 먼저 해당 단계의 증명을 다시 실행하고, 유효하면 다음 단계를 시작하십시오. 캡처는 --resume으로 재개됩니다. 인테이크를 절대 반복하지 마십시오. 나중에 제안을 적용하는 것은 convert-site --apply <id> (references/apply-suggestion.md), 실행 자체의 일부가 아닙니다.
참조
| 파일 | 내용 |
|---|---|
references/intake.md | 한 번의 메시지: 질문, 기본값, 누락된 항목 및 발생 상황 |
references/phases.md | 모든 단계: 정확한 명령, 완료 증명, 기록할 내용 |
references/build-rules.md | 레이아웃, 콘텐츠, CSS, 미디어, 폰트, 지연 로딩 이미지 및 리디렉션 구축 방법 |
references/forms.md | Formspree 연결, 필드 이름, 허니팟, 감사 페이지, 폼 ID, 한 번의 테스트 제출 |
references/third-party.md | baseline/scripts.json 및 docs/third-party.md의 keep 허용 목록 |
references/hosting-vercel.md | 프로젝트, 공개 noindex 스테이징, 인덱싱, Blob 미디어, 옵트인 보호 |
references/hosting-cloudflare.md | Pages 프로젝트, _redirects, _headers, R2 미디어 함수, 쿼리 리디렉션 |
references/runbook.md | docs/LAUNCH.md: A 사용자 필요, B 마감, C 론치일, D 30일 관찰 |
references/components-optional.md | 선택적 컴포넌트 패스 |
references/apply-suggestion.md | --apply <id>: 제안 레코드, 브랜치 커밋, 게이트, 시트 |