# 작업 리스트 (FEEDBACK.md 기반, 우선순위 순)

> 다른 에이전트가 `src/` 디렉터리에서 UI 프로그램을 구현 중이므로 `src/`는 건드리지 않음.

---

## P0 — 진행 전 반드시 해결

### 1. quic-go + gRPC transport interface 호환성 PoC 검증

- **리스크**: quic-go의 `quic.Stream`이 `net.Conn` 인터페이스를 완전히 충족하지 않을 가능성
- **구체적 확인 사항**:
  - `SetDeadline()`, `SetReadDeadline()`, `SetWriteDeadline()` 동작 여부
  - `LocalAddr()` / `RemoteAddr()` — quic-go Stream에서 Connection 정보를 가져오는 방법
  - `Close()`의 half-close 의미와 gRPC 예상 동작 차이
  - quic-go Stream을 gRPC transport에 주입하는 구체적 방법
- **대비책**: 실패 시 HTTP/2(gRPC-H2)만으로 게이트웨이 검증을 먼저 수행하고, QUIC은 별도 실험으로 분리
- **결과**: `docs/decisions/002-quic-grpc-compatibility-poc.md`에 기록

### 2. Novelty 재정의 및 문서 반영

- 문제: 「gRPC over QUIC 구현」만으로는 선행 연구 대비 차별성이 부족함
- 해결 방안:
  - 연구를 「**AIoT 도메인에서의 실증 연구(empirical study)**」로 포지셔닝
  - **무엇을 측정하고 증명할 것인가**를 전면에 내세움
    - (a) QUIC의 세 가지 특성(0-RTT, HoL Blocking 해소, 연결 마이그레이션)이 AIoT 환경에서 실제로 유의미한 성능 개선을 보이는가?
    - (b) gRPC-QUIC 통신 모듈을 써서 엣지 게이트웨이를 구축할 때 기존 대비 measurable한 이점이 있는가?
  - `CLAUDE.md`의 헤더(서문)와 2.0절(기여)을 수정
  - 선행 연구(SGS)와의 차별성 표(2.3절)를 더 구체화

---

## P1 — 구현 시작 전에 결정해야 할 사항

### 3. 게이트웨이 아키텍처 기여 재정의

- 현재: 「프로토콜 변환 + 정적 라우팅」만으로는 연구 기여로 부족
- 해결 방안:
  - **gRPC-QUIC 통합 자체**가 게이트웨이의 novelty임을 명시
  - 또는 게이트웨이의 구체적 설계 결정(예: gRPC stream을 IoT 프로토콜에 매핑하는 방식, edge/cloud 분기 로직의 구체적 설계)을 기여로 내세움
  - 게이트웨이의 정확한 아키텍처 다이어그램(데이터 흐름 포함)을 문서에 추가
- **결정사항을 ADR로 기록**: `docs/decisions/003-gateway-architecture.md`

### 4. MQTT/CoAP 변환 전략 정의

- 현재: 파일명만 있고 변환 전략 미정의
- 결정 필요:
  - MQTT message payload → Protobuf message 역직렬화? (가장 단순)
  - MQTT topic 구조 → gRPC service/method에 매핑? (복잡함)
  - MQTT connection → gRPC streaming session으로 변환? (가장 복잡)
  - CoAP도 동일한 결정 필요
- **권장**: P0 구현에는 MQTT만 포함하고, CoAP은 P1로 격하. MQTT는 payload 변환만 먼저 구현
- **결과**: `docs/decisions/004-protocol-adapter-design.md`에 기록 + `IMPLEMENTATION.md`에 반영

### 5. 라우팅 데이터 모델 정의

- 현재: 「정적 룰 기반 라우팅」이라는 추상적 표현만 있음
- 결정 필요:
  - 라우팅 룰의 데이터 모델은? (입력 조건 → 대상 서비스)
  - 설정 형식은? (YAML 파일 / 코드 내 map / DB 테이블)
  - 런타임 변경 가능한가? (재시작 필요한가)
- **권장**: YAML 기반 단순 룰 테이블로 시작. 변경 시 재시작 필요
- **결과**: `internal/gateway/route_table.go`의 데이터 구조 확정 + 예제 YAML 파일 추가

### 6. 실험 설계 강화 (CLAUDE.md 5절 수정)

- Lossy 조건 다양화:
  - 현재: 50ms + 1% loss
  - 추가: 50ms + 3% loss, 100ms + 5% loss (P1)
  - 최소 3%에서 QUIC과 HTTP/2의 차이가 유의미한지 확인
