---
task_id: task-2273
type: context
scope: task
created: 2026-04-28
updated: 2026-04-28
status: completed
---

# 맥락 노트: task-2273

**task**: task-2273

---

## 결정 근거

### 3 Step Why

**1st Why: 왜 이 설계가 필요한가?**
→ 모든 AI 기능이 아누 서버(claude CLI subprocess)로 집중되는데, 현재 콘텐츠 생성만 Semaphore 기반 큐가 적용되어 있어 나머지 AI 기능(채팅, 코파일럿, 온보딩 등)에서 동시 요청 과부하 위험이 있다.

**2nd Why: 왜 통합 큐가 최선의 접근인가?**
→ 개별 엔드포인트마다 Semaphore를 추가하면 코드 중복이 심해지고 전체 동시 실행 수 제어가 불가능하다. 하나의 통합 큐로 모든 AI 호출을 관리하면 전체 리소스를 효율적으로 제어 가능.

**3rd Why: 왜 기존 generation_queue.py 유지가 대안보다 나은가?**
→ 기존 generation_queue를 제거하면 API 호환성이 깨질 위험. wrapper로 전환하면 기존 코드의 import/참조를 유지하면서 점진적 마이그레이션 가능.

### PriorityQueue 미채택 결정
- Codex 리뷰에서 asyncio.PriorityQueue + dispatcher 패턴 권고
- 검토 결과: 현재 규모에서는 과도한 복잡성. asyncio.Semaphore의 FIFO fair scheduling으로 충분
- 우선순위(AIPriority)는 메타데이터로 저장·조회에 활용하되 실제 스케줄링에는 미적용
- 향후 과부하 패턴이 확인되면 PriorityQueue 도입 검토

### max_concurrent=10 유지 결정
- Codex 리뷰에서 기존 10 → 5 변경 제안 경고
- 기존 generation_queue.MAX_CONCURRENT=10 유지하여 처리량 급감 방지
- threading.Semaphore(3) 파싱 경로와 중첩 가능성 있지만, ai_queue는 async 세마포어라 blocking 없음

## 참조 자료

- Codex 사전 검증 결과: 8개 리스크 식별 (critical 1, high 4, medium 3)
- 기존 generation_queue.py: `/home/jay/projects/InsuRo/server/generation_queue.py`
- 태스크 지시서: `/home/jay/workspace/memory/tasks/task-2273.md`

## 주의사항

- _run_compliance_check_async는 이미 generation_queue.submit 내부에서 호출되므로 중복 큐 적용하지 않음
- keywords/analyze는 BackgroundTasks를 사용하여 별도 처리 (ai_queue 미적용)
- parse_premium_file은 동기 subprocess(_smart_parse_file) 사용으로 구조가 달라 현재 미적용