SEO Machine: Claude code로 작성하는 SEO 글쓰기

AI가 글을 써주는 시대는 이미 지났습니다. 이제 중요한 건 “글을 한 편 생성하느냐”가 아니라, 검색 의도 분석부터 경쟁사 조사, 초안 작성, 최적화, 발행까지를 하나의 운영 시스템으로 묶을 수 있느냐입니다. SEO Machine은 바로 그 지점을 겨냥한 프로젝트입니다. 단순한 프롬프트 모음이 아니라, Claude Code 위에 올라가는 콘텐츠 생산 워크스페이스에 가깝습니다. (GitHub)

특히 이 저장소가 흥미로운 이유는, “AI에게 블로그 글을 써 달라” 수준에서 멈추지 않고 리서치 → 작성 → 분석 → 최적화 → WordPress 발행까지를 하나의 흐름으로 설계했다는 점입니다. 저장소 설명에서도 이 프로젝트를 long-form SEO 콘텐츠 작성을 위한 Claude Code workspace로 정의하고 있고, 실제로 슬래시 커맨드, 에이전트, Python 분석 모듈, WordPress 연동이 각각 역할을 나눠 갖고 있습니다. (GitHub)

GitHub - TheCraigHewitt/seomachine: A specialized Claude Code workspace for creating long-form, SEO-optimized blog content for a

 

프로젝트 소개

SEO Machine은 TheCraigHewitt 계정에서 공개한 오픈소스 프로젝트로, Claude Code를 기반으로 기업용 SEO 콘텐츠 제작 워크플로를 구성합니다. 저장소 설명에 따르면 이 시스템은 키워드 리서치, 경쟁 콘텐츠 분석, 장문형 블로그 글 작성, SEO 품질 점검, 성과 기반 우선순위 분석, WordPress 발행까지 지원합니다. 또한 원래 Castos를 위해 개발되었고, 이후 어떤 비즈니스에도 적용할 수 있도록 공개되었습니다. (GitHub)

기술적으로 보면 이 프로젝트는 전형적인 웹 애플리케이션이라기보다 Claude Code용 오퍼레이팅 레이어입니다. 핵심 구성은 세 가지입니다. 첫째, .claude/commands에 들어 있는 슬래시 커맨드. 둘째, .claude/agents에 들어 있는 역할별 분석 에이전트. 셋째, data_sources/modules에 들어 있는 Python 분석 및 데이터 수집 모듈입니다. 여기에 context/ 디렉터리로 브랜드 보이스와 스타일 가이드, 키워드 전략을 주입하고, wordpress/ 디렉터리로 최종 발행 경로를 연결합니다. (GitHub)

의존성도 이 구조를 잘 보여줍니다. Google Analytics Data API, Search Console API, DataForSEO, pandas, scikit-learn, nltk, textstat, BeautifulSoup, markdown 등이 요구사항에 포함되어 있어, 단순 텍스트 생성기가 아니라 SEO 분석과 성과 기반 의사결정을 함께 수행하도록 설계된 것을 알 수 있습니다. (GitHub)

왜 이 프로젝트가 등장했을까

많은 팀이 AI로 콘텐츠를 만들기 시작했지만, 실제 운영 단계에 들어가면 금방 한계가 드러납니다. 프롬프트 한두 개로는 검색 의도와 경쟁 구도, 내부 링크 전략, 메타 요소, 발행 포맷, 성과 추적을 일관되게 관리하기 어렵습니다. SEO Machine은 이 문제를 “좋은 프롬프트를 더 많이 쓰자”가 아니라, 작업을 명령 체계와 파일 구조로 표준화하자는 방식으로 풀고 있습니다. /research, /write, /optimize, /analyze-existing, /publish-draft 같은 명령이 그 표준화된 입구입니다. (GitHub)

또 하나의 배경은, SEO 콘텐츠가 이제 정적인 문서가 아니라 지속적으로 갱신해야 하는 자산이 되었다는 점입니다. 이 저장소는 신규 작성뿐 아니라 기존 글 분석과 리라이트 흐름도 별도로 제공합니다. /analyze-existing는 현재 글의 건강 점수를 평가하고, /rewrite는 갱신된 정보와 SEO 개선안을 반영해 업데이트 버전을 만듭니다. 이 구조는 “새 글 생성”보다 “기존 자산 최적화”가 중요해진 콘텐츠 팀의 현실을 잘 반영합니다. (GitHub)

즉, SEO Machine은 AI 글쓰기 도구라기보다 콘텐츠 운영 자동화 템플릿에 가깝습니다. LLM을 생산 수단으로만 쓰는 것이 아니라, 리서치와 평가, 발행까지 이어지는 프로세스 안에 묶어두는 것이 핵심입니다. (GitHub)

