Claude Code로 하는 JavaScript SEO: 템플릿을 건드리기 전에 증거 폴더부터 만드세요

JavaScript SEO에서 정말 위험한 일은 체크리스트를 실행하는 것이 아닙니다. 그럴듯하게 들리는 체크리스트 한 줄만 믿고 여러 페이지가 공유하는 템플릿을 바꾸는 일이 더 위험합니다. 카테고리 페이지가 내 브라우저에서는 멀쩡해 보여도 링크가 클릭 핸들러에 의존하거나, 유용한 콘텐츠가 늦게 나타나거나, canonical과 HTTP 응답 동작이 서로 다른 이야기를 할 수 있습니다. 잘못된 "SEO 수정"은 내비게이션, 분석, 접근성은 물론 그 컴포넌트를 사용하는 모든 페이지를 망가뜨릴 수 있습니다.

Claude Code는 실제 페이지에서 관찰한 현상을 원인일 가능성이 있는 가장 작은 코드 경로, 검토 가능한 diff, 테스트로 연결할 때 가장 유용합니다. 프레임워크를 다시 쓰거나 패치를 바로 배포하는 것부터 시작해서는 안 됩니다.

이 과정을 마치면 얻게 되는 것: 저장소 안의 증거 폴더, 로컬 조사 규칙, 페이지 증상 하나에서 관련 가능성이 있는 파일로 이어지는 코드 지도, 담당자가 승인한 구현 브리프, 테스트를 마친 변경 기록입니다. 여기서 "완료"는 Google이 페이지를 다시 크롤링했거나 순위가 올랐다는 뜻이 아닙니다.

1부: 저장소를 열기 전에 JavaScript SEO 이해하기

페이지가 JavaScript에 의존하면 무엇이 달라지는가

웹 서버는 URL 요청에 응답합니다. 그 응답에 주요 페이지 콘텐츠가 이미 들어 있을 수도 있고, 브라우저에게 스크립트를 실행하고 데이터를 더 요청하라고 지시하는 껍데기만 들어 있을 수도 있습니다. 브라우저는 그다음 최종 페이지 상태를 구성합니다.

검색 시스템도 URL을 발견하고, 응답을 가져오고, 허용된 리소스를 처리하고, 완성된 페이지를 이해해야 합니다. 최신 JavaScript를 쓴다는 사실 자체가 SEO 문제는 아닙니다. 중요한 단계가 불안정하거나 페이지의 여러 계층이 서로 다른 신호를 보낼 때 문제가 생깁니다.

초보자에게는 다음 모델이 유용합니다.

URL 발견
  -> 서버 응답 수신
  -> HTML과 리소스 처리
  -> JavaScript와 데이터 요청 완료
  -> 콘텐츠, 링크, 페이지 신호 해석
  -> 검색 시스템이 URL을 색인할지, 어떻게 다룰지 결정

각 화살표에서 문제가 생길 수 있으며, 저장소에는 전체 증거 중 일부만 들어 있습니다. 코드는 컴포넌트가 의도상 어떻게 동작해야 하는지 보여 줍니다. 하지만 코드만으로 Google이 어떤 URL을 색인했는지, 어제 프로덕션 요청이 실패했는지, 특정 기기의 사용자가 무엇을 경험했는지는 알 수 없습니다.

"JavaScript 문제" 하나가 아니라 여섯 가지 페이지 동작 확인하기

1. URL이 의도한 상태 코드를 반환하는가

정상 페이지는 보통 200을 반환합니다. 삭제된 페이지는 의미 있는 not found 또는 gone 상태를 전달해야 합니다. 리디렉션은 의도한 최종 URL로 이어져야 합니다. 클라이언트 측 리디렉션은 더 느릴 수 있고, HTTP 계층에서는 분명하게 드러날 실수를 감출 수도 있습니다.

2. 주요 콘텐츠를 사용할 수 있는가

페이지의 정체성을 결정하는 텍스트와 항목이 관련 응답 또는 렌더링된 상태에 나타나야 합니다. 콘텐츠를 보려면 스크립트, 데이터 요청, 스크롤, 클릭, 로그인 같은 조건이 필요한지 기록하세요. 소스 HTML에 없다는 사실은 관찰 결과일 뿐, 페이지가 색인될 수 없다는 자동 판정이 아닙니다.

