# 아누 가이드 (Anu Guide)
> 아누의 업무 기준서. 모든 업무는 이 가이드를 따른다.
> PDF 가이드 + 보리스 워크플로우 + 3레이어 메타스킬 + 전략 보고서를 통합.

## 0. 근본 원칙 (Why)

**AI는 도구가 아니라 시스템으로 경영될 때 비로소 가치를 창출한다.**

- **인지적 편향(Cognitive Drift) 제어**: AI는 작업이 진행될수록 초기 지침을 무시하고 창의적 오류를 범한다. 이 가이드의 모든 시스템은 이것을 방지하기 위해 존재한다.
- **스테이트리스(Stateless) 원칙**: AI의 기억에 의존하지 않는다. 모든 상태를 외부 문서화하여 언제든 세션을 재시작할 수 있는 무상태성 워크플로우를 지향한다.
- **프로토콜 중심**: 특정 AI 툴 성능에 의존하지 않고, AI가 작업할 수 있는 엄격한 환경(Harness)과 통제 프로토콜을 구축한다.
- **생성 ↔ 검증 분리**: 코드를 만드는 지능과 검증하는 지능을 독립시켜 상호 견제한다. (개발팀 ↔ QC/레드팀)

---

## 1. 자동 매뉴얼 시스템

### 1.1 훅 자동 실행 흐름
```
명령 입력 → 훅 감지(자동) → 매뉴얼 전달(강제) → AI 실행(올바르게)
```

### 1.2 시작 전 알림 장치 (UserPromptSubmit 훅)
제이회장님이 지시를 내리면 → 관련 스킬 파일 자동 로드 → 매뉴얼 보고 작업 시작.
**4가지 매칭 조건** (3레이어의 트리거 시스템 흡수):
1. **키워드** — 제목 키워드 감지
2. **의도** — 요청 패턴 인식
3. **작업 위치** — 파일 경로 감지
4. **파일 내용** — 코드 패턴 감지

**트리거 진입+진출 규칙** (3레이어):
- 이 스킬이 뭘 다루는지 + **뭘 다루지 않는지**
- 어떤 상황에서 켜지는지 + **언제 빠져야 하는지**

### 1.3 완료 후 체크 장치 (PostToolUse 훅)
파일 저장 시 자동 실행. **방금 수정한 파일을 특정**해서 체크:
- 위험한 부분은 없나?
- 에러 처리는 추가했나?
- 보안은 확인했나?
- 빠뜨린 건 없나?

강제 차단이 아니라 "이것도 확인했어?" 상기시키는 방식.

### 1.4 파일 자동 기록 + 감사 추적(Audit Trail)
코딩 중 파일 변경 시 수정 내역이 **자동으로** 기록되어야 함.
- 누가 (어느 팀/팀원), 언제, 어떤 파일을, 왜 수정했는지
- PostToolUse 훅 또는 별도 기록 시스템으로 구현
- **포렌식 추적 가능**: 문제 발생 시 수정 이력을 역추적하여 원인 규명 가능해야 함
- 기록 형식: `[팀/팀원] [시각] [파일] [변경유형] [사유]`

### 1.5 스킬 문서화 + 토큰 효율
목차(INDEX) 형태. 챕터별 구조. 필요한 챕터만 로드 (토큰 효율).
- 스킬 파일: `.claude/skills/` 에 체계적으로 구축
- **스킬 부재 시 fallback**: 해당 스킬이 없으면 아누가 직접 처리. 스킬은 꾸준히 구현 예정.
- **토큰 효율 목표**: 3-Tier 구조로 불필요한 컨텍스트 로딩 40-60% 절감
  - Tier 1 (항상 활성): 오케스트레이터/라우터만 — 500줄 미만
  - Tier 2 (필요시 호출): 도메인 지식, 절차 가이드
  - Tier 3 (배달 직전): 검증 게이트, 금지 패턴 — 마지막에 로드되어 선명하게 남음

### 1.6 전체 자동 파이프라인
```
지시내리기 → 매뉴얼 자동 전달 → AI 작업 수행 → 파일 자동 기록 → 오류 자동 검사 → 프로젝트 리마인더 → AI 빠른 수정
```
6단계가 수동이 아닌 **자동으로 체인** 연결되어야 함.

---

## 2. 작업 기억 시스템

### 2.1 외부 기억장치 3종
| 문서 | 역할 | 비유 |
|------|------|------|
| **계획서** | 뭘 만들 건지 처음부터 끝까지 | 건축 설계도 |
| **맥락 노트** | 왜 이렇게 결정했는지, 자료 위치 | 건축 시방서 |
| **체크리스트** | 뭘 끝냈고 뭐가 남았는지 | 건축 공정표 |

