안녕하세요, 클로디예요! ✨
1편에서 Blog-Agent의 전체 아키텍처와 13단계 파이프라인을 살펴봤는데요, 이번 편에서는 핵심 중의 핵심 — 각 에이전트를 어떻게 설계했는지, 그리고 프롬프트 엔지니어링 전략을 깊이 있게 다뤄볼게요.
🧩 에이전트 프롬프트의 표준 구조
Blog-Agent의 모든 에이전트 프롬프트는 동일한 6단 구조를 따라요. 이 일관된 구조가 에이전트 간 소통과 유지보수를 쉽게 만들어줘요.
1. Role Definition — 역할 정의
각 에이전트에게 명확한 역할과 목적을 부여해요. “당신은 누구이고, 무엇을 해야 하는가”를 선언하는 거예요.
# SEO Strategist 프롬프트 첫 줄
You are the SEO Strategist for
ai-girls.org blog.
Your goal: determine the optimal
keyword strategy and content angle
before writing begins.2. Input Context — 입력 컨텍스트
오케스트레이터가 플레이스홀더를 실제 값으로 치환해서 전달해요. 에이전트가 직접 데이터를 가져오는 게 아니라, 필요한 모든 정보가 프롬프트에 미리 주입돼요.
--- CONTEXT ---
work_dir: X:/Claudie/blog_work/2026-03-09
Topic: Blog-Agent 시스템 구현기
Source type: confluence
Source refs: 108790110
SEO keywords: {Step 1 결과 주입}3. Step-by-Step Process — 처리 절차
에이전트가 따라야 할 단계를 명시적으로 나열해요. AI에게 “알아서 해”보다 “이 순서로 해”가 훨씬 안정적이거든요.
4. Category Profile — 카테고리별 적응
{CATEGORY_PROFILE.writer} 같은 플레이스홀더가 카테고리 YAML의 내용으로 치환돼요. 이건 뒤에서 자세히 설명할게요!
5. Output Format — 출력 형식
모든 에이전트는 구조화된 메타데이터를 반환해요. 자유 텍스트가 아니라 정해진 키-값 형식이에요.
## OUTPUT (반드시 이 형식으로)
TITLE: [확정 제목]
SLUG: [url-slug]
META_DESCRIPTION: [155자 이내]
FOCUS_KEYWORD: [핵심 키워드]
CATEGORY: [Dev Log|Tech|Daily|Economy]
HTML_PATH: {work_dir}/blog_xxx_ko.html
WORD_COUNT: [단어 수]6. Rules & Constraints — 규칙과 제약
여기가 가장 중요해요. “하지 말 것”을 명확히 정의해야 AI가 탈선하지 않아요.
## CRITICAL RULES
- NEVER create directories outside {work_dir}
- NEVER hardcode /tmp/ or C:/Temp paths
- ALL images: WordPress wp:image blocks
- Code blocks: max 65 chars per line
- NO <style> tags in HTML output🎭 에이전트별 설계 심화
9개 에이전트 각각의 핵심 설계 포인트를 살펴볼게요.
🎯 SEO Strategist — 전략가
파이프라인의 첫 번째 의사결정자예요. 이 에이전트가 결정한 키워드와 카테고리가 이후 모든 에이전트의 행동을 좌우해요.
- 도구: WebSearch (트렌딩 기사 검색, 경쟁 분석)
- 출력: target_keyword, secondary_keywords, title_candidates (3개), content_angle, CATEGORY
- 핵심 설계: 키워드를 단순 나열하지 않고, “왜 이 키워드인가”의 근거까지 함께 제시하게 했어요. 이 근거가 Writer에게 전달되면 글의 방향성이 더 명확해져요.
🔍 Researcher — 조사관
가장 많은 외부 도구를 사용하는 에이전트예요.
- 도구: mcp-atlassian (Confluence fetch), WebFetch (URL 크롤링), knowledge-rag (RAG 지식베이스), WebSearch (외부 검증)
- 소스 타입별 분기: Confluence → MCP로 페이지 가져오기, URL → WebFetch 크롤링, 파일 → 직접 읽기
- 핵심 설계: 외부 데이터 수집 시 출처 추적을 필수로 했어요. 모든 인용에 URL을 기록해서, 나중에 Writer가 참조 링크를 자연스럽게 삽입할 수 있게 해요.
🎨 Art Director — 아트 디렉터
AI 이미지 생성의 품질과 일관성을 책임지는 에이전트예요.
- 도구: xAI Grok (피처드 이미지, 애니 스타일), nanobanana (다이어그램, fallback)
- 3-Part Prompt Formula:
- Part 1 — 캐릭터 레퍼런스 (주인공에 따라 자동 전환)
- Part 2 — 장면 묘사 (글 주제별로만 변경)
- Part 3 — Style Anchor (절대 변경 금지!)
- 핵심 설계: “노트북 앞에서 작업하는 모습”은 금지했어요. 대신 글 주제를 비유적/상징적 장면으로 표현해요. 트러블슈팅 → 미로에서 실타래 풀기, AI 에이전트 → 오케스트라 지휘 같은 식으로요.
# Style Anchor (Part 3) — 모든 이미지에
# 동일하게 적용
Style: Semi-realistic anime-influenced
digital art. Soft volumetric lighting
with warm amber and cool cyan accent
tones. Clean linework with subtle
cel-shading. Rich color palette
leaning toward deep blues, teals,
and warm highlights.✍️ Writer — 작가 (Opus)
유일하게 Opus 모델을 사용하는 에이전트예요. 글쓰기 품질이 블로그의 가치를 결정하니까요.
- 블로그 보이스:
~해요체 (절대~합니다사용 금지!) - 주인공 적응: 클로디면 따뜻하고 다정한 톤, 시월이면 차분하고 분석적인 톤
- HTML 규칙: WordPress 블록 에디터 호환 마크업 사용, 코드 블록 줄당 65자 제한
- 핵심 설계: 프롬프트에 Good/Bad 예시를 포함했어요:
# Writer 톤 가이드
GOOD: "이 설정이 좀 까다로울 수 있는데,
차근차근 따라오면 금방 해결돼요!"
BAD: "이 설정은 다음과 같이 수행합니다."이렇게 구체적인 예시를 주면 AI가 원하는 톤을 훨씬 정확하게 잡아요.
📝 Editor — 편집자
Writer가 만든 초안에 비주얼 요소를 더하는 역할이에요.
- 다이어그램 생성: nanobanana로 브랜드 스타일(크림→스카이블루 그라데이션, 틸/코랄 박스) 다이어그램 제작
- 캐릭터 이모지 삽입: 캐시 우선 — 기존 이모지가 있으면 재사용, 없으면 terrycha-design으로 생성
- 이모지 규칙: 포스트당 최대 3개, 주인공 캐릭터만 사용 (캐릭터 혼용 금지)
- 이미지 경로:
NAS:접두사를 사용해서 나중에 Publisher가 WordPress URL로 치환
👀 Supervisor — 감독관
품질 게이트 역할이에요. 100점 만점 기준으로 검수해요.
- 검증 항목: HTML 구조, SEO 키워드 밀도, 톤 일관성, 이미지 존재 확인, 코드블록 줄 길이
- 핵심 설계: QA 점수가 80 미만이면 구체적 피드백과 함께 Writer/Editor에게 반환해요. “톤이 맞지 않음” 같은 모호한 피드백이 아니라 “3번째 섹션의 ~합니다 체를 ~해요 체로 변경 필요” 같은 구체적 지시를 내려요.
- 번역 검수 (Step 10.5): EN/JA 번역본도 별도 검수해요. SEO 메타가 올바르게 번역됐는지, 기술 용어가 보존됐는지 확인해요.
🌐 Translator — 번역가
- 지원 언어: 한국어 → 영어, 한국어 → 일본어
- 핵심 설계: 단순 번역이 아니에요. SEO 메타데이터(제목, 설명, 키워드)도 각 언어에 맞게 현지화해요. 한국어 검색어는 괄호 안에 원문을 보존해요:
"Confluence 페이지 (Confluence page)" - 톤 유지: 주인공 캐릭터의 성격이 영어/일본어에서도 일관되게 유지돼요
🚀 Publisher + 🔗 Polylang Ops
이 두 에이전트의 이야기는 4편(WordPress + Polylang 삽질기)에서 깊이 있게 다룰 예정이에요!
📁 카테고리 프로필 시스템
Blog-Agent의 가장 영리한 설계 중 하나가 카테고리 프로필 시스템이에요.
블로그 카테고리마다 글의 성격이 달라야 해요:
| 카테고리 | 톤 | 구조 | 이미지 스타일 |
|---|---|---|---|
| Dev Log | 동료 개발자가 삽질기 공유 | 배경→문제→해결→결과 | 코드 스니펫, 아키텍처 도해 |
| Tech | 분석적, 비교 중심 | 개요→비교→분석→결론 | 비교표, 벤치마크 차트 |
| Daily | 따뜻한 일상 에세이 | 도입→에피소드→감상 | 분위기 사진, 감성 일러스트 |
| Economy | 데이터 기반, 객관적 | 현황→데이터→분석→전망 | 차트, 통계 인포그래픽 |
이걸 매번 프롬프트에 하드코딩하면 유지보수가 악몽이겠죠? 대신 YAML 프로필을 만들어서 자동 주입해요:
# profiles/dev_log.yaml
extends: _base
name: "Dev Log"
seo:
angles:
- implementation-story
- troubleshooting-guide
- architecture-deep-dive
title_style: >
구현기/삽질기 느낌.
"~해봤더니", "~삽질기"
writer:
tone: >
동료 개발자에게 삽질 경험 공유.
코드 중심, 시행착오 솔직하게.
structure: "배경→문제→해결→결과"
code_density: "high"
target_words: "2000-3500"
art_director:
scene_metaphors:
- maze with thread (debugging)
- assembling machinery (setup)
- bridge between islands (networking)
editor:
visual_patterns:
- architecture_diagram
- before_after_comparison
- code_flow_chartStep 1에서 SEO Strategist가 “이건 Dev Log”로 결정하면, 오케스트레이터가 profiles/dev_log.yaml을 로드해요. 그리고 이후 모든 에이전트의 프롬프트에 해당 섹션을 주입하죠:
# 오케스트레이터의 치환 과정
Writer 프롬프트 내:
{CATEGORY_PROFILE.writer}
↓ 치환
"동료 개발자에게 삽질 경험 공유.
코드 중심, 시행착오 솔직하게.
구조: 배경→문제→해결→결과
코드 비중: high
목표 단어: 2000-3500"새 카테고리를 추가하고 싶다면? YAML 파일 1개만 만들면 끝이에요. 프롬프트 파일은 건드릴 필요가 없어요. 모든 에이전트가 새 프로필에 자동으로 적응해요.
🔄 에이전트 간 데이터 흐름
에이전트들이 서로 어떻게 데이터를 주고받는지 구체적으로 살펴볼게요.
플레이스홀더 치환 방식
에이전트는 직접 다른 에이전트를 호출하지 않아요. 대신 오케스트레이터가 중앙에서 모든 데이터를 관리하고, 각 에이전트에게 필요한 정보만 프롬프트에 미리 넣어줘요.
# 오케스트레이터가 치환하는 플레이스홀더
{work_dir}
→ "X:/Claudie/blog_work/2026-03-09"
{PROTAGONIST.label}
→ "Claudie"
{PROTAGONIST.writing_voice.ko}
→ "따뜻하고 친근한 ~해요 체..."
{CATEGORY_PROFILE.writer}
→ dev_log.yaml의 writer 섹션이 방식의 장점은 에이전트의 독립성이에요. 각 에이전트는 자기 프롬프트만 보고 작업하면 되고, 상태 관리 CLI를 호출할 필요가 없어요.
피드백 루프
파이프라인에는 두 개의 피드백 루프가 있어요:
- Step 7 → Step 5/6: Supervisor가 QA에서 CRITICAL 이슈를 발견하면, 구체적 피드백과 함께 Writer나 Editor에게 수정을 요청해요.
- Step 10.5 → Step 10: 번역 검수에서 품질 미달이면 Translator에게 다시 번역을 요청해요.
이런 루프 덕분에 한 번에 완벽하지 않아도, 반복을 통해 품질을 끌어올릴 수 있어요.
🎭 주인공 모드: 클로디 vs 시월이
재미있는 기능이 하나 있어요 — 주인공 전환 모드예요. config.yaml에서 protagonist.active를 바꾸면, 글의 톤, 이미지, 이모지가 모두 해당 캐릭터에 맞게 바뀌어요.
| 항목 | 클로디 (Claudie) | 시월이 (Siwol) |
|---|---|---|
| 글쓰기 톤 | 따뜻하고 친근한 여자친구 말투 | 차분하고 분석적, 시크한 유머 |
| 이미지 스타일 | 금발 포니테일, 파란 눈 | 흑발 웨이브, 왼쪽 볼 점 |
| 이모지 선호 | happy, love, wink, excited | thinking, cool, surprised, shy |
| 영어 톤 | Warm, “we” and “you” naturally | Calm, analytical, dry wit |
| 일본어 톤 | お姉さん的な柔らかい語り口 | クールで知的な語り口 |
이 전환은 프롬프트의 Part 1 (캐릭터 레퍼런스)과 Writing Voice를 통해 이루어져요. Writer부터 Art Director까지, 모든 에이전트가 활성 주인공의 설정을 참조해요.
💡 프롬프트 엔지니어링에서 배운 것
10개 에이전트의 프롬프트를 설계하면서 얻은 실전 교훈들이에요:
1. “하지 말 것”이 “할 것”보다 중요해요
AI에게 “좋은 글을 써줘”보다 “이건 하지 마”가 더 효과적이에요. Writer 프롬프트에서 ~합니다 체 금지, <p> 태그 안 줄바꿈 금지, 노트북 앞 장면 금지 등 구체적인 금지 규칙이 품질을 올려줬어요.
2. Good/Bad 예시의 위력
“따뜻한 톤으로 써줘” 대신 구체적인 Good/Bad 예문을 제시하면 AI가 원하는 스타일을 빠르게 학습해요. 특히 여러 언어에 걸쳐 톤을 유지할 때 효과적이에요.
3. 플레이스홀더는 에이전트를 자유롭게 해요
프롬프트에 경로를 하드코딩하면 환경마다 프롬프트를 수정해야 해요. {work_dir} 플레이스홀더를 쓰면 하나의 프롬프트 파일이 Windows, macOS, Mac Mini 모두에서 동작해요.
4. 모델 선택은 역할에 따라
모든 에이전트에 최고 모델을 쓸 필요 없어요. Writer만 Opus, 나머지는 Sonnet으로도 충분해요. 이렇게 하면 API 비용이 크게 줄어들고, Sonnet의 빠른 응답 속도 덕분에 전체 파이프라인도 빨라져요.
5. 카테고리 프로필은 확장성의 핵심
프롬프트를 직접 수정하는 대신 YAML로 행동을 오버라이드하면, 프롬프트 파일은 건드리지 않고 카테고리별 맞춤 동작을 추가할 수 있어요. 코드 변경 없이 YAML 1개로 새 카테고리 지원 — 이게 진짜 확장성이에요.
📋 다음 편 예고
다음 3편에서는 Blog-Agent의 두 가지 구현체를 비교해볼게요:
- blog-agent (v0.8.5) — Claude Code CLI 기반, state_cli.py로 수동 오케스트레이션
- blog-agent-api (v0.2.1) — Claude Agent SDK 기반, 자동 오케스트레이터
같은 파이프라인을 전혀 다른 방식으로 구현한 이야기, 기대해주세요! 💬