핵심 기능

1. 슬래시 커맨드 기반 워크플로

이 프로젝트의 중심은 Claude Code 안에서 실행하는 커맨드입니다. /research는 키워드 조사와 상위 10개 경쟁 콘텐츠 분석, 콘텐츠 갭 파악, 아웃라인 생성을 수행하고 결과를 research/에 저장합니다. /write는 이를 바탕으로 2000~3000단어 이상의 장문형 글을 만들고 drafts/에 저장합니다. /optimize는 최종 점검, /publish-draft는 WordPress 발행을 담당합니다. (GitHub)

이 방식의 장점은 프롬프트를 사람이 매번 조립하지 않아도 된다는 점입니다. 개발자 관점에서 보면, 이것은 “LLM 사용법”이 아니라 명령형 인터페이스로 캡슐화된 콘텐츠 파이프라인입니다. 팀원마다 프롬프트 실력이 달라도, 같은 커맨드를 실행하면 비슷한 결과 구조를 기대할 수 있습니다. (GitHub)

2. 에이전트 자동 실행

/write 이후에는 SEO Optimizer, Meta Creator, Internal Linker, Keyword Mapper 같은 에이전트가 자동으로 후속 분석을 수행하도록 설계되어 있습니다. 즉, 초안을 만든 뒤 별도의 수동 점검 없이도 온페이지 SEO, 메타 태그 옵션, 내부 링크 추천, 키워드 밀도 점검이 이어집니다. (GitHub)

이 구조는 소프트웨어 아키텍처 관점에서 꽤 중요합니다. LLM 한 번 호출해서 “최종 결과”를 기대하는 대신, 생성 단계와 검수 단계를 분리했습니다. 생성 모델이 초안을 만들고, 이후 전문 역할을 가진 에이전트가 서로 다른 기준으로 검토합니다. 이건 마치 한 서비스 안에 writer, reviewer, linter를 분리한 셈입니다. (GitHub)

3. 컨텍스트 주입형 콘텐츠 생성

context/brand-voice.md, context/writing-examples.md, context/style-guide.md, context/seo-guidelines.md, context/internal-links-map.md, context/target-keywords.md 같은 파일들이 모든 생성 과정의 기준점이 됩니다. 프로젝트는 이 파일들을 채워 넣으라고 강하게 요구하고 있고, 예제로 Castos용 완성 샘플도 제공합니다. (GitHub)

이 설계는 RAG와 비슷하지만, 검색 기반 지식 질의보다 운영 정책 주입에 더 가깝습니다. 브랜드 보이스, CTA 방식, 내부 링크 정책, 주요 기능 설명이 파일로 관리되기 때문에, 팀 차원의 일관성을 프롬프트 바깥에서 유지할 수 있습니다. 즉, 사람이 매번 “우리 톤은 이렇고, CTA는 이렇게 하고…”를 길게 입력할 필요가 없습니다. (GitHub)

4. Python 기반 SEO 분석 파이프라인

Content Analyzer 에이전트는 search_intent_analyzer.py, keyword_analyzer.py, content_length_comparator.py, readability_scorer.py, seo_quality_rater.py 같은 모듈을 조합해 글을 평가합니다. 문서상으로는 검색 의도 분류, 키워드 밀도·분포 분석, SERP 대비 분량 비교, 가독성 계산, 종합 SEO 점수 산정이 핵심입니다. (GitHub)

특히 seo_quality_rater.py는 최소 단어 수, 내부/외부 링크 수, 메타 제목·설명 길이, H2 개수, 문장 길이, 읽기 수준 등을 기준으로 카테고리별 점수를 계산하고, 최종적으로 publishing_ready 여부까지 반환합니다. 즉, “그럴듯한 문장”이 아니라 배포 가능한 글인지를 정량적으로 판정하려는 시도입니다. (GitHub)

5. 실측 데이터 기반 우선순위 분석

이 프로젝트는 단순히 새 글을 잘 쓰는 데서 끝나지 않습니다. GA4, GSC, DataForSEO를 통합하는 DataAggregator가 있고, quick wins, declining content, low CTR, trending topics 같은 기회를 뽑아냅니다. 검색 노출은 높지만 CTR이 낮은 글, 11~20위에 걸쳐 있는 키워드, 트래픽이 감소하는 문서 등을 찾아내는 식입니다. (GitHub)

또 OpportunityScorer는 볼륨 25%, 포지션 20%, 의도 20%, 경쟁도 15%, 클러스터 가치 10%, CTR 5%, 신선도 5%, 트렌드 5%라는 가중치를 사용해 SEO 기회를 점수화합니다. 이 부분은 콘텐츠 팀의 감각적 판단을 우선순위 알고리즘으로 바꾸려는 시도로 볼 수 있습니다. (GitHub)

