iop/agent-ops/rules/project/rules.md

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 연결을 받아 token 기반 등록을 처리하고 중앙 설정을 내려주는 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-name>/SKILL.md를 생성하고 이 표에 등록한다.