# Agency-Agents 패턴 전체 적용 — 문서화 + 코드화

**위임 유형**: 한시적위임 (제이회장님 승인 완료)
**참조 분석**: `/home/jay/workspace/memory/research/agency-agents-analysis.md`
**레벨**: Lv.2 (문서화 + 설정 코드 변경)

---

## 작업 목표

Agency-Agents 분석에서 도출된 모든 패턴을 우리 시스템에 적용한다.
문서화(specs/guides) + 코드화(team_prompts.py, QC-RULES.md 등) 병행.

---

## Phase 1: 핵심 문서 업데이트 (High 우선순위)

### 1-1. QC-RULES.md v3.0 업데이트
**파일**: `/home/jay/workspace/teams/shared/QC-RULES.md`

추가할 규칙들:
- **"기본값 NEEDS WORK" 원칙**: 모든 QC의 기본 판정은 NEEDS WORK. 증거로 뒤집어야 PASS.
- **Zero Issue = Red Flag**: 첫 구현에서 이슈 0건은 비현실적. 최소 3개 이슈를 발견해야 함.
- **Fantasy Approval 탐지**: "모든 것이 완벽합니다", "A+ 품질" 등의 표현 사용 금지. 정량적 증거 필수.
- **Evidence 필수 규칙**: 주장만으로는 PASS 불가. 테스트 결과, 스크린샷, 로그 등 증거 첨부 의무화.
- 변경이력에 v3.0 추가

### 1-2. 핸드오프 메타데이터 템플릿
**파일 생성**: `/home/jay/workspace/memory/specs/handoff-template.md`

dispatch.py 위임 시 task-file에 포함할 표준 메타데이터:
```
## 핸드오프 메타데이터
- From: <위임자>
- To: <수신팀>
- Phase: <Phase 번호/이름>
- TaskRef: <task_id>
- Priority: <High/Medium/Low>
- 참조문서: <경로 목록>
- 기대산출물: <파일/결과물 목록>
- 품질기준: <구체적 완료 조건>
- 완료 체크리스트: <항목별>
```

### 1-3. 3회 재시도-에스컬레이션 프로토콜
**파일 생성**: `/home/jay/workspace/memory/specs/retry-escalation-protocol.md`

내용:
- Sonnet 팀원 구현 → QA 검증 → FAIL 시 Sonnet 재시도 (최대 3회)
- 3회 실패 → Opus 팀장 직접 개입 (기존 규칙과 연동)
- 에스컬레이션 시 결정 트리: 재배정 / 작업 분해 / 보류+보고
- task-timer에 attempt 카운터 필드 기록 방안 (task_metadata에 "attempt": N)

---

## Phase 2: 보고/전략 문서 (Medium 우선순위)

### 2-1. SCQA 보고서 포맷 템플릿
**파일 생성**: `/home/jay/workspace/memory/specs/scqa-report-template.md`

McKinsey SCQA 프레임워크:
- **S**ituation: 현재 상황 (1-2문장)
- **C**omplication: 문제/변화 (1-2문장)
- **Q**uestion: 핵심 질문 (1문장)
- **A**nswer: 답변/제안 (1-3문장)
- 325-475 단어 제한
- 모든 발견에 정량적 데이터 포인트 1개 이상 필수
- 제이회장님 보고용으로 활용 (간결 + 핵심)

### 2-2. Phase Gate 체크리스트 템플릿
**파일 생성**: `/home/jay/workspace/memory/specs/phase-gate-checklist.md`

Phase 경계마다 적용:
- Gate Keeper: 아누(개발실장)
- GO 기준: 모든 산출물 존재 + 테스트 통과 + QC PASS
- NO-GO 기준: 산출물 누락 / 테스트 실패 / QC FAIL
- Gate 실패 시 이전 Phase로 회귀 프로세스
- 체크리스트 항목 표준화

### 2-3. 마케팅 콘텐츠 전략 가이드
**파일 생성**: `/home/jay/workspace/memory/specs/marketing-content-guide.md`

내용:
- 콘텐츠 1/3 법칙: 브랜드 33% + 교육 33% + 커뮤니티 33%
- Topic Cluster 아키텍처: Pillar 콘텐츠 + Cluster 콘텐츠 + 내부링크
- E-E-A-T 적용 (Experience, Expertise, Authoritativeness, Trustworthiness)
- 플랫폼별 최적화: Threads/Instagram/네이버블로그/티스토리
- Growth KPI: 바이럴 계수(K-factor), 참여율, 팔로워 증가율
- 런칭 시퀀스: T-7(티저) → T-0(런칭) → T+7(피드백) → T+14(최적화)
- 서울대보험쌤/서울대연금쌤 브랜드에 맞춤

### 2-4. 브랜드 가이드 프레임워크
**파일 생성**: `/home/jay/workspace/memory/specs/brand-guide-framework.md`

비너스(디자인센터) 참조용:
- 브랜드 5요소: 목적/비전/미션/가치/성격
- CSS 변수 시스템 가이드 (색상, 폰트, 간격 표준화)
- Voice Guidelines: Do/Don't + 톤 변형 (Professional/Conversational/Supportive)
- 월 1회 브랜드 일관성 감사 기준 (95%+ 일관성 목표)

---

## Phase 3: 운영/조직 문서 (Low 우선순위)

### 3-1. Incident Response 프로토콜
**파일 생성**: `/home/jay/workspace/memory/specs/incident-response.md`