6. WordPress + Yoast 메타 발행

최종 단계에서는 WordPress REST API를 통해 초안을 발행할 수 있고, 커스텀 MU-plugin 또는 functions.php 스니펫을 통해 Yoast SEO 필드를 REST API에서 읽고 쓸 수 있게 만듭니다. focus keyphrase, SEO title, meta description을 API 요청에 포함할 수 있도록 열어두는 구조입니다. (GitHub)

이건 작은 기능처럼 보여도 실제 운영에선 매우 중요합니다. 많은 AI 콘텐츠 도구가 “글 생성”까지만 하고 끝나는데, SEO Machine은 CMS 반영까지 자동화 범위에 포함합니다. 다시 말해, 이 저장소의 목적은 글쓰기 자체보다 콘텐츠 공급망 자동화에 더 가깝습니다. (GitHub)

프로젝트 아키텍처 분석

이 저장소를 아키텍처 관점에서 보면, 전형적인 LLM 애플리케이션보다 훨씬 운영형 구조에 가깝습니다.

이 구조에서 가장 중요한 포인트는 명령, 에이전트, 분석 모듈, 외부 데이터 소스가 느슨하게 역할 분리되어 있다는 점입니다. 커맨드는 워크플로를 오케스트레이션하고, 에이전트는 역할 기반 검토를 수행하고, Python 모듈은 정량 분석을 담당하며, 외부 데이터 소스는 실제 성과 데이터를 공급합니다. 저장소의 디렉터리 구조도 정확히 이 책임 분리를 반영합니다. (GitHub)

이걸 개발자식으로 표현하면, SEO Machine은 “LLM prompt pack”이 아니라 file-based workflow engine for content ops입니다. 코드 실행 런타임이 메인 제품은 아니지만, Claude Code를 orchestration shell로 쓰고, 파일 시스템을 상태 저장소처럼 활용하며, Python 모듈과 외부 API를 보조 서비스처럼 붙인 구조입니다. (GitHub)

내부 동작을 조금 더 현실적으로 풀어보면

예를 들어 사용자가 /research podcast editing software를 실행한다고 가정해 보겠습니다. 그러면 시스템은 우선 대상 토픽에 대한 키워드와 SERP를 조사하고, 상위 경쟁 문서에서 공통 섹션과 빠진 주제를 정리한 뒤, 자사 관점에서 차별화 가능한 아웃라인을 research/에 저장합니다. 그 다음 /write는 이 리서치 결과와 context/에 있는 브랜드 정보, SEO 규칙, 내부 링크 정책을 읽어 장문 초안을 만듭니다. 이후 자동 실행된 에이전트들이 키워드 배치, 메타 요소, 링크 전략을 점검하고, 필요하면 /optimize가 마지막 폴리싱을 수행합니다. 마지막으로 /publish-draft는 WordPress REST API를 통해 본문과 Yoast 메타를 함께 발행합니다. (GitHub)

이 흐름이 좋은 이유는, 사람이 매 단계마다 “다음엔 뭘 해야 하지?”를 고민하지 않아도 되기 때문입니다. 결국 이 프로젝트는 AI를 잘 쓰는 법을 가르치기보다, 콘텐츠 팀의 업무 순서를 강제하는 도구에 가깝습니다. 그래서 개인 창작자보다, 여러 명이 같은 규칙으로 운영해야 하는 팀에서 더 빛날 가능성이 큽니다. (GitHub)

코드 예제로 보면 더 이해가 쉽다

이 저장소의 핵심 중 하나는 데이터 소스를 합쳐 성과를 읽는 부분입니다. 문서에 소개된 DataAggregator 사용 예시는 대략 이런 흐름입니다. (GitHub)

from data_sources.modules.data_aggregator import DataAggregator

aggregator = DataAggregator()

performance = aggregator.get_comprehensive_page_performance(
    url="/blog/podcast-monetization-guide",
    days=30
)

print(performance["ga4"])
print(performance["gsc"])
print(performance["dataforseo"])

이 코드는 단일 URL에 대해 GA4 트래픽 추세, GSC 검색 성과, 그리고 상위 키워드 기반 DataForSEO 랭킹 데이터를 한 번에 모아줍니다. 블로그 운영에서는 “이 글이 왜 안 오르지?”라는 질문이 자주 나오는데, 그때 원인을 하나의 지표로 보지 않고 트래픽, 노출, 순위를 함께 봐야 합니다. SEO Machine은 바로 이 지점을 기본 구조에 넣어 둡니다. (GitHub)