- 통계적 유의성:
  - 반복 횟수: count=5 → count=30 (특히 Lossy 환경)
  - 신뢰 구간(95% CI) 계산 방법 명시
  - 이상치(outlier) 처리 정책 정의
- AI Agent RPC 시나리오 KPI 조정:
  - Payload Size는 이 시나리오에서 제외 (수 KB라서 직렬화 차이 미미)
  - Connection Overhead / 0-RTT Resumption에 집중
- 측정 인터셉터의 observer effect 문서화:
  - 인터셉터 자체 overhead 측정 방법 추가
  - 모든 비교군에 동일 bias가 적용됨을 확인

### 7. 위험 관리 문서화

- 다음 위험 식별 및 대비책을 `CLAUDE.md`나 `docs/risks.md`에 명시:

| 위험 | 영향 | 가능성 | 대비책 |
|------|------|--------|--------|
| quic-go + gRPC transport interface 불호환 | 프로젝트 전체 지연 | 중간 | HTTP/2만으로 게이트웨이 검증 후 QUIC 별도 실험 |
| Docker 내 tc(traffic control) 미작동 | 네트워크 조건 시뮬레이션 불가 | 낮음 | 호스트 레벨 tc 또는 네트워크 네임스페이스 분리 |
| MQTT/CoAP 어댑터 구현 범위 과다 | 게이트웨이 일정 지연 | 중간 | P1 격하 또는 MQTT만 먼저 검증 |
| Go 버전업에 따른 quic-go 호환성 이슈 | 빌드 실패 | 낮음 | go.mod에 quic-go 버전 고정 |

---

## P2 — 구현과 병행 가능

### 8. BACKGROUND.md 전반 개선

- 1.3절 학원 관리 예시 → AI Agent 일반 아키텍처 다이어그램으로 교체
- 2.2절 제목 「사람과 달리, ...」 → 「컨텍스트 메모리 한계에 따른 AI Agent 성능 저하 문제」
- 3절 결론 강화 — 세 가지 추세 → gRPC over QUIC 연구 필요성으로의 논리적 연결 추가
- Timeliness argument 추가: 「왜 지금 이 연구인가?」 섹션 신설

### 9. CLAUDE.md 세부 보강

- 1.4~2.1절: 세 가지 향후 연구 중 왜 HTTP/3을 선택했는지 근거 명시
- 5.1절 비교 대상 표: REST-Cloud의 처리 위치 → 「엣지 → 클라우드 (원시 데이터)」로 통일
- 1절 각 항목을 2-3문장 요약으로 축약 (상세는 BACKGROUND.md 참조)
- 6.4절: 측정 인터셉터 overhead 고려사항 추가

### 10. IMPLEMENTATION.md 보강

- 벤치마크 방식 역할 분담 명시:
  - `benchmarks/scenarios/` (testing.B): 단일 프로세스 내 마이크로벤치마크 (직렬화 시간, 처리량)
  - `cmd/benchmark-runner/`: 분산 end-to-end 측정 (P50/P95/P99 latency, RPS)
  - Docker Compose 환경에서 benchmark-runner 실행 위치
- `.golangci-lint.yaml` 추가 (errcheck, govet, staticcheck 등)
- 각 어댑터의 변환 전략을 protocol_adapter.go 인터페이스 정의 근처에 문서화

### 11. 문서 간 중복 제거

- BACKGROUND.md 2.1~2.3과 CLAUDE.md 1.1~1.3의 중복 제거
  - CLAUDE.md는 요약(각 2-3문장)으로 축소
  - BACKGROUND.md는 상세 논의로 유지

---

## 작업 진행 순서 요약

```
Step 1 (P0):  quic-go 호환성 PoC 검증 → docs/decisions/002
Step 2 (P0):  Novelty 재정의 → CLAUDE.md + docs/decisions/ 재작성
  │
Step 3 (P1):  게이트웨이 기여 재정의 → docs/decisions/003
Step 4 (P1):  MQTT 변환 전략 결정 → docs/decisions/004
Step 5 (P1):  라우팅 데이터 모델 정의 → route_table.go 설계
Step 6 (P1):  실험 설계 강화 → CLAUDE.md 5절 수정
Step 7 (P1):  위험 관리 문서화 → docs/risks.md
  │
Step 8 (P2):  BACKGROUND.md 개선
Step 9 (P2):  CLAUDE.md 세부 보강
Step 10 (P2): IMPLEMENTATION.md 보강
Step 11 (P2): 문서 간 중복 제거
```

> **주의**: `src/` 디렉터리는 다른 에이전트가 UI 프로그램을 구현 중이므로 수정하지 않음.