102 lines
6.5 KiB
Markdown
102 lines
6.5 KiB
Markdown
# 프로젝트 규칙
|
|
|
|
## 응답 언어
|
|
|
|
한국어로 응답한다.
|
|
|
|
## 프로젝트 개요
|
|
|
|
**Proto Socket** — 다중 언어/플랫폼 간 양방향 통신을 위한 바이너리 소켓 프로토콜 라이브러리.
|
|
|
|
- Protocol Buffers 기반 직렬화
|
|
- TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍 / WebSocket 바이너리 프레임
|
|
- 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트
|
|
- 현재 구현 완료: Dart, Go, Kotlin, Python, TypeScript / 계획: C#, Swift
|
|
|
|
## 주요 구조
|
|
|
|
```
|
|
dart/ — Dart/Flutter 구현체 (lib/, test/, crosstest/)
|
|
go/ — Go 구현체 (*.go, test/, crosstest/)
|
|
kotlin/ — Kotlin/Android 구현체 (src/, crosstest/)
|
|
python/ — Python 구현체 (proto_socket/, test/, crosstest/)
|
|
typescript/ — TypeScript 구현체 (src/, test/, crosstest/)
|
|
tools/ — proto 생성/동기화 스크립트
|
|
agent-roadmap/ — 전체 목표 / 단계 / Milestone 기반 로드맵과 현재 마일스톤 포인터
|
|
PROTOCOL.md — 와이어 포맷 명세 (정식 스펙)
|
|
PORTING_GUIDE.md — 새 언어 구현 가이드
|
|
VERSIONING.md — 프로토콜/패키지 버전 정책
|
|
```
|
|
|
|
## 기술 스택
|
|
|
|
| 영역 | 기술 |
|
|
|------|------|
|
|
| 직렬화 | Protocol Buffers (proto3) |
|
|
| 전송 | TCP, WebSocket/WSS |
|
|
| Dart | dart pub, protoc_plugin |
|
|
| Go | Go modules, google.golang.org/protobuf |
|
|
| Kotlin | Gradle, protobuf-kotlin |
|
|
| Python | pytest, protobuf |
|
|
| TypeScript | npm, tsx, TypeScript |
|
|
| Proto 관리 | tools/generate_proto.sh, tools/check_proto_sync.sh |
|
|
|
|
## 프로젝트 특화 컨벤션
|
|
|
|
- proto 정의는 `proto/message_common.proto`가 정식 원본이다. Go/Kotlin은 언어별 옵션(go_package, java 패키지)만 추가 허용
|
|
- proto 변경 시 반드시 `tools/generate_proto.sh` 실행 후 `tools/check_proto_sync.sh`로 동기화 확인
|
|
- 새 언어 구현은 PORTING_GUIDE.md에 따라 동일 언어 테스트 + 크로스 언어 테스트 통과 후 Available 표시
|
|
- 프로토콜 버전과 패키지 버전은 분리 관리 (VERSIONING.md 참조)
|
|
|
|
## 검증 운영 기준
|
|
|
|
- 이 프로젝트의 주 사용 방식과 릴리즈 기준은 package registry나 CI/CD 배포 흐름이 아니라 Git ref/tag 기반 소비다.
|
|
- 검증 루프는 내부 로컬 매트릭스 실행 결과를 기준으로 판단한다.
|
|
- 기본 검증 명령은 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`이다.
|
|
- 테스트 coverage 평가는 라인/브랜치 수치가 아니라 프로토콜 계약 시나리오가 매트릭스에서 빠짐없이 검증되는지로 판단한다.
|
|
- Dart.web remote browser host 사용은 의도된 local 테스트 환경이다. 환경을 이전할 때는 그대로 유지할 규칙이 아니라 새 local 환경 규칙으로 재정의해야 한다.
|
|
- Dart.web WSS는 self-signed certificate로 자동화할 수 없는 항목이 아니다. 현재 남은 coverage gap은 브라우저가 테스트용 self-signed CA/certificate를 신뢰하도록 만드는 자동화와 그에 따른 Dart.web WSS 매트릭스 편입이다.
|
|
- CI/CD runner 연결은 현재 설계상 과하며, 사용자가 명시적으로 요청하지 않으면 제안하거나 요구하지 않는다.
|
|
|
|
## 마일스톤 컨텍스트 로딩
|
|
|
|
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다.
|
|
- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다.
|
|
- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
|
|
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다.
|
|
- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
|
|
- `agent-roadmap/ROADMAP.md`는 로드맵 생성/갱신, 단계 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
|
|
- 활성 Milestone 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
|
|
- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다.
|
|
- 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.
|
|
|
|
## 도메인 매핑
|
|
|
|
더 구체적인 경로가 우선한다. 여러 도메인에 걸친 변경이면 가장 구체적인 도메인 규칙을 먼저 읽고, 실제로 함께 수정하는 관련 도메인 규칙도 읽는다.
|
|
|
|
| 경로 패턴 | 도메인 | rules.md |
|
|
|----------|--------|----------|
|
|
| `proto/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `dart/lib/src/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `go/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `kotlin/src/main/proto/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `python/proto_socket/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `typescript/src/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `PROTOCOL.md` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `VERSIONING.md` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
|
|
| `tools/**` | tools | `agent-ops/rules/project/domain/tools/rules.md` |
|
|
| `PORTING_GUIDE.md` | tools | `agent-ops/rules/project/domain/tools/rules.md` |
|
|
| `dart/**` | dart | `agent-ops/rules/project/domain/dart/rules.md` |
|
|
| `go/**` | go | `agent-ops/rules/project/domain/go/rules.md` |
|
|
| `kotlin/**` | kotlin | `agent-ops/rules/project/domain/kotlin/rules.md` |
|
|
|
|
## 기타 경로
|
|
|
|
- `agent-task/<task-name>/` — 에이전트 작업 로그 (plan, code_review 등). 소스 코드 아님. PLAN.md 또는 CODE_REVIEW.md 파일을 읽고 작업하는 작업이 아닌이상. 수정하지 않는다.
|
|
|
|
## 스킬 라우팅
|
|
|
|
| 요청 키워드 | SKILL.md |
|
|
|------------|----------|
|
|
| 새 언어 구현, 언어 포팅, language scaffold, 템플릿, 크로스 언어 테스트 추가, 새 언어 crosstest | `agent-ops/skills/project/add-proto-socket-crosstest-language/SKILL.md` |
|
|
| 전체 테스트해, 전체테스트해, 전체 검증, 테스트 매트릭스, 언어간 크로스 테스트해, 언어별 크로스 테스트, 크로스 테스트해, 통신 테스트 | `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md` |
|