# 최적 실행 전략: AGENTS.md v16.0 기반

**목표:** 로드맵 & WBS를 AGENTS.md v16.0 20가지 원칙에 따라 최적으로 실행

---

## 📋 원칙 기반 실행 전략

### 1. SOLID (Single Responsibility, Open-Closed, Liskov, Interface Segregation, Dependency Inversion)

**로드맵 적용:**
```
각 Phase는 단일 책임:
- Phase 1: 자동 검증 (Hangfire 담당)
- Phase 2: 증거 수집 (Engineering 담당)
- Phase 3: 배포 (DevOps 담당)
- Phase 4: 운영 (SRE 담당)

교차 기능 팀 구성:
- 각 팀은 명확한 계약(contract) 기반 협력
- 팀 간 직접 테이블 접근 금지 (API/이벤트 사용)
```

**실행 방법:**
```
✅ Phase 2 증거 검증: 각 메트릭 팀 독립 실행
   └─ PBO 팀, DSR 팀, OOS 팀 병렬 진행
   └─ 최종 엔드포인트에서만 통합 검증

✅ Phase 3 배포: DBA ↔ DevOps ↔ Engineering 명확한 역할
   └─ 롤백 계획 미리 수립 (Open-Closed)
   └─ 새로운 환경에서도 배포 스크립트 재사용 (Liskov)
```

---

### 2. 코드리팩토링 (Characterized, Isolated, Verified)

**로드맵 적용:**
```
Phase 2 시작 전: 기존 코드 특성화
- 현재 테스트 커버리지 (249/266) 기록
- 성능 기준선 (baseline) 수립
- 알려진 이슈 문서화

Phase 2 진행 중: 격리된 변경
- DEBT 해결 시 각 변경을 별도 커밋
- 하나의 DEBT = 하나의 PR (atomic)
- 테스트 통과 후 머지

Phase 2 후: 검증
- 테스트 커버리지 전후 비교
- 성능 회귀 테스트
- Golden 데이터셋 재검증
```

**실행 방법:**
```
✅ 매월 기술부채 결제 시 (Phase 4):
   - 변경 전 테스트 스냅샷 (git tag: debt-{id}-before)
   - 변경 적용
   - 변경 후 테스트 스냅샷 (git tag: debt-{id}-after)
   - diff 분석 및 회귀 검증
```

---

### 3. 데이터 정합성 (Normalization, PIT Queries)

**로드맵 적용:**
```
Phase 1: 감사 이벤트 정합성 검증 (자동)
- operation_audit_trail 3NF 유지 (자동)
- 모든 쿼리 PIT 패턴 (published_at <= cutoff)
- 중복 감지 자동 로깅 (DEBT-014)

Phase 2: 데이터 무결성 검증
- Phase 1 기간 중 저장된 모든 데이터 검증
- 스키마 버전 호환성 확인
- 마이그레이션 이후 데이터 무결성 재검증 (Phase 3 전)
```

**실행 방법:**
```
✅ Phase 2 체크리스트:
   □ operation_audit_trail row count 검증
   □ 모든 쿼리 PIT 패턴 재확인 (grep "published_at")
   □ 중복 감지 로그 분석 (false positive < 0.1%)
   □ 외래키 무결성 검증 (FK constraint)
```

---

### 4. 과유불급 (No Gold-Plating)

**로드맵 적용:**
```
Phase 2: 필요한 것만 검증
- 배포 전 필수 증거만 수집 (PBO, DSR, OOS, DEBT, audit)
- 미래 기능 (auto-learning, auto-promotion)은 Phase 4로 이연
- 추가 최적화는 배포 후 (운영 중 개선)

Phase 3: 최소한의 배포
- 현재 코드 그대로 배포 (새 기능 추가 금지)
- 배포 후 모니터링만 집중
- 새 기능 개발은 Post-go-live로 계획

Phase 4: 점진적 개선
- 월별 20% DEBT만 결제
- 분기별 1-2개 기능만 추가 (A/B 테스트)
```

**실행 방법:**
```
✅ 각 Phase 승인 기준:
   - Phase 2 승인: PBO/DSR/OOS 임계값만 (추가 검증 금지)
   - Phase 3 승인: 배포 체크리스트만 (feature freeze)
   - Phase 4 진입: 72시간 모니터링 SLA 달성
```

---

### 5. 정규화 (3NF Database Design)

