# task-310.1 보고서: Agent Mode 가이드라인 vs 우리 시스템 적용도 분석

**작업자**: 오딘 (Odin), 개발2팀장
**작성일**: 2026-03-06
**팀**: dev2-team

---

## 1. 항목별 적용도 체크표

### A. Agent Mode Workflow (7단계)

**1. Understand the task (작업 이해)**
- 판정: 🔄 **우리가 더 나음**
- 근거:
  - 가이드라인: "작업을 이해한다" — 구체적 방법론 없음
  - 우리 시스템: **작업 레벨 시스템** (`work-level-system.md`)으로 Lv.1~4 판정 → 레벨별 조사 깊이 차등 적용
  - **"어떻게?" 체크** (Lv.2 이상 필수): 탐지 방법, 데이터 흐름, 외부 의존성, 엣지케이스, 검증 방법까지 답이 나온 후에야 코딩 진입
  - **리서치 단계** (`anu-guide.md` 2.5): 코드베이스/문제 깊이 읽기 → `memory/research/` 정리 → 충분히 파악 후 미팅 소집
  - 실패 사례 DB (인포키워드 교훈)로 반복 실수 방지
- 위치: `/home/jay/workspace/memory/specs/work-level-system.md`, `anu-guide.md` 2.5

**2. Create a step-by-step plan (단계별 계획 수립)**
- 판정: 🔄 **우리가 더 나음**
- 근거:
  - 가이드라인: "단계별 계획을 세운다" — 개인이 혼자 세우는 리스트 수준
  - 우리 시스템: **3문서 시스템** (계획서 + 맥락노트 + 체크리스트) — 구조화된 외부 기억장치
  - **Agent 미팅** (`anu-guide.md` 2.2): 여러 페르소나 소집 → 반복 검토 (최대 6사이클)
  - **Devil's Advocate** (Lv.3 이상): 매 사이클 반대 입장 검증 필수
  - **핵미사일 발사코드**: Context Purge + 3문서 영속화 + 제이회장님 강제 승인 → "3문서 없이 코딩 절대 금지"
  - **Phase 분리 원칙**: 호흡이 긴 작업을 Phase 단위로 분해, 각 Phase = 1 세션
- 위치: `anu-guide.md` 2.1~2.3, `work-level-system.md` Lv.3~4

**3. Execute tasks using shell tools (도구로 실행)**
- 판정: 🔄 **우리가 더 나음**
- 근거:
  - 가이드라인: 개인이 쉘 도구(rg, git, npm)로 직접 실행
  - 우리 시스템: **조직적 위임 구조**
    - `dispatch.py`: 독립 세션으로 팀에 작업 위임 (cokacdir --cron)
    - Task tool: 팀장이 팀원 서브에이전트를 **병렬 실행** (백엔드/프론트/UX/테스터 동시)
    - MCP 서버: openclaw (GLM 코더), playwright (브라우저 자동화)
    - **봇 라우팅**: 팀별 전용 봇으로 세션 격리 (dev1/dev2/dev3 봇)
    - **모델 선택 가이드**: 작업 복잡도에 따라 haiku/sonnet 자동 선택
- 위치: `dispatch.py`, `team_prompts.py`, `DIRECT-WORKFLOW.md`

**4. Modify code (코드 수정)**
- 판정: 🔄 **우리가 더 나음**
- 근거:
  - 가이드라인: 개인이 직접 코드 수정
  - 우리 시스템: **역할별 전문 에이전트** — 20명 매트릭스 조직
    - 백엔드 전문가 (토르/불칸/아누비스), 프론트엔드 (프레이야/이리스/이시스), UX/UI (미미르/아테나/토트)
    - **Audit Trail 자동 기록**: PostToolUse 훅 → `audit-trail.jsonl`에 누가/언제/어떤 파일/어떤 도구로 수정했는지 자동 추적
    - **팀원 상태 추적**: PreToolUse → working, PostToolUse → idle 자동 기록 (`member-status.json`)
    - **pyright/TS LSP 자동 체크**: 코드 변경 후 타입 에러 즉시 감지
  - **생성 ↔ 검증 분리**: 코드를 만드는 팀 ≠ 검증하는 팀
