GitHub 활동을 Notion & DEV.to 블로그로 자동 변환!
GitHub 활동을 GraphQL API를 통해 수집하여, 매주 개발 활동을 자동 기록하는 DevNotion 구축
Gemini를 활용하여 수집된 데이터를 1인칭 시점의 블로그 게시물로 생성하고, Notion과 DEV.to에 동시 게시
Mastra를 사용하여 3개의 에이전트(수집, 생성, 게시) 파이프라인을 구축하여 확장성 및 유지보수성 확보
Notion MCP(Model Context Protocol)를 활용하여 Notion API를 효율적으로 사용하고, Markdown Content API를 통해 페이지 레이아웃 구성
GitHub Actions를 통해 자동화된 배포 파이프라인 구축 및 API Rate Limit 문제 해결
3-Agent 파이프라인 아키텍처
DevNotion은 3개의 독립적인 에이전트(Agent)로 구성된 파이프라인 아키텍처를 채택하여 각 단계별 책임 분리(Separation of Concerns)를 구현했다.
github-harvest-agent: GitHub GraphQL API를 호출하여 주간 활동 데이터를 확정적으로(Deterministic) 수집
narrator-agent: Gemini를 사용하여 수집된 데이터를 1인칭 블로그 게시물로 생성하며, LLM(Large Language Model) 실패 시 폴백(Fallback) 메커니즘을 통해 안정성 확보
publisher-agent: Notion 페이지 생성 및 DEV.to 초안 게시를 담당하며, Notion MCP(Model Context Protocol)와 직접 API 호출을 혼합하여 유연성 확보
이러한 구조는 각 에이전트의 단일 책임 원칙(Single Responsibility Principle)을 준수하며, 디버깅 및 유지보수성을 향상시킨다.
Gemini를 활용한 블로그 게시물 생성
Narrator-agent는 Gemini를 사용하여 GitHub 활동 데이터를 기반으로 블로그 게시물을 생성하며, 다양한 톤 프로파일(Tone Profile)을 지원한다.
시스템 프롬프트(System Prompt): 1인칭 시점, 기술 스택, OSS(Open Source Software) 작업 언급 등 개인화된(Personalized) 블로그 스타일 정의
YAML Frontmatter: 생성된 블로그 게시물에 메타데이터(Metadata)를 포함하여 Notion 및 DEV.to에서 활용
폴백 체인(Fallback Chain): Gemini 사용 불가 시, 확정적(Deterministic) 폴백 메커니즘을 통해 기본적인 블로그 게시물 생성
LLM의 할루시네이션(Hallucination) 위험을 줄이기 위해, 수집 및 게시 단계는 LLM을 사용하지 않고, 필요한 경우에만 활용한다.
Notion MCP 및 Markdown Content API 활용
DevNotion은 Notion API를 효율적으로 사용하기 위해 Notion MCP(Model Context Protocol)와 Markdown Content API를 적극적으로 활용한다.
Notion MCP: Mastra의 MCP 클라이언트를 통해 Notion API의 모든 기능(Full API Surface)에 접근 가능
Direct Tools: MCP에서 지원하지 않는 기능(Markdown Content API, DEV.to 게시)은 직접 API 호출을 통해 구현
Markdown Content API: 단일 PATCH 요청(Single PATCH Request)으로 전체 페이지 콘텐츠를 업데이트하여, 페이지 레이아웃 구성 및 API 호출 횟수 감소
이러한 접근 방식은 Notion API Rate Limit 문제를 해결하고, 풍부한 기능의 블로그 게시물 작성을 가능하게 한다.
API Rate Limit 및 안정성 확보 전략
DevNotion은 API Rate Limit 문제를 해결하고, 시스템의 안정성을 확보하기 위해 다양한 전략을 사용한다.
P-Queue 및 P-Retry: P-Queue를 사용하여 API 호출의 동시성을 제어하고, P-Retry를 통해 일시적인 오류(Transient Failure)에 대한 재시도
Rate Limiter: Notion, DEV.to, GitHub GraphQL API에 대한 개별 Rate Limiter 구현
Fallback Chain: Gemini 사용 불가 시, 확정적(Deterministic) 폴백 메커니즘을 통해 블로그 게시물 생성 보장
이러한 전략은 API 사용량 최적화 및 시스템의 가용성(Availability)을 향상시킨다.
Zod 버전 충돌 문제 해결
DevNotion 개발 과정에서 Zod 버전 충돌(Zod Version Conflict)로 인한 문제 발생 및 해결 과정을 보여준다.
문제 상황: Mastra와 DevNotion 코드에서 서로 다른 Zod 버전을 사용하면서, 스키마 유효성 검사(Schema Validation) 실패
해결 방법: PNPM Overrides를 사용하여 모든 의존성에 대해 단일 Zod 버전 강제 적용
교훈: 프로젝트 내에서 사용되는 의존성(Dependency) 버전 관리의 중요성 강조
이러한 경험을 통해, 개발자는 의존성 관리 도구의 기능을 이해하고, 의존성 충돌(Dependency Conflict) 문제를 효과적으로 해결할 수 있다.
