# 계획서: codegraph-anu — 아누 시스템 코드그래프 정식 통합

**프로젝트**: 아누 시스템에 코드그래프 기반 컨텍스트 최적화 도입
**작업 레벨**: Lv.3 (시스템 인프라)
**status**: in-progress
**작성일**: 2026-05-01
**근거**: 2026-04-16 Agent 미팅 만장일치(10/10) + 4월 부분 적용 후 Phase 2~4 미완 + 금번 재검토(2026-05-01)
**선행 자산**:
- 4월 메모리: `memory/meetings/2026-04-16-codegraph-adoption.md`, `2026-04-16-code-review-graph-cycle2-consensus.md`
- 4월 보고서: `memory/reports/codegraph-benchmark.md`, `task-1869.md`, `task-1869_2.2.md`, `task-1869_2.2+1.md` 등
- 4월 머지: dispatch.py `_get_ast_blast_radius`(line 1027), `_enrich_affected_files_with_ast`(line 3147)

---

## 1. 배경 및 문제 정의

4월 16일 미팅에서 함수 의존성 자동 추적(affected_files 자동 보강)을 위해 코드그래프 도입을 만장일치 합의. Phase 1(벤치마크) 결과 자체 AST 스크립트가 Python 위주 dispatch 정확도 측면에서 더 적합 → 자체 AST를 dispatch.py에 통합 머지(task-1869_2.2+2/+3).

**그러나 두 가지 미완 영역:**

1. **AST 통합이 timeout 빈번** — 최근 task-2335/2336 위임 시 `[ast-blast-radius] 타임아웃(30s) — 원래 affected_files 사용` 로그 발생 → 자동 보강 실효성 50% 미만
2. **봇 MCP 컨텍스트 절감 미적용** — code-review-graph가 진짜 노리는 8.2x 토큰 절감(8개 dev 봇 대량 작업 시 큰 비용 효과)은 4월에 한 번도 실험 안 됨. 4월 결정은 "dispatch 보강 용도 부적합"이지 "MCP 컨텍스트 부적합"이 아님.

→ 두 트랙 분리해서 재정비 필요.

---

## 2. 목표

- **트랙 A (dispatch 트랙)**: 자체 AST 스크립트 timeout 0%로 안정화 → affected_files 자동 보강 작동률 100%
- **트랙 B (봇 MCP 트랙)**: code-review-graph 정식 도입 → 8개 dev 봇 컨텍스트 토큰 30%+ 절감 (4월 벤치마크 8.2x는 옵션)

---

## 3. 범위 (Phase 분리)

### Phase 1 — 잔존물 정리 + AST 안정화 (트랙 A)
- 워크스페이스 루트 `.code-review-graph/graph.db` 612MB 정리 (4월 잔존물)
- 워크트리 `task-2117-dev1`의 `.codegraph-venv` 검토 및 정리
- `scripts/ast_dependency_map.py` 30초 timeout 원인 진단:
  - 캐시 미사용? 병렬 처리? 분석 깊이 무제한? 큰 파일?
  - `dispatch.py:1027 _get_ast_blast_radius()` + `dispatch.py:3147 _enrich_affected_files_with_ast()` 로직 점검
- 진단 후 timeout 0% 만드는 패치 적용
- 검증: 최근 5개 task에 대해 dry-run 시뮬레이션 → 모두 30초 안 통과

### Phase 2 — code-review-graph MCP PoC (트랙 B, 1주 시한)
- `pip install code-review-graph` (최신 버전, 4월 v2.3.2 → 5월 신버전 확인)
- **InsuRo 프로젝트 1개만** 그래프 빌드 (워크스페이스 전체 X — 4월 실패 원인)
- crg-daemon으로 InsuRo만 watch
- **dev7-team 봇 1개**에 MCP 서버 등록 (`~/.claude/settings.json` 또는 dev7 settings)
- 다음 dev7 task 시 토큰 사용량 측정:
  - Before(현재): task당 입력 토큰 평균
  - After: MCP 활성 후 task당 입력 토큰 평균
- 1주 안 결과 보고

### Phase 3 — 8팀 확장 (조건부, PoC 성공 시)
- 6개 프로젝트 그래프 빌드 (InsuRo, insuwiki, ThreadAuto, MediScan, BlogAuto, dashboard)
- crg-daemon 백그라운드 가동 (systemd 또는 수동)
- 8개 dev 봇 settings.json 일괄 등록
- 일관성 관리 자동화 (등록 스크립트)

