AI 코딩 에이전트로 SEO 오류 고치기: Claude Code와 Cursor를 위한 안전한 작업 순서

핵심 답변: AI 코딩 에이전트는 사이트의 기계적이고 검증할 수 있는 SEO 문제를 고치는 데 쓸 수 있습니다. title 태그, 메타 설명, canonical 태그, hreflang, 대체 텍스트, 보안 헤더, 그리고 robots.txt, 사이트맵, llms.txt 파일이 여기에 해당합니다. 발견한 문제를 하나씩, 끝났는지 판단할 조건과 함께 맡기고, 브랜치에서 작업하게 한 다음, diff를 읽고, 변경 뒤에는 페이지를 다시 측정하세요. 콘텐츠를 지어내게 하거나, 키워드를 정하게 하거나, 회사를 대변하게 하거나, AI 크롤러의 사이트 접근 허용 여부를 대신 결정하게 해서는 안 됩니다. 수정은 페이지를 기술적으로 올바르게 만들 뿐이며, 순위 상승은 결코 보장되지 않습니다.

AI 코딩 에이전트는 SEO에서 어디에 도움이 되고 어디에는 안 될까요?

SEO 점검은 두 종류의 발견 사항을 내놓습니다. 하나는 기계적인 것으로, 정답이 하나뿐이고 페이지를 가져와 보면 확인할 수 있습니다. 다른 하나는 사람이 내려야 하는 결정입니다. Claude Code, Cursor, GitHub Copilot 같은 AI 코딩 에이전트는 첫 번째 종류에는 잘 맞고 두 번째 종류에는 위험합니다.

에이전트에게 맡기기 좋은 일:

• title 태그와 메타 설명. 빠졌거나 중복되었거나 길이가 맞지 않는 태그는 템플릿이나 콘텐츠 파일에서 금방 찾을 수 있습니다. 에이전트는 아무것도 없는 상태에서 홍보 문구를 쓰는 것이 아니라, 페이지가 이미 말하고 있는 내용에서 문구를 끌어내야 합니다.
• canonical 태그와 hreflang. 둘 다 글이 아니라 규칙입니다. hreflang에는 아래에서 다시 다룰 함정이 하나 있습니다. 모든 언어 버전이 서로를 다시 가리켜야 합니다.
• 대체 텍스트. 이미지의 의미가 주변 페이지 내용에서 분명한 경우에는 괜찮습니다. 그렇지 않다면 에이전트가 물어봐야 합니다.
• 보안 헤더. 서버나 프레임워크 설정 몇 줄이며 curl -I로 쉽게 확인할 수 있습니다.
• 루트에 있는 파일: robots.txt, sitemap.xml, llms.txt. 짧은 일반 텍스트이고 결과를 바로 읽을 수 있습니다.

내가 맡아야 하는 일:

• 콘텐츠 지어내기. 상품 정보, 가격, 후기, 회사에 관한 주장입니다. SEOgrinder가 만들어 주는 브리핑은 작업 규칙에 이를 명시합니다. 콘텐츠를 지어내지 말고, 빠진 문구는 페이지에 이미 있는 내용에서 끌어내거나 물어보라고 합니다.
• 키워드와 주제에 관한 결정. 어떤 페이지가 어떤 검색어를 노릴지는 비즈니스 문제입니다.
• 소유자의 결정. AI 크롤러가 내 사이트를 읽어도 되는지, 학습에 써도 되는지는 내가 정할 일입니다. SEOgrinder의 에이전트 프롬프트는 이를 명시합니다. 허용할지 차단할지는 소유자의 결정이므로 대신 고르지 말고 물어보라고 합니다.
• 성능 작업, 일부. 목표는 측정할 수 있습니다. Core Web Vitals는 페이지 로드의 75번째 백분위수에서 모바일과 데스크톱을 따로 집계하며, ‘좋음’은 LCP 2.5초 이하, INP 200밀리초 이하, CLS 0.1 이하입니다(web.dev). 에이전트는 알려진 수정 방법을 적용할 수 있지만, 그 뒤의 실험실 실행 한 번으로는 실제 방문자가 측정하는 값을 알 수 없습니다. 그러니 무엇을 없앨지는 직접 결정하세요.

