---
task_id: task-43.0
type: context
scope: system
project: anu-guide-system
created: 2026-03-02
updated: 2026-04-24
status: active
---

# 맥락 노트: 아누 가이드 시스템 구축

**task**: task-43.0

---

## 결정 근거

### 왜 hooks가 최우선인가?
- Agent 미팅 6명 전원 동의: hooks가 모든 자동화의 뿌리
- 아누 가이드 Section 1 전체가 hooks 의존
- hooks 없이는 매뉴얼 자동 주입, Audit Trail, 셀프체크 리마인더 모두 불가

### 왜 보안을 즉시 조치하는가?
- 로키 발견: dispatch.py 34-39행에 BOT_KEYS 평문 하드코딩 (폴백)
- 환경변수 미설정 시 키가 코드에 노출 → 보안 위반
- 파일 권한 664 → 그룹 내 누구나 변조 가능

### 왜 1팀에 Phase 0, 2팀에 Phase 1?
- Phase 0(hooks)는 실행 중심 → 헤르메스(빠른 판단)에 적합
- Phase 1(skills)은 설계 중심 → 오딘(아키텍처 관점)에 적합

### 비너스 경고 반영
- 동시 구현 금지 → 순차 실행 (즉시→Phase 0→Phase 1)
- 각 Phase 완료 확인 후 다음 진행
- 인터페이스 단순하게 유지

## 참조 자료
- 아누 가이드: `memory/specs/anu-guide.md`
- Agent 미팅: `memory/meetings/2026-03-02-anu-guide-gap-analysis.md`
- Claude Code hooks 스펙: 1팀이 리서치 필요
- 조직도: `memory/organization-structure.json`

## 주의사항
- hooks는 전역 공유 (야누스 경고) → detect-bot.sh로 봇별 분기 필수
- hooks 실패 시 전체 블로킹 위험 (헤르메스 경고) → try/except + fallback
- QC 트리거는 Phase 2로 미룸 → hooks에 QC 로직 넣지 말 것

---

## Phase 4 결정 근거 (2026-04-24 추가)

### 3대 루트 원인 분석

**RC-1: 영향 범위 전수조사 누락**
- 사례: task-2142 — FeatureGate.tsx L41 수정했으나 use-feature-access.ts에 동일 로직 누락
- 원인: affected_files를 아누가 수동 기재하는 구조. 아누가 빠뜨리면 전체 무력화
- 기존 방어: dispatch.py `_enrich_affected_files_with_ast()`는 Python만 지원, TS/TSX는 범위 밖

**RC-2: 연쇄 이슈 직렬 발견**
- 사례: task-2143(Vitest supabaseUrl) → task-2144(pytest doc_parser) — 같은 CI인데 2건 분리
- 원인: finish-task.sh의 test_runner가 `--check-files` 기반 부분 테스트만 실행
- 기존 방어: 없음 (멀티 러너 CI 게이트 부재)

**RC-3: 실동작 미검증**
- 사례: task-2140 — "인증 필요 환경으로 UI 직접 확인 불가"인데 완료 처리
- 원인: l1_smoketest_check가 "해당없음" 패턴을 허용
- 기존 방어: browser_verify는 스크린샷 파일 존재만 확인 (캡처 자동화 없음)

### 핵심 설계 판단

**왜 post-flight(finish-task.sh) 중심인가?**
- 로키 제안: pre-flight(dispatch.py)는 아누 의존 → 아누가 빠뜨리면 무력화
- post-flight는 봇이 작업 완료 후 자동 실행 → 아누 의존도 제거
- 합의: pre-flight + post-flight 양면 방어, post-flight에 무게

**왜 Phase 1A/1B 분리인가?**
- 로키 경고: grep 기반 false positive 폭발 위험 + CI 타임아웃 → 정당한 작업 차단
- 합의: 명백한 위반(l1_smoketest, goal_assertions)만 즉시 FAIL, 나머지는 WARN 모드 2주 데이터 수집
- 전환 기준: false positive < 10% 시 WARN → FAIL 승격

**왜 grep 기반이고 AST/LSP가 아닌가?**
- 헤르메스: Python은 AST 가능하지만 TypeScript는 tsc 파서 의존성 과다
- 합의: Python=AST, TypeScript=regex 기반 (`export function/class/type/interface`)
- 로키 반론 반영: 백틱 코드 토큰만 추출 + COMMON_FILTER 20단어로 정밀도 확보

**Goal Assertions 패턴 채택 이유**
- 오딘 제안: task 파일에 실행 가능한 shell command로 완료 기준 명시
- 코딩 4원칙 "Goal-Driven Execution"과 완벽 합치
- dispatch.py가 task 파일의 검증 시나리오에서 자동 생성 가능

### 기각된 대안
- **Shadow Run (라 제안)**: Haiku 세션 추가 spawn으로 독립 검증 → 세션 관리 복잡도 + 완료 지연 위험으로 기각
- **affected_files 전면 AST 분석 (헤르메스 초안)**: TypeScript AST 파서 의존성 과다, grep + regex로 충분
- **CI 전체 실행 (엔키 초안)**: InsuRo 4000+ TS 파일 → tsc 3분 소요 → 타임아웃 위험. 러너당 120초 제한으로 타협
- **미해결 이슈 전면 차단 (쿠쿨칸 초안)**: "범위 외" 정당한 미해결도 차단 → "범위 내" 미해결만 카운트로 수정

## 참조 자료 (Phase 4)
- Agent 미팅: `memory/meetings/2026-04-24-dispatch-quality-automation.md` (13명 5사이클)
- dispatch.py 기존 함수: `_parse_affected_files()`(766행), `_enrich_affected_files_with_ast()`(812행)
- finish-task.sh 기존 게이트: Step 0~2.10 (부록 참조)
- qc_verify.py verifier 21개: l1_smoketest_check, scope_check, browser_verify 등

## 주의사항 (Phase 4)
- 신규 게이트는 subshell 격리 실행 (C-FINAL-9) — 한 게이트 실패가 다른 게이트 차단 방지
- gate-config.json이 단일 소스 — 코드에 임계치 하드코딩 금지
- impact_scanner의 grep 타임아웃: 심볼당 3초, 전체 15초 (무한 대기 방지)
- ci_preflight의 러너 타임아웃: 120초/러너, 전체 300초 (봇 세션 보호)
- "확인 불가" 차단의 EXEMPT 조건: task 키워드에 UI/컴포넌트/화면 없으면 스크린샷 면제