From 8a8636762d24c63de701e7beb7e5646ab7c7f168 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 12 Apr 2026 17:30:20 +0900 Subject: [PATCH] Update project structure and rules --- .gitignore | 3 + CLAUDE.md | 17 ++++++ agent-ops/rules/project/domain/dart/rules.md | 37 ++++++++++++ agent-ops/rules/project/domain/go/rules.md | 40 +++++++++++++ .../rules/project/domain/kotlin/rules.md | 35 +++++++++++ .../rules/project/domain/protocol/rules.md | 39 ++++++++++++ agent-ops/rules/project/domain/tools/rules.md | 34 +++++++++++ agent-ops/rules/project/rules.md | 60 +++++++++++++++++++ agent-ops/skills/project/.gitkeep | 0 .../{code_review_0.md => code_review_0.log} | 0 .../dart_close_fix/{plan_0.md => plan_0.log} | 0 11 files changed, 265 insertions(+) create mode 100644 CLAUDE.md create mode 100644 agent-ops/rules/project/domain/dart/rules.md create mode 100644 agent-ops/rules/project/domain/go/rules.md create mode 100644 agent-ops/rules/project/domain/kotlin/rules.md create mode 100644 agent-ops/rules/project/domain/protocol/rules.md create mode 100644 agent-ops/rules/project/domain/tools/rules.md create mode 100644 agent-ops/rules/project/rules.md delete mode 100644 agent-ops/skills/project/.gitkeep rename agent-task/dart_close_fix/{code_review_0.md => code_review_0.log} (100%) rename agent-task/dart_close_fix/{plan_0.md => plan_0.log} (100%) diff --git a/.gitignore b/.gitignore index b816475..8355e12 100644 --- a/.gitignore +++ b/.gitignore @@ -51,3 +51,6 @@ rust/Cargo.lock .DS_Store Thumbs.db Desktop.ini + +# ── Agent-Ops private rules ─────────────────────── +agent-ops/rules/private/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..29ccc4b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,17 @@ +# 공통 규칙 + +- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다. +- 코드 변경 전 관련 domain rule을 먼저 확인한다. +- 요청 범위를 넘는 변경을 하지 않는다. +- 불확실하면 단정하지 말고 후보를 제시한다. + +아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다. +- agent-ops 초기화 +- domain rule 생성 +- skill 생성 +- git commit / git push +- 버전 올려줘 +- agent-ops 업데이트 / 진입 파일 재적용 + +`agent-ops/rules/project/rules.md`와 +`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다. diff --git a/agent-ops/rules/project/domain/dart/rules.md b/agent-ops/rules/project/domain/dart/rules.md new file mode 100644 index 0000000..021ee18 --- /dev/null +++ b/agent-ops/rules/project/domain/dart/rules.md @@ -0,0 +1,37 @@ +# dart + +## 목적 / 책임 + +Toki Socket의 Dart/Flutter 구현체를 담당한다. ProtobufClient, ProtobufServer 등 핵심 클래스를 제공하며, 크로스 언어 테스트의 기준 구현으로 동작한다. + +## 포함 경로 + +- `dart/lib/` — 공개 API 및 구현 +- `dart/test/` — 동일 언어 단위/통합 테스트 +- `dart/crosstest/` — 크로스 언어 테스트 (Go, Kotlin과 연동) +- `dart/pubspec.yaml` — 패키지 의존성 + +## 제외 경로 + +- `dart/lib/src/packets/` — protocol 도메인 + +## 주요 구성 요소 + +- `ProtobufClient` — 소켓 클라이언트 기반 클래스 +- `ProtobufServer` — 소켓 서버 기반 클래스 + +## 유지할 패턴 + +- `dart pub get` 후 `dart test`로 테스트 실행 +- crosstest는 상대방 언어 서버/클라이언트가 실행 중인 상태에서 수행 +- Available 표시 조건: 동일 언어 테스트 + 크로스 언어 테스트 통과 + +## 다른 도메인과의 경계 + +- **protocol**: proto 타입을 사용하지만, proto 파일 자체는 protocol 도메인 +- **go/kotlin**: crosstest에서 상호 연동하지만, 각 구현체 내부 로직은 독립 + +## 금지 사항 + +- Dart 구현체에 Go/Kotlin 특화 로직을 추가하지 않는다 +- proto 원본 파일 변경 시 proto 도메인 규칙을 먼저 따른다 diff --git a/agent-ops/rules/project/domain/go/rules.md b/agent-ops/rules/project/domain/go/rules.md new file mode 100644 index 0000000..d0f21cf --- /dev/null +++ b/agent-ops/rules/project/domain/go/rules.md @@ -0,0 +1,40 @@ +# go + +## 목적 / 책임 + +Toki Socket의 Go 구현체를 담당한다. TCP/WebSocket 서버·클라이언트, TLS 지원, 타입 헬퍼 함수를 제공하며, 서버·툴링·스크립팅 용도로 사용된다. + +## 포함 경로 + +- `go/*.go` — 핵심 구현 (packets/ 제외) +- `go/test/` — 동일 언어 테스트 +- `go/crosstest/` — 크로스 언어 테스트 +- `go/go.mod`, `go/go.sum` — 모듈 의존성 +- `go/examples/` — 사용 예제 + +## 제외 경로 + +- `go/packets/` — protocol 도메인 + +## 주요 구성 요소 + +- `TcpServer` / `TcpClient` — TCP 서버/클라이언트 +- `WsServer` / `WsClient` — WebSocket 서버/클라이언트 +- `Communicator` — 메시지 라우팅 및 요청-응답 상관관계 공통 로직 +- `AddListenerTyped`, `AddRequestListenerTyped`, `SendRequestTyped` — 타입 헬퍼 + +## 유지할 패턴 + +- `go test ./...`로 테스트 실행 +- `ParserMap`으로 타입명 → 파서 함수 등록 +- TLS 변형은 기본 구현과 같은 인터페이스 유지 + +## 다른 도메인과의 경계 + +- **protocol**: packets/ 패키지를 import하지만, 패키지 내용은 protocol 도메인 +- **dart/kotlin**: crosstest에서 상호 연동 + +## 금지 사항 + +- `go/packets/` proto 파일을 메시지 스키마 변경 목적으로 편집하지 않는다 +- Communicator에 애플리케이션 도메인 로직(인증, 세션 등)을 추가하지 않는다 diff --git a/agent-ops/rules/project/domain/kotlin/rules.md b/agent-ops/rules/project/domain/kotlin/rules.md new file mode 100644 index 0000000..2a50572 --- /dev/null +++ b/agent-ops/rules/project/domain/kotlin/rules.md @@ -0,0 +1,35 @@ +# kotlin + +## 목적 / 책임 + +Toki Socket의 Kotlin/Android 구현체를 담당한다. Android 및 JVM 환경을 대상으로 하며, 현재 구현 진행 중이다. + +## 포함 경로 + +- `kotlin/src/` — 구현 소스 +- `kotlin/crosstest/` — 크로스 언어 테스트 +- `kotlin/build.gradle.kts`, `kotlin/settings.gradle.kts` — Gradle 빌드 설정 + +## 제외 경로 + +- `kotlin/src/**/packets/` — protocol 도메인 + +## 주요 구성 요소 + +- (구현 진행 중 — Dart/Go 구조 참고) + +## 유지할 패턴 + +- `./gradlew test`로 테스트 실행 +- `./gradlew run -PmainClass=...`으로 crosstest 실행 +- Available 표시 조건: 동일 언어 테스트 + 크로스 언어 테스트 통과 + +## 다른 도메인과의 경계 + +- **protocol**: proto 타입을 사용하지만, 스키마 정의는 protocol 도메인 +- **dart/go**: crosstest에서 상호 연동 + +## 금지 사항 + +- Kotlin proto 복사본에서 메시지 스키마를 변경하지 않는다 +- 아직 Available이 아니므로 README의 구현 상태를 임의로 변경하지 않는다 diff --git a/agent-ops/rules/project/domain/protocol/rules.md b/agent-ops/rules/project/domain/protocol/rules.md new file mode 100644 index 0000000..6690f2a --- /dev/null +++ b/agent-ops/rules/project/domain/protocol/rules.md @@ -0,0 +1,39 @@ +# protocol + +## 목적 / 책임 + +와이어 포맷 명세와 proto 정의를 관리한다. PacketBase 프레이밍, 타입 라우팅, 요청-응답 상관관계, 하트비트의 공식 계약을 정의한다. + +## 포함 경로 + +- `dart/lib/src/packets/` — proto 원본 및 Dart 생성 코드 (정식 원본) +- `go/packets/` — Go용 proto 복사본 (go_package 옵션만 추가) +- `kotlin/src/**/packets/` — Kotlin용 proto 복사본 (Java 패키지 옵션만 추가) +- `PROTOCOL.md` — 공식 와이어 포맷 명세 +- `VERSIONING.md` — 프로토콜/패키지 버전 정책 + +## 제외 경로 + +- `dart/lib/src/` (packets/ 외) — Dart 구현체 로직 (dart 도메인) +- `go/*.go` (packets/ 외) — Go 구현체 로직 (go 도메인) + +## 주요 구성 요소 + +- `message_common.proto` — PacketBase, 메시지 타입 정의 (Dart 원본) +- `PacketBase` — 모든 패킷의 공통 래퍼 (type_name, payload, correlation_id) + +## 유지할 패턴 + +- proto 원본은 `dart/lib/src/packets/`에서만 편집 +- Go/Kotlin proto는 언어별 옵션만 추가. 메시지 스키마는 건드리지 않는다 +- 변경 후 반드시 `tools/generate_proto.sh` + `tools/check_proto_sync.sh` 실행 + +## 다른 도메인과의 경계 + +- **dart/go/kotlin**: 구현체가 proto 타입을 사용하지만, 타입 정의 자체는 protocol 도메인 +- **tools**: proto 생성/검증 스크립트는 tools 도메인. proto 파일 자체는 protocol 도메인 + +## 금지 사항 + +- proto 파일을 Go/Kotlin 복사본에서 직접 편집하지 않는다 (메시지 스키마 변경은 Dart 원본에서만) +- PROTOCOL.md에 정의되지 않은 프레이밍 방식을 구현체에서 임의로 추가하지 않는다 diff --git a/agent-ops/rules/project/domain/tools/rules.md b/agent-ops/rules/project/domain/tools/rules.md new file mode 100644 index 0000000..0a86c4e --- /dev/null +++ b/agent-ops/rules/project/domain/tools/rules.md @@ -0,0 +1,34 @@ +# tools + +## 목적 / 책임 + +Proto 생성·동기화 스크립트와 크로스 언어 테스트 인프라를 담당한다. 모든 언어 구현체가 공통으로 사용하는 빌드 도구를 관리한다. + +## 포함 경로 + +- `tools/` — proto 생성/검증 스크립트 +- `*/crosstest/` — 각 언어의 크로스 언어 테스트 진입점 + +## 제외 경로 + +- `dart/lib/`, `go/*.go`, `kotlin/src/` — 각 언어 구현체 도메인 + +## 주요 구성 요소 + +- `tools/generate_proto.sh` — 모든 언어용 proto 바인딩 생성 +- `tools/check_proto_sync.sh` — 언어 간 proto 스키마 동기화 검증 + +## 유지할 패턴 + +- proto 변경 후 항상 generate → check_sync 순서로 실행 +- crosstest는 상대 서버가 먼저 시작된 상태에서 클라이언트 측 실행 + +## 다른 도메인과의 경계 + +- **protocol**: 스크립트가 proto 파일을 읽지만, proto 파일 자체는 protocol 도메인 +- **dart/go/kotlin**: crosstest 코드는 각 언어 도메인 경로에 있지만 tools 도메인으로 분류 + +## 금지 사항 + +- `check_proto_sync.sh` 실패를 무시하고 다음 단계로 진행하지 않는다 +- crosstest를 단일 언어 unit test로 대체하지 않는다 diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md new file mode 100644 index 0000000..b0cda54 --- /dev/null +++ b/agent-ops/rules/project/rules.md @@ -0,0 +1,60 @@ +# 프로젝트 규칙 + +## 응답 언어 + +한국어로 응답한다. + +## 프로젝트 개요 + +**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` | diff --git a/agent-ops/skills/project/.gitkeep b/agent-ops/skills/project/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/agent-task/dart_close_fix/code_review_0.md b/agent-task/dart_close_fix/code_review_0.log similarity index 100% rename from agent-task/dart_close_fix/code_review_0.md rename to agent-task/dart_close_fix/code_review_0.log diff --git a/agent-task/dart_close_fix/plan_0.md b/agent-task/dart_close_fix/plan_0.log similarity index 100% rename from agent-task/dart_close_fix/plan_0.md rename to agent-task/dart_close_fix/plan_0.log