- 위치: `organization-structure.json`, `post-tool-use.sh`, `pre-tool-use.sh`, `settings.json`

**5. Run tests (테스트 실행)**
- 판정: 🔄 **우리가 더 나음**
- 근거:
  - 가이드라인: "npm test" 실행 — 단일 테스트 명령
  - 우리 시스템: **다층 자동 검증 체계** (`qc_verify.py` 6개 verifier)
    - `api_health`: HTTP 200 응답 확인
    - `file_check`: 보고서 파일 존재 + 크기
    - `data_integrity`: task-timers.json ↔ .done 파일 교차 검증
    - `test_runner`: pytest exit code 검증
    - `schema_contract`: Pydantic ↔ JSON Schema ↔ Zod 계약 검증 (SC-1~SC-8, 8개 세부 항목)
    - `pyright_check`: LSP 타입 체크 (v2.1 신규)
  - **위험도별 검증 분기**: normal (셀프QC + 자동검증) → critical (+마아트 독립검증) → security (+로키 보안감사)
  - **셀프 QC 5항목** + **데이터 계약 체크리스트** (조건부 추가 5항목)
- 위치: `QC-RULES.md`, `anu-guide.md` 3.1~3.5

**6. Fix errors (에러 수정)**
- 판정: ✅ **적용됨**
- 근거:
  - `QC-RULES.md`: "결과가 FAIL이면 해당 항목을 수정한 후 재실행하세요"
  - `anu-guide.md` 3.1: 오류 적으면 즉시 수정, 많으면 전문 담당 추천
  - 마아트 독립 검증에서 FAIL 시 "구체적 불일치와 재작업 요청을 기록"
- 위치: `QC-RULES.md` 2절, `anu-guide.md` 3.1

**7. Repeat until tests pass (테스트 통과까지 반복)**
- 판정: ⚠️ **부분 적용**
- 근거:
  - 가이드라인: 자동 반복 루프 (테스트 통과까지)
  - 우리 시스템: **자동 반복 루프는 미구현**. 팀장 판단에 의해 수동 재작업 지시.
  - 다만 구조적으로는 존재: qc_verify.py FAIL → 수정 → 재실행 / 마아트 FAIL → 재작업 요청
  - 하지만 이것이 자동화된 루프가 아니라 사람(팀장/마아트)의 판단에 의존
  - **followup 시스템**: dispatch 후 아누가 자동으로 완료 확인 예약 → 미완료 시 재확인 등록 (반복 구조)

---

### B. Agent Mode Rules (3개)

**8. Always run tests after code changes (코드 변경 후 항상 테스트)**
- 판정: ✅ **적용됨**
- 근거:
  - `DIRECT-WORKFLOW.md` LSP 활용 규칙: "코드 작성/수정 후 반드시 pyright로 타입 체크 실행"
  - `QC-RULES.md` 2절: 셀프 QC 후 자동 검증 스크립트 실행 필수
  - Stop hook (`stop-qc-reminder.sh`): 작업 완료 시 자동으로 5항목 셀프체크 리마인더 출력
- 위치: `DIRECT-WORKFLOW.md`, `QC-RULES.md`, `stop-qc-reminder.sh`

**9. Never leave failing tests (실패 테스트 방치 금지)**
- 판정: ✅ **적용됨**
- 근거:
  - `QC-RULES.md`: FAIL 항목 수정 후 재실행 의무
  - critical 이상: 마아트가 독립 재실행 → "개발자 보고를 절대 신뢰하지 않음"
  - 에러 처리 원칙 (`QC-RULES.md` 5절): "잘못된 데이터의 묵음 표시 허용하지 않음. 파싱 실패는 명시적으로 실패해야 함"
- 위치: `QC-RULES.md` 2절, 5절

