Godopu
963645c82a
FEEDBACK.md 발행 이후 작성된 보조 문서.
PROMPT.md:
새로 투입되는 AI 에이전트(Claude Code, Codex 등)나 협업자가
프로젝트를 빠르게 이해할 수 있도록 1페이지로 정리한 onboarding 자료.
- 프로젝트 한 줄 요약, 핵심 정보 표
- 문서 구성과 읽는 순서 (CLAUDE → IMPLEMENTATION → BACKGROUND → SGS)
- 비교 대상·시나리오·KPI·네트워크 조건 요약
TASK_LIST.md:
FEEDBACK.md 권고를 우선순위(P0/P1/P2)별로 분류한 액션 아이템.
- P0: quic-go 호환성 PoC, novelty 재정의, 게이트웨이 기여 보강,
실험 설계 강화, 위험 관리 문서화
- P1: MQTT/CoAP 어댑터 설계, 라우팅 룰 형식 정의,
측정 방법 정밀화, 통계적 유의성 계획
- P2: golangci-lint 설정, 벤치마크 이중성 정리, 자동화 도구
비고:
본 commit 시점에서 BACKGROUND.md와 CLAUDE.md는 이미 FEEDBACK.md의
주요 권고를 반영한 1차 수정판이다. 후속 작업은 본 TASK_LIST를 따라
IMPLEMENTATION.md 보강과 PoC 검증을 우선 진행한다.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
141 lines
6.3 KiB
Markdown
141 lines
6.3 KiB
Markdown
# 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. 단위 테스트 → 벤치마크 시나리오 추가
|
|
|
|
### 서버 실행
|
|
```bash
|
|
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 비교군
|
|
```
|
|
|
|
### 네트워크 조건
|
|
```bash
|
|
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 두 시나리오 연결 논리 강화
|