3. 중요한 목적지가 실제 링크인가

검색 시스템은 일반적으로 표준 링크를 통해 목적지를 발견합니다. onClick, 버튼, 프래그먼트만으로 이동하는 카드는 화면에서는 작동해도 URL 발견 경로로서는 더 약할 수 있습니다. 적절한 수정은 실제 링크를 추가하는 것일 수 있지만 키보드 동작, 분석, 스타일, 애플리케이션 라우팅을 그대로 유지해야 합니다.

4. canonical, robots, 사이트맵 신호가 일치하는가

요청 URL, canonical 대상, robots 지시문, 내부 링크, 사이트맵 항목이 같은 우선 페이지를 설명하는지 확인합니다. canonical은 힌트입니다. 깔끔한 URL 처리를 대신하지 않으며, 관련 없는 페이지를 가리켜서는 안 됩니다.

5. 지연 로딩과 무한 스크롤에 도달 가능한 상태가 있는가

지연 로딩은 성능을 개선할 수 있지만 핵심 콘텐츠가 임의의 사용자 동작에 의존해서는 안 됩니다. 무한 스크롤은 보통 안정적인 페이지네이션 URL이나 더 깊은 항목으로 이어지는 다른 크롤링 가능 경로를 제공해야 합니다. 정확한 구현은 사이트마다 다르므로 변경을 제안하기 전에 기존 라우팅과 데이터 모델을 살펴보세요.

6. 메타데이터와 구조화 데이터가 화면 내용과 일치하는가

title, canonical, robots 지시문, 구조화 데이터가 JavaScript 실행 후 생성될 수 있습니다. 이 정보는 화면에 보이는 콘텐츠와 정확하고 일관되어야 합니다. 구조화 데이터는 페이지 해석을 도울 수 있지만 리치 결과나 순위를 보장하지 않습니다.

네 가지 증거를 분리하기

저장소 에이전트를 사용할 때 이 분리가 중요합니다. Claude Code는 컴포넌트 추적에 뛰어나지만, 코드 가까이에서 조사하다 보면 그럴듯한 메커니즘을 확인된 원인처럼 취급하기 쉽기 때문입니다.

증거에 근거한 증상 하나 작성하기

"Google이 우리 사이트를 렌더링하지 못한다"로 시작하지 마세요. 아직 입증하지 않은 결론이 들어 있는 문장입니다. 범위를 더 좁혀 다음처럼 씁니다.

제공된 카테고리 페이지 캡처에서 상품명은 렌더링 후 나타나지만, 렌더링된 DOM의 상품 카드에는 표준 목적지 링크가 없습니다. 검색 엔진의 색인 상태는 알 수 없습니다.

이렇게 쓰면 Claude Code가 추적할 구체적인 대상이 생깁니다. 또한 조사 범위를 애플리케이션의 모든 렌더링 판단이 아니라 카테고리 카드와 내비게이션을 담당하는 코드로 제한할 수 있습니다.

2부: 증거에서 검토된 diff까지 이어지는 Claude Code 워크플로 만들기

저장소에 증거 폴더 준비하기

애플리케이션 소스가 아닌 위치를 선택합니다. 저장소에 생성 산출물이나 보고서 규칙이 있다면 그대로 따르세요. 정해진 규칙이 없다면 다음과 같은 구조로 시작할 수 있습니다.

reports/javascript-seo/
  collection-page-links/
    page-story.md
    response-notes.md
    rendered-notes.md
    search-evidence.md
    decision.md

이 폴더는 네 가지 질문에 답해야 합니다. 어떤 페이지를 조사하는가, 무엇을 관찰했는가, 아직 무엇을 사용할 수 없는가, 담당자가 무엇을 결정했는가입니다. 캡처와 내보내기 파일을 버전 관리에 넣어서는 안 된다면 ignore 대상에 포함하세요.

쿠키, API 토큰, 비밀번호, 비공개 고객 데이터, 제한 없이 내려받은 내보내기 파일을 폴더에 절대 넣지 마세요. 어떤 도구와 증거를 공유하든 먼저 비공개 URL과 사용자 정보를 가립니다.

담당자가 구현 브리프를 승인할 때까지 읽기 전용 조사 기록을 소스 코드와 분리해 둡니다.

