grpc_performance_comparison/PROMPT.md

AIoT gRPC 고성능 통신 모듈 — 프로젝트 빠른 파악

이 프로젝트에 새로 투입된 당신을 위한 프롬프트입니다. AI 에이전트(Claude Code, Codex 등)에게 이 내용을 전달하면 프로젝트를 빠르게 이해하고 작업할 수 있습니다.

---

프로젝트 한 줄 요약

AI Agent와 IoT 디바이스 간 통신을 위해, TCP 기반 gRPC(HTTP/2)의 전송 계층을 QUIC(HTTP/3)으로 교체한 고성능 통신 모듈을 Go로 구현하고, 이를 활용한 엣지 게이트웨이 아키텍처를 설계·구현·성능 검증하는 연구 프로젝트.

---

핵심 정보

항목	내용
언어	Go 1.22+
통신 프로토콜	gRPC over HTTP/3 (QUIC) + Protocol Buffers v3
QUIC 라이브러리	github.com/quic-go/quic-go
비교 대상	gRPC/HTTP3 vs gRPC/HTTP2 vs REST/HTTP2 vs REST/HTTP1.1
연구 범위	통신 모듈 구현 + 엣지 게이트웨이 + 6-way 정량 성능 비교
평가 시나리오	① IoT 데이터 전송 (수 KB~수 MB, 스트리밍) ② AI Agent RPC (수 KB, Unary, burst)
네트워크 조건	Ideal/LAN/WAN-Low/WAN-High/Lossy (tc로 시뮬레이션)

---

문서 구성 (읽는 순서)

1. CLAUDE.md — 연구 방향, 동기, 목표, 평가 지표, 코드 정책. 모든 작업 시작 시 필독.
2. IMPLEMENTATION.md — 디렉터리 구조, 네이밍, 워크플로우, Makefile, 코드 패턴. 코드 작성/수정 시 필독.
3. BACKGROUND.md — 연구 배경 (AI Agent 트래픽 폭증, TCP 한계, QUIC 등장). 연구 동기 이해 시 참조.
4. 참고/SGS/README.md — 선행 연구 (스마트팜 해충 탐지, gRPC vs REST 비교). 차별성 파악 시 참조.

특별 디렉터리:

• docs/decisions/ — 설계 결정 기록 (ADR). 중요한 설계 변경 전후 확인.
• docs/open-questions.md — 미해결 탐색 주제. 새 실험 기획 시 참조.
• src/ — 다른 에이전트가 UI 프로그램 구현 중이므로 건드리지 말 것.

---

연구 동기 (왜 이 프로젝트인가)

1. AI Agent 격리 → 통신 폭증: 보안을 위해 각 Agent를 컨테이너에 격리하면 IPC가 전부 네트워크 통신으로 전환되어 통신 건수가 폭증함
2. 서브에이전트 아키텍처 → 통신 빈도 증가: 컨텍스트 한계 극복을 위해 서브에이전트 + RAG 패턴이 표준화되면서 Agent 간/Agent-서비스 간 통신이 더 빈번해짐
3. 24/7 가동 → 동시 트래픽 누적: 사람이 쉴 때도 Agent는 일하므로 동시간 네트워크 사용량이 급증

→ TCP 기반 HTTP/2(gRPC)의 HoL Blocking, 연결 수립 비용, 연결 고정 문제가 병목이 됨 → QUIC(HTTP/3)이 0-RTT, 스트림 독립성, 연결 마이그레이션으로 이 문제들을 해결 가능 → 그러나 AIoT 환경에서의 gRPC over QUIC 실증 연구는 아직 부재함 — 이 gap을 메우는 것이 본 연구

---

제안 2가지

제안 ①: gRPC over QUIC 통신 모듈

• QUIC의 0-RTT, HoL Blocking 해소, 연결 마이그레이션을 AIoT 환경에서 정량 검증
• 6가지 시스템 간 latency(P50/P95/P99), throughput(RPS), connection overhead 비교
• 성공 기준: 각 측정값 최소 30회 반복, 95% 신뢰 구간 제시

제안 ②: gRPC 엣지 게이트웨이 아키텍처

• 프로토콜 변환 (MQTT/CoAP → Protobuf) + 정적 룰 기반 서비스 라우팅
• gRPC-QUIC 모듈을 사용해 백엔드와 통신
• LLM 기반 동적 라우팅은 범위 밖 (정적 룰 한정)

---

기술적 주의사항

가장 큰 리스크

quic-go의 quic.Stream과 net.Conn 인터페이스 호환성.

• quic-go Stream은 net.Conn의 deadline 설정, LocalAddr/RemoteAddr, Close(반쪽 종료) 방식이 다름
• 이 문제가 해결되지 않으면 QUIC 구현이 불가능함 → HTTP/2(gRPC-H2)만으로 게이트웨이 먼저 검증하고 QUIC은 별도 실험으로 분리

계층 분리 필수

Transport (QUIC/TCP) → Protocol (gRPC/HTTP) → Serialization (Protobuf/JSON) → Business Logic

전송 계층은 인터페이스로 추상화하여 QUIC↔TCP 교체 가능하게 할 것.

금지 사항

• gen/ 디렉터리 직접 수정 금지. .proto 수정 후 make proto로 재생성.
• panic 사용 금지 (초기화 코드 제외)
• 전역 변수 설정 금지. config 구조체 사용.
• 미사용 의존성 추가 금지. go mod tidy 후 커밋.
• src/ 디렉터리 수정 금지 (다른 에이전트가 UI 구현 중)

---

자주 하는 작업

새 RPC 추가

1. proto/aiot/{module}/{service}.proto에 정의
2. make proto → gen/ 생성
3. internal/server/에 핸들러 구현
4. 인터셉터(internal/middleware/metrics.go)로 latency 측정 자동화
5. 단위 테스트 → 벤치마크 시나리오 추가

서버 실행

go run ./cmd/server --transport=quic --port=50051   # gRPC over QUIC
go run ./cmd/server --transport=h2   --port=50052   # gRPC over HTTP/2
go run ./cmd/rest-server                             # REST 비교군

네트워크 조건

sudo ./scripts/tc-setup.sh --delay 50ms --loss 1% --interface eth0
sudo ./scripts/tc-reset.sh --interface eth0

---

선행 연구(SGS) 대비 차별성

항목	선행 연구	본 연구
전송 계층	HTTP/2 (TCP)	HTTP/3 (QUIC) 추가
시나리오	스마트팜 단일	IoT + AI Agent RPC 이중
게이트웨이	개념 제시	구현·정량 검증
평가 지표	응답 시간, 전송량	+ 0-RTT, HoL 내성, 연결 마이그레이션
비교 시스템	3개	6개

---

파일 상태

파일	목적	작성 완료
CLAUDE.md	연구 방향·정책	✅
BACKGROUND.md	연구 배경 (발표 가능)	✅ (1차 개선 완료)
IMPLEMENTATION.md	구현 세부 사항	✅
FEEDBACK.md	문서 비평	✅
TASK_LIST.md	작업 리스트	✅
참고/SGS/README.md	선행 연구	✅

추후 보강 예정 (부록 A 참조)

• 정량적 데이터 근거 (통신 빈도 추정치, 기존 연구 인용)
• AI Agent 트래픽 특성 구체화 (RPC 수, latency 요구사항)
• AI Agent + IoT 두 시나리오 연결 논리 강화