docs: 신규 에이전트 onboarding 프롬프트와 작업 리스트 추가

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>

PROMPT.md

@@ -0,0 +1,140 @@
+# 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 두 시나리오 연결 논리 강화

TASK_LIST.md

@@ -0,0 +1,146 @@
+# 작업 리스트 (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 프로그램을 구현 중이므로 수정하지 않음.