첫 프롬프트 전에 저장소 규칙 추가하기

관련 CLAUDE.md나 기존 .claude 규칙처럼 프로젝트가 이미 사용하는 Claude Code 안내 위치에 정책을 추가합니다. 기존 지시 체계가 있다면 두 번째 체계를 만들지 마세요.

## JavaScript SEO 조사 정책

- JavaScript SEO 작업은 읽기 전용 증거 수집으로 시작한다.
- 조사 메모는 승인된 증거 디렉터리에만 저장한다.
- 관찰 사실, 가능한 메커니즘, 미확인 사항, 담당자 결정을 구분한다.
- 사람이 지정한 구현 브리프를 승인하기 전에는 소스, 라우트, robots 규칙,
  콘텐츠, CMS 데이터, 배포 파일, CI를 수정하지 않는다.
- Search Console, 크롤링 로그, 프로덕션 지표, 색인 상태는 권한 있는
  내보내기 자료가 제공되지 않는 한 사용할 수 없는 것으로 취급한다.
- 비밀 정보, 쿠키, 토큰, 비공개 URL, 고객 데이터를 노출하지 않는다.
- 승인 후에는 범위가 가장 작은 변경을 수행하고 diff를 보여 주며 합의한 테스트를 실행하고,
  롤백 조건을 명시한다. 별도 허가가 없다면 배포하지 않는다.

이 규칙은 지속적인 안내를 제공합니다. 하지만 규칙 자체가 강제 권한 계층은 아닙니다. 프로젝트에 맞는 저장소 권한, 브랜치 보호, 명령 승인, 코드 리뷰를 함께 사용하세요.

페이지 스토리 만들기

저장소 조사가 페이지 목적과 계속 연결되도록 짧은 page-story.md를 추가합니다.

## 페이지
https://example.com/collections/shoes

## 방문자 목적
판매 중인 신발을 비교하고 상품 페이지를 연다.

## 필수 페이지 요소
- 카테고리 제목
- 상품명과 가격
- 안정적인 상품 목적지
- 일관된 title, canonical, robots 지시문, 상태

## 관찰된 증상
제공된 렌더링 DOM에는 상품 카드가 있지만 표준 상품 링크가 없다.

## 사용 가능한 증거
- 저장한 응답 기록
- 렌더링된 DOM 일부
- 저장소 체크아웃

## 사용할 수 없는 증거
- Google URL 검사
- 서버 로그
- 프로덕션 필드 지표

## 금지된 작업
조사 중에는 소스 수정, 배포, CMS 변경, URL 제출, 외부 메시지 발송을 하지 않는다.

페이지 스토리는 조사가 일반 코드 리뷰로 흘러가는 것을 막아 줍니다.

Claude Code에 수정이 아니라 코드 지도를 요청하기

첫 프롬프트는 읽기 전용 모드로 사용합니다.

JavaScript SEO 증상 하나를 읽기 전용 모드로 조사하세요.

페이지 스토리: reports/javascript-seo/collection-page-links/page-story.md
증거 폴더: reports/javascript-seo/collection-page-links/

저장소 안내를 읽으세요. 설명된 페이지와 증상에 관련될 가능성이 있는 코드 경로만
조사한 후 다음을 반환하세요.
1. 확인된 증거 요약
2. 관련 가능성이 높은 라우트, 템플릿, 컴포넌트, 데이터 경로와 그 이유
3. 불확실성과 누락된 데이터
4. 가장 작은 구현 선택지
5. 수락 검사와 롤백 조건

파일 수정, 패키지 설치, 배포, 쓰기 가능한 API 호출을 하지 말고, Google이 페이지를
색인했다거나 색인하지 못했다고 주장하지 마세요. 조사 브리프를 작성한 뒤 멈추세요.

예상 결과: 페이지 라우트에서 템플릿, 컴포넌트, 내비게이션 동작, 관련 테스트로 이어지는 지도입니다. 품질 확인: 모든 후보 파일이 관찰된 증상과 연결되어야 합니다. 복구 방법: 답변이 프레임워크 이전을 제안한다면, 되돌릴 수 있는 가장 작은 템플릿 수준 선택지와 그 근거를 요청하세요.

개발자처럼 코드 지도 검토하기