우선순위 분류:
- P0 (Critical): 서비스 전면 장애 → 즉시 전원 대응
- P1 (High): 핵심 기능 장애 → 1시간 내 대응
- P2 (Medium): 부분 장애 → 4시간 내 대응
- P3 (Low): 개선 필요 → 다음 스프린트에 배정

대응 시퀀스: 탐지 → 분류 → 대응팀 배정 → 해결 → 포스트모템
포스트모템 템플릿 포함

### 3-2. 운영 케이던스 정의
**파일 생성**: `/home/jay/workspace/memory/specs/operational-cadence.md`

주기별 활동:
- Continuous: 모니터링, 알림 대응
- Daily: task-timer 일일 요약, 지연 작업 체크
- Weekly: 진행 상황 리뷰, 다음 주 계획
- Monthly: 프로세스 개선 리뷰, 브랜드 일관성 감사
- Quarterly: 전략 리뷰, KPI 평가

### 3-3. 실험 추적 체계
**디렉토리 생성**: `/home/jay/workspace/memory/experiments/`
**파일 생성**: `/home/jay/workspace/memory/experiments/README.md`

실험 로그 템플릿:
- 실험 ID, 가설, 방법, 기간
- 측정 지표 (primary/secondary)
- 결과 (정량 데이터)
- 결론 + 다음 액션
- A/B 테스트 + 통계적 유의성 기준

### 3-4. Cross-Division 의존성 매트릭스
**파일 수정**: `/home/jay/workspace/memory/organization-structure.json`

`dependency_map` 필드 추가:
```json
"dependency_map": {
  "dev1-team": {"produces": ["코드", "API"], "consumes": ["디자인", "기획"]},
  "dev2-team": {"produces": ["코드", "API"], "consumes": ["디자인", "기획"]},
  "marketing": {"produces": ["콘텐츠", "SNS"], "consumes": ["브랜드가이드", "제품정보"]},
  "design-center": {"produces": ["디자인", "브랜드가이드"], "consumes": ["기획", "요구사항"]},
  "qc-center": {"produces": ["QC리포트", "품질인증"], "consumes": ["코드", "테스트결과"]},
  "devops-center": {"produces": ["배포", "인프라"], "consumes": ["코드", "설정"]},
  "red-team": {"produces": ["보안리포트"], "consumes": ["코드", "인프라설정"]}
}
```

---

## Phase 4: 코드 반영

### 4-1. team_prompts.py 업데이트
**파일**: `/home/jay/workspace/prompts/team_prompts.py`

변경사항:
- 테스터 섹션에 Evidence Collector 규칙 추가:
  - "Zero Issue = Red Flag" 원칙 명시
  - 스크린샷 증거 필수 (browser.py 활용)
  - "기본값 = NEEDS WORK, 증거로 뒤집어야 PASS"
- QC 섹션에 "Fantasy Approval 방지" 문구 추가
- 보고서 작성 가이드에 SCQA 포맷 참조 추가

⚠️ team_prompts.py는 기존 로직을 유지하면서 **최소한의 추가**만 한다.
프롬프트 비대화 방지 원칙 준수 — 상세는 specs 파일 참조로 처리.

### 4-2. Behavioral Nudge 패턴 문서화
**파일 생성**: `/home/jay/workspace/memory/specs/behavioral-nudge-patterns.md`

보험 자동화 UX 적용 패턴:
- 인지 부하 감소: 핵심 1개만 표시
- 기본값 편향: "초안 작성됨. 보내시겠습니까?"
- 마이크로 스프린트: "5분 안에 처리"
- 고객 레포트, 인터뷰 도구 UX에 적용할 원칙

---

## 완료 기준

1. 모든 파일 생성/수정 완료
2. 기존 테스트 회귀 없음 (team_prompts.py 변경 시 test_team_prompts.py 확인)
3. pyright 에러 없음 (코드 변경 파일 대상)
4. QC-RULES.md 변경이력에 v3.0 반영
5. organization-structure.json이 유효한 JSON인지 확인

## 수정/생성 파일 목록 (예상)

수정:
- `/home/jay/workspace/teams/shared/QC-RULES.md` (v3.0)
- `/home/jay/workspace/prompts/team_prompts.py` (테스터/QC 섹션)
- `/home/jay/workspace/memory/organization-structure.json` (dependency_map)

생성:
- `/home/jay/workspace/memory/specs/handoff-template.md`
- `/home/jay/workspace/memory/specs/retry-escalation-protocol.md`
- `/home/jay/workspace/memory/specs/scqa-report-template.md`
- `/home/jay/workspace/memory/specs/phase-gate-checklist.md`
- `/home/jay/workspace/memory/specs/marketing-content-guide.md`
- `/home/jay/workspace/memory/specs/brand-guide-framework.md`
- `/home/jay/workspace/memory/specs/incident-response.md`
- `/home/jay/workspace/memory/specs/operational-cadence.md`
- `/home/jay/workspace/memory/specs/behavioral-nudge-patterns.md`
- `/home/jay/workspace/memory/experiments/README.md`

---

## 주의사항

- **dashboard/ 폴더 미접촉** — 대시보드 관련 파일 건드리지 마세요
- **dispatch.py 미접촉** — 코드 자체는 변경하지 않음 (문서로 가이드)
- **프롬프트 비대화 금지** — team_prompts.py에 내용 직접 삽입 최소화, specs 파일 참조로 처리
- **organization-structure.json 수정 시** 기존 구조 유지, `dependency_map` 필드만 추가
- **한시적위임**: Phase 내부 작업은 팀장 판단으로 진행. 단, 기존 파일 구조 파괴 금지.