**10. Make small commits (작은 커밋)**
- 판정: ❌ **미적용**
- 근거:
  - 우리 시스템에 **git 커밋 전략이 없음**
  - 버전 관리는 파일 기반 이벤트 시스템으로 대체: `.done` 파일, `task-timers.json`, `audit-trail.jsonl`
  - 프로젝트 디렉토리(`/home/jay/workspace/`)가 git 저장소가 아닌 것으로 확인됨
  - 코드 변경 이력 추적은 audit trail JSONL로 수행하나, 롤백 가능한 스냅샷이 아님

---

### C. Agent Mode Process Constraints (2개)

**11. Minimal changes (최소 변경)**
- 판정: ⚠️ **부분 적용**
- 근거:
  - `anu-guide.md` 2.4 "결정론적 실행": "계획서에 명시되지 않은 변경은 금지" — 최소 변경의 정신은 공유
  - `DIRECT-WORKFLOW.md` 작업 규칙: "프로젝트 격리" — 다른 프로젝트/팀 디렉토리 수정 금지
  - 하지만 **변경 파일 수/라인 수 제한** 같은 명시적 제약은 없음
  - work-level-system.md Lv.1은 "파일 1~3개"로 범위가 명확하나, Lv.2 이상은 범위 제한 없음

**12. Maintain style (스타일 유지)**
- 판정: ⚠️ **부분 적용**
- 근거:
  - **타입 체크**: pyright (Python), typescript-lsp (TypeScript) — LSP 플러그인 활성화됨
  - **기술 표준 정의**: Pydantic v2, Zod, JSON Schema 등 사용 라이브러리 명시 (`QC-RULES.md` 1.5절)
  - **에이전트 스타일 속성**: 각 팀원의 코딩 스타일이 `organization-structure.json`에 정의됨
  - **미비점**: 코드 포매팅 도구(black, isort, prettier, ESLint) 자동 실행이 구성되어 있지 않음
  - 커밋 전 린터 강제 실행 같은 자동화 미구현

---

## 2. 적용도 점수

| # | 가이드라인 항목 | 판정 | 점수 |
|---|---------------|------|------|
| 1 | Understand the task | 🔄 우리가 더 나음 | 1.0 |
| 2 | Create a step-by-step plan | 🔄 우리가 더 나음 | 1.0 |
| 3 | Execute tasks using shell tools | 🔄 우리가 더 나음 | 1.0 |
| 4 | Modify code | 🔄 우리가 더 나음 | 1.0 |
| 5 | Run tests | 🔄 우리가 더 나음 | 1.0 |
| 6 | Fix errors | ✅ 적용됨 | 1.0 |
| 7 | Repeat until tests pass | ⚠️ 부분 적용 | 0.5 |
| 8 | Always run tests after changes | ✅ 적용됨 | 1.0 |
| 9 | Never leave failing tests | ✅ 적용됨 | 1.0 |
| 10 | Make small commits | ❌ 미적용 | 0.0 |
| 11 | Minimal changes | ⚠️ 부분 적용 | 0.5 |
| 12 | Maintain style | ⚠️ 부분 적용 | 0.5 |

**총점: 9.5 / 12 = 79%**

분류별 요약:
- 🔄 우리가 더 나음: **5개** (작업 이해, 계획 수립, 도구 실행, 코드 수정, 테스트)
- ✅ 적용됨: **3개** (에러 수정, 변경 후 테스트, 실패 테스트 방치 금지)
- ⚠️ 부분 적용: **3개** (반복, 최소 변경, 스타일 유지)
- ❌ 미적용: **1개** (작은 커밋)

---

## 3. Gap 분석 — 미적용/부분 적용 항목

### Gap 1: Small commits (작은 커밋) — ❌ 미적용

**현상**: git을 사용하지 않아 코드 변경의 원자적 스냅샷이 없음
**우리의 대체제**: audit-trail.jsonl (파일 수정 이력 추적) + .done 이벤트 파일
**한계점**:
- 특정 시점으로 코드 롤백 불가능
- 변경 단위가 "세션" 수준으로 너무 큼 (하나의 세션에서 여러 파일 동시 수정)
- 코드 리뷰 시 diff 확인이 어려움

