KArtSell.Aegis/docs/WBS_EXECUTION_GUIDELINES.md

WBS 실행 지침 (Work Breakdown Structure)

문서 버전: 2.0 (최적화판)
작성일: 2026-08-11
기준: AGENTS.md v16.0 + CLAUDE.md WBS 최적화 원칙
상태: ✅ ACTIVE

---

📌 핵심 원칙

1. WBS 날짜는 참고만 (CLAUDE.md)

❌ 해석: WBS 날짜 = 절대 마감일
✅ 해석: WBS 날짜 = 최악의 시나리오 기준

예시:
  WBS: "Phase 2 검증: 2026-11-01 시작"
  
  ❌ 틀림: 11-01까지 기다렸다가 시작
  ✅ 맞음: 지금 바로 준비 → 11-01에 공식 확인

2. 병렬화 극대화

직렬 접근 (3-4개월):
  Phase 1 (50-90일) → Phase 2 (2주) → Phase 3 (1주) → Phase 4 (월별)
  └─ 순차 실행

병렬 접근 (50-90일 + 병렬 완료):
  ┌─ Phase 1: 자동 (50-90일) ◄─ 기다리는 동안
  ├─ Phase 2: 준비 ✅ 완료
  ├─ Phase 3: 배포 ✅ 완료
  └─ Phase 4: 계획 ✅ 완료
  └─ 결과: 2-3개월 절약

3. 자동화로 수동 작업 제거

수동 작업:
  - 데이터 백필: 매일 손으로 입력 (불가능)
  - 메트릭 계산: 매주 수동 계산
  - 리포트 작성: 매월 수동 구성

자동화:
  ✅ Hangfire Job: 매일 자동 실행
  ✅ phase2_verification_scripts.py: 자동 계산
  ✅ phase2_automation.ps1: 자동 리포트
  └─ 결과: 수동 작업 제거 → 사람은 검증만

---

🔄 실행 프로세스

Step 1: 의존성 분석

각 작업마다 먼저 확인:

Q1: 이 작업은 다른 것을 기다려야 하나?
    ├─ YES → Step 2 (대기하지 말고 준비)
    └─ NO → Step 3 (지금 실행)

Q2: 기다리는 것이 필수인가?
    ├─ YES (외부 데이터): Phase 1 메트릭 필요
    │  └─ → 자동화하고 기다리는 동안 다른 일
    └─ NO (내부 작업): 지금 실행 가능
       └─ → 즉시 실행

Step 2: 준비 → 자동화

대기 중인 작업도 준비합니다:

Phase 2 (11-01 실행 예정):
  │
  └─ 08-11: 준비 완료
     ├─ 검증 스크립트 ✅ 작성됨
     ├─ 자동화 도구 ✅ 작성됨
     ├─ 리포트 템플릿 ✅ 작성됨
     └─ Go/No-Go 기준 ✅ 정의됨
  
  └─ 11-01: 공식 실행
     ├─ 실제 데이터로 검증
     ├─ 5팀 병렬 실행
     └─ 결과 통합

결과: 11-01에 "처음부터" 하는 게 아니라 "확인"만 함

Step 3: 즉시 실행

대기 없는 작업은 지금 실행:

Phase 3 (배포):
  
  08-11: 배포 패키지 생성 ✅
  08-12: 프로덕션 배포 🚀 (지금)
  08-13: 모니터링 안정화

---

📋 WBS 레이아웃

4-Level Structure

Level 1: Program
  └─ K-ArtSell Aegis v16.0

Level 2: Phase
  ├─ Phase 1: 252+ 일 Shadow Run
  ├─ Phase 2: 검증 & Go/No-Go
  ├─ Phase 3: 프로덕션 배포
  └─ Phase 4: 기술부채 결제

Level 3: Component/Activity
  ├─ 1.1 데이터 백필
  ├─ 1.2 리플레이
  ├─ 1.3 메트릭 계산
  ├─ 1.4 메트릭 저장
  └─ 1.5 모니터링

Level 4: Task
  ├─ 1.1.1 OHLCV 백필 (KRX API)
  ├─ 1.1.2 수수료 스케줄 (KIS)
  ├─ 1.1.3 시장 캘린더 (공휴일)
  └─ ...

