grpc_performance_comparison/CLAUDE.md

AIoT gRPC 고성능 통신 모듈 — 연구 프로젝트

언어: Go | 프로토콜: gRPC over HTTP/3 (QUIC) + Protocol Buffers v3 목적: AI Agent 및 AIoT 환경에서 고성능·경량 서비스 간 통신을 위한 gRPC-QUIC 통신 모듈과 이를 활용하는 엣지 게이트웨이 설계·구현·실증 연구의 성격: 새로운 프로토콜의 발명이 아니라, AIoT 도메인 워크로드(AI Agent RPC + IoT 데이터 전송)에 gRPC over QUIC을 적용한 domain-specific empirical study. AIoT 워크로드 특성에 따른 효과 측정이 부재한 격차(gap)를 메우는 것이 목적이다.

---

0. 문서 지침 (먼저 읽을 것)

본 저장소의 문서는 역할별로 분리되어 있다. 작업을 시작하기 전에 자신의 작업 종류에 맞는 문서를 함께 참조한다.

문서	역할	언제 참조하는가
CLAUDE.md (본 파일)	연구 방향·동기·목표·평가 지표·코드 정책·위험 관리	모든 작업 시작 시
IMPLEMENTATION.md	디렉터리 구조, 네이밍, 워크플로우, 코드 패턴, Makefile, 멀티 에이전트 작업 분담	코드를 작성·수정·실행할 때
BACKGROUND.md	연구 시작의 구조적 배경 (AI Agent 시대의 통신 인프라 변화) — 발표 자료 추출 가능 형태	연구 동기를 깊이 이해하거나 슬라이드로 추출할 때
참고/SGS/README.md	선행 연구 (스마트팜 해충 탐지, gRPC vs REST/HTTP-2)	연구 차별성·시나리오 설계 시
FEEDBACK.md	외부 리뷰어의 비평 (긍정 평가 생략, 개선 지점만)	큰 설계 변경 전 또는 보강 항목을 찾을 때
docs/decisions/	설계 결정 기록 (ADR)	중요한 설계 변경 전후
docs/open-questions.md	미해결 탐색 주제	새 실험을 기획할 때

원칙: CLAUDE.md는 연구 방향과 정책만 다룬다. 디렉터리 경로, 명령어, 코드 샘플, 파일 단위 작업 분담 등 구현 세부 사항은 모두 IMPLEMENTATION.md에 둔다. 연구 배경의 자세한 서술은 모두 BACKGROUND.md에 두고, 본 문서는 요약·정책·평가 계획에 집중한다.

---

1. 연구 배경 및 동기 (요약)

본 절은 핵심 요약만 다룬다. 추세·기술 한계·QUIC 개요의 자세한 서술은 BACKGROUND.md를 참조한다. (FEEDBACK §4.5에 따라 중복을 제거했다.)

1.1. 세 가지 구조적 추세 (한 줄 요약)

추세	핵심 함의
보안 격리	컨테이너/VM 격리로 같은 노드 내 통신도 네트워크 스택 경유 → 통신 건수 폭증
서브에이전트 + RAG	컨텍스트 한계 극복을 위한 외부 서비스 통신 빈도 증가 → 통신 속도가 응답성을 좌우
24/7 가동	사람이 쉬는 시간에도 동작하는 Agent로 동시간 트래픽 누적 → 동시성 폭증

→ 자세한 분석은 BACKGROUND.md §1, §2.

1.2. 기존 통신 기술의 한계 (한 줄 요약)

• gRPC(HTTP/2) > REST는 선행 연구로 검증됨 (참고/SGS)
• 그러나 HTTP/2 기반 gRPC는 TCP의 근본적 한계(연결 수립 비용, HoL Blocking, 연결 고정)를 그대로 상속
• QUIC(HTTP/3)은 위 세 한계를 모두 해결하는 차세대 전송 계층

→ 자세한 분석은 BACKGROUND.md §3.

1.3. 선행 연구의 향후 과제 중 본 연구의 위치 — 왜 HTTP/3을 선택했는가

참고/SGS는 향후 연구로 다음 세 가지를 제시했다.

