proto-socket/agent-ops/rules/project/rules.md

프로젝트 규칙

응답 언어

한국어로 응답한다.

프로젝트 개요

Toki Socket — 다중 언어/플랫폼 간 양방향 통신을 위한 바이너리 소켓 프로토콜 라이브러리.

• Protocol Buffers 기반 직렬화
• TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍 / WebSocket 바이너리 프레임
• 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트
• 현재 구현 완료: Dart, Go / 진행 중: Kotlin / 계획: C#, Swift, Python, Rust

주요 구조

dart/          — Dart/Flutter 구현체 (lib/, test/, crosstest/)
go/            — Go 구현체 (*.go, test/, crosstest/)
kotlin/        — Kotlin/Android 구현체 (src/, crosstest/)
tools/         — proto 생성/동기화 스크립트
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
Proto 관리	tools/generate_proto.sh, tools/check_proto_sync.sh

프로젝트 특화 컨벤션

• proto 정의는 dart/lib/src/packets/message_common.proto가 정식 원본이다. Go/Kotlin은 언어별 옵션(go_package, java 패키지)만 추가 허용
• proto 변경 시 반드시 tools/generate_proto.sh 실행 후 tools/check_proto_sync.sh로 동기화 확인
• 새 언어 구현은 PORTING_GUIDE.md에 따라 동일 언어 테스트 + 크로스 언어 테스트 통과 후 Available 표시
• 프로토콜 버전과 패키지 버전은 분리 관리 (VERSIONING.md 참조)

도메인 매핑

경로 패턴	도메인	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
dart/lib/src/packets/, go/packets/, kotlin/src/**/packets/	protocol	agent-ops/rules/project/domain/protocol/rules.md
tools/**, */crosstest/**	tools	agent-ops/rules/project/domain/tools/rules.md

스킬 라우팅

요청 키워드	SKILL.md
크로스 언어 테스트 추가, 새 언어 crosstest	agent-ops/skills/project/add-toki-socket-crosstest-language/SKILL.md