grpc_performance_comparison/TASK_LIST.md

작업 리스트 (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.12.3과 CLAUDE.md 1.11.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 프로그램을 구현 중이므로 수정하지 않음.