전문가용 시작

이 매뉴얼은 블로그를 한 번이라도 운영해 봤고, 터미널에서 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-optimization이 정책 위반 가능성이 있는 글을 발행 전에 걸러 냅니다. 검수를 통과해야 합니다. 저가치 콘텐츠는 자동으로 플래그되고, AdSense가 이미 플래그한 글은 “draft로 되돌리기” 워크플로로 빠집니다. 이 추적은 로컬에만 남고 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 흐름으로 다시 풀립니다.

한 글, 두 언어

한글이 source입니다. 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 0~~5 흐름, 보안 기준선 S1~~S8이 전부 여기 모여 있습니다. 두 자동화 도구의 진입점이 한 canonical 문서를 공유하기 때문에, Claude Code에서 잡힌 결정이 Codex 세션에서도 그대로 통합니다. AI-smell 게이트의 점수 임계값도 blog-orchestrator와 이 문서가 같은 값을 쓰고, 한쪽에서 다시 정의하지 않습니다.

지금 빠져 있는 것

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

콘텐츠 쪽에서도 빈 자리가 있습니다. fork 직후 _workspace/는 골격뿐이고, 블로그 정체성(.claude/product-marketing-context.md)도 placeholder입니다. 이 매뉴얼이 가르치는 건 그 빈 골격이 /start와 Phase 흐름을 거치며 어떻게 채워지는지의 절차이지, blog-studio 자체에 들어있는 발행물 샘플이 아닙니다.

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

OS별 설치 분기, Python 버전 매니저 선택, Google Cloud 콘솔에서 OAuth 자격증명 발급하는 화면 캡처, 터미널이 처음인 사람을 위한 단계별 안내는 여기 없습니다. 그쪽이 필요하면 비개발자용 매뉴얼을 봅니다. 같은 base를 다른 호흡으로 푼 짝입니다.

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