Astro SEO

Astro SEO은(는) 무엇을 하나요?

Astro SEO: 완벽 가이드에 설명된 전체 스택을 기준으로 Astro 사이트의 SEO 설정을 감사하고 개선합니다. 이 스킬은 기술 기초, 구조화된 데이터, 콘텐츠, 사이트 구조, 성능, 사이트맵 및 색인, 에이전트 검색, 리디렉션, 분석의 9개 영역을 다루며, 누락되거나 취약한 부분에 대한 즉시 사용 가능한 코드를 생성합니다.

이 스킬의 중추는 @jdevalk/astro-seo-graph입니다. 대부분의 수정 사항이 이 패키지를 통해 제공됩니다. 프로젝트에서 아직 사용하지 않는 경우, 설치하는 것이 첫 번째 권장 사항입니다.

코드 레시피는 AGENTS.md에 있습니다 — 특정 수정 사항을 구현해야 할 때 이를 읽으세요. 이 파일에는 워크플로우와 감사 체크리스트가 포함되어 있습니다.

워크플로우

1. 프로젝트 감지 — Astro 사이트인지 확인하고 구조를 파악합니다.
2. 감사 — 9개 카테고리를 각각 평가하고 실행 가능한 결과를 생성합니다.
3. 개선 — 격차를 해소하기 위해 파일을 생성하거나 수정합니다. 레시피는 AGENTS.md에 있습니다.
4. 메타데이터 검증 — 스킬이 생성한 모든 짧은 문자열(제목, 설명, 스키마 description 필드, FAQ 답변, 프론트매터 발췌문)에 대해 metadata-check를 실행합니다.
5. 확인 — 빌드를 실행하고, 유효성 검사가 통과하는지 확인하며, 파일 작업이 아닌 작업(Search Console, Bing Webmaster Tools, IndexNow 키 확인)에 대해 사용자에게 상기시킵니다.

---

0단계: 프로젝트 감지

감사 전 기본 사항을 확인합니다:

• astro.config.mjs / astro.config.ts 파일이 존재합니다.
• package.json에 astro가 의존성으로 있습니다.
• site:가 astro.config에 설정되어 있어야 합니다 — 표준 URL, 사이트맵, OG 이미지 URL이 모두 이 값에서 파생됩니다. 누락되었거나, 비어 있거나, http://localhost로 설정된 경우, 다른 모든 것보다 먼저 차단 문제로 표시하세요. 이것은 가장 흔한 잘못된 구성입니다.
• src/content/ (또는 레거시 src/pages/ 마크다운)의 콘텐츠 컬렉션.
• 배포 대상 — package.json, vercel.json, netlify.toml, wrangler.toml 또는 public/_headers를 읽어 호스트를 확인합니다. 이는 2단계에서 리디렉션 및 헤더 구문을 결정합니다.
• @jdevalk/astro-seo-graph가 이미 설치되었습니까? 그렇다면 버전과 어떤 기능이 연결되어 있는지 기록하십시오(<Seo, seoGraph(, createSchemaEndpoint, createSchemaMap, FuzzyRedirect, createIndexNowKeyRoute, createMarkdownEndpoint, createApiCatalog, gitLastmod를 grep). 설치된 버전을 npm의 최신 버전과 확인하십시오(npm view @jdevalk/astro-seo-graph version). 프로젝트가 뒤쳐져 있다면, 기능 격차를 감사하기 전에 2단계에서 업그레이드를 권장하십시오. 패키지는 정기적으로 새로운 기본값과 수정 사항을 제공하며, 오래된 버전은 감사 결과의 그럴듯한 원인이 될 수 있습니다. 2단계는 이에 따라 분기합니다.
• 사이트가 다국어입니까? astro.config에서 i18n을 확인하거나 src/content/ 아래에 여러 로케일 디렉토리가 있는지 확인하십시오. 그렇다면 hreflang이 중요합니다. 아니라면 건너뜁니다.

감지할 수 없는 것만 물어보십시오. 사이트가 무엇에 관한 것인지 사용자에게 묻지 마십시오 — astro.config.mjs와 홈페이지 콘텐츠를 읽으십시오.

---

1단계: 감사

각 카테고리를 10점 만점으로 평가합니다. 각각에 대해 실제 코드나 구성을 인용하는 2-4개의 구체적인 결과를 제공합니다. 각 카테고리 내에서 검사는 계층화됩니다:

• 필수 — 출시 차단 요소입니다. 여기서 실패하면 눈에 띄는 SEO 회귀가 발생합니다.
• 권장 — 표준 관행입니다. 건너뛰면 도달 범위가 줄어듭니다.
• 좋은 기능 — 미래 지향적이거나 상황에 따라 다릅니다. 모든 사이트에 기본은 아니지만 유용합니다.

사용자가 전체 처리를 요청하지 않는 한 소규모 개인 블로그의 경우 좋은 기능 검사를 건너뜁니다.

1. <Seo> 컴포넌트 및 head 메타데이터 (/10)

• 필수 — 모든 head 메타데이터를 위한 단일 컴포넌트(레이아웃 전체에 분산되지 않음).
• 필수 — astro.config의 site:가 프로덕션 출처로 설정되어야 합니다.
• 필수 — 추적 매개변수가 제거된 site 구성에서 파생된 표준 URL.
• 필수 — noindex가 true인 경우 표준 URL 생략(Google 권장 사항에 따름).
• 필수 — 누락된 SEO 필드에 대한 폴백 체인: seo.title → title → siteName; seo.description → excerpt → 첫 번째 문단. 제목이나 설명이 비어 있는 페이지는 폴백 체인이 끊어진 가장 흔한 증상입니다.
• 권장 — robots 메타에 max-snippet:-1, max-image-preview:large, max-video-preview:-1이 포함됩니다.
• 권장 — Twitter 태그가 Open Graph와 중복될 때 억제됩니다(Twitter는 자동으로 폴백됨).
• 권장 — 다국어 사이트에 hreflang 대체 항목이 있어야 합니다. 단일 언어인 경우 건너뜁니다.
• 좋은 기능 — 수동으로 구현하지 않고 @jdevalk/astro-seo-graph의 <Seo> 컴포넌트를 사용합니다. (위의 모든 사항을 다루는 수동 구현도 괜찮습니다. 이 스킬은 패키지가 기본적으로 폴백 체인과 robots 규칙을 처리하기 때문에 패키지 사용을 권장합니다.)

2. 구조화된 데이터 / JSON-LD 그래프 (/10)

• 단일 평면 Article 객체 또는 여러 엔터티가 연결된 @graph입니까?
• 엔터티가 @id 참조로 연결되었습니까?
• WebSite, Blog/WebPage, Person/Organization, BlogPosting/Article, BreadcrumbList, ImageObject가 모두 관련 위치에 있습니까?
• 신뢰 신호: publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction?
• 리치 결과 테스트 및 ClassySchema에서 유효성 검사가 통과됩니까?

3. 콘텐츠 컬렉션 및 SEO 스키마 (/10)

• Zod 스키마로 정의된 콘텐츠 컬렉션?
• @jdevalk/astro-seo-graph의 seoSchema가 제목(5-120) 및 설명(15-160) 길이를 강제 적용합니까?
• 필수 필드(publishDate, title, excerpt)가 빌드 시간에 강제 적용됩니까?
• 마크다운이 제거된 articleBody가 스키마 엔드포인트에 노출됩니까(최대 10K 자)?

4. 오픈 그래프 이미지 (/10)

• 모든 페이지에 OG 이미지가 있습니까, 아니면 많이 누락되었습니까?
• 1200×675 (Google Discover 최소 1200px 너비, 16:9 비율)?
• satori + sharp를 통해 빌드 시 생성됩니까, 아니면 수동입니까?
• JPEG (소셜 플랫폼은 WebP/AVIF를 안정적으로 지원하지 않음)?
• 경로가 슬러그에서 자동으로 OG URL을 파생시킵니까?
• 렌더링된 HTML의 모든 <img>에 alt 속성이 있습니까(또는 장식용 이미지의 경우 alt="" / role="presentation")? ≥ 1.1.0에서 seoGraph()의 validateImageAlt가 빌드 시 이를 포착합니다.

5. 사이트맵 및 색인 (/10)

• 필수 — @astrojs/sitemap이 설치되고 사이트맵 인덱스에 접근 가능해야 합니다.
• 필수 — robots.txt가 사이트맵 인덱스를 참조해야 합니다.
• 필수 — RSS 피드가 존재하고(@astrojs/rss), <link rel="alternate" type="application/rss+xml">를 통해 알려야 하며, 전체 게시물 콘텐츠를 포함해야 합니다(잘린 발췌문이 아님).
• 권장 — chunks 옵션을 통해 컬렉션별로 분할(sitemap-posts-0.xml 등) — GSC에서 인덱싱을 디버깅하기 훨씬 쉽습니다.
• 권장 — lastmod가 프론트매터 날짜나 CI 파일 타임스탬프가 아닌 git 커밋 타임스탬프로 채워집니다. @jdevalk/astro-seo-graph ≥ 1.4.0은 이를 위해 gitLastmod(filePath, { excludeCommits, depth })를 내보냅니다. 이 파일을 건드린 가장 최근의 제외되지 않은 커밋의 커미터 날짜를 반환하거나, git을 사용할 수 없으면 null을 반환합니다. 사이트맵 serialize 콜백에 연결하십시오. 코드베이스에 수동으로 구현된 execSync('git log ...') 헬퍼가 있다면 패키지 내보내기로 교체하십시오. 내보내기는 대량 커밋 제외(가져오기, 재포맷)를 처리하는 반면, 단순한 -1 조회는 그렇지 않습니다.
• 권장 — IndexNow가 통합되어 각 빌드 시 제출하며, /[key].txt에 키 확인 경로가 있어야 합니다. ≥ 1.0.1은 기본적으로 제출에서 /404를 제외합니다. 프로덕션 호스트에서 제출을 게이트하십시오(예: process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main', VERCEL_ENV === 'production', CONTEXT === 'production'). 조건 없는 제출은 모든 로컬 npm run build 및 미리 보기 배포 시 프로덕션 호스트가 아직 제공하지 않은 URL로 엔드포인트를 핑(ping)하여 키가 유효하지 않음(403)으로 표시되고 강제로 순환되도록 합니다.

6. 에이전트 검색 (/10)

• 권장 — 코퍼스 전체의 JSON-LD를 노출하는 스키마 엔드포인트(/schema/*.json).
• 권장 — 모든 엔드포인트를 나열하는 스키마 맵(/schemamap.xml), robots.txt에 Schemamap: 지시문이 있어야 합니다.
• 권장 — LLM 소비자를 위해 페이지(제목 + 설명)를 나열하는 사이트 루트의 llms.txt. @jdevalk/astro-seo-graph ≥ 0.9.0은 llmsTxt 통합 옵션을 통해 이를 생성합니다.
• 권장 — AI 에이전트가 HTML 구문 분석 없이 소비할 수 있도록 YAML 프론트매터가 포함된 깨끗한 마크다운을 제공하는 마크다운 대체 URL(/blog/post.md가 /blog/post/ 옆에 있음). @jdevalk/astro-seo-graph ≥ 1.2.0은 경로를 위한 createMarkdownEndpoint와 모든 페이지에 <link rel="alternate" type="text/markdown">를 내보내는 markdownAlternate: true 통합 옵션을 제공합니다. ≥ 1.3.0은 빌드 후 검증을 추가합니다. 통합이 빌드 출력을 살펴보고 디스크에 없는 .md 대상에 대한 링크를 제거합니다(발생당 warn). 따라서 잘못 구성된 엔드포인트는 배송된 404 대신 빌드 경고로 표시됩니다. SSR 없이 Accept: text/markdown에 대한 콘텐츠 협상을 위해 Cloudflare Transform Rule(URL 재작성 via wildcard_replace, Vary: Accept 헤더 없음 — CF는 사용자 정의 Vary 값을 제거함)과 함께 사용하십시오.
• 권장 — RFC 9727에 따른 /.well-known/api-catalog의 API 카탈로그. @jdevalk/astro-seo-graph ≥ 1.4.0은 createApiCatalog를 제공하며, 이는 스키마 엔드포인트를 https://schema.org/<Type> URL로 자동 유형 지정하고 siteUrl에 대해 경로를 절대 경로로 만듭니다. 스키마 엔드포인트, 스키마 맵 및 모든 사이트별 API(/ask, /feed.xml 등)를 나열하십시오. RFC가 확정되었으므로 형식이 안정적입니다. 채택은 초기 단계이지만 비용은 하나의 경로 파일입니다.
• 권장 — robots.txt의 콘텐츠 신호 지시문(예: Content-Signal: ai-train=yes, search=yes, ai-input=yes). 크롤 액세스와 독립적으로 AI 훈련, 검색 근거 및 AI 입력 사용에 대한 기본 설정을 선언합니다. 사양은 IETF 초안이며 채택은 초기 단계이지만 모든 사이트가 이미 가지고 있는 파일에 한 줄만 추가하면 됩니다.
• 권장 — 검색 파일(사이트맵, llms.txt, api-catalog, schemamap 및 사이트가 게시하는 모든 MCP/A2A 카드)을 가리키는 /*의 Link 헤더. 응답 헤더를 읽는 에이전트는 HTML을 구문 분석하지 않고 이를 찾습니다. Cloudflare Pages/Netlify에서는 public/_headers이고, Vercel에서는 vercel.json입니다.
• 좋은 기능 — /.well-known/mcp/server-card.json(SEP-1649)의 MCP 서버 카드 및/또는 /.well-known/agent-card.json(A2A 프로토콜)의 A2A 에이전트 카드. 사이트가 실제로 MCP 서버 또는 A2A 에이전트를 노출하는 경우에만 관련됩니다. 둘 다 엔드포인트, 기능 및 기술을 선언하는 정적 JSON 파일입니다. 그렇지 않으면 건너뜁니다.
• 좋은 기능 — 대화형 엔드포인트를 가리키는 <link rel="nlweb">. NLWeb은 초기 단계입니다. 태그는 한 줄이며 가질 가치가 있지만 2026년에는 점수 차단 요소가 아닙니다.
• 좋은 기능 — /.well-known/ai-catalog.json의 ARD(Agentic Resource Discovery) 카탈로그로, 도메인이 제공하는 것(MCP 서버, A2A 에이전트, OKF 번들, 사이트별 API)을 나열합니다. v0.9 초안이므로 선택 사항입니다. 그러나 MCP/A2A 카드와 OKF 번들이 활용되는 검색 계층입니다. 두 가지 주의 사항: 기본 사양(Agent-Card/ai-catalog)은 미디어 유형 필드 이름을 mediaType으로 지정하는 반면 ARD 계층(ards-project/ard-spec)은 type으로 지정합니다. 항목이 두 판독 중 하나에서 유효성을 검사할 수 있도록 동일한 값으로 두 키를 모두 내보내십시오(두 사양 모두 소비자가 알 수 없는 키를 무시하도록 요구함). ARD는 또한 항목당 선택적 representativeQueries 샘플 프롬프트 배열을 추가합니다.
• 좋은 기능 — OKF(Open Knowledge Format) 번들: 페이지당 하나씩(경로가 표준 URL을 미러링함) 유형이 지정된 마크다운 개념 파일 트리로, 단일 .tar.gz로 패키징되고 그 사이에 인덱스 파일이 있습니다. 제공 및 검색은 OKF의 명시적 비목표입니다. 이것이 ARD 카탈로그 항목의 용도입니다. v0.9 초안, 선택 사항. 등록된 미디어 유형이 아직 없으므로 임시 문자열은 application/okf-bundle+gzip입니다(knowledge-catalog#111 및 ard-spec#27에서 추적됨). 임시로 표시하십시오. 변경될 수 있습니다. 수동으로 유지 관리하는 복사본보다는 기존 콘텐츠 파이프라인의 또 다른 출력으로 생성하는 것이 가장 좋습니다.

7. 성능 (/10)

• 기본적으로 정적 출력(필요하지 않은 페이지에 SSR 없음)?
• 섬(island)이 필요하지 않는 한 제로 클라이언트 측 JS?
• 모든 콘텐츠 이미지에 Astro <Image> 컴포넌트 사용(반응형 srcset, WebP, 지연 로딩, 비동기)?
• 기본 웹 폰트가 woff2로 사전 로드됩니까?
• <ClientRouter />에 defaultStrategy: 'viewport'가 프리페치를 위해 사용됩니까?
• 해시된 자산이 /_astro/ 아래에서 Cache-Control: public, max-age=31536000, immutable을 제공합니까?
• 캐시 키에서 UTM 매개변수를 제거하는 No-Vary-Search 응답 헤더가 있습니까?

8. 리디렉션 및 오류 처리 (/10)

• 존재하고 이동한 모든 URL에 대해 public/_redirects(또는 이에 상응하는 것)가 유지 관리됩니까?
• 영구 이동에 301이 아닌 302를 사용합니까?
• @jdevalk/astro-seo-graph의 FuzzyRedirect 컴포넌트가 404 페이지에 연결되었습니까?
• 404 페이지 자체가 200이 아닌 404 상태를 반환합니까?

9. 빌드 시간 검증 및 콘텐츠 품질 (/10)

• 필수 — 각 빌드에서 validateH1 및 validateUniqueMetadata가 활성화된 seoGraph() 통합이 실행되어야 합니다. JSON-LD 검증을 위해 seo-graph-core에서 assembleGraph()에 warnOnDanglingReferences: true를 전달하십시오. 이것은 통합 옵션이 아닌 어셈블리 시간 검사입니다.
• 권장 — seoGraph()에서 validateImageAlt, validateMetadataLength 및 validateInternalLinks가 활성화되어야 합니다(≥ 1.1.0에서 모두 기본 true). 누락된 대체 텍스트, SERP 경계를 벗어난 제목 또는 설명(기본값: 제목 30-65, 설명 70-200), 그리고 404가 발생하거나 후행 슬래시 불일치가 있는 내부 링크를 포착합니다. 프로젝트가 1.1.0에 있는 경우 ≥ 1.1.1로 업그레이드하십시오. 해당 패치 릴리스는 두 가지 검증기 버그를 수정합니다. validateInternalLinks는 이제 public/ 자산을 유효한 대상으로 인식하고(/images/* 또는 /fonts/*에 대한 더 이상 오탐 없음), validateMetadataLength는 더 이상 설명이 포함하는 경우 잘리지 않습니다.

...

[번역을 위해 잘림]