# 머지 판단 자동 감지 시스템 스펙 문서 ## 1. 문제 정의 ### 실제 사고 사례 팀 운영 중 다음과 같은 사건이 발생했습니다: 1. **팀장이 worktree에서 작업 완료** - 로컬 워크트리에서 기능 개발/버그 수정 완료 2. **보고서에 머지 요청 기록** - 완료 보고서에 "merge 판단은 아누에게 위임" 등의 텍스트로 머지 필요성 기록 - 자유로운 텍스트 형식의 문장으로 작성 (구조화되지 않음) 3. **파싱 실패** - 아누(개발실장)가 보고서를 읽을 때 머지 관련 정보를 구조적으로 추출하지 못함 - 자유로운 문장에서 머지 의도를 자동으로 감지하는 로직 부재 4. **머지 대기 상태 누락** - 머지 필요 여부가 시스템에 기록되지 않음 - 워크트리의 변경사항이 메인 브랜치에 반영되지 않은 상태로 방치됨 5. **확대 사고** - 제이회장님이 직접 상황을 확인하고 개입해야 하는 상황 발생 - 자동화 시스템의 신뢰도 감소 ### 근본 원인 - 팀장의 보고서와 시스템 간 인터페이스 미정의 - 머지 의도를 감지하는 자동화 로직 부재 - .done 파일 형식에 머지 관련 필드 미지정 --- ## 2. 감지 흐름도 ``` ┌─────────────────────────────────────────────────────────────┐ │ 팀장 작업 완료 │ │ (worktree에서 개발/버그수정 완료) │ └────────────────────────┬────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 보고서 작성 │ │ - 작업 요약 │ │ - 머지 판단 섹션 (추가됨) │ │ - 브랜치명 명시 │ └────────────────────────┬────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ .done 이벤트 파일 생성 │ │ { │ │ "status": "completed", │ │ "merge_needed": true/false, │ │ "merge_branch": "task/task-100.1-dev2", │ │ "merge_reason": "팀장의 판단 또는 보고서 내용" │ │ } │ └────────────────────────┬────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 아누가 .done 파일 읽기 및 파싱 │ │ (자동 모니터링 프로세스) │ └────────────────────────┬────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ merge_needed 필드 감지 │ │ ├─ TRUE: 머지 필요 상태로 진입 │ │ └─ FALSE: 머지 불필요, 정상 종료 │ └────────────────────────┬────────────────────────────────────┘ │ ┌──────┴──────┐ │ │ ↓ ↓ (TRUE) (FALSE) │ │ ↓ ↓ ┌──────────────────────┐ ┌──────────────────┐ │ 🔀 머지 대기 표시 │ │ 정상 종료 │ │ merge_branch 값으로 │ │ 작업 완료 │ │ 대상 브랜치 식별 │ └──────────────────┘ │ 제이회장님께 보고 │ └────────────┬─────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 제이회장님 or 아누가 머지 실행 판단 │ │ (최종 검토 후 git merge 명령 실행) │ └────────────────────────┬────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 머지 완료 │ │ 메인 브랜치에 변경사항 반영 │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 3. 키워드 패턴 목록 ### 3.1 긍정 패턴 (merge_needed = True) | 패턴 | 설명 | 예시 | |------|------|------| | `머지 판단` | 머지 판단을 누군가에게 위임 | "merge 판단은 아누에게 위임" | | `merge 판단` | 영문 버전 | "merge 판단이 필요함" | | `머지 필요` | "없음/불필요" 미포함 시만 해당 | "머지 필요" | | `merge 필요` | 영문 버전 (부정 제외) | "merge 필요" | | `아누에게 위임` | 아누(개발실장)에게 머지 판단 위임 | "아누에게 위임" | | `아누 판단` | 아누의 최종 판단 필요 | "아누 판단 필요" | | `worktree + merge` | 워크트리 작업과 머지 언급 함께 | "worktree 작업 후 merge 필요" | | `워크트리 + 머지` | 한글 버전 | "워크트리 수정 후 머지 필요" | ### 3.2 부정 패턴 (merge_needed = False 유지) | 패턴 | 설명 | 우선순위 | |------|------|---------| | `머지 필요 없음` | 명시적 머지 불필요 선언 | 높음 | | `merge 불필요` | 영문 버전 | 높음 | | `머지 필요없음` | 띄어쓰기 없는 버전 | 높음 | | `merge 필요 없음` | 영문 띄어쓰기 있는 버전 | 높음 | ### 3.3 추출 패턴 | 대상 | 정규표현식 패턴 | 설명 | |------|-----------------|------| | 브랜치명 | `task/task-\d+\.\d+-dev\d+` | task/task-100.1-dev2 형식 | | 워크트리 경로 | `/home/jay/projects/.+/.worktrees/.+` | 표준 워크트리 경로 구조 | | 커미트 해시 | `[0-9a-f]{7,40}` | 짧은/긴 깃 커미트 해시 | --- ## 4. .done 파일 포맷 명세 ### 4.1 스키마 ```json { "status": "completed", "task_id": "task-100", "timestamp": "2026-03-07T15:30:45Z", "summary": "Worktree에서 작업 완료 - merge 판단은 아누에게 위임", "merge_needed": true, "merge_branch": "task/task-100.1-dev2", "merge_reason": "자동 감지: '아누에게 위임' 키워드 발견", "detected_keywords": ["아누에게 위임", "merge 판단"], "confidence": 0.95 } ``` ### 4.2 필드 설명 | 필드 | 타입 | 필수 | 설명 | |------|------|------|------| | status | string | Y | "completed" 고정값 | | task_id | string | Y | 작업 아이디 | | timestamp | ISO8601 | Y | 이벤트 발생 시간 (UTC) | | summary | string | Y | 작업 요약 (보고서 제목) | | merge_needed | boolean | Y | 머지 필요 여부 | | merge_branch | string | N | 대상 브랜치명 (merge_needed=true일 때만) | | merge_reason | string | Y | 판단 근거 (자동/수동) | | detected_keywords | array | N | 매칭된 키워드 목록 | | confidence | float | N | 감지 확신도 (0.0 ~ 1.0) | --- ## 5. 아누 처리 절차 ### 5.1 .done 파일 발견 시 처리 과정 #### Step 1: 파일 읽기 및 merge_needed 확인 ``` IF .done 파일 발견: - JSON 파싱 - merge_needed 필드 검사 - confidence 값 확인 (0.8 이상 권장) ``` #### Step 2: 머지 필요 상태 감지 ``` IF merge_needed == true AND confidence >= 0.8: - merge_branch 값 추출 - 브랜치 존재 여부 확인 - 보고서 요약에 "🔀 머지 대기" 강조 표시 추가 ``` #### Step 3: 로깅 및 보고 ``` - 로그: "[MERGE_DETECTED] branch={merge_branch}, confidence={confidence}" - 아누 상태 업데이트: merge_pending_branches = [merge_branch, ...] ``` #### Step 4: 제이회장님께 보고 ``` 보고 메시지: "🔀 머지 대기: {merge_branch} - 감지 사유: {merge_reason} - 확신도: {confidence*100}% - 팀장 메모: {summary}" ``` #### Step 5: 머지 실행 대기 ``` - 제이회장님 승인 대기 - 아누의 추가 검토 - git merge 명령 실행 ``` ### 5.2 예외 처리 | 상황 | 처리 방식 | |------|---------| | confidence < 0.8 | 수동 검토 필요, 아누에게 확인 요청 | | merge_branch 존재 안 함 | 오류 로그, 아누에게 브랜치 확인 요청 | | 보고서 파싱 실패 | 폴백: 보고서 텍스트 직접 키워드 검색 | | .done 파일 형식 오류 | 경고 로그, 무시 후 다음 파일 처리 | --- ## 6. 테스트 시나리오 ### 시나리오 1: 정상 머지 요청 감지 (Positive Case) **입력:** ``` 보고서 텍스트: "Worktree task-100.1-dev2에서 버그 수정 완료 결과물을 메인 브랜치에 반영하기 위해 merge 판단은 아누에게 위임합니다." .done 파일: { "merge_needed": true, "merge_branch": "task/task-100.1-dev2" } ``` **기대 결과:** - ✓ merge_needed = true - ✓ merge_branch = "task/task-100.1-dev2" - ✓ confidence >= 0.95 - ✓ detected_keywords = ["merge 판단", "아누에게 위임"] - ✓ 아누에게 "🔀 머지 대기: task/task-100.1-dev2" 보고 --- ### 시나리오 2: 머지 불필요 감지 (Negative Case) **입력:** ``` 보고서 텍스트: "Worktree task-200.1-dev1에서 문서 수정 완료 변경사항이 컴파일에 영향 없으므로 머지 필요 없음" .done 파일: 작성 안 함 또는 { "merge_needed": false } ``` **기대 결과:** - ✓ merge_needed = false - ✓ merge_branch = null 또는 undefined - ✓ 시스템이 머지 대기 상태로 전환하지 않음 - ✓ "작업 완료" 상태로 정상 종료 --- ### 시나리오 3: .done 파일 연동 자동 감지 **입력:** ``` .done 파일 생성: { "status": "completed", "task_id": "task-300", "timestamp": "2026-03-07T14:20:00Z", "summary": "Worktree 마이그레이션 작업 - 아누 판단 필요", "merge_needed": true, "merge_branch": "task/task-300.1-dev3", "merge_reason": "자동 감지: '아누 판단' 키워드 발견", "detected_keywords": ["아누 판단"], "confidence": 0.92 } ``` **기대 결과:** - ✓ 아누의 이벤트 모니터 가 .done 파일 감지 - ✓ merge_needed=true 파싱 완료 - ✓ 아누가 "🔀 머지 대기: task/task-300.1-dev3" 보고 - ✓ merge_branch 값으로 git 브랜치 존재 여부 확인 - ✓ 제이회장님 또는 아누가 머지 실행 판단 --- ### 추가 테스트 케이스 (엣지 케이스) #### 시나리오 4: 부정 패턴이 있는 경우 ``` 입력: "머지 필요 없음" 또는 "merge 불필요" 기대: merge_needed = false (부정 패턴이 긍정 패턴 우선) ``` #### 시나리오 5: 복합 조건 (머지 + 특정 브랜치) ``` 입력: "worktree task-400.2-dev1에서 작업 후 merge 필요" 기대: merge_needed = true, merge_branch = "task/task-400.2-dev1" ``` --- ## 7. 수정 대상 파일 목록 ### 7.1 `/home/jay/workspace/report_parser.py` **수정 사항:** - `parse_report()` 함수에 머지 필드 추출 로직 추가 - `detect_merge_needed()` 함수 구현 - `extract_branch_name()` 함수 구현 - 키워드 패턴 매칭 엔진 추가 **예상 함수 시그니처:** ```python def parse_report(report_text: str) -> dict: """보고서 파싱 및 머지 필드 추출""" result = { "summary": str, "merge_needed": bool, "merge_branch": str, "merge_reason": str, "detected_keywords": list, "confidence": float } return result def detect_merge_needed(text: str) -> tuple: """머지 필요 여부 감지 (boolean, confidence)""" pass def extract_branch_name(text: str) -> str: """텍스트에서 브랜치명 추출""" pass ``` ### 7.2 `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` **수정 사항:** - 보고서 필수 섹션 정의에 "머지 판단 섹션" 추가 - .done 파일 확장: merge_needed, merge_branch, merge_reason 필드 추가 - 팀장이 사용할 권장 표현식 (키워드 목록) 추가 - 예시 보고서 템플릿 업데이트 **추가 내용:** ```markdown ## 머지 판단 섹션 (필수) 보고서 마지막에 다음 중 하나를 명시: - 머지 필요: "merge 판단은 [담당자]에게 위임" 또는 "머지 필요" - 머지 불필요: "머지 필요 없음" 또는 "merge 불필요" ## .done 파일 형식 [위 4장의 스키마 참조] ``` ### 7.3 `/home/jay/workspace/tests/test_report_parser.py` **추가 테스트 케이스:** 1. `test_parse_report_positive_case()` - 시나리오 1 2. `test_parse_report_negative_case()` - 시나리오 2 3. `test_detect_merge_needed_keywords()` - 긍정 패턴 각 1개씩 4. `test_detect_merge_not_needed()` - 부정 패턴 각 1개씩 5. `test_extract_branch_name_valid()` - 브랜치명 추출 6. `test_extract_branch_name_invalid()` - 잘못된 브랜치명 7. `test_confidence_score_high()` - confidence >= 0.95 8. `test_confidence_score_low()` - confidence < 0.8 9. `test_edge_case_mixed_keywords()` - 긍정+부정 혼합 10. `test_edge_case_missing_branch()` - merge_needed=true지만 브랜치 미지정 --- ## 8. 구현 일정 및 우선순위 | 우선순위 | 작업 | 예상 기간 | |---------|------|---------| | P0 (긴급) | report_parser.py 머지 감지 로직 | 1일 | | P1 (높음) | 테스트 케이스 5개+ 작성 | 1일 | | P2 (중간) | DIRECT-WORKFLOW.md 업데이트 | 0.5일 | | P3 (낮음) | 아누 보고 UI 개선 | 필요시 | --- ## 9. 기대 효과 ### 9.1 시스템 개선 - 머지 판단 자동 감지로 수동 개입 제거 - 보고서와 시스템 간 인터페이스 명확화 - 머지 대기 상태 추적 가능 ### 9.2 팀 운영 효율성 - 제이회장님의 직접 확인 필요성 감소 - 아누의 업무 자동화 수준 향상 - 머지 누락으로 인한 사고 방지 ### 9.3 신뢰도 향상 - 일관된 처리 프로세스 확립 - 감지 확신도(confidence) 명시로 투명성 증가 - 엣지 케이스 처리 가이드라인 제시 --- ## 10. 참고사항 ### 10.1 키워드 감지 우선순위 1. **부정 패턴 우선** (높은 우선순위): "머지 필요 없음" 발견 시 merge_needed=false로 확정 2. **긍정 패턴**: "아누에게 위임", "머지 판단" 등 순서대로 확인 3. **컨텍스트 분석**: 문장 구조와 앞뒤 문맥 고려 ### 10.2 Confidence 점수 계산 ``` base_confidence = 0.5 + 0.25 (정확한 키워드 매칭) + 0.15 (브랜치명 추출 성공) + 0.10 (앞뒤 컨텍스트 일치) + 0.05 (추가 신호들) = 최대 1.0 ``` ### 10.3 향후 확장 가능성 - 자동 머지 실행 (제이회장님 승인 후) - 머지 충돌 자동 감지 - Slack 알림 통합 - 대시보드에서 머지 대기 상태 시각화 --- ## 부록 A: 키워드 매칭 정규표현식 ```python MERGE_POSITIVE_PATTERNS = [ r'머지\s*판단', # 머지 판단 r'merge\s*판단', # merge 판단 r'머지\s*필요(?!\s*없음)', # 머지 필요 (부정 미포함) r'merge\s*필요(?!\s*없음)', # merge 필요 (부정 미포함) r'아누(?:\s*에게)?\s*위임', # 아누에게 위임 / 아누 위임 r'아누\s*판단', # 아누 판단 r'워크트리.*머지|머지.*워크트리', # 워크트리 + 머지 r'worktree.*merge|merge.*worktree', # worktree + merge ] MERGE_NEGATIVE_PATTERNS = [ r'머지\s*필요\s*없음', # 머지 필요 없음 r'merge\s*불필요', # merge 불필요 r'머지\s*필요없음', # 머지 필요없음 (띄어쓰기 없음) r'merge\s*필요\s*없음', # merge 필요 없음 ] BRANCH_PATTERN = r'task/task-\d+\.\d+-dev\d+' WORKTREE_PATTERN = r'/home/jay/projects/[^/]+/\.worktrees/[^/]+' COMMIT_PATTERN = r'[0-9a-f]{7,40}' ``` --- **문서 버전:** 1.0 **작성일:** 2026-03-07 **작성자:** 헤임달(테스터) **상태:** 초안