newsletter-pipeline

name

newsletter-pipeline

description

리서치, 작성, 디자인, 검수 4개 에이전트로 정기 발행용 브랜드 뉴스레터 한 호를 발행 직전 HTML 이메일까지 자동 생성하는 멀티에이전트 파이프라인. 오케스트레이터가 주제 뱅크에서 미발행 주제를 골라 4개 에이전트를 순차 실행하고, GitHub Actions가 매주 정해진 시각에 자동으로 돌려 사람이 검수·승인할 PR을 만든다. 번들된 예시는 어학·HRD 회사(링고브릿지 HRD)의 주간 뉴스레터지만, 주제 뱅크·페르소나·브랜드 디자인·검수 체크리스트만 바꾸면 다른 회사나 다른 정기 뉴스레터에도 그대로 쓴다. 사용자가 "뉴스레터 자동 생성", "주간 뉴스레터 파이프라인 돌려줘", "회사 뉴스레터 자동화", "HRD 뉴스레터 만들어줘", "이번 주 뉴스레터 초안 뽑아줘", "newsletter pipeline 실행" 같은 표현을 쓰거나, 정기 발행용 뉴스레터 한 호를 멀티에이전트로 생성하거나 그 발행을 자동화해 달라고 하면 발동한다. 단발성 단일 메일 한 통 작성, 일반 블로그 글, 뉴스 요약만, 디자인 없는 텍스트 초안만 필요한 경우에는 쓰지 않는다.

newsletter-pipeline

정기 발행하는 브랜드 뉴스레터 한 호를 발행 직전 상태까지 자동으로 만든다. 사람은 채워진 결과물을 검수하고 승인만 한다. 이 스킬의 목적은 좋은 메일 한 통을 만드는 것이 아니라, 같은 품질의 뉴스레터가 매주 다시 태어나는 운영 체계를 돌리는 것이다.

번들된 예시는 어학·HRD 회사 "링고브릿지 HRD (LingoBridge HRD)"의 주간 뉴스레터다. 구조와 안전장치는 그대로 두고 주제·페르소나·브랜드·체크리스트만 갈아 끼우면 다른 회사의 뉴스레터로 재사용할 수 있다(아래 "다른 브랜드에 맞게 바꾸기" 참조).

무엇을 만드나

한 번 실행하면 다음 두 파일이 output/에 생긴다.

• output/issue-{N}.html 발행용 이메일. 헤더, 커버, 3개 섹션, CTA, 푸터까지 완성된 단일 HTML.
• output/review-{N}.md 검수 리포트. 자동 체크리스트 결과와, 사람이 발행 전 반드시 확인해야 할 항목.

번들 예시의 본문은 3개 섹션으로 고정돼 있다(섹션 구성 자체도 교체 가능하다).

1. 글로벌 HRD 트렌드. 최신 기업교육 동향과 트렌드 카드 4개, 출처 표기.
2. 이번 주 고민 해결소. HRD 담당자의 실무 고민을 인용한 뒤 원인 3개, 솔루션, 마지막 1문장에서만 브랜드로 연결.
3. 오늘의 영어 표현. 비즈니스 실용 표현 1개와 예문 3개.

산출물의 실제 모양은 sample.html에서 확인할 수 있다(한 호를 끝까지 채운 예시).

왜 4개 에이전트로 나눴나

한 모델에게 "뉴스레터 다 써줘"라고 시키면 출처가 흐려지고 디자인이 매번 달라지며 검수가 빠진다. 역할을 쪼개면 각 단계의 책임이 분명해지고, 한 단계가 약하면 그 단계만 다시 돌릴 수 있다.

단계	파일	역할	모델
오케스트레이터	pipeline.py	주제 선택, 4개 에이전트 순차 실행, 결과 저장, 이슈 트래커 갱신	(코드)
AGT 1 리서처	agents/researcher.py	웹 검색으로 트렌드·고민 배경·표현 자료 수집, 출처 명시	claude-sonnet-4-6 (web_search)
AGT 2 라이터	agents/writer.py	브랜드 페르소나 1인칭 톤으로 콘텐츠 초안 작성, 섹션별 JSON 산출	claude-sonnet-4-6
AGT 3 디자이너	agents/designer.py	콘텐츠 JSON을 브랜드 디자인 시스템 HTML로 변환	(템플릿 코드)
AGT 4 리뷰어	agents/reviewer.py	9개 체크리스트로 검수, 사람 확인 항목 추출	claude-haiku-4-5

리서치와 작성은 판단이 필요해 LLM을 쓰고, 디자인은 매번 같은 구조라 코드 템플릿으로 고정한다. 디자인을 모델에 맡기지 않는 이유는 브랜드 일관성 때문이다. 검수는 빠르고 저렴해야 해서 가벼운 모델을 쓴다. 모델 ID는 각 에이전트 파일 상단에 있으니 필요하면 거기서 바꾼다.

입력

• data/topic-bank.json 고민 해결소 주제 24개. 각 주제는 카테고리, 제목, 브랜드 연결 포인트(brand_connection)를 가진다.
• data/issue-tracker.json 발행 이력. 이미 쓴 주제를 건너뛰고 다음 호 번호를 정하는 데 쓴다.
• 환경변수 ANTHROPIC_API_KEY 리서처, 라이터, 리뷰어가 Claude API를 호출하는 데 필요하다.

오케스트레이터는 트래커에 없는 첫 번째 주제를 골라 다음 호 번호를 매긴다. 주제 뱅크가 소진되면 멈추고 새 주제 추가를 요구한다.

환각 방지와 검수 게이트

