단독 개발 (0 → 1 재구축)
아코디언에 접힌 본문은 AI 크롤러에게 존재하지 않는다
회사 소개 사이트를 재구축하면서 텍스트의 약 50%(FAQ는 84%)가 접힘 UI 안에 있다는 것을 확인했다. 조건부 렌더링으로 두면 JS를 실행하지 않는 AI 크롤러에게는 그 절반이 존재하지 않는다. 상태와 무관하게 항상 DOM에 두고 CSS로만 숨기는 규약을 세우고, 초기 HTML을 실제 HTTP로 받아 특정 문자열의 생존을 확인하는 CI 게이트를 만들었다.
무엇을 만들었나
빌드 도구가 없던 기존 정적 HTML 사이트 7페이지를 Next.js 16 App Router 기반으로 전면 재구축했다. 한국어·영어 이중 언어를 붙이고 최종적으로 8라우트 × 2로케일을 정적 생성한다. 요구사항 정리부터 배포 구성까지 혼자 담당했다.
무엇이 문제였나
사이트 텍스트의 약 50%가 아코디언·캐러셀·드롭다운 안에 있었다. FAQ 페이지는 84%였다.
접힘 UI를 리액트로 만들 때 가장 흔한 구현은 조건부 렌더링이다.
{isOpen && <Answer>{content}</Answer>}
이 코드는 사람에게는 완벽하게 동작한다. 클릭하면 열리고 다시 클릭하면 닫힌다. 접근성 속성만 제대로 붙이면 스크린 리더도 읽는다.
그런데 JavaScript를 실행하지 않는 크롤러에게 이 콘텐츠는 존재하지 않는다. 초기 HTML에 없기 때문이다.
검색엔진은 렌더링하는데 왜 문제인가
답변 엔진과 검색엔진이 같은 방식으로 읽지 않기 때문이다.
검색엔진은 렌더링 큐를 거쳐 JavaScript 실행 후의 DOM을 색인한다. 조건부 렌더링된 FAQ도 시차는 있지만 결국 들어간다.
초기 HTML만 받아가는 클라이언트에게는 그 콘텐츠가 없다. 어떤 크롤러가 어디까지 실행하는지를 일일이 확인하지는 못했다. 확인한 것은 하나다 — 우리 초기 HTML 응답에 본문 절반이 들어 있지 않았다는 사실이다.
우리 제품이 “AI가 브랜드를 얼마나 언급하는가”를 측정하는 SaaS였기 때문에, 회사 소개 사이트가 그 상태인 것은 그냥 두기 어려웠다.
왜 아무도 못 봤나
사람 눈에는 완전히 똑같이 보이기 때문이다.
브라우저로 열면 정상이다. 클릭하면 열린다. 스크린샷으로도 차이가 없다. 코드 리뷰에서 {isOpen && ...} 를 보고 “이건 AI 크롤러가 못 읽는다”고 지적하려면, 리뷰어가 그 순간 그 사실을 떠올려야 한다.
이런 종류의 결함은 사람의 주의력에 의존하는 방식으로는 계속 재발한다. 오늘 고쳐도 다음 컴포넌트에서 다시 나온다. 그래서 규약과 자동 검사가 함께 필요했다.
어떻게 해결했나
규약 — 상태와 무관하게 항상 DOM에 둔다
접힘 콘텐츠를 언마운트하지 않고 CSS로만 숨긴다. display: none 대신 그리드 트랙 높이를 0fr ↔ 1fr 로 전환하면 높이를 픽셀로 계산하지 않고도 부드럽게 열린다. 콘텐츠는 상태와 무관하게 항상 DOM에 있으므로 초기 HTML에 남는다.
크롤러가 읽도록 DOM에 남기는 것과, 사용자에게 닫힌 것으로 취급되는 것은 별개의 요구사항이다. 닫힌 상태에서 내부 요소가 포커스를 받지 않도록 하는 처리가 함께 필요하다.
게이트 — 초기 HTML을 실제 HTTP로 받아 확인한다
규약만으로는 부족하다. 다음 사람이, 혹은 6개월 뒤의 내가 다시 조건부 렌더링을 쓴다.
그래서 센티널 문자열 99개를 정하고, 빌드 결과물을 실제 HTTP로 받아 그 문자열들이 응답 본문에 살아 있는지 확인하는 검사를 CI에 넣었다. 브라우저로 렌더링한 DOM이 아니라 네트워크로 받은 원본 바이트를 본다는 점이 중요하다. 렌더링된 DOM을 검사하면 조건부 렌더링도 통과해버린다.
이 게이트가 잡는 것은 결국 하나다 — “사람 눈에는 똑같이 보이지만 크롤러에게는 사라진 변경”.
구조화 데이터도 끊어져 있었다
기존 JSON-LD는 노드가 18개인데 @id 가 1개뿐이었다.
노드가 서로를 참조하지 못하면 답변 엔진은 “이 페이지의 FAQ는 이 회사가 만든 이 제품에 관한 것” 이라는 그래프를 만들 수 없다. 개별 노드는 문법적으로 유효하지만 서로 연결되지 않은 섬으로 남는다.
@id 를 단일 출처로 두고 사이트 그래프와 페이지 그래프로 분리해 전 페이지를 연결했다. 잘못 선언돼 있던 alternateName 과 sameAs 도 함께 바로잡았다.
측정 도구가 없어서 직접 만들었다
명암비를 검사하려 했는데 기존 도구가 전부 실패했다. 배경이 그라디언트와 캔버스라 조상 요소를 거슬러 올라가며 배경색을 찾는 방식이 성립하지 않기 때문이다. 계산된 스타일에는 transparent 만 나온다.
그래서 다르게 접근했다. 모든 글자를 투명하게 만든 상태로 배경판을 스크린샷으로 찍고, 각 텍스트의 실제 좌표에서 픽셀을 직접 읽었다. 배경이 무엇으로 그려졌든 최종 픽셀 값은 거짓말하지 않는다.
2,485건을 측정했고 실패가 402건 나왔다. 고치는 방식도 정했다 — 값을 하나씩 눌러 맞추지 않고, 조용한 텍스트들의 위계를 유지한 채 바닥만 올렸다. 개별 수정은 결국 위계를 무너뜨려서 디자인이 평평해진다.
결과
| 항목 | 내용 |
|---|---|
| CI 자동 검증 게이트 | 17종 (정적 6 + 런타임 11) |
| 초기 HTML 센티널 | 99개 문자열 생존 확인 |
| 명암비 | 2,485건 측정 → 실패 402건 → 회귀 0건 (WCAG AA) |
| 라우트당 이미지 전송 | 688.6KB → 118.8KB |
| i18n RSC 페이로드 | 라우트당 16~27KB(gz) 절감 |
| 영문 카탈로그 | 856개 항목(31,168자) 전량 번역, 미번역 0 |
게이트는 실패해도 중단하지 않게 구성했다. 한 번의 실행에 전체 상태가 보이는 편이, 첫 실패에서 멈춰 나머지를 감추는 것보다 낫다.
시각 회귀는 기준 이미지를 저장소에 두지 않는다. 같은 러너에서 merge-base 와 head 를 각각 빌드해 비교한다. OS·폰트 렌더링 차이로 생기는 거짓 실패와 재베이스라인 작업이 구조적으로 사라진다.
되돌아보면
성능 게이트의 수치는 로컬 랩 조건 측정이다. 실사용자 필드 데이터가 아니다. 회귀를 감지하는 용도로는 충분하지만 “이 사이트가 실제 사용자에게 빠르다”는 근거로 쓰면 안 된다.
영문 로케일은 사람 검수를 거치지 않아 색인을 열지 않았다. 기계 번역 품질로 색인되면 되돌리기 어렵다고 판단했다.
이번 일로 코드 리뷰로 잡을 수 없는 결함 부류가 있다는 걸 알았다. 사람 눈에 똑같이 보이는 차이는 사람이 검토해서 잡을 수 없다. 그런 결함은 규약으로 예방하고 자동 검사로 가둬야 하며, 그 검사를 만드는 일 자체가 개발 작업의 일부다.