경험 현대화 에이전트에 대한 안내 메시지 표시 prompting-guide

마이그레이션은 7단계 워크플로를 따릅니다.

1. 에이전트가 소스 페이지를 스크랩합니다.
2. 섹션 구조를 식별합니다.
3. 작성 분석을 수행합니다.
4. 콘텐츠를 블록 변형에 매핑합니다.
5. Markdown을 생성합니다.
6. 가져오기 인프라를 생성합니다.
7. 결과를 미리 봅니다.

에이전트는 두 수준 계층 구조를 사용하여 페이지를 분석합니다.

• 먼저 단면 경계(배경 변경, 간격 이동)를 식별합니다
• 그런 다음 각 섹션 내의 콘텐츠 시퀀스를 식별합니다.

작성 분석은 David의 모델을 따릅니다.

• 각 콘텐츠 시퀀스에 대해 먼저 "작성자가 일반 입력을 통해 만들 수 있습니까?"를 확인합니다.
• 기본 콘텐츠(제목, 단락, 목록, 인라인 이미지)가 블록보다 선호됩니다.

에이전트는 새 블록을 생성하기 전에 저장소의 블록 라이브러리에서 기존 블록을 재사용하려고 합니다.

• 콘텐츠를 기존 블록에 매핑할 수 없는 경우 새 블록 변형이 만들어집니다.
• 변경을 묻는 메시지를 표시하거나, 새 변형을 요청하거나, 매핑을 대화식으로 조정할 수 있습니다.

블록 변형은 메타데이터로 추적됩니다.

• 여러 페이지를 마이그레이션할 때 에이전트는 기존 사용자 지정 변형을 먼저 로드하고 스타일이 일치할 때(목적, 색상, 타이포그래피, 간격, 레이아웃에 따른 70% 유사성 임계값) 다시 사용합니다.

머리글, 탐색 및 바닥글은 페이지 마이그레이션에서 제외됩니다. 이러한 작업은 전담 기술에 의해 처리됩니다.

각 마이그레이션은 향후 대량 가져오기를 위해 가져오기 인프라(페이지 템플릿, 블록 작성기, 변환기)를 만듭니다.

• 여기에는 페이지 템플릿(섹션 구조), 변환기(사이트 전체 DOM 정리) 및 구문(블록별 HTML 대 테이블 변환)이 포함됩니다.

• 처음부터 템플릿을 추론하는 것은 아닙니다.

• 단일 실행에서 템플릿 혼합은 지원되지 않습니다.

이 프롬프트는 일반적으로 페이지 마이그레이션의 첫 번째 단계로 자동으로 호출됩니다.

CSS를 통해 숨겨진 콘텐츠는 DOM에 있는 경우에도 캡처됩니다.

Headless Chromium에서 페이지를 스크롤하고 스크립트가 실행되도록 하여 지연 로드된 이미지와 클라이언트측 렌더링된 콘텐츠가 처리됩니다.

WebP/AVIF/SVG 이미지는 호환성을 위해 PNG로 변환됩니다.

메타데이터는 제목, 설명, Open Graph 태그, JSON-LD 구조화된 데이터, 표준 URL을 포함하여 추출됩니다.

DOM의 이미지가 수정되었습니다.

• background-image가 img로 변환됩니다.
• 그림 요소의 래핑이 해제되었습니다.
• srcset가 src로 확인됨
• 상대 URL은 절대 URL로 변환됩니다
• 인라인 SVG이에 img 파일로 변환됩니다.

정리된 문서 경로가 생성됩니다(.html 확장명이 없는 소문자).

다음과 같은 출력이 생성됩니다.

• screenshot.png
• cleaned.html(스크립트/스타일 없음)
• metadata.json
• 로컬 복사본이 있는 images/ 폴더

스크린샷 차원에 대해 질문하고 컨텐츠 추출을 위해 특정 디바이스 크기(모바일, 데스크탑)를 요청할 수 있습니다.

여러 중단점에서 컨텐츠를 추출하면 처리 시간이 늘어납니다.

설계 마이그레이션은 다음 두 가지 단계로 이루어집니다.