**로드맵 적용:**
```
Phase 1 ~ Phase 3: 스키마 불변
- operation_audit_trail 3NF 유지
- 새 테이블 추가 금지
- 마이그레이션 추가 금지 (0041만)

Phase 4: 운영 중 최적화
- Read-only 덴노말라이제이션 검토
- 인덱스 최적화 (성능 메트릭 기반)
- 아카이빙 전략 (Phase 4.2 분기 검토)
```

**실행 방법:**
```
✅ Phase 2 데이터 정합성 검증:
   □ PK/FK 모두 존재하는지 확인
   □ NULL 값이 없어야 하는 컬럼 확인
   □ UNIQUE 제약 조건 적용 여부 확인
```

---

### 6. 역정규화 (Denormalization for Read Performance)

**로드맵 적용:**
```
Phase 2: 읽기 성능 기준선 수립
- 메트릭 조회 응답 시간 기록 (PBO, DSR, OOS)
- 감사 로그 조회 성능 측정

Phase 3: 배포 전 최적화 (필요시)
- 느린 쿼리 식별 (응답 > 500ms)
- 뷰(VIEW) 또는 캐시 추가 (읽기 최적화만)

Phase 4: 진행 중 모니터링
- 월별 응답 시간 추적
- 병목 쿼리 식별 및 개선
```

**실행 방법:**
```
✅ Phase 2 성능 기준선:
   - EXPLAIN ANALYZE로 각 주요 쿼리 분석
   - Index 사용 여부 확인
   - 응답 시간 기록 (Phase 3, 4에서 비교)
```

---

### 7. 프로세스 단순화 (Automation)

**로드맵 적용:**
```
Phase 1: 완전 자동화 (Hangfire Job 3227)
- 수동 개입 금지
- 일일 메트릭 자동 계산
- 주간 리포트 자동 생성

Phase 2: 반자동화 (검증 도구)
- 스크립트로 PBO/DSR/OOS 계산
- SQL 쿼리로 감사 로그 자동 분석
- 체크리스트 자동 생성

Phase 3: 배포 자동화
- 배포 스크립트 (bash/powershell)
- 롤백 자동 스크립트
- 모니터링 대시보드 자동 활성화

Phase 4: 운영 자동화
- 월별 DEBT 식별 자동화
- SLA 모니터링 자동 알림
- 월간 리포트 자동 생성
```

**실행 방법:**
```
✅ Phase 2 준비 작업:
   - Python/SQL 스크립트 미리 작성
   - 테스트 환경에서 실행 검증
   - 자동화 문서 작성 (재현 가능)

✅ Phase 3 준비 작업:
   - Deployment 스크립트 (sandbox 테스트 완료)
   - Rollback 스크립트 (sandbox 테스트 완료)
```

---

### 8. 패턴화 (Standard Architecture Patterns)

**로드맵 적용:**
```
전 Phase: 기존 패턴만 사용
- Outbox/Inbox (비동기 이벤트)
- Vertical Slice (기능 구조)
- PIT 쿼리 (시간축 데이터)
- DI 컨테이너 (의존성)
- Handler → Policy → SQL (계층화)

Phase 2 검증:
- 모든 쿼리가 Vertical Slice 패턴인지 확인
- 모든 이벤트가 Outbox/Inbox 패턴인지 확인
- 모든 데이터 쿼리가 PIT 패턴인지 확인

Phase 4 개선:
- 새로운 패턴 도입은 금지 (기존 패턴만 사용)
- 기존 패턴 개선은 분기별 1-2개만 (리스크 최소화)
```

**실행 방법:**
```
✅ Phase 2 패턴 검증:
   grep -r "SELECT \*" src/  # 금지 패턴
   grep -r "new SqlCommand" src/  # 금지 패턴
   grep -r "published_at <=" src/  # PIT 패턴 확인
```

---

### 9. 표준화 (Technology Stack)

**로드맵 적용:**
```
Phase 1 ~ Phase 4: 기존 스택만 사용
- .NET 10 (변경 금지)
- Dapper (ORM, 변경 금지)
- FastEndpoints (API, 변경 금지)
- Hangfire (jobs, 변경 금지)
- PostgreSQL (DB, 버전 유지)
- Vue 3 (FE, 변경 금지)
- Vitest (테스트, 변경 금지)

Phase 4 검토:
- 마이너 버전 업그레이드 (보안)
- 새로운 라이브러리는 분기별 1-2개만
```