1. HTTP/3(QUIC) 기반 gRPC 도입 ← 본 연구의 주제
2. 다양한 스트리밍 패턴 비교 (Unary / Server / Client / Bidi)
3. LLM 기반 동적 작업 라우팅

본 연구가 (1)을 우선 선택한 근거(FEEDBACK §2.1 반영):

• (2) 스트리밍 패턴은 응용 계층의 표현 변화로, 전송 계층의 병목(연결 수립 비용·HoL Blocking)을 해결하지 못한다. 같은 TCP 위에서 호출 모양만 바꾸는 셈이다.
• (3) LLM 라우팅은 라우팅 의사결정의 지능화에 관한 것으로, 통신 채널의 효율 자체를 개선하지 않는다. 라우팅이 똑똑해져도 채널이 느리면 응답성에 한계가 있다.
• (1) HTTP/3 도입은 §1.1의 세 추세(보안 격리·빈번한 RPC·동시성)가 모두 만나는 전송 계층을 직접 개선하는 가장 영향력 있는 단일 변경이며, AIoT 도메인에서 실증이 부재하다.

따라서 (1)을 우선 다루고, (2) 스트리밍 패턴은 본 연구의 P2 항목으로 부분 포함하며, (3) LLM 라우팅은 명시적 비목표(§3.2)로 제외한다.

1.4. 본 연구가 다루는 트래픽 두 종류

종류	특성	페이로드	대표 예시
AI Agent ↔ 외부 서비스/Agent	짧고 빈번한 RPC, 컨테이너 격리 환경	1–8 KB, Unary 위주	서브에이전트 호출, RAG 조회, 도구 호출
IoT Device ↔ Edge ↔ Cloud	다양한 응용 프로토콜(MQTT/CoAP), 엣지 단계적 처리	64 KB ~ 2 MB, 스트리밍 가능	해충 탐지 ROI 전달, 센서 데이터 적재

두 시나리오를 동일한 gRPC-QUIC 스택으로 다루는 근거 (FEEDBACK §4.1 반영):

QUIC 특성	AI Agent 시나리오에서의 효용	IoT 시나리오에서의 효용
0-RTT 연결 수립	격리 에이전트 간 빈번한 단발성 RPC 가속	디바이스 reconnect 시 latency 감소
스트림 독립성 (HoL Blocking 해소)	다중 동시 RPC의 안정성	무선/모바일 IoT 패킷 손실 환경 강건
연결 마이그레이션	컨테이너 재배치 시 일부 시나리오에서 유효	모바일 IoT, NAT rebinding
Protobuf 표현 (gRPC 공통)	호출 인터페이스 IDL 일관성	페이로드 절감 (특히 큰 메시지)

두 시나리오는 페이로드 크기와 패턴은 다르지만 연결 빈도가 높고 패킷 손실에 노출되며 다양한 네트워크 조건에서 동작해야 한다는 공통점을 가지며, QUIC의 핵심 이점이 두 시나리오 모두에 작용한다. 단, 각 시나리오에서 지배적인 KPI는 다르므로(§5.4 참조) 단일 KPI로 두 시나리오를 평가하지 않는다.

---

2. 제안 기법

본 연구의 기여는 **AIoT 도메인에서의 실증(domain-specific empirical study)**이다. gRPC over QUIC의 발명은 본 연구의 기여가 아니다 — 이미 quic-go 커뮤니티의 PoC, MsQuic 등에서 시도되고 있다(FEEDBACK §4.2 반영).

2.1. 제안 ① — AIoT 환경에서의 gRPC-QUIC 실증

기여의 성격: 새로운 프로토콜의 발명이 아니라, AIoT 도메인의 실제 워크로드에 gRPC over QUIC을 적용하고, 통제된 네트워크 조건에서 정량 비교를 수행하는 empirical study다.

왜 이 실증이 필요한가:

• 기존 QUIC/HTTP-3 벤치마크는 웹 트래픽(브라우저-서버) 중심이며, AI Agent의 burst RPC 패턴이나 IoT 단계적 처리에 그대로 적용되지 않는다.
• gRPC core team의 gRPC-over-QUIC도 stable에 도달하지 않았으며, AIoT 워크로드 특성에 따른 효과 측정이 부재하다.
• 본 연구는 *"gRPC over QUIC이 AIoT 환경에서 얼마만큼의 개선을 가져오며, 어느 조건에서 가장 큰가?"*에 대한 정량 답을 제공한다.

QUIC의 어떤 특성이 어떻게 작용하는지(0-RTT, HoL Blocking, 연결 마이그레이션)는 §1.4 표 참조.

본 연구는 0-RTT 측정에 필요한 TLS 1.3 설정 자체는 실험 범위에 포함하며(self-signed 인증서 사용), 인증서 관리·인증/인가 등 프로덕션 수준의 보안 시스템은 비목표로 둔다 (§3.2).

2.2. 제안 ② — AI Agent + IoT 통합 엣지 게이트웨이

기여의 성격(FEEDBACK §2.2 반영): 프로토콜 변환과 정적 라우팅 자체는 이미 존재하는 개념이다. 본 게이트웨이의 기여는 다음 두 가지에 있다.

1. AI Agent와 IoT를 단일 스택으로 통합 — 기존 IoT 게이트웨이는 MQTT↔HTTP 변환에 머무르고, AI Agent gateway는 별도 계열(LangGraph, MCP 등). 본 연구는 두 트래픽을 하나의 게이트웨이가 처리하는 아키텍처를 정의·구현·측정한다.
2. gRPC-QUIC 백본과의 통합 검증 — 게이트웨이가 백엔드와 gRPC-QUIC으로 통신할 때의 성능 영향(추가 hop의 latency, 자원 사용)을 정량 측정한다. 기존 게이트웨이 연구는 HTTP/2 위에서만 평가되었다.

게이트웨이의 두 책임:

1. 프로토콜 변환 — 외부 IoT 응용 프로토콜(MQTT, CoAP)에서 들어오는 메시지를 gRPC/Protobuf로 변환. AI Agent 측 트래픽은 이미 gRPC이므로 변환 없이 라우팅 단계로 진입.
2. 서비스 라우팅 — 정적 룰 기반(룰 테이블) IoT 데이터의 단계적 처리 분배 및 AI Agent 호출의 백엔드 서비스 디스커버리.

선행 연구의 LLM 기반 라우팅은 본 연구의 범위 밖이다 (§3.2). 본 연구의 라우팅은 정적 룰 기반으로 한정한다.

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

비교 항목	선행 연구 (SGS)	본 연구
전송 계층	HTTP/2 (TCP)	HTTP/3 (QUIC) 추가 및 비교
시나리오	스마트팜 단일 시나리오	IoT 시나리오 + AI Agent RPC 패턴 이중
게이트웨이	센서/엣지 인터페이스 변환기 (개념적 제시)	AI Agent + IoT 통합 게이트웨이의 실증
평가 지표	응답 시간, 데이터 전송량	+ 0-RTT 효과, HoL Blocking 내성, 연결 마이그레이션, 통계적 유의성
비교 시스템 수	3개	6개 (4-way 전송 비교 + 스트리밍 + 게이트웨이)

---

3. 프로젝트 목표 및 범위

3.1. 우선순위별 목표 (의존성 및 리스크 명시)

FEEDBACK §2.3에 따라 각 P0 목표의 의존성과 주된 리스크를 함께 표기한다.

우선순위	목표	주된 의존 / 리스크
P0	gRPC over QUIC 통신 모듈 구현 — Go 기반 서버/클라이언트	quic-go ↔ gRPC transport interface 호환성 (§3.3 R-01)
P0	gRPC 엣지 게이트웨이 설계·구현 — 프로토콜 변환 + 정적 룰 라우팅	통신 모듈(P0-1) 의존, MQTT/CoAP 어댑터 범위 통제 필요 (§3.3 R-03)
P0	gRPC/HTTP3 vs gRPC/HTTP2 vs REST/HTTP2 vs REST/HTTP1.1 4-way 정량 성능 비교	P0-1 지연 시 HTTP/2까지 우선 측정, QUIC은 후속 추가 (§3.3 R-01 fallback)
P1	IoT 시나리오 벤치마크 — 이미지/센서 데이터 (해충 탐지 ROI 단계적 처리)	gRPC 서버/클라이언트 완성 후
P1	AI Agent 통신 시나리오 벤치마크 — 짧고 빈번한 RPC, 다수 동시 에이전트 환경	동일
P2	gRPC 스트리밍 패턴 비교 (Unary / Server-side / Client-side / Bidirectional)	Unary 측정 후
P2	QUIC 0-RTT 재연결 성능 측정 및 연결 마이그레이션 시나리오 검증	P0-1 완료 후