### Phase 4 — 고급 기능 (조건부, Phase 3 안정화 후)
- hub/bridge 노드 분석 → 영향 큰 변경 식별
- knowledge gap detection → 미테스트 영역 자동 알림
- detect_changes risk score → PR 머지 게이트(G3)에 자동 첨부
- get_suggested_questions → 리뷰 시 자동 질문 생성

---

## 4. 측정 지표 (KPI) — 4월 실패 방지 핵심

### Phase 1 KPI
- AST timeout 발생률: 현재 ~50% → 목표 **0%**
- 평균 응답 시간: 현재 (timeout 발생 시) 30s → 목표 **5초 이내**
- dispatch 시 affected_files 자동 보강 적용률: 목표 **100%**

### Phase 2 PoC KPI (1주 측정)
- dev7 봇 task 입력 토큰 평균: Before vs After **30%+ 절감**
- 작업 품질 유지: 테스트 회귀 **0건**
- MCP 안정성: 1주간 daemon 다운 **0건**
- ⚠️ **PoC 성공 = 30% 절감 + 회귀 0** 두 조건 동시 충족 시에만 Phase 3

### 정착 vs 폐기 결정 기준
- ✅ 정착: KPI 충족 + 운영 부담 작음 → Phase 3 진입
- ❌ 폐기: KPI 미충족 또는 운영 부담 큼 → 자체 AST만 유지

---

## 5. 4월 실패 방지 장치

| 4월 실패 원인 | 이번 방지책 |
|---|---|
| 워크스페이스 전체 612MB 단일 그래프 | **프로젝트별 분리** (InsuRo만 우선) |
| 모든 봇 일괄 적용 시도 | **PoC: 1봇 + 1프로젝트만** |
| 측정 지표 모호 → 흐지부지 | **명확한 KPI** (토큰 30% 절감, 회귀 0) |
| 시한 없음 | **1주 안 측정 보고 의무** |
| "정밀도 낮다"로 폐기 | **두 트랙 분리** — dispatch는 자체 AST, MCP만 별도 |

---

## 6. 의존성 / 영향 범위

**수정/생성:**
- `scripts/ast_dependency_map.py` (트랙 A 패치)
- `dispatch.py:1027/3147` (트랙 A 보조 패치 가능)
- `~/.claude/settings.json` 또는 dev7 봇 전용 설정 (트랙 B MCP)
- `~/.code-review-graph/watch.toml` (crg-daemon 설정, 트랙 B)

**정리:**
- `/home/jay/workspace/.code-review-graph/graph.db` (612MB 잔존물)
- `.worktrees/task-2117-dev1/scripts/.codegraph-venv/` (검토 후 정리)

**측정 도구:**
- 봇 task별 토큰 로그 (이미 task-timer/dispatch에 일부 있음)
- 또는 별도 측정 스크립트

---

## 7. 보안 / 운영 메모

- code-review-graph는 로컬 SQLite, 외부 의존성 0 → 보안 위험 작음
- daemon 가동 시 CPU/메모리 모니터링 필요
- 워크트리 격리: 각 봇 워크트리에서 별도 그래프? 또는 메인 프로젝트 그래프 공유? → PoC 단계에서 결정

---

## 8. 리스크

1. ⚠️ AST timeout 원인이 아키텍처적이면 (예: 23,000줄 dispatch.py 자체 분석에 30초 부족) 단순 패치 어려울 수 있음 → fallback: AST 분석 대상에서 dispatch.py 제외
2. ⚠️ MCP 등록 후 봇이 자발적으로 graph 도구 호출 안 하면 효과 0 → 봇 prompt에 명시적 지시 필요할 수 있음
3. ⚠️ crg-daemon이 워크트리 변동마다 재인덱스하면 부하 가능 → exclusion rule 설정 필요

---

## 9. 다음 단계

- [x] 3문서 작성
- [x] Phase 1+2 task 위임 (dev7-team 한정승인) — task-2337
- [x] Phase 1 완료 보고 (`memory/reports/codegraph-anu-phase1.md`, 2026-05-01)
- [x] Phase 2 인프라 셋업 (`memory/reports/codegraph-anu-phase2-setup.md`, 2026-05-01)
- [ ] Phase 2 1주 후 KPI 측정 보고 (2026-05-08까지 → `codegraph-anu-phase2-poc.md`)
- [ ] 정착 vs 폐기 결정