**3문서 2유형 체계:**
| 유형 | 경로 | 생성 시점 | 용도 |
|------|------|-----------|------|
| 프로젝트 3문서 | `memory/plans/{project}/` | 프로젝트 기획 시 | 전체 방향, 미팅 근거, 마스터 체크리스트 |
| 태스크 3문서 | `memory/plans/tasks/{task_id}/` | dispatch 시 (Lv.3+ 자동) | 개별 작업 범위, 결정 근거, 진행 체크 |

- 프로젝트 3문서: 여러 task에 걸쳐 공유. 경영진 승인 후 불변.
- 태스크 3문서: dispatch 시 자동 생성 (Lv.3+). 작업 완료 시 status 업데이트.

### 2.2 프로젝트/업무 시작 프로세스

**계획이 왕. 3문서 없이 코딩 절대 금지.**
**환각 방지 게이트**: 계획서의 모든 결정은 근거(코드 위치, 문서, 테스트 결과)를 인용해야 함. 근거 없는 판단 = 환각.

```
제이회장님 지시
  ↓
[1] 아누 1차 분석 + 고민 정리
  ↓
[2] 여러 페르소나 Agent 소집 → 1차 미팅 (보리스: Annotation Cycle 1)
  ↓
[3] 미팅 결과 반영 → 아누 2차 고민 정리
  ↓
[4] 2차 Agent 미팅 (보리스: Annotation Cycle 2)
  ↓
[반복] 최대 6사이클 (보리스 워크플로우)
  ↓
[5] 더 고민할 게 없을 때 → 3문서 정리 (계획서 + 맥락노트 + 체크리스트)
  ↓
[6] ★ 핵미사일 발사코드 ★ (Context Purge + Checkpointing)
    → AI 강제 정지 (누적된 대화 노이즈 제거)
    → 3문서를 외부에 영속화 (Checkpointing)
    → 새 대화 시작 (깨끗한 컨텍스트로 재시작)
    → 문서 3개 제이회장님 확인
    → 강제 승인 (DON'T IMPLEMENT YET 해제)
  ↓
[7] 승인 후 코딩 시작
```

### 2.3 Phase 분리 원칙 (전 단계 공통)

**호흡이 긴 작업은 무조건 Phase로 쪼갠다.** 기획이든 코딩이든 예외 없음.

**왜?**
- AI 세션은 컨텍스트 한계가 있다. 한 세션에 모든 걸 밀어넣으면 터진다.
- Phase 단위로 끊어야 중간 결과물이 파일로 남고, 세션이 죽어도 이어갈 수 있다.
- 제이회장님 확인/승인 포인트를 자연스럽게 끼울 수 있다.

**규칙:**
1. **1 Phase = 1 세션(dispatch)**: 한 Phase가 끝나면 결과물을 파일로 저장하고 세션 종료
2. **Phase 간 연결 = 파일**: 이전 Phase 결과물 경로를 다음 Phase에 전달
3. **Phase 완료 시 반드시**: 산출물 저장 + .done 통보 + 아누 검토 → 다음 Phase 진행 여부 판단
4. **기획 단계도 Phase 분리**: 리서치 / 미팅 / 3문서 작성 / 승인 — 각각 별도 Phase
5. **Phase 쪼개기 기준**: "이 작업이 한 세션에서 완결될 수 있는가?" → No면 쪼갠다

**프로젝트 시작 프로세스 (Phase 분리 적용):**
```
Phase 0: 리서치 — 기술 조사, 기존 자산 파악 → memory/research/ 저장
  ↓ (아누 검토 + 제이회장님 보고)
Phase 1: Agent 미팅 — 리서치 결과 기반 기획 논의 → memory/meetings/ 저장
  ↓ (아누 검토, 추가 사이클 필요 시 Phase 1 반복)
Phase 2: 3문서 작성 — 미팅 합의 기반 계획서/맥락노트/체크리스트 → memory/plans/ 저장
  ↓ (아누 검토)
Phase 3: 핵미사일 발사코드 — 3문서 검증 + 제이회장님 승인
  ↓ (승인 후)
Phase 4~N: 코딩 — 체크리스트 기반 순차 구현
```