1. 1단계(사이트 전체)는 styles/styles.css에 다음을 추출합니다.

   • 전역 색상 팔레트 및 강조 색상
   • 타이포그래피 시스템(글꼴, 크기, 무게)
   • 간격 시스템(패딩, 여백, 간격)
   • 섹션 배경(밝은 색상, 어두운 색상)
   • 기본 구성 요소 스타일(단추, 링크, 이미지)
   • 출력 대상

2. 2단계는 개별 블록 스타일을 마이그레이션하고 /blocks/{name}/{name}.css에서 블록별 CSS를 만듭니다.

블록 스타일링(2단계)을 사용하려면 먼저 사이트 전체 설계(1단계)를 완료해야 합니다.

• 전역 디자인 시스템에서는 참조를 차단하는 CSS 사용자 지정 속성을 제공합니다.

예상 시간:

• 1단계: 5-10분
• 2단계: 10-15분

모호한 요청은 기본적으로 마이그레이션을 완료합니다(두 단계 모두).

블록 비판은 마이그레이션된 블록을 원래 소스와 비교하고 85%의 시각적 유사성이 달성되거나 3회의 반복이 완료될 때까지 CSS 수정 사항을 반복적으로 적용합니다.

이 스킬을 사용하려면 먼저 페이지 마이그레이션에 의해 블록을 만들어야 합니다.

블록 비판은 6단계 워크플로를 따릅니다.

1. XPath 선택기를 사용하여 소스 페이지에서 원본 블록을 캡처합니다.
2. 비평 세션을 초기화합니다.
3. 원본 블록(스크린샷, 스타일, HTML)을 검사합니다.
4. 마이그레이션된 블록을 검사합니다.
5. 요소를 비교하고 CSS 수정 사항을 포함한 유사성 점수를 생성합니다.
6. 85% 목표에 도달할 때까지 수정을 적용하고 재검사합니다.

각 반복에는 모든 차이점이 있는 전체 비평 보고서가 표시되고, 모든 CSS 수정 사항(시각적 영향을 기준으로 우선 순위가 지정됨)을 적용하고, 미리 보기에서 확인하고, 다시 검사하고, 개선 지표를 표시합니다.

디자인 마이그레이션이 완료된 후 차단 기준을 사용하십시오.

페이지 비판은 원본 페이지와 마이그레이션된 페이지 간의 전체 페이지 시각적 비교를 수행하여 85% 유사성 대상 또는 세 번의 반복이 완료될 때까지 반복합니다.

페이지 비판에는 5단계 워크플로가 있습니다.

1. 비평 세션을 초기화합니다.
2. 원본 페이지의 모든 요소를 검사합니다.
3. 마이그레이션된 페이지의 모든 요소를 검사합니다.
4. 우선 순위가 지정된 CSS 수정 사항과 유사성 점수를 비교하고 생성합니다.
5. 85% 목표에 도달할 때까지 수정을 적용하고 재검사합니다.

페이지 비판에는 소스 페이지 URL과 마이그레이션된 경로(예:"/about")가 입력으로 필요합니다.

전체 페이지 충실도를 확인하거나 여러 블록을 동시에 확인할 때 페이지 평론을 사용하십시오.

특정 구성 요소에 대한 집중 유효성 검사에 블록 비평을 사용합니다.

다음 워크플로우를 권장합니다.

1. 페이지 마이그레이션.
2. 디자인을 적용합니다.
3. 주요 블록에 대한 블록 비평 실행
4. 전체 유효성 검사를 위해 앱 페이지 비평 을 실행합니다.

이 기술은 전체 페이지나 전체 그림 파일이 아니라 한 번에 한 블록씩 마이그레이션합니다.

최상의 결과를 얻으려면:

• Figure에서 마이그레이션할 특정 블록을 선택하고 해당 링크(node-id 포함) 또는 이름을 복사합니다.
• 정확한 블록을 대상으로 지정하려면 URL에 node-id 매개 변수를 제공하십시오.

이 스킬을 실행하면 호스팅 환경에서 다음 단계가 자동으로 수행됩니다.