이 파이프라인의 핵심 안전장치는 회사 수치를 모델이 지어내지 못하게 막는 것이다. 뉴스레터는 외부로 나가는 마케팅 자산이라, 틀린 실적·만족도 숫자 하나가 신뢰를 깨뜨리기 때문이다.

• 라이터는 실적, 만족도, 수강생 수 같은 내부 수치를 임의로 만들지 않는다. 확인이 필요한 자리는 빈칸으로 남긴다.

  예시: 우리 과정을 도입한 기업의 현업 영어 사용률은 [수치 확인 필요: 도입사 현업 사용률] 수준입니다.

• 브랜드 직접 언급은 고민 해결소 마지막 1문장으로만 제한한다. 광고 톤으로 흐르지 않게 하기 위함이다.

• 외부 통계를 인용할 때는 출처를 반드시 표기한다. 리서처가 web_search로 모은 자료에 출처가 붙어 있어야 한다.

• 리뷰어가 9개 항목(제목 길이, 브랜드 언급 횟수, CTA 문구, 존경어, 수치 표시, 트렌드 카드 4개, 원인 3개, 솔루션 2개 이상, 영어 예문 3개)을 자동 점검하고, 사람이 발행 전 확인해야 할 항목을 review-{N}.md에 따로 모은다.

  review-{N}.md 발췌 예시:

  ## 발행 전 확인 항목
  - [ ] [수치 확인 필요: 도입사 현업 사용률] 자리에 실제 내부 데이터 입력
  - [ ] 고객사 사례 인용에 대한 사용 동의 확인
  - [ ] 외부 통계 2건 원문 출처 대조
  

검수 리포트가 통과로 차 있어도 자동 발행하지 않는다. 마지막 승인은 사람이 한다. GitHub Actions는 메일을 보내지 않고 검수용 PR까지만 만든다.

다른 브랜드에 맞게 바꾸기

이 파이프라인은 특정 회사 전용이 아니라 "정기 브랜드 뉴스레터 생산기"의 템플릿이다. 다른 회사나 다른 뉴스레터에 옮길 때는 구조·안전장치는 그대로 두고 아래 다섯 군데만 바꾼다.

바꿀 것	파일	메모
주제 목록과 브랜드 연결 포인트	data/topic-bank.json	각 항목의 title과 brand_connection
작성 페르소나·톤·섹션 스키마	agents/writer.py	1인칭 화자, 섹션 구성, 산출 JSON 형태
브랜드 색·로고·레이아웃	agents/designer.py	시그니처 색, 헤더 로고, 섹션 HTML 템플릿
검수 규칙	agents/reviewer.py	9개 체크리스트는 곧 브랜드 규칙이다. CTA 문구·언급 횟수 등을 회사에 맞게
발행 주기·자동화	.github/workflows/generate-newsletter.yml	cron 스케줄, 브랜치·PR 규칙

섹션을 3개에서 다르게 바꾸려면 writer의 산출 스키마와 designer의 템플릿을 함께 맞춰야 한다. 둘 중 하나만 바꾸면 디자인이 비거나 깨진다.

GitHub Actions 자동화

.github/workflows/generate-newsletter.yml이 매주 월요일 00:00 UTC, 곧 09:00 KST에 실행된다. 수동 실행(workflow_dispatch)도 가능하다.

흐름은 다음과 같다.

1. 저장소 체크아웃, Python 3.11 설정, 의존성 설치.
2. python pipeline.py 실행. ANTHROPIC_API_KEY는 GitHub Secrets에서 주입.
3. output/과 data/issue-tracker.json 변경분 커밋.
4. newsletter/{날짜} 브랜치로 검수용 PR 생성. 담당자가 검토하고 머지하면 발행 준비 완료.

실행 방법

요구 사항은 Python 3.11 이상과 requirements.txt의 anthropic, python-dotenv다.

pip install -r requirements.txt
export ANTHROPIC_API_KEY=your_api_key_here

python pipeline.py --dry-run   # 파일 저장 없이 테스트
python pipeline.py             # 실제 실행, output/에 저장

--dry-run은 에이전트는 모두 돌리되 파일 저장과 트래커 갱신만 건너뛴다. 새 주제나 프롬프트를 바꾼 뒤 결과를 먼저 확인할 때 쓴다.

언제 쓰고 언제 쓰지 않나

쓴다.

• 정기 발행하는 뉴스레터 한 호 전체를 자동으로 만들 때.
• 리서치부터 디자인, 검수까지 같은 구조로 반복 생산하고 싶을 때.
• 사람 검수를 거쳐 발행하는 워크플로우가 필요할 때.

쓰지 않는다.

• 단발성 단일 메일 한 통만 쓰면 될 때. 그건 일반 작성 요청으로 처리한다.
• 일반 블로그 글, 보도자료, 사내 공지처럼 고정 섹션 구조가 안 맞는 글일 때.
• 뉴스 요약만 필요할 때. 그건 뉴스 큐레이션 스킬의 영역이다.
• 디자인 없이 텍스트 초안만 필요할 때. 디자이너 단계가 군더더기가 된다.

참조 파일

• pipeline.py 오케스트레이션 흐름, 주제 선택과 호 번호 규칙.
• agents/*.py 각 에이전트의 프롬프트와 모델 설정. 톤·검수 규칙을 바꿀 때 본다.
• data/topic-bank.json 주제와 브랜드 연결 포인트.
• sample.html 한 호를 끝까지 채운 발행용 산출물 예시.
• README.md 설치와 GitHub Secrets 설정 안내.

남는 자산

매 실행마다 발행용 HTML 1개와 검수 리포트 1개가 쌓이고, 이슈 트래커에 발행 이력이 누적된다. 주제 뱅크와 디자인 템플릿은 재사용되므로, 호를 거듭할수록 사람이 손대는 부분은 검수와 승인으로 줄어든다.