# 프로젝트 규칙

## 응답 언어

한국어로 응답한다.

## 프로젝트 개요

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

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

## 주요 구조

```
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 정의는 `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 참조)

## 도메인 매핑

더 구체적인 경로가 우선한다. 여러 도메인에 걸친 변경이면 가장 구체적인 도메인 규칙을 먼저 읽고, 실제로 함께 수정하는 관련 도메인 규칙도 읽는다.

| 경로 패턴 | 도메인 | 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/**/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-toki-socket-crosstest-language/SKILL.md` |