**도입 제안**:
- 프로젝트별 git 초기화 (`/home/jay/workspace/projects/{id}/`)
- 서브태스크 단위 커밋 (팀원 에이전트가 작업 완료 시 자동 커밋)
- 커밋 메시지 컨벤션: `[task-id] [팀원명] 변경 내용`
- **우선순위: 중간** — 현재 audit trail이 일부 역할을 대체하고 있으나, 롤백 기능 부재가 리스크

### Gap 2: Maintain style (코드 스타일 강제) — ⚠️ 부분 적용

**현상**: 타입 체크(pyright/TS LSP)는 있으나 코드 포매팅 자동화 없음
**우리가 가진 것**:
- pyright + typescript-lsp (타입 에러 감지)
- organization-structure.json에 스타일 가이드 텍스트 정의
- QC-RULES.md에 기술 표준(Pydantic v2, Zod 등) 명시

**도입 제안**:
- Python: `black` + `isort` 자동 포매팅
- TypeScript: `prettier` + `eslint --fix` 자동 포매팅
- 적용 방식: PostToolUse 훅에서 Edit/Write 시 자동 실행, 또는 qc_verify.py에 `style_check` verifier 추가
- **우선순위: 높음** — 구현 비용 낮고 효과 큼. 기존 훅 인프라에 쉽게 통합 가능

### Gap 3: Repeat until tests pass (자동 반복 루프) — ⚠️ 부분 적용

**현상**: qc_verify.py FAIL 시 수동 재실행. 자동 재시도 루프 없음.
**우리가 가진 것**:
- qc_verify.py FAIL → "수정 후 재실행하세요" (지시 수준)
- 마아트 독립 검증 → FAIL → 재작업 요청 (사람 판단)
- followup 시스템: 미완료 시 재확인 등록 (완료 여부 체크)

**도입 제안**:
- DIRECT-WORKFLOW.md에 "qc_verify.py 실행 → FAIL 시 자동 수정 → 최대 3회 재실행" 루프 명시
- 무한루프 방지: 최대 재시도 횟수(3회) + 3회 실패 시 팀장에게 에스컬레이션
- **우선순위: 낮음** — 현재 구조에서도 팀장이 적절히 처리하고 있음. 자동화 시 오류 증폭 리스크

### Gap 4: Minimal changes (변경 범위 제한) — ⚠️ 부분 적용

**현상**: "계획서에 없는 변경 금지"는 있으나, 정량적 범위 제한 없음
**우리가 가진 것**:
- 결정론적 실행 원칙 (anu-guide.md 2.4)
- 프로젝트 격리 규칙 (DIRECT-WORKFLOW.md)
- Lv.1 "파일 1~3개" 범위 제한

**도입 제안**:
- 작업 지시서에 "예상 변경 파일 목록" 사전 정의 (Lv.2 이상)
- qc_verify.py에 `scope_check` verifier 추가: 실제 변경 파일 ↔ 예상 파일 목록 대조
- 미예상 파일 변경 시 WARN (정당한 사유 기록 필수)
- **우선순위: 중간** — "어떻게?" 체크에 "무엇을 변경하는가?" 항목 추가로 자연스럽게 통합 가능

---

## 4. 우리 시스템의 독자적 강점 (가이드라인에 없는 것)

가이드라인이 다루지 않지만 우리 시스템이 보유한 고급 기능:

1. **조직적 위임 구조**: 1인 에이전트가 아닌 20인 매트릭스 조직. 역할 분리 + 병렬 실행 + 교차 검증.
2. **3문서 시스템 + 핵미사일 발사코드**: 계획 품질을 구조적으로 강제. "3문서 없이 코딩 금지."
3. **다층 QC 체계**: normal → critical → security 3단계. 마아트 독립 검증 + 로키 보안 감사.
4. **자동 매뉴얼 시스템**: 4종 훅 (UserPromptSubmit, PreToolUse, PostToolUse, Stop)으로 규칙 자동 주입.
5. **Audit Trail**: 파일 수정 내역 자동 JSONL 기록. 포렌식 추적 가능.
6. **봇 라우팅 + 세션 격리**: 팀별 독립 봇으로 세션 충돌 방지.
7. **Agent 미팅 + Devil's Advocate**: 복수 페르소나 합의 기반 의사결정.
8. **작업 레벨 시스템**: 작업 복잡도에 따라 프로세스 깊이 차등 적용 (Lv.1~4).
9. **이벤트 큐 + pending actions**: 미처리 작업/미이행 약속 자동 감지 및 리마인드.
10. **토큰 효율 3-Tier 구조**: 스킬 파일의 계층적 로딩으로 컨텍스트 절감 (40~60%).