P0-1(통신 모듈)이 본 프로젝트의 핵심 병목이므로, §3.3의 위험 관리가 본 프로젝트 운영의 가장 중요한 과제다.

3.2. 비목표 (명시적 제외)

• 프로덕션 수준 인증/인가 시스템 및 인증서 관리 (0-RTT 측정에 필요한 TLS 1.3 설정 자체는 실험 범위에 포함, self-signed 인증서 사용)
• LLM 기반 동적 작업 라우팅 (선행 연구의 향후 과제로 제시되었으나, 본 연구는 정적 룰 기반 라우팅에 한정)
• 특정 하드웨어 최적화 (Raspberry Pi 등 임베디드 전용 튜닝)
• Kubernetes 오케스트레이션 자동화
• 프로덕션 UI/대시보드 (데모 목적의 Terminal UI는 별도 산출물로 제공 — src/README.md)

3.3. 위험 관리 (Risk Register)

FEEDBACK §4.4 권고에 따라 도입했다. 각 위험은 발생 시 ADR로 정식 등록하고, 변경이 발생하면 본 표를 갱신한다.

ID	위험	영향	가능성	대비책
R-01	quic-go의 Stream과 gRPC transport(net.Conn) 인터페이스 의미 차이 — SetDeadline/Close(half-close)/LocalAddr 등	프로젝트 핵심 모듈 좌초 → P0 전체 지연	중간	(a) PoC를 본 구현 전에 분리 제작하여 호환성 검증 (b) 실패 시 HTTP/2 기반 게이트웨이로 P0-2,3 우선 진행, QUIC은 별도 실험으로 분리
R-02	Docker 환경에서 tc(netem) 미작동 또는 컨테이너 격리로 인한 효과 미반영	네트워크 시뮬레이션 신뢰도 저하	낮음~중간	호스트 레벨 tc 적용, 또는 Linux network namespace로 노드 분리 후 적용. Phase 2(Mininet)에서는 자동 적용
R-03	MQTT/CoAP 어댑터 구현 범위 과다	P0-2 일정 지연	중간	MQTT만 우선 구현, CoAP은 P1으로 격하
R-04	Go/quic-go 버전업에 따른 API 변경	빌드 실패, 재작업	낮음	go.mod에 quic-go 버전 고정, ADR로 변경 사유 기록
R-05	AI Agent 시나리오의 부하 발생기는 합성 부하 — 실제 LLM 호출 패턴과 차이 가능	결론의 일반화 약함	중간	부하 generator의 burst 파라미터(휴지·burst 크기·burst 간격)를 명시하고, 합성 부하임을 결론에 명기

---

4. 기술 스택

영역	기술	비고
언어	Go 1.22+	go.mod 기준
IDL	Protocol Buffers v3	.proto → Go 스텁 자동 생성
gRPC	google.golang.org/grpc	공식 Go gRPC 라이브러리
QUIC / HTTP/3	github.com/quic-go/quic-go	Go 순수 구현 QUIC 라이브러리 (버전 고정 — R-04)
gRPC-QUIC 바인딩	커스텀 transport 패키지	quic-go 위에 gRPC 전송 계층 구현 (R-01)
Protobuf 코드젠	protoc + protoc-gen-go + protoc-gen-go-grpc	Makefile로 자동화
HTTP 비교군	Go 표준 net/http + encoding/json	REST API (HTTP/1.1, HTTP/2)
벤치마크	Go 내장 testing.B + 커스텀 러너(cmd/benchmark-runner)	측정 도구 (역할 분담은 IMPLEMENTATION.md)
자원 사용 측정	pidstat (1초 샘플링), pprof(핫스팟 분석 한정)	§5.2 측정 방법 참조
컨테이너	Docker + Docker Compose	실험 환경 재현성 확보
네트워크 제어	Linux tc (Phase 1), Mininet (Phase 2)	지연/손실/대역폭 시뮬레이션

