# 시스템 개선 우선순위 목록 v1.0 > 기준: 영향도 × 실현 용이성 매트릭스 > 작성일: 2026-03-22 > 작성자: 헤르메스 (개발1팀장) --- ## 우선순위 매트릭스 ### 영향도 기준 (1~5) - 5: 시스템 전체 안정성/효율성에 직결 - 3: 특정 팀/영역의 품질 향상 - 1: nice-to-have ### 실현 용이성 기준 (1~5) - 5: 1~2줄 수정, 설정 변경 수준 - 3: verifier 1개 추가 또는 스크립트 작성 - 1: 아키텍처 변경 필요 --- ## 우선순위 정렬 (영향도×용이성 내림차순) ### P1: 병렬 실행 강화 (C) - **제목**: dispatch.py warning → block 전환으로 중복 작업 원천 차단 - **영향도**: 4/5 - **실현 용이성**: 5/5 - **종합 점수**: 20 - **예상 효과**: 동일 팀에 중복 작업이 배정되는 상황을 dispatch 단계에서 원천 차단. 현재 경고(warning)만 출력하고 통과시키는 구조를 거부(block) + 큐잉 방식으로 전환하여 경쟁 조건(race condition) 제거 - **필요 작업량**: 소 - **담당 적합 팀**: dev1-team - **의존 관계**: 없음 (즉시 실행 가능) - **구체적 구현 내용**: - `dispatch.py` 내 동일 팀 running 상태 확인 로직에서 `WARNING` 로그 후 통과하는 분기를 `dispatch 거부 + 대기열(queue) 등록`으로 교체 - 큐잉 시 caller에게 `QUEUED` 상태 반환, 선행 작업 완료 후 자동 재시도 --- ### P2: 보고서 내용 검증 강화 (F) - **제목**: file_check verifier 강화 + 보고서 유사도 검사 도입 - **영향도**: 5/5 - **실현 용이성**: 4/5 - **종합 점수**: 20 - **예상 효과**: task-787.1 유형의 허위/복사 보고서를 QC 단계에서 자동 탐지. 보고서 결과물 신뢰도가 시스템 전체 신뢰도와 직결되므로 영향도 최고 수준. 유사도 검사로 copy-paste 패턴을 조기 포착 - **필요 작업량**: 소~중 - **담당 적합 팀**: dev1-team - **의존 관계**: 없음 (즉시 실행 가능) - **구체적 구현 내용**: - **3-1** `file_check` verifier 강화: 보고서 본문에 `task_id` 포함 여부 확인, 필수 섹션(## 작업 결과, ## 변경 내용 등) 최소 N개 존재 여부 체크 - **3-2** 유사도 검사: 최근 N개 보고서와 텍스트 유사도(TF-IDF 코사인 유사도 또는 단순 diff 비율) 비교 → 80% 이상 일치 시 `WARN: 복사 의심` 경고 출력 및 수동 검토 플래그 설정 > **참고**: P1과 P2는 종합 점수가 동일(20)하나, P2는 영향도가 더 높고 P1은 용이성이 더 높음. 의존 관계가 없는 두 항목을 병렬로 착수하는 것이 최적 --- ### P3: 기능 검증 Eval 도입 (A) - **제목**: qc_verify.py에 spec_compliance verifier 추가 - **영향도**: 5/5 - **실현 용이성**: 3/5 - **종합 점수**: 15 - **예상 효과**: 작업 결과물이 지시서(tasks/task-xxx.md)의 요구사항을 실제로 충족하는지 자동 검증. 허위 완료 보고를 구조적으로 방지하며, 전체 QC 시스템의 핵심 기반이 됨 - **필요 작업량**: 중 - **담당 적합 팀**: dev1-team 또는 dev2-team - **의존 관계**: 없음 (독립 구현 가능) - **구체적 구현 내용**: - `qc_verify.py`에 `spec_compliance` verifier 클래스 추가 - `tasks/task-xxx.md` 파일에서 요구사항 섹션(## 작업, ## 요구사항 등)을 파싱하는 로직 구현 - 파싱된 요구사항 체크리스트와 실제 결과물(보고서, 생성 파일 목록 등)을 대조하여 PASS/FAIL/WARN 판정 - 초기에는 파일 존재 여부, 키워드 포함 여부 등 규칙 기반(rule-based)으로 구현 후 점진적 고도화 --- ### P4: 벤치마크 확장 (B) - **제목**: task-timer.py QC 결과 필드 추가 + 대시보드 히스토리컬 통계 탭 - **영향도**: 4/5 - **실현 용이성**: 3/5 - **종합 점수**: 12 - **예상 효과**: 팀별·작업유형별 성과 데이터가 축적되어 위임 의사결정 및 회귀 감지의 데이터 기반이 마련됨. P5(위임 정확도), P5(회귀 감지)의 전제 조건 - **필요 작업량**: 중 - **담당 적합 팀**: dev1-team (timer/QC 연동) + dev2-team (대시보드 UI) - **의존 관계**: 없음 (독립 착수 가능, 단 P5·P6이 이 데이터에 의존) - **구체적 구현 내용**: - **2-1** `task-timer.py` 데이터 모델에 `qc_result: "PASS" | "FAIL" | "WARN" | null` 필드 추가 - **2-2** `finish-task.sh` 또는 `qc_verify.py` 완료 훅에서 QC 판정 결과를 `task-timers.json`의 해당 task 레코드에 기록 - **2-3** 대시보드에 "히스토리컬 통계" 탭 추가: 팀별 평균 소요시간, QC 통과율 트렌드, 작업유형별 분포 차트 --- ### P5: 위임 정확도 개선 (D) - **제목**: dispatch.py에 팀별 실패율 기반 경고 로직 + team_specialties 필드 추가 - **영향도**: 4/5 - **실현 용이성**: 3/5 - **종합 점수**: 12 - **예상 효과**: 부적합 팀 배정으로 인한 재작업을 사전에 차단. 팀 전문성 정보가 dispatch 의사결정에 반영되어 전체 처리량(throughput) 향상 - **필요 작업량**: 소~중 - **담당 적합 팀**: dev1-team - **의존 관계**: B(벤치마크)에 의존 — `qc_result` 데이터가 누적되어야 실패율 집계 가능. P4 완료 후 착수 - **구체적 구현 내용**: - **5-1** `task-timers.json`의 `qc_result` 필드를 팀별로 집계하여 작업유형별 성공률 통계 산출 - **5-2** `dispatch.py`에 "해당 팀이 동일 작업유형에서 최근 3건 연속 FAIL이면 배정 경고 또는 대안 팀 제안" 로직 추가 - **5-3** `TEAM_INFO` 설정에 `team_specialties: [작업유형 목록]` 필드 추가, dispatch 시 전문성 매칭 점수 반영 --- ### P6: 회귀 감지 시스템 (E) - **제목**: 일일 canary 테스트 + 주간 메트릭 리포트 자동화 - **영향도**: 4/5 - **실현 용이성**: 2/5 - **종합 점수**: 8 - **예상 효과**: 시스템 전체 건강도를 지속 모니터링. stale 작업, QC FAIL 급증, 소요시간 이상 등을 조기 탐지하여 장애로 번지기 전에 대응 가능 - **필요 작업량**: 중 - **담당 적합 팀**: dev3-team (DevOps 성격) - **의존 관계**: B(벤치마크)에 부분 의존 — 주간 메트릭 리포트는 `qc_result` 데이터 필요. canary 테스트는 독립 구현 가능 - **구체적 구현 내용**: - **4-1** canary 테스트: `cron`으로 일 1회 dummy task dispatch → 실행 → 완료 확인 자동화. 실패 시 알림 - **4-2** 주간 핵심 메트릭 리포트: stale 발생 빈도, QC FAIL 비율, 팀별 평균 소요시간 트렌드를 마크다운 리포트로 자동 생성 및 지정 경로 저장 - **4-3** `task-timer.py` cleanup cron 등록 (기구현 로직을 스케줄러에 연결) --- ### P7: 워크플로우 Spec화 (G) - **제목**: DIRECT-WORKFLOW.md What/How 분리 + team_prompts.py 외부 파일화 - **영향도**: 3/5 - **실현 용이성**: 2/5 - **종합 점수**: 6 - **예상 효과**: 프롬프트 토큰 절감으로 비용 및 레이턴시 감소. 모델 업그레이드 시 How 섹션만 교체하면 되어 유지보수 유연성 확보. 단, 현재 How 기술이 품질 보장에 필수이므로 A(Eval)와 E(회귀 감지) 구축 완료 전까지는 신중하게 점진적으로 축소해야 함 - **필요 작업량**: 중 - **담당 적합 팀**: dev2-team - **의존 관계**: A(Eval, P3)와 E(회귀 감지, P6)가 먼저 구축되어야 How 섹션 축소 시 품질 저하를 안전망으로 포착 가능. 가장 나중에 착수 - **구체적 구현 내용**: - **7-1** `DIRECT-WORKFLOW.md`를 `WORKFLOW-WHAT.md`(항상 포함)와 `WORKFLOW-HOW.md`(실패 시에만 로드)로 분리 - **7-2** `team_prompts.py`의 `_build_cowork_section` 메서드를 외부 파일(`cowork-section.md`)로 분리하고, 필요 시에만 동적 로드하는 방식으로 리팩터링 - 리팩터링 전후 QC 통과율 비교 필수 (A, E 완료 후 측정 가능) --- ## 의존 관계 맵 ``` P1 (병렬 실행 강화) ── 독립 실행 가능 P2 (보고서 검증 강화) ── 독립 실행 가능 P3 (기능 검증 Eval) ── 독립 실행 가능 P4 (벤치마크 확장) ── 독립 실행 가능 │ ┌───────────┴───────────┐ ↓ ↓ P5 (위임 정확도) P6 (회귀 감지) ← P4 데이터 필요 ↑ P3(Eval) + P6 완료 후 안전 │ ↓ P7 (워크플로우 Spec화) ``` **요약**: - P4(벤치마크) → P5(위임 정확도): P5는 QC 결과 데이터 없이는 팀별 실패율 집계 불가 - P4(벤치마크) → P6(회귀 감지): 주간 메트릭 리포트 구성에 QC 결과 데이터 필요 (canary 테스트는 독립 가능) - P3(Eval) + P6(회귀 감지) → P7(워크플로우 Spec화): How 섹션 축소 시 품질 저하를 감지할 안전망이 먼저 필요 - P1, P2, P3는 상호 독립. 즉시 병렬 착수 권장 --- ## 추천 실행 순서 ### Phase 1: 즉시 실행 가능 (의존 관계 없음, 2~4주) | 항목 | 우선순위 | 담당 | |------|----------|------| | P1: 병렬 실행 강화 | 최우선 | dev1-team | | P2: 보고서 내용 검증 강화 | 최우선 | dev1-team | | P3: 기능 검증 Eval 도입 | 우선 | dev1-team 또는 dev2-team | | P4: 벤치마크 확장 | 우선 | dev1-team + dev2-team | > P1과 P2는 작업량이 소~중이며 즉각적인 품질 향상 효과가 크므로 최우선 병렬 착수. > P3와 P4는 중간 작업량이나 이후 단계의 전제 조건이므로 함께 착수하여 데이터 파이프라인을 조기 확립. ### Phase 2: P4(벤치마크) 완료 후 (4~8주) | 항목 | 우선순위 | 담당 | |------|----------|------| | P5: 위임 정확도 개선 | 중 | dev1-team | | P6: 회귀 감지 시스템 | 중 | dev3-team | > `task-timers.json`에 `qc_result` 데이터가 충분히 쌓인 후 착수. > canary 테스트(P6의 4-1)는 P4와 무관하게 Phase 1에서 선행 구현 가능. ### Phase 3: P3 + P6 완료 후 (8주 이후, 장기) | 항목 | 우선순위 | 담당 | |------|----------|------| | P7: 워크플로우 Spec화 | 낮음 | dev2-team | > Eval 시스템과 회귀 감지가 안전망으로 작동하는 것을 확인한 후 점진적으로 How 섹션을 분리. > 한 번에 전체를 리팩터링하지 말고, 섹션별로 분리 → 2주 관찰 → 다음 섹션 순서로 진행.