각 항목 필수 정보

이름:       [명확하고 유일]
목표:       [SMART: Specific, Measurable, Achievable, Relevant, Time-bound]
의존성:     [선행 작업]
소유자:     [담당 팀 / 사람]
기간:       [예상 일정 (참고만)]
산출물:     [완료 증거]
상태:       [진행도]
위험:       [문제 가능성]
자동화:     [수동 vs 자동]

예시

작업: 1.1 OHLCV 데이터 백필
목표: 2024-01-02 ~ 2024-09-10 모든 거래일의 OHLCV 수집
의존성: KRX OpenAPI 연결
소유자: DataBackfiller (기술팀)
기간: 매일 자동 (평일)
산출물: model_operations.ohlcv 테이블 (데이터)
상태: ✅ 자동 진행 중 (매일)
위험: API 다운 → Fallback 스텁 데이터 사용
자동화: ✅ Hangfire Job (자동)

---

🎯 상태 추적

Burn-Down Chart (3주 단위)

Week 1 (08-11 ~ 08-18):  Phase 3 배포 마무리
                        Phase 4 9월 계획

Week 2 (08-19 ~ 09-01):  Phase 1 모니터링
                        기술부채 9월 결제 시작

Week 3 (09-02 ~ 09-15):  Phase 1 계속 (매일)
                        DEBT-014/015/016 완료

...

Week 12 (10-20 ~ 11-03): Phase 1 완료 대기 (243일)
                        Phase 2 준비 → 실행 (11-01)

Week 13+ (11-01 ~ 11-20): Phase 2 검증 (5팀)
                         Phase 3 최종 GO
                         기술부채 결제 계속

체크포인트

✓ 2026-08-15: Phase 3 배포 최종화
✓ 2026-09-01: Phase 4 첫 번째 결제 (20%)
✓ 2026-10-01: 기술부채 누적 20% 달성
✓ 2026-11-01: Phase 2 공식 실행
✓ 2026-11-15: Phase 2 완료 → Go/No-Go
✓ 2026-12-31: Phase 4 완료 (모든 기술부채)

---

⚙️ 작업 방식 (AGENTS.md v16.0)

모든 작업은 13가지 기준 확인

Before Implementation:
  ☐ SOLID 원칙 적용?
  ☐ Cyclomatic Complexity ≤ 10?
  ☐ 데이터 정합성 (3NF + PIT)?
  ☐ 요구사항 기반 (추측 NO)?
  ☐ 정규화/역정규화 최적?
  
Before Merge:
  ☐ 간단하게 읽힐 수 있나?
  ☐ 패턴 준수 (Vertical Slice/Job)?
  ☐ Source/Assumption/Decision 추적?
  ☐ Idempotent + Rollback 가능?
  ☐ Maturity (Contract/Schema/Test)?
  
After Merge:
  ☐ 지름길 사용 안 함 (정공법)?
  ☐ 기술부채 등록?
  ☐ 월별 20% 결제 계획?

ADR (Architecture Decision Record)

모든 중요 결정마다:

ADR-###-NAME

Context:
  어떤 상황에서?

Decision:
  무엇을 결정했나?

Rationale:
  왜 그렇게 결정했나?

Consequences:
  좋은 점은? 나쁜 점은?

Alternatives Considered:
  다른 방법은?

Test Coverage

단위 테스트: Pure functions (Policy, Mapper)
통합 테스트: Handler + DB + Transaction
E2E 테스트: 전체 HTTP flow
성능 테스트: Response time P95

---

🚨 위험 관리

Phase 1 위험 (252+ 일 대기)

위험: 메트릭 계산 오류 (NaN/NULL)
→ 완화: null 검증 + 로깅 추가 ✅

위험: 메트릭 저장 안 됨
→ 완화: InsertShadowRunAsync 로깅 ✅

위험: 데이터 이상 탐지 못 함
→ 완화: 매일 체크 + 이상 감지 알림 설정

위험: API 다운 (KRX/OpenDart)
→ 완화: Fallback 스텁 데이터 사용

Phase 2 위험 (검증 실패)

