전문가용 시작

이 매뉴얼은 블로그를 한 번이라도 운영해 봤고, 터미널에서 git과 Python을 다뤄 봤고, Claude Code 또는 Codex로 글이나 코드를 맡겨 본 적 있는 독자를 가정합니다. Blogger API나 AdSense 정책을 외워 둘 필요는 없습니다. 자동 발행과 OAuth 자격증명은 다음 섹션들에서 설명합니다.

여기서 다루는 것은 명령 목록이 아니라 “왜 이런 구조인지”입니다. 구조가 왜 이렇게 정해졌는지를 한 번 읽고 architecture로 넘어가야 그 뒤의 verification과 publishing이 의미 있게 읽힙니다.

풀려는 문제 한 줄

AI에게 블로그 글을 맡기면 첫 두세 문단은 멀쩡하게 나옵니다. 그다음부터 문체가 흐트러집니다. 한 문단에 em-dash가 세 개씩 들어가고, “단순히 X가 아니라 Y”가 반복되고, 도입부가 결론부터 꺼내고, 일반적인 형용사가 내용을 대신 채웁니다. 거기에 AdSense 정책에 걸릴 저품질 신호가 섞이고, 한글본과 영문본이 서로 어긋나고, 검색에는 잡혀도 Claude나 ChatGPT가 인용하지 않는 글이 쌓입니다. blog-studio는 그런 지점마다 게이트와 트랙을 배치해 둔 출발점입니다.

발행 직전을 막는 두 게이트

AI-smell 게이트

ai-pattern-check가 14개 항목으로 AI 문체를 0~100점으로 점수화합니다. 점수가 높을수록 AI가 쓴 티가 강합니다.

판정	점수	동작
합격	30 미만	Phase 5 발행으로 진행합니다
경고	30 ~ 60	명백한 문제를 먼저 고치고, 전체 자동화를 요청받은 경우에만 진행하며 사유를 보고서에 남깁니다
불합격	60 초과	발행을 차단합니다. Phase 2로 돌아가 최대 2회까지 다시 씁니다. 그래도 실패하면 사용자에게 넘깁니다

불합격한 글은 scripts/deploy_to_blogger.py가 업로드를 거부합니다. 게이트를 코드 차원에서 강제하기 때문에, 오케스트레이터를 우회해 스크립트를 직접 실행해도 막힙니다. --skip-gate는 재발행이나 긴급 상황에만 쓰도록 남겨 둔 통로입니다.

AdSense 게이트

adsense-optimization이 정책을 위반할 가능성이 있는 글을 발행 전에 걸러 냅니다. 이 검수를 통과해야 발행할 수 있습니다. 가치가 낮은 콘텐츠는 자동으로 표시되고, AdSense가 이미 문제로 표시한 글은 “초안으로 되돌리기” 작업 흐름으로 넘어갑니다. 이 추적 기록은 로컬에만 남고 git에 커밋되지 않습니다.

집필과 마케팅, 두 트랙

진입점이 둘로 나뉩니다.

blog-orchestrator는 글을 씁니다. Phase 0(오리엔테이션)부터 Strategy와 Production, Quality, AI Pattern Gate, Publish까지 끌고 갑니다. 시작 신호는 자연어입니다. “X 주제로 글 써줘”, “검수까지만 해줘”, “발행까지 해줘” 같은 말이 필요한 Phase 범위를 결정합니다.

marketing-director는 발행 후 배포를 맡습니다. X 스레드와 Reddit, Hacker News로 글을 알리고, AI-SEO로 LLM 인용 가능성을 높입니다. 집필 트랙과 분리된 진입점이라서, 글을 쓰지 않고 이미 발행된 글의 배포만 실행할 수도 있습니다.

두 트랙은 architecture에서 에이전트 팀과 Phase 흐름으로 다시 설명합니다.

한 글, 두 언어

한글본이 원본입니다. blog-localization이 영문 번역본을 만들고, _workspace/posts/{ko,en}/에 같은 구조로 쌓입니다. hreflang 태그는 frontmatter의 hreflang_en과 hreflang_ko로 양쪽을 묶어 자동으로 들어갑니다. 한 글이 두 언어 URL을 갖되, 두 본문이 서로 어긋나는 것을 frontmatter 계약이 막습니다.

자동화 진입점은 한 곳을 가리킵니다

Claude Code 쪽 진입점은 .claude/agents/와 .claude/skills/입니다. Codex 쪽 진입점은 저장소 루트의 AGENTS.md입니다. 두 경로 모두 결국 같은 파일 하나를 읽습니다.

그 파일이 AI_AUTOMATION.md입니다. Runtime 매핑과 Module Source Map, 디렉터리 계약, 지원하는 사용자 의도, Phase 05 흐름, 보안 기준선 S1S8이 전부 여기 모여 있습니다. 두 자동화 도구의 진입점이 하나의 기준 문서를 공유하기 때문에, Claude Code에서 내린 결정이 Codex 세션에서도 그대로 통합니다. AI-smell 게이트의 점수 기준값도 blog-orchestrator와 이 문서가 같은 값을 쓰고, 한쪽에서 다시 정의하지 않습니다.

지금 빠져 있는 것

이 base는 솔직히 미완성인 부분이 있습니다. 매뉴얼과 랜딩 페이지는 공개돼 있지만, 템플릿 자체는 상업 라이선스 모델입니다. 그런데 결제 흐름과 구매자 자격 확인이 아직 붙지 않았습니다. COMMERCIAL-LICENSE.md도 초안 상태이고 변호사 검토가 끝나지 않았습니다. 실제 판매를 시작하기 전에 둘 다 마무리해야 합니다.

콘텐츠 쪽에도 비어 있는 부분이 있습니다. fork 직후 _workspace/는 구조만 있고, 블로그 정체성(.claude/product-marketing-context.md)도 자리 표시 값입니다. 이 매뉴얼이 가르치는 것은 그 빈 구조가 /start와 Phase 흐름을 거치며 어떻게 채워지는지에 대한 절차이지, blog-studio에 들어 있는 발행물 샘플이 아닙니다.

이 매뉴얼이 가정하지 않는 것

운영체제별 설치 분기, Python 버전 관리 도구 선택, Google Cloud 콘솔에서 OAuth 자격증명을 발급하는 화면 캡처, 터미널이 처음인 사람을 위한 단계별 안내는 여기 없습니다. 그런 내용이 필요하면 비개발자용 매뉴얼을 봅니다. 같은 base를 다른 방식으로 설명한 한 쌍입니다.

다음

다음 섹션은 architecture입니다. 에이전트 여섯이 Phase 0~5에서 어떻게 맞물리는지, 집필과 마케팅 두 트랙이 어디서 갈라지는지, 모든 산출물이 _workspace/ 한 폴더 안에 격리되는 계약이 어떤 모습인지를 다이어그램 두 개와 함께 봅니다.