**실행 방법:**
```
✅ Phase 2 스택 검증:
   dotnet --version  # .NET 10.x 확인
   psql --version  # PostgreSQL 버전 확인
   npm list  # 의존성 버전 확인
```

---

### 10. 구조화 (Module Isolation)

**로드맵 적용:**
```
Phase 1 ~ Phase 3: 스키마 격리 유지
- compliance.* (감사) ← 독립
- model_operations.* (모델) ← 독립
- signal_engine.* (신호) ← 독립
- building_blocks.* (공유) ← 읽기만

Phase 2 검증:
- 각 모듈이 자신의 스키마만 수정하는지 확인
- 모듈 간 직접 테이블 접근이 없는지 확인 (API만)

Phase 4 개선:
- 모듈 경계 리팩토링 (분기별 1개)
```

**실행 방법:**
```
✅ Phase 2 격리 검증:
   grep -r "model_operations\." src/KArtSell.Modules.SignalEngine/
   # 금지: signal_engine 모듈이 model_operations 직접 접근
   
   grep -r "outbox" src/  # Outbox 패턴 사용하는지 확인
```

---

### 11. 바이브코딩 (Clear & Simple Code)

**로드맵 적용:**
```
Phase 2: 코드 리뷰 기준 강화
- 클래스/메서드 이름이 목적을 명확히 하는지
- 10줄 이상 주석은 금지 (한줄만)
- Cyclomatic complexity < 10 (Policy 제외)

Phase 3: 코드 정리
- Unused imports 제거
- 사용되지 않는 메서드 제거
- 일관된 포맷팅 (dotnet format)

Phase 4: 지속적 개선
- 매월 복잡한 메서드 1개씩 리팩토링
- 월별 코드 커버리지 추적
```

**실행 방법:**
```
✅ Phase 2 검증:
   dotnet format --verify-no-changes --verbosity diagnostic
   dotnet test /p:CollectCoverage=true
```

---

### 12. 홀루시네이션 방지 (Real Data Validation)

**로드맵 적용:**
```
Phase 1: 실제 데이터 검증 (자동)
- 스텁 데이터 사용 금지 (실제 KRX API)
- Mock 제거 (실제 DB)

Phase 2: 증거 검증
- Phase 1 실제 데이터 분석
- 계산 공식 재현 검증 (git 트래킹)

Phase 3: 배포 검증
- Sandbox에서 실제 config로 테스트
- Production과 동일한 데이터로 smoke test

Phase 4: 지속 모니터링
- 실제 메트릭 추적 (대시보드)
- 이상치 자동 감지
```

**실행 방법:**
```
✅ Phase 1 검증:
   grep -r "new Mock" src/  # Mock 사용 여부 확인
   grep -r "stub\|fake" src/  # Stub 데이터 확인

✅ Phase 2 검증:
   - PBO 계산: 실제 Phase 1 데이터로 재계산
   - DSR 계산: 실제 수익률 데이터로 재계산
```

---

### 13. 현장감 (On-Site Evidence)

**로드맵 적용:**
```
Phase 1: 실제 환경에서 자동 실행
- 실제 Production DB (178.104.200.7)
- 실제 KRX/OpenDart API
- 실제 시장 데이터

Phase 2: 실제 결과 검증
- Phase 1 실제 로그 분석
- 실제 DB에서 데이터 쿼리 (개발 환경 아님)

Phase 3: 실제 배포
- Staging이 아닌 Production 배포
- 실제 사용자 트래픽

Phase 4: 실제 모니터링
- 실제 메트릭 추적 (mock이 아님)
- 실제 SLA 달성 검증
```

**실행 방법:**
```
✅ Phase 1 검증:
   ssh kjh2064@178.104.200.7  # 실제 서버 확인
   psql kartsell  # 실제 DB 데이터 확인

✅ Phase 2 검증:
   select count(*) from compliance.operation_audit_trail;  # 실제 데이터
```

---

### 14. 재현성 (Reproducibility)

**로드맵 적용:**
```
Phase 1: 일일 스냅샷 저장
- Job 3227 로그 일일 저장 (git)
- 메트릭 데이터 일일 백업

Phase 2: 계산 재현 가능
- PBO 공식 문서화 (재현 가능)
- DSR 공식 문서화 (재현 가능)
- SQL 쿼리 모두 git 트래킹

Phase 3: 배포 재현 가능
- 배포 스크립트 버전 관리 (git)
- 배포 절차 문서화 (README)

Phase 4: 모니터링 재현 가능
- 대시보드 쿼리 git 저장
- 알림 규칙 코드화 (as-a-code)
```