유용한 코드 지도는 데이터와 마크업이 페이지에 도달하는 과정을 설명합니다. 카테고리 카드 문제라면 다음을 찾아야 합니다.

• 라우트 또는 페이지 진입점
• 카테고리 템플릿
• 카드 컴포넌트
• 상품 목적지를 만드는 함수
• 내비게이션과 분석 핸들러
• 기존 컴포넌트, 접근성, 엔드투엔드 테스트

미확인 사항도 적어야 합니다. 카드 컴포넌트는 href를 지원하지만 템플릿이 값을 넘기지 않는 것일 수 있습니다. 래퍼 구조 때문에 중첩 링크를 피하고 있을 수도 있습니다. 초기 응답에서는 사용할 수 없는 데이터로 목적지를 생성할 수도 있습니다. 이것들은 서로 다른 메커니즘이며 수정 방법도 다릅니다.

다음 표를 사용해 검토하세요.

코드를 구현 브리프로 전환하기

수정 전에 담당자가 다음 내용을 포함한 문서를 승인해야 합니다.

Finding(발견 사항): [관찰된 조건 하나]
Evidence(증거): [파일 또는 캡처]
Affected page family(영향받는 페이지군): [확인된 범위]
Candidate mechanism(후보 메커니즘): [코드 경로와 불확실성]
Approved action(승인된 조치): [범위가 제한된 변경 하나]
Behavior to preserve(유지할 동작): [내비게이션, 접근성, 분석, 스타일, 라우팅]
Acceptance checks(수락 검사): [목록]
Rollback condition(롤백 조건): [목록]
Owner(담당자): [이름 또는 역할]
Status(상태): APPROVED FOR LOCAL IMPLEMENTATION / NOT APPROVED

"크롤링 가능한 링크 추가"만으로는 여전히 너무 넓습니다. 더 나은 승인 문구는 컴포넌트와 의도된 동작을 지정하면서도 코드 담당자가 기존 애플리케이션에 맞는 유효한 마크업을 선택할 수 있게 합니다.

제약을 둔 수정 한 번 실행하기

승인 후에는 새 프롬프트를 시작합니다. 폭넓은 조사 문맥이 이미 변경 권한을 부여한 것처럼 이어서 작업하지 마세요.

다음 문서에 기록된 승인 작업만 구현하세요.
reports/javascript-seo/collection-page-links/decision.md

수정 전에 대상 파일, 유지할 동작, 수락 검사, 금지 작업, 롤백 조건을 다시 말하세요.

일관성을 유지하는 가장 작은 변경을 수행하세요. 관련 없는 코드 리팩터링, 의존성 변경,
배포 설정 변경, CMS 콘텐츠 수정, 배포는 하지 마세요.

수정 후:
- 전체 diff를 보여 준다
- 승인된 로컬 검사만 실행한다
- 범위를 넓히지 않고 실패를 보고한다
- 결과를 decision.md에 업데이트한다

저장소 증거가 승인된 메커니즘과 충돌하면 멈추고 수정된 브리프를 반환하세요.

대상 템플릿, 검토 관문, 미리보기 검사, 롤백 경로가 명확해야 인계가 완료됩니다.

설명을 믿기 전에 diff 확인하기

diff를 주요 변경 기록으로 읽으세요. 다음을 확인합니다.

• 예상한 파일만 변경했는가
• 필요한 이벤트 처리와 분석을 유지했는가
• 유효하지 않은 중첩 인터랙티브 요소를 만들지 않았는가
• 키보드와 스크린 리더 동작을 유지했는가
• 안정적이고 올바른 목적지를 생성하는가
• 관련 테스트를 추가하거나 업데이트했는가
• robots, canonical, 리디렉션, 관련 없는 메타데이터를 몰래 바꾸지 않았는가

아무리 설명이 매끄러워도 범위가 지나치게 넓은 diff를 정당화할 수는 없습니다.

방문자와 크롤러가 만나는 순서대로 페이지 검증하기

로컬 및 기능 동작

영향받는 영역을 빌드하고 방문자의 과업을 테스트합니다. 마우스와 키보드로 목적지를 열 수 있는가? 클라이언트 라우팅이 계속 작동하는가? 분석 요구 사항이 유지되는가? 데이터가 없을 때도 컴포넌트가 올바르게 동작하는가를 확인하세요.