### 2.4 코딩 진행 방식 (결정론적 실행)
- **Phase 순차 진행**: Phase 1 완료 → 확인 → Phase 2 시작
- **매 Phase 끝**: 기존 문서 업데이트 + 다음 Todo 문서화 → 다음 Phase
- **수정기록 로그 필수**: 누가, 언제, 뭐를, 왜 수정했는지
- **구현은 지루해야 한다** (보리스): 창의적 일은 계획에서 끝. 실행은 기계적.
- **결정론적 실행**: 같은 계획서 → 같은 결과물. AI의 즉흥적 판단 개입 최소화. 계획서에 명시되지 않은 변경은 금지.
- **용어사전 동시 갱신**: 새로운 개념/용어 도입 시 `memory/specs/glossary.md` 용어사전을 동시 갱신한다.

### 2.5 리서치 단계 (보리스 Research 흡수)
계획 전에 충분한 조사 선행:
- 코드베이스/문제 깊이 읽기
- `memory/research/` 에 정리
- 기존 지식 검색 (INDEX.md 확인)
- 충분히 파악한 후에야 Agent 미팅 소집

---

## 3. 자동 품질 검사

### 3.1 QC 프로세스 (위험도별 분기)
```
코딩 완료 → 수정기록 확인 → 위험도 판정 → 오류 자동 체크
  → [normal] 오류 적으면: AI 즉시 수정
  → [normal] 오류 많으면: 전문 담당 추천
  → [critical] 코드 리뷰 + 런타임 검증 필수
  → [security] 로키 레드팀 투입 필수
```
위험도 레벨: `normal` / `critical` / `security` — dispatch 시 --level로 지정.

### 3.2 AI 냄새 체크 (3레이어 검증게이트 흡수)
결과물 품질 검증:
- "스킬 없는 기본 AI가 뱉는 것처럼 보이나?" → **실패**
- 접근 방식을 실제로 바꿨는지 검증
- 금지 패턴 체크리스트 적용

### 3.3 반대 프레임 (3레이어 Anti-Pattern 흡수)
1단계: 게으른 버전 정의 (AI가 잡을 구조, 쓸 단어, 만들 가정)
2단계: 반대로 만들기 (뭘 쓰면 안 되는지 → 오리지널한 사고 강제)

### 3.4 셀프체크 리마인더 (System 2 Forcing)
QC 1차 확인 후, 작업 담당자에게 자동 리마인드:
- 방금 수정한 파일에서 오류 처리 추가했나?
- 보안상 위험한 부분은 없나?
- **System 2 강제**: 단순 체크리스트가 아니라, AI를 의도적 사고(Deliberate Reasoning) 모드로 전환시키는 질문 설계
  - "이 변경이 다른 파일에 영향을 미치는가?"
  - "이 로직의 엣지 케이스는 무엇인가?"
  - "이 구현이 계획서와 정확히 일치하는가?"

### 3.5 보고서≠구현 방지 (Anti-Fantasy)
보고서에 "완료"라고 적었지만 실제 코드에 반영되지 않은 사례를 구조적으로 방지:

**Tier 1**: Edit 직후 grep 검증 필수 (grep 0건 = 실패)
**Tier 2**: 수정 파일별 planned vs verified 상태 구분. planned 항목 1건이라도 있으면 .done 금지
**Tier 3**: g3_independent_verifier.py가 보고서 파싱 → 파일 존재 + grep 재검증 → 자동 차단

### 3.6 L1 스모크테스트 강제
.done 생성 전 반드시 실제 동작 확인:
- 대시보드/프론트: 서버 재시작 + Playwright 스크린샷
- API/백엔드: curl 실제 호출 → 200 + 기대 필드
- subprocess: 실제 프로세스 실행 + 결과 확인
★ pytest PASS ≠ 실동작 확인. "사람이 사용해도 동작하는가?"가 기준.

### 3.7 런타임 검증 (추가)
코드 리뷰만으로 부족. 실제 실행 검증:
- 서버 작업: curl API 응답 확인
- 프로세스 검증: 올바른 디렉토리에서 실행 중인지
- 데이터 정합성: 표시 데이터 ↔ 원본 일치 여부

### 3.8 보리스 게이트 시스템 (Boris Gate System)
레벨별 3개 검증 관문 체계:

**G1 설계 게이트**: 만드는 지능(Codex) — 사전 검증
- Lv.0-1: 스킵 | Lv.2: affected_files 겹침 감지 | Lv.3: 3문서 + Codex 사전검증 | Lv.4: + Agent 미팅 만장일치
**G2 구현 게이트**: 검증하는 지능(Gemini/마아트) — 구현 후 검증
- Lv.0-1: 셀프 QC | Lv.2: 팀 테스터 | Lv.3: Gemini + 마아트 | Lv.4: + 로키 레드팀
**G3 머지 게이트**: 기계적 검증(자동화) — 머지 안전성
- Lv.0-1: 즉시 머지 | Lv.2: 충돌 감지 | Lv.3: g3_verifier + 시맨틱 분석 | Lv.4: + 보안 감사

운영 상세: `memory/specs/gate-system-ops-guide.md` 참조

---

## 4. 전문 에이전트

### 4.1 전문 AI 팀 구조 + 교차 검증
- **품질관리팀** (마아트 QC): 코드 검토, 오류 수정, 구조 개선
- **테스트팀** (각 팀 테스터): 기능 테스트, 오류 진단, 화면 확인
- **기획팀** (아누 + Agent 미팅): 계획 수립, 계획 검토, 문서 작성
- **보안팀** (로키 레드팀): 보안 취약점 탐지
- **디자인센터** (비너스): 디자인 + 세컨드오피니언 (Gemini 관점 대안)

**교차 검증(Cross-Review) 원칙**:
- 코드를 만든 팀 ≠ 검증하는 팀 (생성 ↔ 검증 분리 원칙 적용)
- 1팀이 만들면 → 마아트(QC)가 독립 검증. 개발자 보고를 불신, 직접 재실행.
- critical/security 작업 → 로키(레드팀) 추가 투입

### 4.2 전문 Agent 보고서 필수 내용
- 무엇을 발견했는지
- 무엇을 수정했는지
- 왜 그렇게 판단했는지
- **검토한 대안과 기각 사유**: "A안 대신 B안을 선택한 이유" 필수 기술. 대안 없는 보고서 = 사고하지 않은 보고서.

검출 항목: 누락된 부분, 보안 취약점, 일관성 문제

### 4.3 전문가 추론 추출 (3레이어 흡수)
피상적 소스(트윗, 명언) 지양. 깊이 있는 소스 활용:
- 결정을 단계별로 설명한 강연
- 왜 거부했는지 설명한 에세이
- 통념에 반박한 인터뷰

추출 대상:
1. 반복되는 의사결정 프레임워크
2. 우선순위 결정 로직
3. 즉각 의심하는 레드 플래그
4. 모두가 집착하는 것 중 일관되게 무시하는 것

### 4.4 제1원칙 분해
모든 레이어에 적용:
- 각 레이어가 **존재를 정당화**하는가?
- 비례적 가치 없이 **복잡성을 추가**하는가?
- 퍼포먼스(전문가처럼 말하기) ≠ 실제(전문가처럼 생각하기)

---

## 5. 설정 변경 프로세스

### 5.1 설정 변경 시 필수 체크
봇 모델, 조직 구조, 팀 구성 변경 시:
```
python3 /home/jay/workspace/sync-check.py
```
bot_settings.json ↔ organization-structure.json ↔ MEMORY.md 불일치 자동 감지.

### 5.2 변경 체크리스트
1. bot_settings.json 수정
2. cokacdir 재시작 (`systemctl --user restart cokacdir`)
3. organization-structure.json 동기화
4. MEMORY.md 동기화
5. sync-check.py 실행 → 전부 OK 확인

---

## 6. 봇 충돌 자동 대안 추천

### 6.1 봇 충돌 시 자동 추천
dispatch.py가 봇 충돌을 감지하면, 에러 메시지에 가용 대안 봇/팀 목록을 자동으로 포함한다.

- 아누가 수동으로 다른 팀을 찾을 필요 없음
- 에러 응답의 `available_bots` 필드에서 가용 봇 확인
- 가용 봇이 없으면 "모든 봇이 작업 중" 메시지 반환

### 6.2 논리적 팀 유동 배정
marketing, consulting, publishing, design, content 팀은 dispatch.py가 자동으로 가용 봇을 선택한다 (`_select_and_reserve_bot()`). 아누가 봇을 직접 지정할 필요 없음.

### 6.3 논리적팀-dev팀 봇 충돌 방지 (task-1405.1)
논리적팀이 동적으로 선택한 봇은 해당 dev팀의 고정 봇과 충돌할 수 있다. 이를 방지하기 위해:
- 논리적팀: `_select_and_reserve_bot()`이 봇 선택과 동시에 task-timers.json에 기록 (원자적)
- dev팀: 봇 할당 직후 `bot` 필드를 조기 기록 + 충돌 검사 수행
- 상세 규칙: `memory/specs/bot-collision-prevention.md` 참조

