# 마케팅 시스템 업그레이드 맥락 노트 (task-1054.1)

**작성일:** 2026-03-26
**목적:** 이 변경이 왜 필요한지, 기존 시스템과의 관계, 설계 결정 사항과 그 이유를 기록한다.

---

## 1. 왜 이 변경이 필요한가

### 문제 1: 스킬 품질 정량 보증 부재 (evals 부재)
현재 38개 마케팅 스킬 중 evals.json을 보유한 스킬은 copywriting, seo-audit, content-strategy 3개뿐이다 (전체의 약 8%). 나머지 스킬은 동작 기대값(expected_output)과 검증 항목(assertions)이 문서화되어 있지 않아 스킬 동작이 기대치에 맞는지 확인할 방법이 없다. 특히 ad-creative, paid-ads, analytics-tracking, ai-seo, social-content는 운영 빈도가 높은 핵심 스킬임에도 품질 검증 체계가 없다.

### 문제 2: 컨텍스트 참조 불일치
마케팅 스킬은 보험 서비스(InsuWiki, InsuRo) 도메인 특화 스킬이다. 최적 산출물을 위해서는 `.agents/product-marketing-context.md`의 제품 컨텍스트(타겟 고객, 차별화 요소, 브랜드 보이스 등)를 참조해야 한다. 그러나 blog-dominance, geo-optimizer, thread-architect, naver-seo 4개 스킬은 이 참조가 완전히 누락되어 있어 컨텍스트 없이 동작하고 있다. 이는 산출물의 도메인 특화도를 저하시킨다.

### 문제 3: 스킬 간 경계 라우팅 부재
ad-creative와 paid-ads, ai-seo와 geo-optimizer, social-content와 thread-architect처럼 기능적으로 인접한 스킬들 사이의 경계가 description에 명시되어 있지 않다. 결과적으로 사용자 입력이 잘못된 스킬로 라우팅되거나, 스킬 자체가 범위 밖의 요청을 처리하려 시도하는 문제가 발생할 수 있다. copywriting과 seo-audit은 이미 "For X, see Y" 패턴을 사용하여 이 문제를 해결하고 있으며, 이를 전체로 확산하는 것이 이번 변경의 핵심이다.

---

## 2. 기존 시스템과의 관계

### 라우팅 시스템
`dispatch.py`와 `team_prompts.py`가 SKILL.md의 `description` frontmatter 필드를 파싱하여 스킬을 선택한다. 이 파일들은 변경 대상이 아니다. description 필드의 내용(트리거 키워드, 라우팅 경계)을 개선함으로써 라우팅 정확도를 높이는 것이 목표다.

### 스킬 실행 구조
각 SKILL.md는 독립적인 마크다운 문서이며, LLM에 system prompt로 제공된다. evals.json은 스킬 실행 경로에 포함되지 않는 순수 메타데이터로, 실행 시 로드되지 않는다. 따라서 evals.json 추가는 기존 스킬 동작에 영향을 주지 않는다.

### product-marketing-context 스킬과의 관계
`skills/product-marketing-context/SKILL.md`는 `.agents/product-marketing-context.md` 파일을 생성·관리하는 스킬이다. 각 마케팅 스킬의 Before Starting 섹션은 이 파일을 참조하도록 설계되어 있다. 이는 단방향 의존성(마케팅 스킬 → product-marketing-context 파일)이며, product-marketing-context 스킬 자체는 변경하지 않는다.

### 기존 evals 구조
copywriting과 seo-audit의 evals.json이 사실상 표준으로 자리잡았다. 두 파일 모두 동일한 스키마(skill_name, evals 배열, id/prompt/expected_output/assertions/files)를 사용한다. 이 구조는 참조 구현(reference implementation)으로 채택하며, 신규 evals.json은 모두 이 스키마를 따른다.

---

## 3. 설계 결정 사항과 이유

### 결정 1: Phase 순서를 evals → context → routing → validation으로 설정

**이유:** 세 가지 도입 항목은 서로 독립적이지만, 실행 안전성을 위해 순차 진행이 권장된다. evals.json은 완전히 비파괴적(non-destructive)이므로 첫 번째 Phase로 배치하여 이후 변경의 기준선(baseline)을 확보한다. context 강화는 SKILL.md 본문을 수정하므로 두 번째, description 라우팅은 frontmatter를 수정하므로 세 번째. 검증은 마지막.

### 결정 2: description에 "NOT for: X (→ Y-skill)" 패턴 채택 (기존 패턴 표준화)