**실행 방법:**
```
✅ Phase 2 재현성:
   git log --oneline -- src/  # 모든 변경 이력
   git show <commit>:src/QueryPBO.sql  # 특정 시점의 쿼리

✅ Phase 3 재현성:
   git tag deploy-2026-11-20  # 배포 버전 태그
   git show deploy-2026-11-20:deploy.sh  # 배포 스크립트
```

---

### 15. 이력성 (Traceability)

**로드맵 적용:**
```
Phase 1 ~ Phase 4: 모든 변경을 git에 기록
- Commit message: DEBT-{id}, correlation ID
- Tag: Phase별 마일스톤 (Phase-1-Complete, etc.)
- Branch: 기능별 (feature/debt-014, etc.)

TECH_DEBT_REGISTER.md 유지:
- 매월 DEBT 결제 기록
- 미결제 DEBT 이유 문서화

모니터링 이벤트 로깅:
- operation_audit_trail (자동)
- outbox/inbox 이벤트 (자동)
```

**실행 방법:**
```
✅ Phase 2 이력성:
   git log --format="%h %an %ai %s" --grep="DEBT"
   # DEBT-014, DEBT-029 등 모든 기록 조회

✅ 매월 검증:
   grep "2026-11" TECH_DEBT_REGISTER.md
   # 이번 달 DEBT 결제 기록 확인
```

---

### 16. 안정성 (Reliability & Crash Recovery)

**로드맵 적용:**
```
Phase 1: 자동 복구 검증 (자동)
- Job 3227 실패 시 재시도
- DB 연결 끊김 시 재연결
- Crash recovery (4/4 시나리오) 자동 검증

Phase 2: 안정성 검증 리포트
- Phase 1 기간 중 재시도 횟수
- 실패율 (목표: < 0.1%)
- Crash recovery 성공률 (목표: 100%)

Phase 3: 배포 안정성
- Rollback 계획 사전 테스트
- Monitoring 시스템 구성
- SLA 정의 (99.5%)

Phase 4: 지속 모니터링
- 에러율 추적 (< 0.1%)
- 재시도 로그 분석 (월 1회)
- 장애 원인 분석 (RCA)
```

**실행 방법:**
```
✅ Phase 1 검증:
   select event_type, count(*) from compliance.operation_audit_trail
   where event_type = 'JOB_RETRY' group by event_type;

✅ Phase 2 검증:
   - Retry 로그 분석
   - Crash recovery 동작 확인
   - 실패 이유 카테고리화
```

---

### 17. 고도화 (Evolutionary Architecture)

**로드맵 적용:**
```
Phase 1 ~ Phase 3: 현재 아키텍처 고정
- 새로운 패턴 도입 금지
- 마이크로서비스 검토 금지

Phase 4: 진화적 개선
- 분기별 1-2개 아키텍처 개선
- A/B 테스트로 변경 검증
- Feature flag로 점진적 배포

예시:
- Q1 2027: Read replica for metrics (성능 개선)
- Q2 2027: Event sourcing for audit (확장성)
- Q3 2027: API gateway for rate limiting (보안)
```

**실행 방법:**
```
✅ Phase 4 계획:
   - 아키텍처 결정 기록 (ADR)
   - 변경 영향 분석 (dependency map)
   - 회귀 테스트 계획
```

---

### 18. 컴포넌트화 (Modularity)

**로드맵 적용:**
```
Phase 1 ~ Phase 3: 기존 모듈 구조 유지
- AuditTrailConsumer (DEBT-029)
- MetricsSql (DEBT-014)
- PBO/DSR/OOS 계산 (Phase 2)

Phase 4: 모듈 분리 검토
- 각 메트릭을 독립 서비스로? (아니면 이대로)
- 감사 로깅을 별도 db로? (아니면 이대로)
- 결정: 분기별 1회 검토, 필요시만 분리
```

**실행 방법:**
```
✅ Phase 2 검증:
   grep -r "interface I" src/KArtSell.Host/
   # 각 컴포넌트의 contract 확인

✅ Phase 4 계획:
   - 컴포넌트 간 의존성 맵 그리기
   - 긴밀한 결합도(coupling) 식별
   - 분기별 1개씩 리팩토링
```

---