응답 신호

의도한 응답 또는 미리보기를 살펴봅니다. 상태, 리디렉션 동작, title, canonical, robots 지시문, 응답에 있어야 하는 주요 콘텐츠를 확인합니다. 페이지 소스의 내용만으로 SEO 전체를 판정하지 마세요.

렌더링된 출력

최종 DOM에 의도한 콘텐츠와 일반 목적지가 있는지 확인합니다. 대표 페이지뿐 아니라 빈 상태, 오류 상태, 데이터를 사용할 수 없는 상태도 관련이 있다면 테스트하세요.

권한이 있는 검색 증거

팀에 URL 검사, 크롤링, 로그, Search Console 증거가 있다면 날짜와 함께 별도로 기록합니다. 로컬 미리보기로 Google이 페이지를 다시 크롤링하거나 색인했다는 사실을 증명할 수는 없습니다. 검색 데이터 변화에는 시간이 걸릴 수 있으며 어떤 구현도 순위를 보장하지 않습니다.

롤백과 기록

승인된 브리프, 최종 diff, 테스트 출력, 미리보기 참조, 날짜, 담당자 결정을 한곳에 보관합니다. 유지해야 할 동작이 실패하거나 범위가 예상 밖으로 넓어지거나 미리보기가 페이지 스토리와 더 이상 맞지 않으면 합의한 방식으로 되돌립니다.

세 가지 조사 사례

안정적인 링크가 없는 클릭 가능 카드

관찰: 카드 텍스트는 보이지만 렌더링 캡처에서는 일반 목적지 링크가 아닌 컨테이너에 내비게이션이 연결되어 있습니다. 저장소 질문: 어떤 컴포넌트가 주요 목적지를 담당하며 분석과 접근성을 어떻게 유지하는가? 최소 변경 후보: 주요 동작에 적절한 표준 링크를 추가합니다. 가정하지 말 것: 카드 안의 모든 지점을 중첩 링크로 만들어야 한다.

더 깊은 URL 경로가 없는 무한 스크롤

관찰: 스크롤 후 항목이 더 나타나지만 제공된 증거에는 이후 그룹으로 가는 안정적인 페이지 경로가 없습니다. 저장소 질문: 데이터 계층이 URL에 연결할 수 있는 페이지나 커서를 이미 지원하는가? 최소 변경 후보: 점진적 향상을 유지하면서 크롤링 가능한 페이지네이션을 공개합니다. 가정하지 말 것: 인터페이스 전체를 교체해야 한다.

클라이언트 렌더링 not found 페이지가 200을 반환함

관찰: 사용할 수 없는 상품이 렌더링 후 "not found" 메시지를 표시하지만 응답 캡처는 200입니다. 저장소 질문: 라우트를 사용할 수 있는지 어디에서 알 수 있으며 서버나 프레임워크가 의미 있는 상태를 반환할 수 있는가? 최소 변경 후보: 적절한 라우트 경계에서 누락 상태를 처리합니다. 가정하지 말 것: 보이는 문구만 바꾸면 응답 문제가 해결된다.

흔한 실수

Claude Code에 사이트 전체 감사를 요청하기

출력이 넓어지고 검증하기 어려워집니다. 대표 URL 하나와 페이지 스토리 하나로 시작하세요. 같은 메커니즘이 다른 페이지에서도 확인된 뒤에만 범위를 넓힙니다.

CLAUDE.md를 보안 제어로 취급하기

이 파일은 안내이지 독립적인 권한 시스템이 아닙니다. 명령 승인, 저장소 권한, 사람의 검토를 유지하세요.

증거 파일을 제품 커밋과 섞기

캡처와 내보내기에는 비공개 정보가 들어 있거나 불필요하게 시끄러운 diff를 만들 수 있습니다. 승인된 ignore 디렉터리에 보관하고 의도한 코드와 테스트 변경만 커밋하세요.

즉시 순위로 성공 측정하기

먼저 기술 목표를 확인합니다. 나중에 권한 있는 크롤링 및 검색 데이터를 사용하세요. 순위에는 관련성, 경쟁, 콘텐츠 품질, 링크를 비롯한 많은 요인도 영향을 줍니다.