**이유:** blog-dominance, geo-optimizer, naver-seo가 이미 "NOT for:" 패턴을 사용하고 있다. 새로운 패턴을 도입하는 것보다 기존 패턴을 표준화하는 것이 일관성 면에서 우월하다. copywriting의 "For email copy, see email-sequence" 패턴도 유사하게 활용한다. 두 패턴의 조합으로 "포지티브 라우팅(use when)"과 "네거티브 라우팅(NOT for)"을 모두 커버한다.

### 결정 3: Before Starting 섹션 추가 대상을 4개로 제한

**이유:** 실제 파일 확인 결과, copy-editing, lead-magnets, email-sequence, cold-email, churn-prevention, revops, launch-strategy, marketing-ideas, marketing-psychology, referral-program, competitor-alternatives, free-tool-strategy, sales-enablement, programmatic-seo, schema-markup, site-architecture, ab-test-setup, pricing-strategy는 이미 product-marketing-context 참조를 포함하고 있다. 불필요한 중복 수정을 피하고, 실제 누락된 4개 스킬에만 집중하여 변경 범위를 최소화한다.

또한 paid-ads, ad-creative, analytics-tracking은 "시작 전 확인" 섹션(한국어로 Before Starting에 해당)이 이미 존재하고 product-marketing-context 참조도 포함되어 있어 Phase 2 대상에서 제외한다.

### 결정 4: 기존 evals.json 3개는 변경하지 않음

**이유:** copywriting(7개 eval), seo-audit(8개 eval), content-strategy(미확인 개수)의 evals.json은 이미 완성도 높은 테스트 케이스를 포함하고 있다. 이를 변경하면 기존 테스트 기준이 흔들릴 수 있다. Phase 1에서는 이들의 무결성만 검증하고 내용은 건드리지 않는다.

### 결정 5: evals.json 표준 스키마를 copywriting 기반으로 채택

**이유:** copywriting/evals/evals.json이 가장 완성도가 높다(7개 eval, 각 eval에 경계 케이스 포함). seo-audit도 동일 스키마를 사용한다. 두 파일이 수렴하는 구조를 표준으로 채택하면 추후 자동 검증과 통계적 분석에서 일관성이 보장된다.

### 결정 6: 검증 스크립트를 정적 검증으로 설계 (동적 LLM 실행 분리)

**이유:** 현재 작업 환경은 git 레포가 아니고 CI 인프라도 없다. LLM을 실제로 실행하여 assertions를 검증하는 동적 테스트는 별도 인프라와 비용이 필요하다. 따라서 Phase 4에서는 파일 구조·스키마·참조 유효성을 확인하는 정적 검증만 수행하고, 동적 회귀 테스트는 별도 일정으로 분리한다. 이 결정은 현실적 제약을 반영한 최소 유효 검증 전략이다.

### 결정 7: 파일 단위 백업 전략 (git 대신)

**이유:** `Is directory a git repo: No`로 확인되었으므로 git stash, git checkout 등 git 기반 롤백이 불가능하다. 파일 단위 백업을 `/home/jay/workspace/backups/marketing-upgrade-20260326/` 디렉토리에 수행하는 것이 가장 단순하고 확실한 롤백 전략이다. evals.json은 신규 생성이므로 롤백 = 파일 삭제로 처리 가능하여 별도 백업이 불필요하다.

---

## 4. 변경하지 않는 것과 그 이유

| 변경 금지 항목 | 이유 |
|----------------|------|
| dispatch.py | 라우팅 로직 핵심 파일. 변경 시 전체 시스템 영향 |
| team_prompts.py | 팀 프롬프트 어셈블리 로직. 변경 시 모든 스킬에 영향 |
| org-details/*.json | 조직 구성 정보. 마케팅 업그레이드와 무관 |
| Core Principles 섹션 | 스킬의 가이드라인 핵심. 변경 시 스킬 동작 변화 |
| Output Format 섹션 | 출력 구조 정의. 변경 시 산출물 형식 변화 |
| 기존 evals.json 3개 | 이미 완성된 테스트 케이스. 변경 시 기준선 훼손 |

---

## 5. 기대 효과

1. **evals 도입**: 핵심 8개 스킬에 품질 기준선 확보 → 추후 스킬 업데이트 시 회귀 검증 가능
2. **context 강화**: 4개 스킬의 도메인 특화도 향상 → 보험 서비스 관련 산출물 품질 개선
3. **description 라우팅**: 스킬 선택 정확도 향상 → 잘못된 라우팅으로 인한 재시도 감소
4. **통합 검증**: 자동화된 정적 검증 체계 → 이후 스킬 추가/수정 시 품질 게이팅 가능

---

*맥락 노트 버전: 1.0 | task-1054.1*