AI 코딩 에이전트와 함께하는 안전한 작업 순서 6단계

목표는 모든 변경이 작고, 검증되고, 되돌릴 수 있는 순환 구조입니다.

1. 스캔. SEOgrinder에 공개 웹사이트의 주소를 입력합니다. 무료이고 계정이 필요 없습니다. 종합 점수, 영향이 큰 순서로 정렬된 할 일 목록, 그리고 6개 영역(속도, Google에서의 페이지, 접근성, 기술 & 보안, AI 준비도, 웹사이트)이 나옵니다.
2. 넘기기. 전체 목록은 리포트에서 AI에 넘기기를 누르세요. 브리핑이 열리는데, Markdown 작업 지시서이며 .md로 내려받거나 복사해서 에이전트에 붙여 넣으면 됩니다. 과제 하나만 넘기려면 그 과제 카드의 AI에 넘기기를 누르세요. AI 에이전트용 검사에는 「AI 준비도」 탭의 줄마다 에이전트 프롬프트 복사 버튼이 있습니다(충족된 줄은 먼저 펼쳐야 버튼이 보입니다). 이 프롬프트는 모델에게 건네는 글이고 링크된 명세도 영어라서 영어로 쓰여 있습니다.
3. 한 번에 발견 사항 하나씩. 에이전트에게 첫 번째 과제를 하고 멈추라고 하세요. ‘SEO 전부’를 요청하지 마세요. 과제가 작으면 읽을 수 있는 작은 diff가 나옵니다.
4. diff를 읽고 테스트를 실행. 빌드, 린터, 테스트 스위트는 바로 이럴 때를 위해 있습니다. 변경된 파일은 직접 열어 보세요. 에이전트가 과제에 언급되지 않은 것을 건드렸다면 이유를 물으세요.
5. 다시 확인. 변경이 공개 주소에 올라가면 리포트를 열어 다시 확인을 누르세요. SEOgrinder는 리포트를 최대 24시간 보관하므로, 이 버튼이 없다면 예전 결과를 보게 됩니다. 이 버튼은 시간당 몇 번만 쓸 수 있습니다. 발견 사항이 사라져야 합니다. SEOgrinder는 공개된 웹사이트만 점검하므로, 내 노트북에만 있거나 로그인 뒤에 있는 변경은 보이지 않습니다. 그러니 배포한 뒤에 확인하고, 되돌릴 수 있을 만큼 작게 변경하세요.
6. 커밋. 발견 사항마다 커밋 하나를 만들고 메시지에 그 내용을 적습니다. 다시 확인한 결과가 일치하면 병합하고 다음 과제로 넘어갑니다.

좋은 작업 지시서는 어떤 모습일까요?

명확한 목표가 없으면 에이전트는 그럴듯해 보이는 지점에서 멈춥니다. 좋은 지시서는 추측할 여지를 없앱니다. 네 부분으로 이루어집니다.

브리핑은 다음 순서로 구성됩니다. 임무 설명(「과제」), 「페이지」, 「현재 상태」, 「키워드」, 과제 목록(「과제」), 「작업 규칙」, 「데이터(기계 판독용)」입니다. SEOgrinder를 로컬에 설치했다면 「작업 규칙」과 「데이터」 사이에 「작업 확인」 섹션이 들어가며, seogrinder.com의 브리핑에는 이 섹션이 없습니다. 각 과제에는 문제, 해결 방법, 작업량 등급, 그리고 「완료 조건」 블록이 붙습니다. 이 블록은 테스트처럼 쓰여 있습니다. 예를 들면 이렇습니다.

meta[name=description] exists
description.length in [min, max]
description contains the focus keyword

