SEO 감사 결과를 AI 코딩 에이전트가 실제로 수정할 수 있는 작업으로 변환하는 방법 (Claude Code, Cursor, Codex)

일반적인 SEO 감사(audit) 내보내기 파일은 몇백 개의 행을 가진 스프레드시트입니다. 여기에는 '누락된 canonical 태그 (18 페이지)', '중복 제목 (11 페이지)', '고아 페이지(Orphan page)', '리디렉션 체인(Redirect chain)' 등이 포함됩니다. 이것을 Claude Code, Cursor 또는 Codex에 붙여넣으며 '이것들을 수정해 줘'라고 요청하는 것은 보통 잘 되지 않습니다. 에이전트는 잘못된 템플릿을 편집하거나, 중요하지 않은 경고를 '수정'하거나, 아무도 검토하지 않는 방식으로 robots.txt 파일을 변경합니다.

코딩 에이전트가 SEO 수정에 능숙한 이유는 대부분의 기술적 SEO 문제가 템플릿 문제이며, 템플릿은 코드이기 때문입니다. 핵심은 감사 결과와 에이전트 사이의 번역 단계(translation step)입니다. 이 게시물은 제가 사용하는 프로세스입니다.

1단계: 발견 사항을 세 개의 바구니로 분류하기

모든 SEO 발견 사항이 코딩 작업인 것은 아닙니다. 어떤 것이든 에이전트에게 전달하기 전에 목록을 분류합니다.

에이전트에게 위임할 것 (결정론적이며, 코드에 존재하고, 검증하기 쉬움):

누락되거나 중복되거나 자기 모순적인 rel="canonical" 태그
템플릿으로 인해 생성된 중복 또는 빈 <title> 및 메타 설명(meta descriptions)
운영 경로에 남아 있는 noindex (메타 태그 또는 X-Robots-Tag 헤더)
사이트맵 문제: 잘못된 호스트, 비정규화 URL, 404 오류가 나거나 리디렉션되는 URL
리디렉션이나 404를 가리키는 내부 링크
단일 점프여야 할 리디렉션 체인 (A→B→C)
누락되거나 유효하지 않은 JSON-LD (Organization, SoftwareApplication, BlogPosting, BreadcrumbList)
콘텐츠 이미지의 누락된 alt 속성, 그리고 컴포넌트 내 헤딩 레벨 순서

에이전트와 함께 하되 스스로 결정할 것 (비즈니스 결정을 인코딩하는 코드 변경):

robots.txt 규칙, 특히 AI 크롤러를 위한 규칙
두 페이지가 겹칠 때 어떤 URL을 canonical로 할지 여부
URL 재구조화 후의 리디렉션 맵(Redirect maps)
hreflang 세트

에이전트와 거리를 둘 것 (코드 문제가 아님):

콘텐츠 품질, 검색 의도, 토픽 격차
백링크 및 권위성
진정한 키워드 전략 결정 사항인 모든 것

첫 번째 그룹은 기술 감사(technical audit)가 지적하는 대부분의 내용을 다룹니다. 두 번째 그룹은 에이전트에게 스스로 결정하게 내버려 둔다면 심각한 문제를 일으킬 수 있는 부분입니다.

단계 2: URL별이 아닌 원인별로 그룹화하기

감사 보고서는 URL별 증상을 보고합니다. 하지만 에이전트는 원인을 고칩니다. '18개 페이지에서 canonical 태그 누락'은 18개의 작업이 아닙니다. 보통은 하나의 레이아웃이나 generateMetadata 스타일의 함수가 canonical을 설정하지 않은 경우입니다. 작업을 작성하기 전에 영향을 받는 URL들을 살펴보고, 그들이 무엇을 공유하는지 질문하세요: 라우트 패턴(/blog/[slug]), 레이아웃, CMS 콘텐츠 유형 등.

원인당 하나의 작업을 수행하면 변경 사항(diff)이 작고 검토 가능하며, 에이전트가 18개 페이지를 하나씩 패치하게 만드는 것을 막을 수 있고, 그렇게 되면 나중에 유지보수해야 할 작업이 생깁니다.

단계 3: 검증 가능한 방식으로 각 작업을 작성하기

이 템플릿은 세 가지 에이전트 모두에게 잘 작동했습니다:

## 작업: 블로그 게시물에 자체 참조 canonical 추가