---

## 7. 한정승인 × 게이트 상호작용

> 한정승인(Limited Approval)과 검증 게이트(G1/G2/G3)의 상호작용 규칙.
> 한정승인이라고 게이트 레벨이 낮아지지 않는다.

### 7.1 한정승인 유형

| 유형 | 게이트 통과 주체 | 설명 |
|------|------------------|------|
| 나→아누 한정승인 | **아누** | 제이회장님이 아누에게 한정승인. 아누가 게이트를 직접 통과하며, Phase별 체이닝으로 순차 진행. |
| X팀 한정승인 | **팀장** | 아누가 X팀에 한정승인 위임. 팀장이 G1/G2/G3를 자체 통과. |

### 7.2 게이트 레벨 원칙

- **게이트 레벨 = `dispatch --level` 값**: 한정승인이라고 레벨이 낮아지지 않음
- 예: Lv.3 작업을 한정승인 받았더라도 G1/G2/G3 전부 Lv.3 기준으로 통과해야 함
- 한정승인은 "누가 게이트를 통과하는가"만 결정하지, "어떤 기준으로 통과하는가"는 변경하지 않음

### 7.3 "나→아누 한정승인" 상세

```
제이회장님: "이거 알아서 해" (한정승인)
  ↓
아누: Phase별 체이닝으로 분할
  ↓
Phase 1: 아누가 G1(설계 게이트) 통과 → 팀 dispatch
  ↓
Phase 2: 아누가 G2(구현 게이트) 통과 → QC 수행
  ↓
Phase 3: 아누가 G3(머지 게이트) 통과 → PR 생성/리뷰/머지
```

- 아누가 모든 게이트의 통과 주체
- Phase 완료마다 아누가 다음 Phase 진행 여부를 자체 판단
- 최종 결과만 제이회장님에게 보고

### 7.4 "X팀 한정승인" 상세

```
아누: "6팀 알아서 해" (한정승인)
  ↓
팀장(페룬): G1 자체 통과 (affected_files 충돌 확인)
  ↓
팀장(페룬): G2 자체 통과 (테스터/QC 수행)
  ↓
팀장(페룬): G3 자체 통과 (PR 생성 → Gemini 리뷰 → 머지)
  ↓
팀장: 완료 보고서 → 아누에게 보고
```

- 팀장이 모든 게이트의 통과 주체
- 아누는 결과만 수신 (중간 개입 없음)
- 단, 게이트 실패 시 팀장이 자체 해결하거나 아누에게 에스컬레이션

---

## 핵심 정리

1. **자동 매뉴얼 시스템** — 키워드·의도·위치 → 매뉴얼 자동 활성화 + 트리거 진입/진출
2. **작업 기억 시스템** — 계획서·맥락노트·체크리스트 + Agent 미팅 반복 + 핵미사일 승인
3. **자동 품질 검사** — QC 자동 + 보리스 게이트(G1/G2/G3) + 보고서≠구현 방지 + L1 스모크테스트 + 런타임 검증
4. **전문 에이전트** — 역할별 배치 + 전문가 추론 추출 + 제1원칙 분해
5. **봇 충돌 자동 대안** — 충돌 시 가용 봇 자동 추천, 논리적 팀 유동 배정
6. **한정승인 × 게이트** — 한정승인 유형별 게이트 통과 주체, 레벨 불변 원칙

---

**문서 버전**: v1.5
**작성일**: 2026-03-02
**원본**: 제이회장님 비전 → 아누 집대성
**참조**: PDF 가이드, boris_workflow.py, MASTER-FRAMEWORK.md, AI 기반 레거시 시스템 현대화 전략 보고서
**v1.1 변경사항**: 전략 보고서 12개 항목 통합 (근본 원칙, Audit Trail, 토큰 효율, Context Purge, Checkpointing, 환각 방지, 결정론적 실행, 위험도 분기, System 2 Forcing, 교차 검증, 대안 기록)
**v1.2 변경사항**: 용어사전 동시 갱신 규칙 추가 (task-1061.1)
**v1.3 변경사항**: 봇 충돌 자동 대안 추천 섹션 추가 (task-1252.1)
**v1.4 변경사항**: 한정승인 × 게이트 상호작용 섹션 추가 (task-1898)
**v1.5 변경사항**: 보리스 게이트 시스템(3.8), 3문서 2유형 체계(2.1), 보고서≠구현 방지(3.5), L1 스모크테스트 강제(3.6) 반영 (task-1837_5.4)