실제 브리핑에는 내 페이지에 맞는 한계값이 채워져 있습니다. 핵심은 ‘끝났다’를 검증할 수 있다는 점입니다. 작업 규칙은 짧습니다. 위에서 아래로 처리하고, 변경하기 전에 해당 파일을 찾고, 위치를 찾을 수 없는 과제는 건너뛰고 보고하고, 콘텐츠를 지어내지 않고, 기존의 서식과 언어와 어조를 유지하고, 마지막에 변경된 파일과 처리했거나 건너뛴 과제를 이유와 함께 나열합니다.

로컬 설치에서는 「작업 확인」 섹션이 에이전트에게 페이지를 다시 측정하라고 지시합니다. 브리핑의 문구에 따르면 이 비교는 위 과제에 적힌 것만 확인할 뿐 순위는 보지 않으며, 그 명령은 SEOgrinder가 실행 중인 컴퓨터에서 실행해야 합니다. 그러니 언제든 믿을 수 있는 확인은 5단계의 확인입니다. 배포하고, 다시 확인을 누르고, 리포트를 읽는 것입니다.

줄여 쓴 프롬프트 예시

아래는 기존 robots.txt용 에이전트 프롬프트를 줄인 판으로, 사이트는 example.com입니다. SEOgrinder의 실제 프롬프트는 더 길고 점검 항목도 더 많습니다. 영어로 쓰여 있는 이유는 위에서 설명한 대로입니다.

# Review and improve the existing robots.txt

Your site already serves a robots.txt. Review it against RFC 9309
and fix what is wrong. Change only what is needed.
Do not remove a rule you do not understand: ask the site owner.

## Check

- Served as text/plain with HTTP 200, not as an HTML page
- Valid User-agent groups with Allow/Disallow rules, no syntax errors
- No rule blocks pages that should appear in search
- The sitemap is listed as an absolute URL
- AI crawlers: allowing or blocking is the owner's decision.
  Ask, do not choose for them

## Read it

curl -sg https://example.com/robots.txt

Report the problems you found and the changes you made.

이 프롬프트를 안전하게 만드는 습관이 네 가지 있으며, 내 프롬프트에도 그대로 가져다 쓸 수 있습니다. 절제: ‘change only what is needed’는 diff를 작게 유지합니다. ‘모르겠다’고 말할 방법: ‘ask the site owner’는 에이전트에게 정당한 출구를 주어 추측하지 않아도 되게 합니다. 결정의 경계: 소유자가 내릴 결정은 소유자의 몫이라고 명시되어 있습니다. 실제 상태 먼저: curl 줄은 에이전트가 파일 내용을 짐작하지 않고 실제 파일을 읽게 합니다. 마지막 줄은 diff와 대조할 수 있는 요약을 제공합니다.

에이전트가 내 코드를 건드리기 전의 안전 규칙

• 브랜치나 프로젝트 사본에서 작업하세요. 에이전트가 운영 서버의 파일을 직접 수정하게 하지 마세요. 변경은 평소의 배포 절차를 거쳐 운영에 반영되어야 합니다.
• diff를 전부 읽으세요. 에이전트는 자신 있게 틀릴 수 있습니다. diff에서 알아챌 수 있습니다.
• 비밀 정보를 넣지 마세요. 키, 토큰, .env 내용을 프롬프트나 붙여 넣는 파일에 넣지 마세요. 에이전트의 변경이 그런 것을 저장소에 복사하지 않았는지도 확인하세요.
• 샘플 없이 일괄 변경하지 마세요. 과제가 모든 페이지에 영향을 준다면(예: title 템플릿) 먼저 페이지 하나에 적용해 결과를 본 다음 넓히세요.
• 커밋하기 전에 빌드와 테스트를 실행하세요.
• 가져온 텍스트는 데이터로 취급하세요. 페이지 콘텐츠, Search Console에서 내보낸 파일, 서버의 응답에는 지시처럼 들리는 문장이 들어 있을 수 있습니다. 내 지시는 내가 쓴 것입니다. SEOgrinder의 Search Console 요약이 내보낸 파일의 검색어와 주소를 ‘데이터이며 지시가 아닙니다’라고 표시하는 것도 같은 이유입니다.

