From 7e8df53ae0b65200934dd0da053dc5faeb9b396c Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 2 May 2026 20:19:47 +0900 Subject: [PATCH] docs: add agent-ops project rules and edge domain rule - Add agent-ops/rules/project/rules.md with project overview, domain mapping, skill routing - Add agent-ops/rules/project/domain/edge/rules.md for edge domain --- agent-ops/rules/project/domain/edge/rules.md | 48 ++++++++++++++ agent-ops/rules/project/domain/node/rules.md | 54 +++++++++++++++ .../project/domain/platform-common/rules.md | 55 ++++++++++++++++ agent-ops/rules/project/rules.md | 66 +++++++++++++++++++ 4 files changed, 223 insertions(+) create mode 100644 agent-ops/rules/project/domain/edge/rules.md create mode 100644 agent-ops/rules/project/domain/node/rules.md create mode 100644 agent-ops/rules/project/domain/platform-common/rules.md create mode 100644 agent-ops/rules/project/rules.md diff --git a/agent-ops/rules/project/domain/edge/rules.md b/agent-ops/rules/project/domain/edge/rules.md new file mode 100644 index 0000000..61b4807 --- /dev/null +++ b/agent-ops/rules/project/domain/edge/rules.md @@ -0,0 +1,48 @@ +# edge + +## 목적 / 책임 + +외부 API gateway로 발전할 앱 영역이며, 현재는 node 연결을 수락하고 capability를 조회하여 registry에 등록하는 TCP/protobuf 서버 책임을 가진다. + +## 포함 경로 + +- `apps/edge/cmd/iop-edge/` — edge CLI 진입점과 serve 커맨드 +- `apps/edge/internal/bootstrap/` — fx 의존성 주입과 서버 시작/종료 lifecycle +- `apps/edge/internal/node/` — 연결된 node registry와 node 선택 +- `apps/edge/internal/transport/` — node 연결 수락, capability 요청, run event 수신 +- `apps/edge/README.md` — edge 계획과 현재 placeholder 범위 + +## 제외 경로 + +- `apps/node/` — 실제 모델 실행과 adapter 관리 +- `apps/control-plane/` — 노드 등록/정책/스케줄링 예정 영역 +- `apps/worker/` — 비동기 작업 처리 예정 영역 +- `packages/` — 공통 설정/관측성/인증 패키지 +- `proto/` — 메시지 계약 원본과 생성물 + +## 주요 구성 요소 + +- `transport.Server` — proto-socket TCP 서버 wrapper +- `node.Registry` — 연결된 node의 `NodeEntry` 저장/조회 +- `node.NodeEntry` — node ID, TCP client, adapter capability 정보 +- `bootstrap.Module` — edge 서버와 metrics lifecycle 구성 + +## 유지할 패턴 + +- edge는 node 연결 상태와 capability를 registry에 반영하는 역할을 먼저 안정화한다. +- 외부 OpenAI-compatible HTTP API는 node/transport 안정화 이후 확장한다. +- 연결 직후 capability request를 보내고 실패 시 연결을 정리하는 흐름을 유지한다. +- registry는 동시성 안전성을 유지하고 외부로 내부 map을 노출하지 않는다. + +## 다른 도메인과의 경계 + +- **node**: edge는 node를 실행하지 않는다. node capability를 기반으로 요청을 보낼 대상만 선택한다. +- **platform-common**: edge 설정, metrics, protobuf 타입은 platform-common 계약을 따른다. +- **control-plane 후보**: 장기적으로 노드 등록/정책/스케줄링이 control-plane으로 분리될 수 있으므로 edge에 해당 책임을 굳히기 전에 경계를 재검토한다. + +## 금지 사항 + +- edge를 구현하면서 node adapter 실행 로직을 복제하지 않는다. +- OpenAI-compatible HTTP API를 추가할 때 내부 TCP/protobuf 경계를 우회하지 않는다. +- gRPC 또는 WebSocket을 기본 내부 transport로 바꾸지 않는다. +- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다. diff --git a/agent-ops/rules/project/domain/node/rules.md b/agent-ops/rules/project/domain/node/rules.md new file mode 100644 index 0000000..0f42b90 --- /dev/null +++ b/agent-ops/rules/project/domain/node/rules.md @@ -0,0 +1,54 @@ +# node + +## 목적 / 책임 + +디바이스당 1개 실행되는 IOP 노드 에이전트 영역이다. edge에서 들어온 실행 요청을 runtime 요청으로 변환하고, 라우팅된 어댑터를 실행하며, 실행 이벤트와 이력을 관리한다. + +## 포함 경로 + +- `apps/node/cmd/iop-node/` — node CLI 진입점과 서브커맨드 +- `apps/node/internal/bootstrap/` — fx 의존성 주입과 adapter registry 구성 +- `apps/node/internal/node/` — transport handler 구현과 실행 오케스트레이션 +- `apps/node/internal/runtime/` — node 도메인 타입과 핵심 인터페이스 +- `apps/node/internal/router/` — RunRequest를 ExecutionSpec으로 해석하는 라우팅 +- `apps/node/internal/transport/` — edge와의 TCP/protobuf 세션 및 메시지 처리 +- `apps/node/internal/adapters/` — mock/ollama/vllm/cli 실행 어댑터 +- `apps/node/internal/store/` — SQLite 실행 이력 저장 + +## 제외 경로 + +- `apps/edge/` — node를 받아들이는 gateway 서버 영역 +- `apps/control-plane/` — 노드 등록/정책/스케줄링 예정 영역 +- `apps/worker/` — 비동기 작업 처리 예정 영역 +- `packages/` — 여러 앱이 공유하는 공통 패키지 +- `proto/` — 앱 간 메시지 계약 + +## 주요 구성 요소 + +- `runtime.Adapter` — 모델/CLI 실행 어댑터 계약 +- `runtime.Router` — 실행 요청을 구체적인 `ExecutionSpec`으로 변환하는 계약 +- `node.Node` — `transport.Handler` 구현체이자 실행 파이프라인 조정자 +- `transport.Session` — edge와 연결된 node 세션 및 실행 취소 함수 관리 +- `adapters.Registry` — 사용 가능한 node 어댑터 등록/조회 +- `store.Store` — 실행 상태와 결과 저장 + +## 유지할 패턴 + +- `runtime` 패키지에는 도메인 타입과 인터페이스를 두고 구체 구현 의존성을 넣지 않는다. +- transport/proto 타입은 `node.Node` 경계에서 runtime 타입으로 변환한다. +- 어댑터 추가 시 `runtime.Adapter`를 구현하고 bootstrap registry에 등록한다. +- 실행 취소는 run ID 기준으로 세션에 등록하고 실행 종료 시 반드시 해제한다. +- node 내부 변경은 가능한 대상 패키지 테스트를 먼저 추가하거나 갱신한다. + +## 다른 도메인과의 경계 + +- **edge**: edge는 node 연결 등록과 capability 조회/라우팅 진입을 담당한다. node는 edge가 보낸 실행 요청을 처리하고 이벤트를 돌려준다. +- **platform-common**: node는 `packages/config`, `packages/observability`, `proto/gen/iop` 등을 사용하지만 공통 타입/설정 자체의 소유자는 platform-common이다. +- **control-plane 후보**: 정책/스케줄링의 시스템 단위 결정은 control-plane에서 다루고, node는 전달받은 실행 단위 수행에 집중한다. + +## 금지 사항 + +- node 도메인 내부에서 gRPC, WebSocket 기본 transport, actor/FSM/plugin framework를 새 기본 구조로 도입하지 않는다. +- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다. +- 새 어댑터 구현을 `node.Node`에 직접 분기문으로 박아 넣지 않는다. +- placeholder 상태인 control-plane/worker 책임을 node에 임시로 흡수하지 않는다. diff --git a/agent-ops/rules/project/domain/platform-common/rules.md b/agent-ops/rules/project/domain/platform-common/rules.md new file mode 100644 index 0000000..49d18ac --- /dev/null +++ b/agent-ops/rules/project/domain/platform-common/rules.md @@ -0,0 +1,55 @@ +# platform-common + +## 목적 / 책임 + +여러 앱이 공유하는 설정, 인증, 정책, 메타데이터, 작업 상태, 관측성, 버전, protobuf 계약을 관리한다. 앱별 구현보다 안정적인 공통 계약과 작은 유틸리티를 제공하는 영역이다. + +## 포함 경로 + +- `packages/auth/` — mTLS 인증 설정 helper +- `packages/config/` — 앱 설정 struct, 기본값, YAML 로딩 +- `packages/jobs/` — 작업 상태와 작업 메타데이터 타입 +- `packages/metadata/` — 공통 metadata map helper +- `packages/observability/` — zap logger와 Prometheus health/metrics 서버 +- `packages/policy/` — 정책 엔진 인터페이스와 passthrough 구현 +- `packages/version/` — 앱 버전 상수 +- `proto/iop/` — protobuf 메시지 계약 원본 +- `proto/gen/iop/` — protobuf 생성물 +- `configs/` — 앱별 설정 예시 + +## 제외 경로 + +- `apps/node/` — node 실행 파이프라인과 adapter 관리 +- `apps/edge/` — gateway 서버와 node registry +- `apps/control-plane/` — control-plane 앱 구현 예정 영역 +- `apps/worker/` — worker 앱 구현 예정 영역 + +## 주요 구성 요소 + +- `config.NodeConfig` / `config.EdgeConfig` — 앱 설정 계약 +- `auth.LoadServerTLS` / `auth.LoadClientTLS` — mTLS TLS config 생성 +- `observability.NewLogger` / `observability.ServeMetrics` — 공통 로깅/메트릭 +- `policy.Engine` — 정책 적용/검증 계약 +- `jobs.Job` — 비동기 작업 상태 모델 +- `proto/iop/*.proto` — 앱 간 메시지 원본 계약 + +## 유지할 패턴 + +- 공통 패키지는 특정 앱의 내부 패키지를 import하지 않는다. +- 설정 struct 필드 변경 시 YAML tag, mapstructure tag, default, `configs/*.yaml` 예시를 함께 확인한다. +- protobuf 계약 변경은 `proto/iop/*.proto`에서 시작하고 `make proto`로 생성물을 갱신한다. +- 생성 파일(`proto/gen/iop/*.pb.go`)은 사람이 직접 편집하지 않는다. +- 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다. + +## 다른 도메인과의 경계 + +- **node**: node가 필요로 하는 설정/타입/계약을 제공하지만 실행 파이프라인의 소유자는 node이다. +- **edge**: edge가 필요로 하는 설정/관측성/protobuf 계약을 제공하지만 gateway 동작의 소유자는 edge이다. +- **control-plane/worker 후보**: 두 앱이 구현되면 필요한 공통 타입만 이 영역으로 승격하고 앱 내부 책임은 각 도메인에 둔다. + +## 금지 사항 + +- `packages`에서 `apps/*/internal` 패키지를 import하지 않는다. +- 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다. +- protobuf 생성물을 직접 수정하지 않는다. +- 설정 파일만 바꾸고 `packages/config`의 로딩/default와 불일치하게 두지 않는다. diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md new file mode 100644 index 0000000..c9e1f88 --- /dev/null +++ b/agent-ops/rules/project/rules.md @@ -0,0 +1,66 @@ +# go-iop 프로젝트 규칙 + +## 응답 언어 + +- 기본 응답은 한국어로 한다. +- 코드, 명령어, 에러 메시지, 식별자는 원문을 유지한다. + +## 프로젝트 개요 + +- IOP(Inference Operations Platform)는 분산 AI 모델 추론 워크로드를 처리하는 Go 모노레포이다. +- 현재 1차 구현 중심은 `apps/node`이며, `apps/edge`는 node 연결/레지스트리/transport가 일부 구현되어 있다. +- `apps/control-plane`과 `apps/worker`는 README와 CLI placeholder 수준이므로, 본격 구현 전 별도 domain rule을 만들거나 갱신한다. + +## 주요 구조 + +- `apps/node/` — 디바이스별 노드 에이전트. 런타임 라우팅, 어댑터 실행, edge 연결, 실행 이력 저장을 담당한다. +- `apps/edge/` — node 연결을 받아 등록하고 capability를 조회하는 gateway 서버 영역이다. +- `apps/control-plane/` — 노드 등록, 정책, 스케줄링 예정 영역이다. 현재 placeholder이다. +- `apps/worker/` — 비동기 작업 처리 예정 영역이다. 현재 placeholder이다. +- `packages/` — 설정, 인증, 정책, 메타데이터, 작업, 관측성, 버전 등 공통 패키지이다. +- `proto/iop/` — IOP 메시지 계약 원본이다. +- `proto/gen/iop/` — protobuf 생성물이다. +- `configs/` — 앱별 YAML 설정 예시이다. +- `docs/` — 아키텍처 및 운영 방향 문서이다. + +## 기술 스택 + +- 언어/모듈: Go `1.24`, module `iop` +- CLI: `github.com/spf13/cobra` +- 설정: `github.com/spf13/viper`, YAML +- DI: `go.uber.org/fx` +- 로깅: `go.uber.org/zap` +- 메트릭/헬스: Prometheus HTTP handler +- 저장소: `modernc.org/sqlite` +- 메시지 계약: `google.golang.org/protobuf`, `proto/iop/*.proto` +- 내부 소켓: `git.toki-labs.com/toki/common-proto-socket/go` + +## 프로젝트 특화 컨벤션 + +- 기존 hexagonal 구조를 유지한다. 특히 `apps/node/internal/runtime` 인터페이스를 중심에 두고 transport/adapters/store는 바깥쪽 구현으로 둔다. +- 새 node 어댑터는 `runtime.Adapter`를 구현하고 `apps/node/internal/bootstrap/module.go`에서 registry에 등록한다. +- 내부 통신은 TCP 기반 protobuf 메시지 흐름을 우선한다. gRPC 도입, WebSocket 기본 transport 전환, actor/FSM/plugin framework 도입은 금지한다. +- protobuf 계약 변경 시 `proto/iop/*.proto`를 먼저 수정하고 `make proto`로 `proto/gen/iop/*.pb.go`를 갱신한다. 생성 파일은 직접 수정하지 않는다. +- 앱 설정 구조 변경 시 `packages/config`의 struct/default와 `configs/*.yaml` 예시를 함께 확인한다. +- 테스트는 변경 범위에 맞춰 `go test ./...` 또는 대상 패키지 테스트를 실행한다. +- `packages/protocol`은 README에 언급되어 있지만 현재 디렉터리가 없으므로, 생성이 필요하면 실제 책임 경계를 먼저 확정한다. + +## 도메인 매핑 + +| 경로 패턴 | 도메인 | rules.md | +|----------|--------|----------| +| `apps/node/**` | node | `agent-ops/rules/project/domain/node/rules.md` | +| `apps/edge/**` | edge | `agent-ops/rules/project/domain/edge/rules.md` | +| `packages/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` | +| `proto/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` | +| `configs/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` | + +## 도메인 후보 + +- `control-plane`: `apps/control-plane/**`가 placeholder를 넘어 노드 등록, 정책, 스케줄링을 구현하기 시작할 때 생성한다. +- `worker`: `apps/worker/**`가 placeholder를 넘어 작업 큐 소비/재시도/결과 저장을 구현하기 시작할 때 생성한다. + +## 스킬 라우팅 + +- 현재 프로젝트 전용 skill은 만들지 않는다. +- 반복 작업이 확인되면 `agent-ops/skills/project//SKILL.md`를 생성하고 이 표에 등록한다.