# 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-name>/SKILL.md`를 생성하고 이 표에 등록한다.