구체적인 빌드/실행 명령은 IMPLEMENTATION.md §3(개발 워크플로우)을 따른다.

---

5. 평가 시나리오 및 지표

5.1. 비교 대상 시스템

각 시스템은 두 시나리오 (① AI Agent RPC, ② IoT 데이터 전송) 모두에서 동일하게 측정한다. "처리 위치"는 데이터의 1차 처리(ROI 탐지·집계 등)가 어디서 수행되는가를 의미한다(FEEDBACK §2.4 반영하여 정의 일관화).

시스템	전송 프로토콜	직렬화	처리 위치	비고
REST-Cloud	HTTP/1.1 (TCP)	JSON	클라우드 (원시 데이터 직송)	베이스라인
REST-Edge	HTTP/2 (TCP)	JSON	엣지 1차 처리 → 클라우드	기존 방식
gRPC-H2	HTTP/2 (TCP)	Protobuf	엣지 1차 처리 → 클라우드	선행 연구 재확인
gRPC-H3 (제안 ①)	HTTP/3 (QUIC)	Protobuf	엣지 1차 처리 → 클라우드	본 연구 통신 모듈
gRPC-H3-Stream	HTTP/3 (QUIC)	Protobuf	엣지, 스트리밍	스트리밍 확장 (P2)
gRPC-H3-GW (제안 ②)	HTTP/3 (QUIC)	Protobuf	게이트웨이 경유 → 백엔드	본 연구 게이트웨이 아키텍처

5.2. 핵심 성능 지표 (KPI) 및 측정 방법

FEEDBACK §2.5 권고에 따라 측정 방법·조건·게이트웨이의 자원 측정 단위를 명시한다.

지표	설명	측정 방법
P50 / P95 / P99 Latency	응답 시간 분포	클라이언트 측 wall-clock 타임스탬프. warm-up 200회 후 측정 시작.
Throughput (RPS)	초당 처리 요청 수	정상 종료된 요청 수 / 측정 구간 길이. 측정 구간은 최소 30초 또는 N≥10000 요청
Payload Size	단일 요청의 직렬화된 페이로드 크기	tcpdump 캡처에서 application payload만 합산. TLS 오버헤드 포함 여부는 별도 ADR로 결정
CPU / Memory	서버 측 자원 사용률	pidstat -p <pid> 1로 1초 단위 샘플링, 측정 구간 평균과 분산 보고. 게이트웨이 시나리오는 게이트웨이 + 백엔드 합계와 개별값 모두 보고(공정 비교를 위해). pprof는 핫스팟 분석에만 사용하며 자원 비교 KPI에는 사용하지 않음
Connection Overhead	연결 수립 비용	첫 요청 vs. 재사용 요청 latency 차이 (10회 평균)
0-RTT Resumption	QUIC 0-RTT 재연결 효과	세션 캐시 적용 후 첫 요청 latency (QUIC only)
HoL Blocking 내성	패킷 손실이 다른 스트림에 미치는 영향	병렬 스트림 4개 동시 전송 중 1개 스트림 강제 손실 시 나머지 3개의 latency

5.3. 네트워크 조건 매트릭스

QUIC의 HoL Blocking 해소 효과를 분명히 드러내기 위해 손실 조건을 다양화했다(FEEDBACK §2.7 반영). TCP의 rapid recovery로 가려지는 1% 영역과 본격 효과가 드러나는 3–5% 영역을 모두 포함한다.

조건	지연	패킷 손실	용도
Ideal	0 ms	0 %	베이스라인
LAN	1 ms	0 %	로컬 엣지
WAN-Low	50 ms	0 %	일반 클라우드
WAN-High	200 ms	0 %	원거리 클라우드
Lossy-1	50 ms	1 %	약한 손실 (TCP rapid recovery 영역)
Lossy-3	50 ms	3 %	중간 손실 (HoL Blocking 효과 본격화)
Lossy-5	100 ms	5 %	강한 손실 (모바일/원거리 무선 환경)