위험: PBO ≥ 20% (과최적화)
→ 대응: 모델 재조정 (2-3주) + Phase 3 연기

위험: DSR ≤ 0.5 (수익성 부족)
→ 대응: 전략 재평가 + Phase 3 연기

위험: OOS ≥ 2.5% (과적합)
→ 대응: 모델 개선 + Phase 3 연기

Phase 3 위험 (배포)

위험: 데이터베이스 마이그레이션 실패
→ 완화: 백업 + 롤백 계획 ✅

위험: 서비스 다운
→ 완화: 헬스체크 자동화 + 24/7 모니터링

위험: 보안 이슈
→ 완화: FailClosedAuthenticationHandler (Release)

---

📊 Reporting

주간 리포트 (매주 월요일)

1. Phase 1 진행률
   - 누적 일수
   - 메트릭 상태
   - 이상 항목

2. Phase 3 안정성
   - 가용성 (%)
   - 에러율
   - 응답시간 (P95)

3. Phase 4 진행
   - 기술부채 결제율
   - 완료 항목
   - 다음주 계획

4. 위험 & 이슈
   - 발생한 문제
   - 영향 범위
   - 해결책

월간 리포트 (매월 1일)

1. Burn-Down Chart
2. KPI 달성도
3. 기술부채 결제 완료
4. 다음달 계획
5. 전체 프로젝트 건강도

---

✅ 최종 체크리스트

작업 시작 전

• 의존성 분석 완료
• AGENTS.md 13가지 기준 확인
• ADR 또는 요구사항 문서 준비
• 테스트 계획 작성
• 산출물 정의

작업 중

• 매일 진행도 업데이트
• 블로커 즉시 보고
• 코드 리뷰 (AGENTS.md 기준)
• 테스트 작성 (동시)
• git 커밋 (이력성)

작업 완료

• 모든 테스트 통과
• Code Review 승인
• README/ADR 작성
• git Merge
• 리포트 작성
• 기술부채 등록 (있으면)

---

🎓 예시: Phase 3 배포

실행 방식

1. 의존성 분석
   ├─ Phase 1: 자동 진행 (기다릴 필요 없음)
   ├─ Phase 2: 준비 완료 (필요하면 다시)
   └─ 결론: NOW - 지금 배포 가능

2. AGENTS.md 13가지 확인
   ├─ SOLID: ✅ FailClosedAuthenticationHandler
   ├─ 테스트: ✅ 249/266 통과
   ├─ 자동화: ✅ nginx + systemd
   ├─ 데이터: ✅ 마이그레이션 준비
   └─ 결론: READY - 모든 기준 만족

3. 산출물 정의
   ├─ deployment/phase3-release/ (바이너리)
   ├─ deployment/phase3_migration.sql (DB)
   ├─ deployment/kartsell-host.service (서비스)
   ├─ deployment/kartsell.conf (nginx)
   └─ DEPLOYMENT_MANIFEST.json (메타)

4. 실행
   ├─ 08-11: 배포 패키지 생성 ✅
   ├─ 08-12: 프로덕션 배포 🚀
   └─ 08-13: 모니터링 확인

결과: ✅ 지금 진행, 대기 없음

---

📞 질문과 답변

Q1: WBS 날짜 무시해도 되나?

A: 무시하는 게 아니라, 이것을 마감일로 보지 말 것. 참고만 하고, 할 수 있으면 지금 → 더 빨리 완료.

Q2: 일정을 못 맞추면?

A: WBS는 참고이므로, 실제 완료 일자가 중요. 차이가 크면 리스크 보고 (블로커 vs 예상 미스).

Q3: 자동화로 수동 제거?

A: Phase 1처럼 반복 작업은 Hangfire Job. 한번만 하는 작업은 스크립트로 자동화. 손은 검증과 의사결정에만.

Q4: 기술부채는 언제?

A: 매달 20% 결제 (의무). 할 것들: DEBT-014/015/016 (9월) DEBT-017/018/019 (10월) ...

---

문서 소유: Architecture Team
최종 수정: 2026-08-11
상태: ✅ ACTIVE & APPROVED
다음 검토: 2026-08-18