# task-614.1 완료 보고서: 코덱스 모델 분기 기능 구현

**S**: 집단지성 봇(multimodel-bot)이 코덱스 호출 시 `gpt-5.2-codex` 모델을 하드코딩하여 사용 중이다.

**C**: 에이전트 미팅 합의(2026-03-16)에 따라, 비용 절감을 위해 기본 모델을 `gpt-5.1-codex-mini`로 변경하고, 사용자가 `--deep` 플래그로 깊은 추론 모델을 선택할 수 있어야 한다. 출력 토큰 비용 차이가 2.3배($6/M vs $14/M)이므로 기본값 변경만으로도 유의미한 비용 절감 효과가 있다.

**Q**: `--deep` 플래그 기반 모델 분기를 기존 코드 패턴(code_analysis_mode)을 참고하여 안전하게 구현할 수 있는가?

**A**: TDD 방식으로 14개 신규 테스트 작성 후 구현 완료. engine.py에 model 파라미터 추가, discussion_manager.py에 --deep 감지 + codex_model 상태 관리, main_bot.py/codex_bot.py에 모델 전달 로직, 3개 봇 핸들러에 UX 표시 구현. 전체 278 테스트 PASS, pyright 0 errors (핵심 파일 기준).

## 구현 내용

### 1. engine.py — call_codex model 파라미터 추가
- `call_codex(prompt, timeout=600)` → `call_codex(prompt, model="gpt-5.1-codex-mini", timeout=600)`
- cmd 생성: `'model="gpt-5.2-codex"'` (하드코딩) → `f'model="{model}"'` (파라미터화)
- 기존 호출처는 기본값으로 동작하여 호환성 유지

### 2. discussion_manager.py — deep_analysis_mode 상태 추가
- `DiscussionState` dataclass에 `codex_model: str = "gpt-5.1-codex-mini"`, `deep_announced: bool = False` 필드 추가
- `on_user_message()`: `--deep` 감지 → `state.codex_model = "gpt-5.2-codex"`, 메시지에서 `--deep` 제거 후 duration/code_analysis 파싱
- `get_codex_model(chat_id) -> str` 메서드 추가
- `should_announce_deep_mode(chat_id) -> bool` 메서드 추가 (1회만 True)
- `stop_discussion()`: codex_model, deep_announced 초기화 추가

### 3. main_bot.py — trigger_next_bot_response에서 모델 전달
- `next_bot_username == "codex_view_bot"` 분기 추가
- `dm.get_codex_model(chat_id)`로 모델 조회 → `call_codex(context_prompt, model=codex_model)` 호출
- 기존 claude code_analysis 분기와 동일한 패턴 적용

### 4. codex_bot.py — handle_message에서 모델 전달
- `dm.get_codex_model(chat_id)` 조회 후 `call_codex(..., model=codex_model)` 호출 (memory 유/무 양쪽)
- `--deep` 플래그 메시지에서 제거 후 memory/context에 사용
- 심층 분석 모드 안내 메시지 전송

### 5. UX — 사용자 피드백
- 3개 봇 핸들러(gemini_bot.py, codex_bot.py, claude_bot.py) 모두에 deep 모드 안내 추가
- `should_announce_deep_mode()`로 1회만 "🔬 심층 분석 모드" 표시
- 일반 모드에서는 별도 표시 없음

## 생성/수정 파일 목록