SEO 품질 점검도 코드 레벨에서 감이 옵니다. seo_quality_rater.py는 길이, 메타 요소, 구조, 링크, 가독성을 가중치로 합산해 점수를 계산합니다. 문서상 가중치는 content 20%, keywords 25%, meta 15%, structure 15%, links 15%, readability 10%입니다. (GitHub)

from data_sources.modules.seo_quality_rater import SEOQualityRater

rater = SEOQualityRater()

result = rater.rate(
    content=article_markdown,
    meta_title="Best Podcast Editing Software for 2026",
    meta_description="Compare podcast editing tools by workflow, cost, and features.",
    primary_keyword="podcast editing software",
    secondary_keywords=["audio editing for podcasters", "podcast editor tools"],
    keyword_density=1.4,
    internal_link_count=4,
    external_link_count=3
)

print(result["overall_score"])
print(result["publishing_ready"])
print(result["critical_issues"])

이런 형태는 일반적인 AI 글쓰기 도구와 차이가 큽니다. 대부분은 “생성”은 잘하지만 “품질 게이트”는 약합니다. 반면 이 프로젝트는 배포 전 점검 로직을 코드화해 두었습니다. 개발팀이 CI에 린터를 붙이듯, 콘텐츠 팀에 SEO 린터를 붙인 셈입니다. (GitHub)

이 프로젝트를 언제 쓰면 좋을까

SEO Machine은 다음과 같은 팀에 특히 잘 맞습니다.

첫째, SaaS나 B2B 기업처럼 장문형 SEO 콘텐츠를 꾸준히 생산해야 하는 팀입니다. 저장소 자체도 Castos 사례를 예시로 들고 있고, brand voice·feature map·internal links map을 채워 넣는 구조라서 제품 중심의 콘텐츠 운영과 잘 맞습니다. (GitHub)

둘째, “글 생성”보다 “운영 표준화”가 더 중요한 팀입니다. 한 명의 숙련된 콘텐츠 마케터가 모든 걸 수작업으로 하는 조직보다, 여러 작성자가 같은 규칙으로 움직여야 하는 조직에서 효과가 큽니다. 슬래시 커맨드와 컨텍스트 파일이 일종의 운영 매뉴얼 역할을 하기 때문입니다. (GitHub)

셋째, 이미 WordPress와 SEO 툴 체인을 갖고 있는 팀입니다. 이 프로젝트는 WordPress 발행, Yoast 메타 필드 제어, GA4/GSC/DataForSEO 연동을 전제로 할 때 가치가 커집니다. 반대로 Notion만 쓰거나 CMS가 전혀 다른 환경이라면, 일부 구성은 수정이 필요합니다. (GitHub)

장점과 한계도 분명하다

장점부터 보면, 이 저장소는 AI 콘텐츠를 “한 번의 생성”이 아니라 “운영 가능한 파이프라인”으로 바라봅니다. 그리고 실제로 그 파이프라인에 필요한 요소들, 즉 명령 체계, 역할형 에이전트, 분석 코드, 성과 데이터 통합, 발행 경로를 모두 넣어 두었습니다. 이 점은 꽤 강력합니다. (GitHub)

반면 한계도 있습니다. 이 프로젝트는 범용 제품이라기보다 Claude Code에 최적화된 워크스페이스 템플릿입니다. 즉, GUI 중심의 SaaS를 기대하면 안 됩니다. 제대로 쓰려면 Claude Code 사용 방식, context 파일 관리, WordPress 설정, 외부 API 자격 증명, SEO 운영 프로세스에 대한 이해가 필요합니다. 또 몇몇 문서는 템플릿 성격이 강하고, 실제 효과는 팀이 얼마나 컨텍스트 파일을 잘 채우는지에 크게 좌우됩니다. (GitHub)

그래서 이 저장소는 “AI가 알아서 블로그를 운영해 준다”는 마법 상자가 아닙니다. 오히려 개발자나 기술 친화적인 마케팅 팀이 직접 자기 회사의 콘텐츠 운영체계를 코드와 파일로 정리해 넣을 때 비로소 힘이 납니다. (GitHub)

한 문장으로 정리하면

SEO Machine은 AI 블로그 생성기가 아닙니다. Claude Code 위에서 동작하는 SEO 콘텐츠 운영 시스템입니다. 커맨드로 워크플로를 정의하고, 에이전트로 역할을 나누고, Python 모듈로 품질과 성과를 분석하며, WordPress까지 연결합니다. AI가 글을 “써주는” 단계에서 멈추지 않고, 팀이 콘텐츠를 “운영하는” 단계로 넘어가고 싶다면 꽤 인상적인 레퍼런스가 될 수 있는 프로젝트입니다. (GitHub)