# 효과 측정 프레임워크 (Metrics Framework)

> 버전: 1.0 | 작성일: 2026-04-17 | 작업: task-1837_5.3

## 개요

시스템3문서 Phase 5.3에서 정의하는 7개 핵심 지표. 분할/자동화 개선의 효과를 정량적으로 측정.

---

## 지표 정의

### M-1: 머지 충돌 감소율

- **설명**: 코드 분할 전후 git merge conflict 발생 횟수 비교. 분할 적용 후 충돌이 얼마나 줄었는지 측정.
- **수집 방법**
  - 데이터 소스: `git log --all --oneline` 출력에서 `"CONFLICT"`, `"Merge conflict"` 패턴 검색
  - 계산 공식: `(이전 기간 충돌 수 - 현재 기간 충돌 수) / 이전 기간 충돌 수 × 100%`
- **수집 주기**: 주간
- **목표값/기준선**: 분할 적용 후 충돌 감소율 30% 이상 (기준선: 첫 실행 시 이전 4주 평균)

---

### M-2: 기능 원복 발생률

- **설명**: 배포된 기능이 문제로 인해 되돌려진 비율. revert 및 cherry-pick 커밋 빈도로 측정.
- **수집 방법**
  - 데이터 소스: `git log --oneline` 출력에서 커밋 메시지에 `"revert"`, `"cherry-pick"` 포함 건 검색
  - 계산 공식: `revert 횟수 / 전체 커밋 수 × 100%`
- **수집 주기**: 주간
- **목표값/기준선**: 원복 발생률 2% 미만 유지 (기준선: 첫 실행 시 이전 4주 평균)

---

### M-3: 팀 생산성

- **설명**: 팀 전체의 일일 task 완료 수. 자동화 및 분할 적용 전후 생산성 변화를 추적.
- **수집 방법**
  - 데이터 소스: `task-timers.json`에서 `status="completed"` 항목 집계
  - 계산 공식: `기간 내 완료 task 수 / 기간 일수`
- **수집 주기**: 일간
- **목표값/기준선**: 일일 완료 task 수 10% 향상 (기준선: 도입 전 2주 평균)

---

### M-4: 레벨 자동 추정 정확도

- **설명**: 시스템이 자동 추정한 작업 레벨과 실제 위임된 레벨의 일치율. 추정 모델의 품질 지표.
- **수집 방법**
  - 데이터 소스: `task-timers.json`의 `work_level` 필드 + 각 task 파일의 `level` 필드
  - 계산 공식: `추정 레벨 일치 건수 / 전체 측정 건수 × 100%`
- **수집 주기**: 월간
- **목표값/기준선**: 정확도 80% 이상 (기준선: 첫 월간 집계 값)

---

### M-5: Gemini 리뷰 결함 탐지율

- **설명**: Gemini AI 리뷰가 HIGH/MEDIUM 수준 결함을 사전에 탐지하는 비율. 마아트 QC에서만 발견된 이슈 대비 Gemini 선제 탐지 효과 측정.
- **수집 방법**
  - 데이터 소스: PR 리뷰 코멘트 (HIGH/MEDIUM severity 태그) + `memory/reports/`의 QC 결과 파일
  - 계산 공식: `Gemini 발견 이슈 수 / (Gemini 발견 + 마아트만 발견) × 100%`
- **수집 주기**: 주간
- **목표값/기준선**: 탐지율 70% 이상 (기준선: 첫 4주 평균)

---

### M-6: Codex 사전 검증 효과

- **설명**: G1 게이트에서 FAIL 판정을 받아 설계 변경이 일어난 비율. Codex 검증이 실제 설계 개선을 유도하는지 측정.
- **수집 방법**
  - 데이터 소스: `memory/events/`의 `g1-fail` 파일 + 해당 이슈 이후 설계 변경 커밋 (커밋 메시지에 `"design"`, `"redesign"`, `"architecture"` 포함)
  - 계산 공식: `G1 FAIL 후 설계 변경 건수 / 전체 G1 검증 건수`
- **수집 주기**: 주간
- **목표값/기준선**: 설계 변경 유도율 20% 이상 (기준선: 첫 4주 집계)

---

### M-7: 비용/ROI

- **설명**: 외부 AI(Gemini, Codex 등) 사용 비용 대비 결함 감소로 인해 절감된 가치. 투자 효율성 측정.
- **수집 방법**
  - 데이터 소스: `task-timers.json`의 `token_usage.cost_estimate_usd` 필드 합산
  - 계산 공식:
    - 외부 AI 총 비용 = `sum(token_usage.cost_estimate_usd)`
    - 결함 감소 가치 = `결함 감소 건수 × 결함 1건당 추정 비용 (기본값: $50/건)`
    - ROI = `(결함 감소 가치 - 외부 AI 총 비용) / 외부 AI 총 비용 × 100%`
- **수집 주기**: 월간
- **목표값/기준선**: ROI 양수 유지, 목표 ROI 200% 이상 (기준선: 첫 월간 집계)

---

## 수집 주기

| 주기 | 지표 |
|------|------|
| 일간 | M-3 (팀 생산성) |
| 주간 | M-1 (머지 충돌 감소율), M-2 (기능 원복 발생률), M-5 (Gemini 리뷰 결함 탐지율), M-6 (Codex 사전 검증 효과) |
| 월간 | M-4 (레벨 자동 추정 정확도), M-7 (비용/ROI) |

---

## 기준선 (Baseline)

현재 시점의 초기 값. `collect_metrics.py` 첫 실행으로 자동 수집.

- M-1, M-2: 첫 실행 시 이전 4주 git 이력에서 자동 산출
- M-3: 도입 전 2주 `task-timers.json` 히스토리에서 자동 산출
- M-4: 첫 월간 집계 결과를 기준선으로 설정
- M-5, M-6: 첫 4주 운영 데이터를 기준선으로 설정
- M-7: 첫 월간 비용/결함 데이터를 기준선으로 설정

---

## 대시보드 연동

```
collect_metrics.py
  → memory/daily/metrics-YYYY-MM-DD.json
  → weekly-report.py 호출 가능
```

- `collect_metrics.py`: 각 지표를 수집 주기에 따라 자동 계산하여 JSON 저장
- `memory/daily/metrics-YYYY-MM-DD.json`: 일별 스냅샷 저장 (일간/주간/월간 모두 포함)
- `weekly-report.py`: 주간 집계 및 트렌드 분석 리포트 생성