통과한 테스트 때문에 잘못된 페이지 상태 놓치기

컴포넌트 테스트가 통과해도 프로덕션 라우트는 다른 데이터, 메타데이터, 상태 처리를 받을 수 있습니다. 실제 방문자 경로와 비슷한 라우트 수준 또는 미리보기 검사를 하나 이상 포함하세요. 페이지에 필터, 페이지네이션, 사용할 수 없는 상품, 현지화 버전이 있다면 승인된 변경이 어떤 상태를 다루고 어떤 상태는 이번 범위 밖인지 명시합니다.

범위 확인 없이 공유 컴포넌트 수정하기

카테고리 카드가 검색, 추천, 장바구니, 계정 화면에도 나타날 수 있습니다. 변경하기 전에 Claude Code에 컴포넌트가 사용되는 위치와 제안한 마크업이 각 맥락에 영향을 주는지 물어보세요. 답변이 범위를 넓힌다면 작은 수정이 조용한 재설계가 되게 두지 말고 담당자에게 새 브리프를 요청하세요.

첫 실전 사례를 처음부터 끝까지 진행하기

페이지 스토리에 방문자가 상품을 비교하고 상세 페이지를 열어야 한다고 적혀 있다고 가정해 봅시다. 증거 폴더에는 상품명은 있지만 일반 목적지 링크는 없는 렌더링 DOM 일부가 있습니다. Claude Code는 프로젝트 안내를 읽고 라우트를 카테고리 템플릿, 재사용 카드 컴포넌트, 내비게이션 핸들러로 연결합니다. 그리고 그 컴포넌트가 추천 레일과도 공유되므로 아직 범위가 확실하지 않다고 보고합니다.

유용한 결과는 즉각적인 패치가 아닙니다. 담당자는 범위가 제한된 두 가지 다음 단계 중 선택할 수 있습니다. 두 맥락에서 컴포넌트를 조사하거나, 유효한 주요 목적지를 제공하는 카테고리 전용 래퍼를 만드는 것입니다. 담당자가 선택하면 구현 프롬프트에 대상 파일, 필수 테스트, 유지할 분석 동작, 롤백 조건을 적습니다.

패치 후 팀은 렌더링된 카테고리 페이지를 확인하고 키보드 내비게이션으로 목적지를 열며 라우트 응답과 canonical을 검사하고 추천 레일이 의도대로 계속 작동하는지 검증합니다. 결정 기록에는 테스트한 내용만 적습니다. 검색 엔진이 이미 모든 상품 URL을 다시 처리했다고 주장하지 않습니다.

자주 묻는 질문

Claude Code가 라이브 사이트와 저장소를 함께 조사할 수 있나요?

필요한 도구와 접근 권한이 제공되고 허가된 경우에만 가능합니다. 라이브 페이지 증거, 저장소 증거, 검색 플랫폼 증거를 각각 구분해 표시하세요.

CLAUDE.md 파일로 Claude Code의 수정을 막을 수 있나요?

지속적인 프로젝트 안내를 제공하지만 그 자체가 강제 장치는 아닙니다. 환경의 실제 권한과 검토 통제를 사용하세요.

모든 JavaScript SEO 문제에 서버 사이드 렌더링이 필요한가요?

아닙니다. 안정적인 링크, 올바른 상태, 일관된 메타데이터, 사용 가능한 데이터 경로, 작은 컴포넌트 변경이 적절한 해결책일 수 있습니다. 먼저 진단하세요.

Claude Code가 승인된 패치를 배포하게 해야 하나요?

담당자, 테스트, 롤백 계획이 포함된 별도 배포 허가가 없다면 안 됩니다. 로컬 구현 승인은 프로덕션 릴리스 승인이 아닙니다.

초보자가 가장 먼저 조사할 것은 무엇인가요?

가치가 높은 페이지 하나와 표준 링크 누락이나 잘못된 응답 상태처럼 눈에 보이는 증상 하나를 고르세요. 코드 변경을 요청하기 전에 증거 폴더를 만드세요.

저자: Auspia에서 14년 경력의 테크니컬 SEO 실무자인 Julian Mercer. 크롤링 가능성, 렌더링, 사이트 구조, AI가 읽기 쉬운 콘텐츠를 위한 기술 기반에 관해 씁니다.