5.4. 시나리오 정의 및 시나리오별 KPI 가중치

§1.4에서 분류한 두 트래픽 종류에 대해 다음 워크로드를 사용한다. 시나리오마다 지배적인 KPI가 다르므로, 결과 해석 시 표의 "주요 KPI"를 우선 기준으로 삼는다(FEEDBACK §2.8 반영).

시나리오	페이로드	호출 패턴	동시성	주요 KPI	보조 KPI
① AI Agent RPC	1–8 KB 작은 요청/응답	Unary, 짧은 burst 반복	격리 에이전트 N=10/50/100	Connection Overhead, 0-RTT Resumption, P50/P95 Latency, RPS	HoL Blocking 내성
② IoT 데이터 전송	64 KB ~ 2 MB	Unary + Streaming	디바이스 N=10/50	Throughput, P95/P99 Latency, Payload Size, HoL Blocking 내성 (Lossy 조건)	Connection Overhead

주의: AI Agent RPC 시나리오에서 Payload Size는 직렬화 효율(Protobuf vs JSON)이 latency를 거의 좌우하지 않는 영역(수 KB)이다(직렬화 시간이 RTT보다 두세 자릿수 작음). 따라서 보고는 하되 결론의 핵심 근거로 사용하지 않는다. 이 시나리오의 핵심 차별 요인은 연결 수립 비용이다.

시나리오별 구체 워크로드 파라미터(이미지 해상도, RPS 목표, burst 크기 등)는 docs/decisions/의 ADR로 별도 고정한다.

5.5. 통계적 유의성 확보 계획

FEEDBACK §4.3을 반영하여 다음 원칙을 따른다. (단순한 count=5는 평균/분산 추정에 부족하다는 지적을 수용.)

항목	방침
반복 횟수	각 (시스템 × 네트워크 조건 × 시나리오) 조합당 최소 30회 반복. Lossy-3, Lossy-5는 분산이 크므로 50회로 증가
Warm-up	측정 전 동일 시스템에 200회 호출하여 JIT/캐시/연결 초기화 효과 안정화
신뢰 구간	모든 요약값에 95% 신뢰 구간 동반 보고. percentile은 percentile bootstrap, 평균은 Student's t
Outlier 처리	Tukey's fence(Q3 + 1.5×IQR 초과)를 outlier로 표시하되 제거하지 않음. 보고에 outlier 비율 포함
유의성 검정	두 시스템 간 차이의 유의성은 Mann–Whitney U test(latency 분포는 정규성 가정 어려움)로 판정, p<0.05 기준
재현성	모든 측정은 ADR로 등록된 워크로드 파라미터를 사용. 측정 환경(호스트, OS, NIC, kernel 버전, tc 명령) 함께 기록

---

6. 코드 작성 정책

본 절은 정책만 정의한다. 디렉터리 구조·네이밍·코드 패턴·예제 코드는 IMPLEMENTATION.md를 따른다.

6.1. 계층 분리 (필수)

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

• 전송 계층은 인터페이스로 추상화하여 QUIC↔TCP를 동일 코드 경로로 교체 가능하게 한다 (벤치마크 공정성 보장)
• 게이트웨이는 외부 IoT 프로토콜 ↔ gRPC Protobuf 변환과 서비스 라우팅만 담당한다
• gRPC 서버 구현은 비즈니스 로직과 분리되어야 한다

6.2. 컨텍스트 전파

모든 RPC 함수는 context.Context를 첫 번째 인수로 받는다. 타임아웃은 클라이언트에서 설정하고 서버는 컨텍스트 취소를 존중한다.

6.3. 에러 처리

gRPC 에러는 google.golang.org/grpc/status 패키지의 표준 코드를 사용한다.

6.4. 측정 가능성 (필수)

모든 신규 RPC 구현은 latency 측정이 가능해야 한다. 인터셉터(internal/middleware/metrics.go)를 활용하거나, 직접 측정이 필요한 경우 명시적으로 기록한다.

