claude code sub agents로 seo 관리하기

S-rim·2025년 12월 13일

개요

프론트엔드 개발을 하다 보면 SEO는 항상 신경 써야 하는 영역입니다. 메타 태그, 이미지 최적화, 구조화된 데이터... 체크해야 할 항목은 많은데 우선순위에서 밀리기 쉽죠. 이 글에서는 Claude Code를 활용해 SEO 작업을 효율적으로 자동화한 경험을 공유합니다.

프론트엔드 개발자가 챙겨야 할 SEO

SEO 작업을 해야하는 시점은 배포 전과 배포 후, 크게 두 시점으로 나눌 수 있습니다.

배포 전에는 h1 태그는 잘 있는지, 이미지가 너무 크진 않은지, 메타 태그는 잘 들어가있는 지, 서버 사이드 렌더링 페이지가 클라이언트 사이드 렌더링으로 잘못 돌아가고 있지는 않은지 등 feature 작업을 하면서 점검해야합니다.

그리고 라이브 배포 후에는 ahrefs와 같은 검색엔진 점검 사이트 기반의 점수가 얼마인지, 놓쳤다거나 발견하지 못했던 부분이 있다면 추가적으로 보완하는 작업이 필요합니다.

배포 전

H1 태그 존재 여부
이미지 용량 최적화
메타 태그 완성도
SSR/CSR 렌더링 방식 검증

배포 전에는 위와 같은 항목들을 feature 작업을 하면서 미리 점검해야합니다.

배포 후

Ahrefs(검색 엔진 툴) 점수 모니터링
놓친 이슈 보완
지속적인 품질 관리

배포 후에는 추가적으로 보완하는 작업이 필요합니다.

이런 작업들을 진행하기 위해 저는 claude code의 sub agent 개념을 활용하면 좋겠다고 생각했습니다.

sub agent란?

특정 유형의 작업을 독립적으로 처리하기 위해 호출할 수 있는 전문화된 AI 어시스턴트입니다.

말은 장황하지만 쉽게 말하자면 담당자입니다.

sub agent는 메인 대화와 분리된 자체 컨텍스트 창을 사용하며, 특정 목적과 전문 영역을 가집니다.

사용자 정의 시스템 프롬프트, 도구 및 별도의 컨텍스트 창을 가진 작업별 구성을 제공하여 더 효율적인 문제 해결을 할 수 있도록 합니다.

sub agent를 생성하는 방법은 간단합니다.

sub agent 생성 방법

claude code 세션에서 /agents 명령 실행
'Create New Agent' 선택, 프로젝트 수준 또는 사용자 수준 중 어느 레벨로 생성할지 선택
1. (서브에이전트 이름이 충돌할 때는 프로젝트 수준 서브 에이전트가 사용자 수준 서브 에이전트보다 우선순위가 높습니다.)
설정
1. 무슨 역할을 하는 지, 언제 써야하는 지 서술합니다. (ex: seo를 점검용으로 코드 리뷰를 하는 sub agent입니다)
2. tool 권한을 부여할 수 있습니다. 아무것도 설정하지 않으면 기본적으로 모든 도구에 접근이 가능하므로 굳이 건드리지 않아도 됩니다.
3. 모델, 색깔 등을 선택할 수 있습니다.
저장 및 사용
1. 이제 저장하고 나면 해당 레벨 내 md파일이 생성됩니다. (ex: .claude/agents/seo-code-reviewer.md )
2. 아래 예시와 같이 명시적으로 호출하여 사용하거나, 해당 agent의 작업이 필요한 느낌 일때 claude code가 알아서 sub agent 환경에서 작업을 시작합니다.
  
  ex)
  
  > code-reviewer 서브에이전트를 사용하여 최근 변경사항을 확인해주세요
  
  > debugger 서브에이전트에게 이 오류를 조사하도록 요청하세요
  
  > 이 프로젝트의 seo 상태를 전체적으로 리뷰해주세요

