KArtSell.Aegis/STRATEGY_OPTIMAL_EXECUTION.md

최적 실행 전략: 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