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>
147 lines
7.2 KiB
Markdown
147 lines
7.2 KiB
Markdown
# 작업 리스트 (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 프로그램을 구현 중이므로 수정하지 않음.
|