측정 도구의 observer effect (FEEDBACK §2.6 반영): 인터셉터의 time.Now() 호출과 metric 기록은 측정값에 마이크로초 단위 bias를 추가한다. 본 연구는 모든 비교군에 동일한 인터셉터를 적용하므로 상대 비교는 유효하지만, 절대값은 인터셉터를 비활성화한 별도 측정으로 추정 보정값을 산출하여 함께 보고한다. AI Agent 시나리오처럼 latency 자체가 작은 영역에서는 이 bias가 비례적으로 커질 수 있으므로 절대값 해석에 주의한다.

6.5. 금지 사항

• gen/ 디렉터리 직접 수정 금지 — .proto 수정 후 재생성한다
• panic 사용 금지 (초기화 코드 제외)
• 전역 변수로 설정 관리 금지 — config 구조체를 사용한다
• 미사용 의존성 추가 금지 — go mod tidy 후 커밋

---

7. 연구 기록 규칙

7.1. 실험 결과

benchmarks/results/YYYY-MM-DD/ 디렉터리에 시나리오별 JSON 결과와 summary.md를 함께 저장한다.

benchmarks/results/2026-05-07/
├── unary_ideal.json
├── unary_wan_200ms.json
├── streaming_wan_200ms.json
├── lossy3_wan_50ms.json
└── summary.md          # 해당 날짜 실험 요약 및 주요 발견사항

각 JSON에는 raw latency 샘플 + 95% 신뢰구간 + outlier 비율(§5.5) + 측정 환경(host, kernel, tc 명령)을 함께 기록한다.

7.2. 설계 결정 (ADR)

docs/decisions/NNN-{title}.md 형식으로 기록한다.

# NNN. {제목}

## 상태
Accepted / Deprecated / Superseded by NNN

## 맥락
왜 이 결정이 필요했는가?

## 결정
무엇을 선택했는가?

## 대안
고려했지만 선택하지 않은 것과 그 이유

## 결과
이 결정으로 인해 생기는 트레이드오프

§3.3의 주요 위험은 발생 시점 또는 mitigation 결정 시 ADR로 정식 등록한다.

7.3. 오픈 질문

docs/open-questions.md에 기록한다. 실험으로 답을 얻으면 해당 항목에 결과를 추가하고 닫는다.

7.4. 실패한 접근도 기록

무엇을 시도했고, 왜 실패했으며, 무엇을 배웠는지 docs/decisions/에 포함한다. 실패 기록은 미래의 시간 낭비를 막는 자산이다.

7.5. 외부 피드백 반영

FEEDBACK.md의 권고를 본 문서·BACKGROUND.md·IMPLEMENTATION.md에 반영할 때는, 어떤 항목을 어디에 어떻게 반영했는지 ADR 또는 본 문서의 해당 절에 명시적으로 표기한다 (현재 본 문서의 (FEEDBACK §x.y 반영) 표기 참조).

---

8. 참고 자료

• 본 저장소 내부
  • IMPLEMENTATION.md — 구현 세부 사항 (디렉터리·네이밍·워크플로우·코드 패턴·멀티 에이전트 분담)
  • BACKGROUND.md — 연구 수행 배경 (발표 자료 추출 가능 형태)
  • 참고/SGS/README.md — 선행 연구
  • FEEDBACK.md — 외부 리뷰어의 비평 (긍정 평가 생략)
  • src/README.md — 데모 Terminal UI 빌드·실행 가이드
  • docs/decisions/ — 설계 결정 기록 (ADR)
  • docs/open-questions.md — 미해결 탐색 주제
• 외부 문서
  • RFC 9000 — QUIC
  • RFC 9114 — HTTP/3
  • gRPC 공식 문서
  • gRPC Go 빠른 시작
  • Protocol Buffers v3 언어 가이드
  • google.golang.org/grpc Go pkg
  • quic-go GitHub

---

본 프로젝트는 연구 목적의 프로토타입입니다. 프로덕션 환경의 안정성·보안·가용성을 보장하지 않습니다.