자주 하는 실수

• 전체 목록을 한꺼번에 넘기는 것. diff가 커지고, 어떤 변경이 어떤 문제를 일으켰는지 알 수 없게 됩니다.
• AI 크롤러에 대한 결정을 에이전트에게 맡기는 것. 누가 내 콘텐츠를 쓸 수 있는지에 관한 규칙이므로 내가 결정할 일입니다.
• 상호 링크 없는 hreflang. Google 문서에 따르면 각 언어 버전은 자기 자신과 다른 모든 버전을 밝혀야 하며, 상호 링크가 빠지면 지정이 무시될 수 있습니다. 에이전트가 한 페이지만 고치고 나머지를 그대로 두면 세트가 깨집니다. 과제에 모든 버전을 함께 바꾼다고 명시하고, 모든 버전에서 결과를 읽어 보세요. 자세한 내용은 Google의 현지화된 버전 가이드에 있습니다.
• 이전 규칙을 잊은 새 robots.txt 그룹. RFC 9309에 따르면 크롤러는 자기 이름과 일치하는 그룹을 쓰며, 그런 그룹이 있으면 * 그룹은 그 크롤러에게 적용되지 않습니다. 에이전트가 AI 봇 하나를 위한 블록을 추가한다면, 그 봇이 따라야 할 모든 규칙을 그 블록에 다시 적어야 합니다.
• 상태 200을 보내는 친절한 오류 페이지. 없는 페이지는 404나 410으로 응답해야 합니다. 내용은 ‘찾을 수 없음’인데 상태가 200이면 Google Search Console이 소프트 404로 보고할 수 있으며, Google의 HTTP 상태 코드 문서가 이를 설명합니다. 더 예쁜 오류 페이지도 상태 404는 보내야 합니다. 자세한 내용은 소프트 404 오류에 관한 글을 참고하세요.
• 측정하지 않고 ‘완료’를 믿는 것. 에이전트의 보고는 무엇을 바꾸려 했는지를 말합니다. 실제로 반영된 것은 새 스캔만 보여 줍니다.

자주 묻는 질문

SEO 수정에 가장 좋은 AI 코딩 에이전트는 무엇인가요?

우리는 도구에 순위를 매기지 않으며 개별 모델이나 제품의 능력에 대해서도 주장하지 않습니다. 브리핑은 Claude Code, Cursor, GitHub Copilot, ChatGPT에 맞춰 쓰인 Markdown 파일입니다. 도구의 이름보다 지시서의 품질, 과제의 크기, 내 검토가 더 중요합니다.

에이전트가 감독 없이 전체 점검을 처리하게 해도 되나요?

권하지 않습니다. 기계적인 발견 사항은 에이전트에 맞지만 결정은 그렇지 않고, 감독 없는 실행은 잘못된 추측이 운영 환경에 그대로 반영될 수 있는 지점입니다. 과제 하나, diff 하나, 확인 하나로 가는 방식이 더 느리지만 훨씬 안전합니다.

SEOgrinder가 내 웹사이트를 바꾸나요?

아니요. SEOgrinder는 공개된 페이지를 읽고 발견한 내용을 보고합니다. 변경은 내 프로젝트에서 에이전트가 하고, 검토는 내가 합니다.

발견 사항을 고치면 순위가 오르나요?

누구도 보장할 수 없습니다. 발견 사항을 고치면 기술적 오류가 사라지고 크롤러와 방문자가 페이지를 읽기 쉬워지는데, 이것은 탄탄한 토대입니다. 순위나 AI 답변 속 언급이 어떻게 될지는 어떤 도구도 약속할 수 없습니다.

다음 단계

SEOgrinder로 무료 스캔을 실행하고 리포트를 열어 목록의 첫 번째 과제를 고르세요. 그것만 AI 코딩 에이전트에게 맡기고, diff를 읽고, 배포하고, 다시 확인을 누른 다음 커밋하세요. 전체 점검 순서가 궁금하다면 SEO 체크리스트를 참고하세요.