- `/home/jay/workspace/services/multimodel-bot/engine.py` — call_codex model 파라미터 추가
- `/home/jay/workspace/services/multimodel-bot/discussion_manager.py` — codex_model 상태 + --deep 감지
- `/home/jay/workspace/services/multimodel-bot/main_bot.py` — codex 모델 전달 분기
- `/home/jay/workspace/services/multimodel-bot/codex_bot.py` — 모델 전달 + UX
- `/home/jay/workspace/services/multimodel-bot/gemini_bot.py` — --deep 제거 + UX
- `/home/jay/workspace/services/multimodel-bot/claude_bot.py` — --deep 제거 + UX
- `/home/jay/workspace/services/multimodel-bot/tests/test_engine.py` — 신규 테스트 3개
- `/home/jay/workspace/services/multimodel-bot/tests/test_discussion_manager.py` — 신규 테스트 11개 (TestDeepMode)
- `/home/jay/workspace/services/multimodel-bot/tests/test_thinking_mode.py` — 기존 테스트 업데이트 (codex 모델 전달 반영)

## 테스트 결과

- **전체**: 278 passed, 0 failed (0.98s)
- **신규 테스트**: 14개 추가 (engine 3 + discussion_manager 11)
- **기존 테스트**: 회귀 0건

### 신규 테스트 상세
**TestCallCodex (engine.py)**:
- `test_call_codex_default_model_is_mini` — PASS
- `test_call_codex_custom_model_passed_to_cmd` — PASS
- `test_call_codex_model_not_hardcoded` — PASS

**TestDeepMode (discussion_manager.py)**:
- `test_default_codex_model_is_mini` — PASS
- `test_deep_flag_sets_codex_model` — PASS
- `test_deep_flag_stripped_from_message` — PASS
- `test_deep_flag_with_duration` — PASS
- `test_get_codex_model_returns_model` — PASS
- `test_get_codex_model_default` — PASS
- `test_get_codex_model_unknown_chat` — PASS
- `test_stop_discussion_resets_codex_model` — PASS
- `test_deep_flag_without_extra_text` — PASS
- `test_no_deep_flag_keeps_default` — PASS
- `test_deep_mode_announced_flag` — PASS

## pyright 결과
- engine.py, discussion_manager.py: 0 errors, 0 warnings, 0 informations
- main_bot.py, codex_bot.py, gemini_bot.py, claude_bot.py: `reportMissingImports` (로컬 모듈 경로) — 기존 구조 이슈, 본 작업 변경과 무관

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **model 파라미터 위치** — `model`을 `timeout` 앞에 배치하여 기존 positional 호출 `call_codex(prompt, timeout=30)` 호환성 유지
   - 수정: engine.py:160 시그니처 `(prompt, model="...", timeout=600)`
2. **--deep 제거 타이밍** — on_user_message 내에서 duration/code_analysis 파싱 전에 --deep을 제거해야 "30분간 --deep 토론" 같은 입력이 정상 파싱됨
   - 수정: discussion_manager.py:242-245 cleaned_text 변수 도입
3. **test_thinking_mode.py 기존 테스트 호환** — codex_view_bot 분기 변경으로 기존 테스트의 mock 패턴 수정 필요
   - 수정: test_thinking_mode.py:329-380 `patch("main_bot.call_codex")` + `mock_dm.get_codex_model` 추가

## 제약 조건 준수 확인
- 모델명(gpt-5.2-codex 등) 사용자 비노출: `--deep` 플래그만 인터페이스, 모델명은 내부 로직에서만 사용
- 기존 테스트 미깨짐: 278 전체 PASS
- TDD 순서: 테스트 먼저 작성(RED) → 구현(GREEN) → 검증 확인

## QC 자동 검증 결과

```json
{
  "task_id": "task-614.1",
  "overall": "WARN",
  "summary": "6 PASS, 3 SKIP, 1 WARN",
  "checks": {
    "file_check": "PASS",
    "data_integrity": "PASS",
    "test_runner": "PASS (278 passed in 0.89s)",
    "tdd_check": "PASS",
    "style_check": "PASS (black+isort OK)",
    "critical_gap": "PASS",
    "pyright_check": "WARN (reportMissingImports — 프로젝트 로컬 경로 이슈, 본 작업과 무관)",
    "api_health": "SKIP",
    "schema_contract": "SKIP",
    "scope_check": "SKIP"
  }
}
```