1. 블록 구조 검색 - 에이전트가 Figma 노드를 읽어 레이어 및 구성 요소를 이해합니다.
2. 전역 스타일 추출 — 에이전트는 색상, 타이포그래피 및 간격을 CSS 사용자 지정 속성(디자인 토큰)으로 styles/styles.css에 가져옵니다.
3. 블록별 스타일 만들기 - 에이전트는 마이그레이션되는 블록과 관련된 추가 CSS 사용자 지정 속성을 만듭니다.
4. 기존 블록에 매핑 — 에이전트는 프로젝트의 블록 라이브러리에서 가장 일치하는 블록을 식별하고 사용자 지정 변형을 만듭니다.
5. CSS 생성 — 에이전트는 추출된 CSS 사용자 지정 속성을 참조하는 스타일을 작성하여 디자인 일관성을 보장합니다.
6. 자산 다운로드 — 에이전트는 Figma의 이미지와 아이콘을 호스팅된 환경의 작업 영역에 저장합니다.
7. Edge Delivery Services 콘텐츠 생성 — 에이전트는 EDS 블록 구조 다음에 Markdown 파일을 만듭니다
8. 출력 유효성 검사 — 에이전트는 결과를 미리 보고 원래 Fi그마 디자인과 시각적으로 비교합니다.

스킬은 먼저 메타데이터(1단계)를 읽어 구조를 파악한 후 세부 설계 맥락을 추출한다(2-5단계).

• 이 단계별 접근 방식은 대형 또는 복잡한 Figma 파일 관련 문제를 방지합니다.

이 스킬은 스타일을 우선으로 하는 방식을 택합니다.

• 모든 스타일은 CSS를 작성하기 전에 CSS 사용자 지정 속성(디자인 토큰)으로 추출됩니다.
• 이렇게 하면 마이그레이션된 블록이 설계 시스템과 일관성을 유지할 수 있습니다.

프롬프트에 Figma URL(fileKey 및 선택적 node-id 포함) 또는 Figma 파일 키가 입력으로 직접 필요합니다.

Edge Delivery Services 탐색은 다음 세 개의 섹션 구조를 적용합니다(header.js에 의해 적용됨).

1. 브랜드(섹션 1): 로고 및 기본 브랜딩 링크
2. 섹션(섹션 2): 드롭다운 옵션이 있는 기본 탐색 메뉴
3. 도구(섹션 3): 유틸리티 링크(구독, 로그인, 장바구니)

탐색 콘텐츠가 루트 디렉터리의 nav.md에 있습니다.

섹션은 (---) 표시자로 구분됩니다.

중첩된 목록이 있는 굵은 항목(**Text**)은 드롭다운을 만듭니다.

문서 작성의 자동 줄바꿈 동작으로 인해 탐색의 링크가 단추로 렌더링될 수 있습니다.

• 머리글 블록에는 탐색 링크에서 단추 클래스를 제거하는 코드가 포함되어 있습니다.

에이전트는 모든 Edge Delivery Services 개발의 필수 프로세스인 CDD(Content-Driven Development)를 따릅니다.

• 코드를 작성하기 전에 콘텐츠 모델에 대해 질문하고 콘텐츠를 테스트합니다.

CDD 철학은 개발자가 필요로 하기 전에 작성자가 와야 한다는 것입니다.

• 콘텐츠 모델은 보다 복잡한 장식 코드를 의미하더라도 작성자는 직관적이어야 합니다.

테스트 콘텐츠를 먼저 만들면 다음을 제공합니다.

• 즉각적인 테스트 기능
• PSI 검사에 대한 PR 유효성 검사 링크
• 작성자를 위한 라이브 설명서
• 코드 우선 접근 방식이 놓치는 경계 사례 발견

에이전트는 구현하기 전에 블록 컬렉션 및 블록 파티에서 유사한 블록을 검색하여 패턴과 재사용 가능한 코드를 찾습니다.

사소한 CSS 전용 변경에 대해서만 CDD를 건너뜁니다(하지만 유효성 검사를 위한 테스트 콘텐츠를 식별함).

Edge Delivery Services에는 네 가지 표준 모델 유형이 있습니다.

• 독립 실행형: 고유한 시각적/서사적 요소(hero, blockquote)
  • 블록 콘텐츠가 있는 단일 테이블