### 19. 정공법 (Right Way, No Shortcuts)

**로드맵 적용:**
```
모든 Phase:
- --no-verify 금지 (git hooks 실행)
- force push 금지
- hardcoded 값 금지
- TODO 주석만 허용 (FIXME, XXX 금지)
- 근본 원인 분석 (band-aid 금지)

Phase 2 검증:
- 모든 버그 수정이 근본 원인 해결인지 확인
- 임시 패치 금지

Phase 3 배포:
- 배포 체크리스트 모두 완료할 때까지 진행 금지
- 문제 발생 시 rollback (workaround 금지)
```

**실행 방법:**
```
✅ Pre-commit hook 확인:
   cat .git/hooks/pre-commit
   # 테스트 자동 실행 여부 확인

✅ PR 승인 기준:
   - 커밋 메시지 명확한지
   - 테스트 추가되었는지
   - 문서 업데이트되었는지
```

---

### 20. 기술부채 관리 (20% Monthly Paydown)

**로드맵 적용:**
```
Phase 1: 부채 현황 파악
- 현재 DEBT-014/029/030/032/016/024 결제 상태 확인
- 누적 부채 점수 계산

Phase 2: 부채 정리
- 미결제 부채 식별
- 우선순위 결정 (Impact × Effort)

Phase 3: 부채 동결
- 배포 전 추가 부채 금지
- 배포 후 모니터링 중에만 결제

Phase 4: 월별 20% 결제
- 첫 달(11월): 20% 결제
- 둘째 달(12월): 추가 20% 결제
- 2027+: 월별 지속 (quarterly 목표 = 60%)
```

**실행 방법:**
```
✅ 매월 이행:
   git log --oneline --grep="DEBT" --since="2026-11-01"
   # DEBT 관련 커밋 확인
   
   grep "2026-11" TECH_DEBT_REGISTER.md
   # 월별 결제 기록 확인
```

---

## 🎯 최적 실행을 위한 체크리스트

### Phase 별 Go/No-Go 기준

#### Phase 1 → Phase 2 (Go-Live 승인)
```
□ Job 3227 50+ 일 실행 (자동)
□ 일일 메트릭 안정적 계산
□ 감사 로그 정상 기록 (DEBT-014/029)
□ 에러율 < 0.1%
→ Go Phase 2
```

#### Phase 2 → Phase 3 (배포 승인)
```
□ PBO < 20% ✅
□ DSR > 0.5 ✅
□ OOS 드리프트 < 2.5% ✅
□ 감사 이벤트 정상 ✅
□ 기술부채 20% 결제 ✅
□ 배포 체크리스트 100% ✅
→ Go Phase 3
```

#### Phase 3 → Phase 4 (운영 모드)
```
□ 배포 성공 ✅
□ 72시간 모니터링 SLA 99.5% 달성 ✅
□ 에러율 < 0.1% ✅
□ 응답 시간 < 500ms (p95) ✅
□ 경영진 최종 승인 ✅
→ Go Phase 4
```

---

## 📊 우선순위 매트릭스 (Phase 2)

| 메트릭 | Impact | Effort | 우선순위 | 병렬화 |
|--------|--------|--------|---------|--------|
| PBO 검증 | 높음 | 중간 | 1순위 | 가능 |
| DSR 검증 | 높음 | 중간 | 1순위 | 가능 |
| OOS 검증 | 높음 | 높음 | 1순위 | 가능 |
| 감사 로그 | 중간 | 낮음 | 2순위 | 가능 |
| DEBT 검토 | 중간 | 중간 | 2순위 | 가능 |

→ **모든 Phase 2 작업 병렬 가능** (의존성 없음)

---

## 🚀 리스크 경감 전략

| 리스크 | 발생 시 조치 | 백업 계획 |
|--------|------------|---------|
| Phase 1 조기 완료 | 배포 앞당김 | 연일 모니터링 강화 |
| Phase 1 지연 | 스케줄 연장 | 우선순위 조정 |
| PBO 임계값 미충족 | Phase 3 연기 | 모델 재조정 및 재검증 |
| 배포 중 장애 | 즉시 롤백 | 근본 원인 분석 후 재배포 |
| SLA 미달 | 72시간 연장 | 성능 최적화 후 재검증 |

---

**Version:** 1.0  
**Last Updated:** 2026-08-11  
**Owner:** CTO  
**Status:** ACTIVE - READY FOR EXECUTION