그래서 이 sub agent 개념을 사용하여 현재 프로젝트 내 seo 코드가 잘 적용이 되어있는지, 품질을 점검해주는 seo-code-reviewer를 생성해봤습니다.

seo-code-reviewer sub agent 추가하기

/agents 명령어를 통해 seo 코드 품질 리뷰어 라고 역할을 작성하면 어떤 것들을 점검하고 어떤 파일들을 점검할 지 자동으로 작성합니다. 거기에 제가 추가로 보완하여 이 sub agent가 주로 확인할 항목들은 총 8가지입니다.

- 메타 태그 & 문서 헤드
    - 필수 메타 태그 유무, 중복 유무
    - 페이지 콘텐츠에 따라 메타 태그가 동적으로 생성되는지 확인
    - Next.js <Head> 컴포넌트가 적절히 사용되었는지
    
- OG, 소셜 미디어 태그
    - Open Graph 프로토콜 구현 검증
    - Twitter 등 소셜 공유 미리보기 렌더링 확인
    
- 구조화 데이터 (JSON-LD)
    - 적절한 [schema.org](http://schema.org) 타입으로 구현이 되었는지 확인(Organization, WebSite, WebPage, BreadcrumbList, BlogPosting 등)
    - 구조화된 데이터가 실제 페이지의 콘텐츠와 일치하는 지 확인
    
- URL 구조 & 정규화
    - canonical URL이 올바르게 설정되었는지 확인
    - URL kebab-case 점검
    
- Next.js 특화 SEO
    - SEO 데이터를 위한 `getServerSideProps` 또는 `getStaticProps` 검토
    - 동적 메타 태그를 위한 `next/head`의 적절한 사용 확인
    - 적절한 alt 텍스트가 있는 Image 컴포넌트 사용 확인
    - 내부 내비게이션을 위한 Link 컴포넌트의 적절한 사용 확인
    - 사이트맵 생성 설정 검증
    - robots.txt 설정 검토
    
- 성능, Core Web Vitals
    - 이미지 컴포넌트 지연 로딩 점검
    - 적절한 이미지 최적화 확인 (next/image)
    
- 접근성, SEO 중복
    - 시맨틱 HTML 구조 검증
    - 적절한 제목 구조 확인 (페이지당 h1 하나)
    - 모든 이미지에 설명적인 alt 텍스트가 있는지 확인
    
- 국제화 SEO
    - 다국어 사이트를 위한 hreflang 태그 점검
    - URL이 언어/로케일 구조를 반영하는지 확인
    - SEO 콘텐츠를 위한 번역 키 검증
    - 적절한 로케일 감지 및 대체(fallback) 확인

sub agents md파일 내에서 발췌하였습니다. 위 사항들을 점검하도록 했고, 한눈에 현재 이 프로젝트의 SEO 상태를 확인하기 위해 점검한 내용을 토대로 10점 만점 기준으로 현재 SEO 점수를 계산하는 채점 시스템을 작성하였습니다. 저는 점수 시스템 기준을 claude code에게 직접 구성하라고 하였습니다.

## SEO 채점 시스템

다음 가중치 카테고리를 기준으로 전체 SEO 점수를 10점 만점으로 계산합니다:

### 채점 세부사항 (총점: 10.0점)

1. **메타 태그 & 문서 헤드** (1.5점)
   - Title 태그: 0.4
   - Description: 0.4
   - Robots & viewport: 0.4
   - 중복 없음: 0.3

2. **Open Graph & 소셜 미디어** (1.0점)
   - OG 태그 완성도: 0.6
   - Twitter Cards: 0.4

3. **구조화된 데이터 (JSON-LD)** (2.0점)
   - 핵심 스키마 (Organization, WebSite): 0.8
   - 페이지별 스키마 (BlogPosting, BreadcrumbList 등): 0.8
   - 유효한 구문 & 필수 필드: 0.4

4. **URL 구조 & 정규화** (1.0점)
   - Canonical URL: 0.5
   - Hreflang 태그: 0.5

5. **시맨틱 HTML & 접근성** (1.5점)
   - H1 태그 존재 & 계층: 0.6
   - 이미지 alt 속성: 0.5
   - 시맨틱 구조: 0.4

6. **기술적 SEO** (1.5점)
   - 사이트맵 설정: 0.5
   - Robots.txt: 0.3
   - 인덱싱 이슈 없음: 0.4
   - 모바일 최적화: 0.3

7. **성능 & Core Web Vitals** (1.0점)
   - 이미지 최적화: 0.5
   - 지연 로딩: 0.3
   - 렌더링 차단 없음: 0.2

8. **국제화 SEO** (0.5점)
   - 적절한 hreflang: 0.3
   - 언어별 URL: 0.2

### 감점 사항
- 치명적 이슈 (깨진 구조화된 데이터, 누락된 title): 각 -0.5
- 중복 메타 태그: 각 -0.3
- 깨진 사이트맵: -0.5
- 다중 h1 태그 또는 h1 누락: -0.4

## 출력 형식
검토 결과를 다음과 같이 구성합니다.

## SEO 코드 리뷰 요약

**SEO 점수: [X.X]/10**

**채점 근거:**
- 메타 태그: [X.X]/1.5
- Open Graph: [X.X]/1.0
- 구조화된 데이터: [X.X]/2.0
- URL & 정규화: [X.X]/1.0
- 시맨틱 HTML: [X.X]/1.5
- 기술적 SEO: [X.X]/1.5
- 성능: [X.X]/1.0
- 국제화 SEO: [X.X]/0.5

### 치명적 이슈 (반드시 수정)
[SEO에 심각한 영향을 미치는 이슈 목록 - 각각 점수에 상당한 감점]

### 중요한 개선사항 (수정 권장)
[중요한 SEO 기회 목록]

### 개선 제안 (추가 고려사항)
[선택적 최적화 목록]

이 sub agent를 사용해 SEO 상태를 점검해달라고 요청했을때의 출력 결과입니다. 이렇게 배포 전에 작업 완료 후 페이지 내 SEO 최적화 작업을 담당하도록 하는 sub agent를 구성해보았습니다.
sub agent 이름을 명시해서 작업을 시작하곤 하는데, 이것조차 프로젝트 내 더 간편하고 통일성있게 사용하고 싶다하면 custom command를 활용할 수 있습니다.

Custom Command

말 그대로 사용자가 직접 정의한 명령어입니다. 자주 사용하는 패턴을 미리 등록해두고 단축키처럼 활용할 수 있습니다.

Custom Command 추가 방법

프로젝트 내 .claude/commands 디렉토리에 마크다운 파일을 생성하면 파일 이름으로 명령어를 추가할 수 있습니다.

seo sub agent 관련하여 예시로 추가해보겠습니다.

.claude/commands/seo-code-review.md 파일을 생성합니다.

이제 Claude 세션에서 /seo-code-review 를 입력하면 seo-code-reviewer sub agent를 사용하여 현재 프로젝트의 seo 상태를 점검하는 워크플로우를 자동 실행합니다.

인수

동적 값 전달의 경우 $1, $2로 해당 위치에 매개변수를 추가할 수 있습니다.

# 명령어 정의  
'Review PR #$1 with priority $2 and assign to $3' > .claude/commands/review-pr.md

# 사용시
> /review-pr 456 high alice
# $1은 "456"이 되고, $2는 "high"가 되고, $3은 "alice"가 됩니다

Custom command vs sub agents

커스텀 커맨드와 서브에이전트 둘다 어느정도 저장해두고 계속 비슷한 형태의 출력을 하게하는 것 아닌가? 라고 생각할 수 있지만 엄연히 개념이 다릅니다.

커스텀 커맨드는 단순 실행, 서브 에이전트는 역할 수행입니다.

📧 Custom Command: 단순 실행

개념

Custom Command는 미리 정의된 체크리스트를 빠르게 실행하는 기능입니다. /review-code처럼 슬래시 명령어로 간단하게 호출할 수 있습니다.

주요 특징

프롬프트를 미리 작성해서 저장해두는 것
반복적인 작업을 자동화하는 명령어 템플릿
단순한 작업에 적합

언제 사용할까?

Custom Command는 다음과 같은 상황에서 빛을 발합니다:

매번 같은 형식으로 반복적인 작업을 할 때

코드 리뷰 체크리스트 실행
테스트 코드 자동 생성
함수에 JSDoc 주석 추가

단순한 변환이나 생성 작업일 때

정해진 포맷으로 문서 변환
표준화된 템플릿 생성

빠른 실행이 중요할 때

한 번의 명령어로 즉시 실행
추가 설정이나 판단 없이 바로 적용

예시

/review-code → 미리 정의된 체크리스트만 빠르게 리뷰

📄 Sub Agent: 역할 수행

개념

Sub Agent는 특정 전문가 역할을 맡아 보안 검토, 전문가 관점의 의사결정, 복잡한 작업 수행 등을 담당하는 AI 에이전트입니다.

주요 특징

해당 직업 담당 전문가를 내 팀에 두는 것
자기 역할을 인식하고 연속적인 의사결정 흐름을 가짐
복잡하고 여러 단계가 필요한 작업에 적합

언제 사용할까?

Sub Agent는 다음과 같은 상황에서 효과적입니다:

전문적인 지식이 필요할 때

보안 전문가 관점에서 깊이 있는 분석
아키텍처 설계 단계에서의 의사결정
React 전문가로서의 최적화 제안

여러 단계의 복잡한 작업일 때

문제 진단 → 해결책 제시 → 구현 → 검증
다단계 리팩토링 프로세스

특정 관점에서 깊이 있는 분석이 필요할 때

성능 최적화 전문가의 상세 분석
보안 취약점 전수 조사

예시

/security-expert agent 사용해서 "이 API 엔드포인트 보안 검토해줘" → 보안 전문가 관점에서 깊이 있게 분석

그렇기 때문에 제가 이 글에서 다뤘던 SEO 점검 작업은 단발성 명령으로 실행하고 끝나는 것이 아니라, 자율적으로 판단하고 후속 분석·리포트까지 이어지는 ‘역할 단위’로 독립시켜서 관리하기 위해 sub agent로 만들었습니다. 물론 custom command와 결합하여 더 간편하고 빠르게 사용할 수 있도록 정의할 수도 있습니다.

결론

Cluade Code는 Custom Command와 Sub Agent와 같은 기능을 통해 작업 특성에 맞는 최적의 자동화를 제공합니다.

작업하기 전에 먼저 이 작업은 반복적인 명령일까, 전문적인 판단이 필요한 일일까? 를 기준으로 한 번 더 생각해보고 활용하면 좋을 것 같습니다.

어떻게 사용하는 지에 따라 작업 효율이 달라지는 것을 경험할 수 있을 것입니다.

개발자가 직접 작업의 성격을 파악하는 것이 자동화의 시작이라고 생각합니다.

S-rim

🤗

이전 포스트

claude code sub agents로 seo 관리하기

개요

프론트엔드 개발자가 챙겨야 할 SEO

sub agent란?

sub agent 생성 방법

seo-code-reviewer sub agent 추가하기

Custom Command

Custom Command 추가 방법

인수

Custom command vs sub agents

📧 Custom Command: 단순 실행

개념

주요 특징

언제 사용할까?

예시

📄 Sub Agent: 역할 수행

개념

주요 특징

언제 사용할까?

예시

결론

CORS

0개의 댓글