• 컬렉션: 반정형 콘텐츠 반복(카드, 회전 메뉴)
  • 반복되는 행 패턴이 있는 표
• 구성: 구성 컨트롤이 표시되는 API 기반 또는 동적 콘텐츠(블로그 목록, 검색 결과)
  • 키-값 구성 행이 있는 테이블.
• 자동 차단: 작성자가 섹션/기본 콘텐츠로 만든 다음 변형되는 복잡한 구조(탭, YouTube 포함)

행당 4개의 셀로 제한됩니다.

• 관련 요소를 셀로 그룹화합니다.

스타일 차이점을 보려면 구성 셀보다 블록 변형을 선호합니다.

Postel의 법칙을 따르세요: 입력 구조에 대해 유연하게 대하세요.

• 히어로 블록은 콘텐츠가 하나의 셀에 있든, 두 개의 셀로 분할되든, 별도의 행에 있든 작동해야 합니다.

이 스킬은 일반적으로 블록 생성 중에 콘텐츠 기반 개발에 의해 자동으로 호출됩니다.

블록 컬렉션은(는) Adobe에서 유지 관리되며 모범 사례, 우수한 콘텐츠 모델링, 고성능 및 접근성을 위해 검사됩니다.

• 일반적으로 필요한 블록으로 제한됩니다. 여기에서 시작하십시오.

차단 파티는 커뮤니티 기반이며 실험적인 접근 방식을 포함하여 더 다양한 기능을 제공합니다.

• 여기에는 사이드 킥 플러그인, 빌드 도구(webpack, vite, sass), 통합도 포함됩니다.
• 블록 컬렉션에 필요한 항목이 없을 때 사용합니다.

검색할 때 대체 이름 고려

• FAQ = 아코디언
• Gallery = 회전/슬라이드 쇼
• 탐색 = 메뉴/헤더

차단 당사자는 승인된/조정된 항목만 반환합니다.

테스트는 가치가 비용을 초과할 때 테스트를 만들고 유지 관리하는 "가치 대 비용" 철학을 따릅니다.

• Keeper 테스트(단위 테스트)는 논리를 많이 사용하는 유틸리티, 데이터 처리, API 통합용입니다. 이러한 기능은 빠르고 관리하기 쉬우며 재사용된 코드에서 회귀를 포착합니다.
• Throwaway 테스트(브라우저 테스트)는 DOM 변환 및 시각적 유효성 검사에 사용됩니다. 를 사용하여 구현의 유효성을 검사하고, PR 검토를 위해 스크린샷을 캡처한 다음, 취소합니다.

Throwaway 테스트는 test/tmp/에서 진행되고 내용은 drafts/tmp/에서 테스트됩니다(두 가지 모두 gignored).

PR을 열기 전에 다음을 확인하십시오.

• 기존 테스트 통과
• 단위 테스트는 새 논리에 대해 작성됩니다.
• 브라우저 유효성 확인이 완료되었습니다.
• 모든 변형을 테스트합니다.
• 반응형 동작이 확인됨
• 가공 패스 린팅

일반적인 문제에는 알려진 패턴이 있습니다.

• "about:error"​을(를) 보여 주는 이미지: 일반적으로 블록 JS에 createOptimizedPicture 호출이 없거나 DOM을 재구성하기 전에 호출됩니다.
• 블록이 렌더링되지 않음: Markdown에서 블록 이름 형식을 확인하고 .js에서 블록에 .css 및 blocks/ 파일이 모두 있는지 확인하십시오.
• CSS가 로드되지 않음: 파일 경로를 확인하고, CSS 파일이 있는지 확인하고, 브라우저에서 네트워크 탭을 확인하십시오.
• 변경 내용이 표시되지 않음: 코드 동기화에 3~5초 정도 소요됩니다. 하드 새로 고침(Ctrl+Shift+R) 시도

에이전트는 각 계층을 체계적으로 확인합니다.

1. Source 파일
2. 렌더링된 출력
3. 블록 코드
4. 브라우저 콘솔

에이전트가 http://localhost:3000에서 로컬 미리 보기를 확인할 수 있습니다.