**발견:** /blog/* 아래의 18개 URL에 <link rel="canonical"> 태그가 없습니다.
...

각 부분이 하는 역할은 다음과 같습니다:

증거(Evidence): 에이전트가 고장 나지 않은 것을 '고치는' 것을 막아줍니다. 증거를 재현할 수 없다면, 그렇게 말해야 합니다.
가능한 원인(Likely cause): 지시가 아니라 힌트입니다. 에이전트는 파일을 열어보면 이를 확인하거나 수정하는 데 능숙합니다.
범위(Scope): 가장 중요한 줄입니다. 이것 없이는 에이전트가 주변 코드를 정리하게 되고, 그 결과 canonical 수정 작업이 40개 파일의 변경 사항으로 변질될 수 있습니다.
수용 기준(Acceptance criteria): 당신이 검토할 기준점입니다. 소스 코드에서가 아니라 렌더링된 HTML에서 관찰 가능하도록 만드세요.
검증(Verify): 에이전트가 작업을 반환하기 전에 스스로 점검할 수 있는 방법을 제공합니다.

단계 4: 리포지토리에 일반 지침 제공하기

모든 SEO 작업에 적용되는 규칙은 각 프롬프트가 아닌 리포지토리 안에 있어야 합니다. Codex와 Cursor는 리포지토리의 AGENTS.md 파일을 읽습니다. Claude Code는 CLAUDE.md를 읽으며, @AGENTS.md 임포트 라인을 통해 공유 파일을 가져올 수 있습니다. 저는 SEO 규칙을 한 곳에 보관합니다:

SEO 규칙

프로덕션 기본 URL: https://example.com (절대 localhost, preview 또는 staging 호스트 사용 금지).
카노니컬(Canonicals): 절대 경로, https, 프로덕션 호스트, 쿼리 문자열 없음, 기본적으로 자체 참조.
...

이 마지막 규칙이 가장 중요합니다. 이 규칙은 '보기 좋다'는 것을 종료 코드가 있는 명령으로 바꿉니다.

5단계: diff가 아닌 렌더링된 HTML을 기준으로 검증하기

SEO 버그는 크롤러가 받는 HTML에 존재합니다. diff는 완벽해 보일 수 있지만, 부모 레이아웃이 카노니컬 태그를 덮어쓰거나 클라이언트 컴포넌트가 두 번째 <title>을 주입할 수 있습니다. 따라서 검사는 실제 페이지를 가져와야 합니다. 제가 에이전트에게 제공하고 (저 자신도 사용하는) 간단한 표준 라이브러리 Python 스크립트를 소개합니다. 이 스크립트는 URL 파일, 누락되거나 중복되는 카노니컬, 다른 곳을 가리키는 카노니컬, noindex, 리디렉션, 오류 상태 코드, 그리고 페이지 전반에 걸쳐 중복된 제목을 확인합니다:

#!/usr/bin/env python3
"""check_seo.py: URL 목록에 대한 기본 SEO 불변성 검증 (줄당 하나의 URL)."""
import sys
...

로컬 프로덕션 빌드(npm run build && npm start)를 대상으로 하고, 템플릿별 페이지 하나씩을 포함하는 URL 목록으로 실행한 다음, 배포 후 다시 프로덕션을 대상으로 실행합니다. URL은 카노니컬 형태로 나열해야 합니다. 트레일링 슬래시 불일치는 의도적으로 실패로 간주되는데, 이는 실제 불일치이기 때문입니다.

이 검사는 의도적으로 좁게 설정되어 있습니다. 제목의 문구나 콘텐츠를 판단하지 않습니다. 에이전트가 가장 실수하기 쉬운 불변성(invariants)을 확인합니다.

6단계: 마이그레이션처럼 검토하기

좋은 작업이라 할지라도, SEO 풀 리퀘스트는 일반적인 UI 변경보다 더 엄격하게 검토해야 합니다. 왜냐하면 실수는 조용하기 때문입니다. 잘못된 카노니컬이나 떨어진 noindex 태그는 오류를 발생시키지 않습니다. 그것은 페이지들을 검색 엔진에서 서서히 제거합니다. 제가 확인하는 사항:

diff가 명시된 범위 내에 머물러 있는지.
작업이 요구하지 않은 경우, robots.txt, 리디렉션, middleware, 또는 사이트맵 생성에 변경 사항이 없는지.
검증 결과가 PR 설명에 붙여넣어져 있는지.
구조화된 데이터(Structured data)가 예시 URL 하나에 대해 Google의 Rich Results Test를 통과하는지.

배포 후에는 영향을 받은 URL들을 재크롤링하고, 그중 한두 개에 대해 Search Console의 URL 검사 기능을 사용하세요. 검색 엔진이 변경 사항을 다시 처리하는 데는 며칠에서 몇 주가 걸릴 수 있으므로, 수정 여부는 현재 HTML로 판단하고 순위는 나중에 판단해야 합니다.

감사 도구가 활용되는 지점

위에 언급된 작업 대부분은 번역 과정입니다. 즉, '캐노니컬 태그 누락 페이지 18개'라는 내용을 하나의 범위가 정해지고 검증 가능한 작업으로 변환하는 것입니다. 이것이 제가 수동으로 하다가 지겨워진 부분이며, 그래서 Siteory를 만들게 되었습니다. 이 도구는 SEO, AI 검색 준비 상태, 보안에 대해 사이트를 감사하며, 모든 발견 사항에는 증거와 Claude, Codex, Cursor 또는 OpenCode에 붙여넣을 수 있는 수정 프롬프트가 함께 제공됩니다. 유료 리포트는 prioritized-fixes.md와 같은 Markdown 파일로도 내보낼 수 있습니다. 이 도구는 코드를 직접 편집하지 않습니다. 사용자가 변경 사항을 검토하고, 배포하며, 재검사합니다.

도구를 사용하든 스프레드시트를 사용하든 규칙은 동일합니다. 작업당 하나의 원인, 명확한 범위, HTML에서 확인할 수 있는 승인 기준(acceptance criteria), 그리고 그것을 증명하는 명령어가 필요합니다. 에이전트는 빠릅니다. 검증할 수 있는 무언가를 제공해 주세요.