---

## 5. 도입 제안 우선순위 정리

| 우선순위 | 항목 | Gap | 구현 난이도 | 기대 효과 |
|---------|------|-----|-----------|----------|
| 1 (높음) | 코드 스타일 강제 | Style | 낮음 | 코드 일관성 즉시 개선 |
| 2 (중간) | git 커밋 전략 | Commits | 중간 | 롤백 가능성 + 코드 리뷰 개선 |
| 3 (중간) | 변경 범위 사전 정의 | Scope | 낮음 | 의도치 않은 변경 방지 |
| 4 (낮음) | 자동 재시도 루프 | Repeat | 중간 | 자동화 향상 (리스크 있음) |

---

## 6. 셀프 QC 체크리스트

- [x] 1. 이 변경이 다른 파일에 영향을 미치는가? → 분석 보고서만 생성. 시스템 코드 변경 없음.
- [x] 2. 이 로직의 엣지 케이스는 무엇인가? → 해당 없음 (코드 변경이 아닌 분석 보고서)
- [x] 3. 이 구현이 작업 지시와 정확히 일치하는가? → 작업 지시 4개 완료 기준 모두 충족:
  - [x] 가이드라인 항목별 적용도 체크표 (섹션 1)
  - [x] 미적용 항목 Gap 분석 (섹션 3)
  - [x] 도입 제안 목록 (섹션 5)
  - [x] 적용도 점수 (섹션 2: 9.5/12 = 79%)
- [x] 4. 에러 처리와 보안은 확인했는가? → 해당 없음 (분석 보고서)
- [x] 5. 테스트가 모든 경로를 커버하는가? → 해당 없음 (분석 보고서)

데이터 계약 체크리스트: **해당 없음** (workers/, src/, shared/schemas/ 파일 변경 없음)

---

## 7. 자동 검증 결과

```json
{
  "task_id": "task-310.1",
  "verified_at": "2026-03-06T14:44:06",
  "overall": "WARN",
  "checks": {
    "api_health": {"status": "SKIP", "details": ["Skipped via --skip flag"]},
    "file_check": {"status": "PASS", "details": ["2/2 checks passed"]},
    "data_integrity": {"status": "WARN", "details": ["WARNING: .done file exists but status='running' (task-timer end 미호출 상태, 완료 절차 진행 후 해소)"]},
    "test_runner": {"status": "SKIP"},
    "schema_contract": {"status": "SKIP"},
    "pyright_check": {"status": "SKIP"}
  },
  "summary": "1 PASS, 4 SKIP, 1 WARN"
}
```
- WARN 사유: task-timer end가 아직 호출되지 않은 상태. 워크플로우 마지막 단계에서 호출하여 해소.

---

## 생성/수정 파일 목록

- `/home/jay/workspace/memory/reports/task-310.1.md` (본 보고서, 신규 생성)

## 테스트 결과
- 코드 변경 없음 — 테스트 해당 없음

## 버그 유무
- 없음

## 비고
- 참조 파일 9종 직접 확인 완료: anu-guide.md, work-level-system.md, organization-structure.json, dispatch.py, team_prompts.py, DIRECT-WORKFLOW.md, QC-RULES.md, settings.json (hooks 4종), skills/ 디렉토리
- hooks 디렉토리(`/home/jay/workspace/hooks/`)는 존재하지 않으나, 실제 훅은 `~/.claude/hooks/`에 4종 구성됨