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

iop 프로젝트 규칙

응답 언어

• 기본 응답은 한국어로 한다.
• 코드, 명령어, 에러 메시지, 식별자는 원문을 유지한다.

프로젝트 개요

• IOP(Inference Operations Platform)는 Control Plane - Edge - Node 계층 구조를 기반으로 모델 서빙과 CLI Agent/Automation 실행을 함께 다루는 실행 오케스트레이션 모노레포이다. 핵심 서비스는 Go이고 Web Portal은 Next.js 스캐폴드로 둔다.
• 내부 실행 개념은 model 중심이 아니라 adapter + target 중심으로 정리한다. 외부 OpenAI-compatible 경계나 외부 CLI 인자에서는 호환성을 위해 model 표현이 남을 수 있다.
• 현재 1차 구현 중심은 apps/node와 apps/edge의 Edge-Node 실행 스켈레톤이며, CLI adapter, node 등록/레지스트리/transport, edge input surface가 우선 검증되고 있다.
• apps/control-plane은 health/readiness HTTP와 wire endpoint 예약을 가진 scaffold이고, apps/web은 Next.js Portal scaffold이다. 본격 구현 전 별도 domain rule을 만들거나 갱신한다.
• apps/worker는 CLI placeholder 수준이므로 본격 구현 전 별도 domain rule을 만들거나 갱신한다.

주요 구조

• apps/node/ — Edge에 연결되는 실행자. 런타임 라우팅, adapter execution, CLI/model runtime 실행, 현재 단계의 로컬 실행 이력 저장을 담당한다.
• apps/edge/ — 여러 Node를 묶는 백엔드 실행 그룹 컨트롤러. token 기반 등록, node registry, node 설정 전달, routing, stream relay, ops console, OpenAI-compatible/A2A 입력 표면을 담당한다.
• apps/control-plane/ — 향후 여러 Edge를 연결하고 상태 조회/설정 변경/명령 전달/이벤트 수신/운영 제어 API 제공을 담당할 Go 기반 중앙 관리 서버 scaffold이다.
• apps/web/ — IOP 전체 Web Portal을 위한 Next.js scaffold이다.
• apps/worker/ — 비동기 작업 처리 예정 영역이다. 현재 placeholder이다.
• packages/ — 설정, 인증, 이벤트 helper, host setup, 정책, 메타데이터, 작업, 관측성, 버전 등 공통 패키지이다.
• proto/iop/ — IOP 메시지 계약 원본이다.
• proto/gen/iop/ — protobuf 생성물이다.
• configs/ — 앱별 YAML 설정 예시이다.
• bin/ — 사용자가 직접 실행하는 edge/node/web shell entrypoint와 field binary build entrypoint이다.
• scripts/ — 보조 E2E smoke와 입력 표면 검증 스크립트이다.
• Makefile — 빌드와 테스트 진입점을 정의한다.
• docs/ — 아키텍처 및 운영 방향 문서이다.
• agent-ops/roadmap/ — 제품 목표, 단계, 마일스톤의 단일 기준 문서이다.

기술 스택

• 언어/모듈: Go 1.24, module iop
• Web Portal: Next.js 16, React 19, TypeScript, Tailwind CSS
• 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/proto-socket/go

프로젝트 특화 컨벤션

• 기존 hexagonal 구조를 유지한다. 특히 apps/node/internal/runtime 인터페이스를 중심에 두고 transport/adapters/store는 바깥쪽 구현으로 둔다.
• 새 node 어댑터는 runtime.Adapter를 구현하고 apps/node/internal/bootstrap/module.go에서 registry에 등록한다.
• 내부 실행 요청과 상태 저장에서는 adapter, target, execution 용어를 우선한다. model은 외부 API 호환이나 legacy placeholder일 때만 허용한다.
• Control Plane은 Node를 직접 연결/스케줄링하지 않고 Edge를 통해 시스템을 제어한다. Edge는 자신의 로컬 런타임 상태와 Node 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 ./... 또는 대상 패키지 테스트를 실행한다.
• 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 agent-ops/rules/project/domain/testing/rules.md의 검증 기준을 따른다.
• 상세 DB schema, event schema, permission/policy/audit model, federation, mTLS 구현 세부, Portal UI 세부 기획은 각 작업에서 별도로 결정한다.

도메인 룰 로딩

• 아래 도메인 매핑에 해당하는 작업에서 해당 domain 최초 진입 시 domain rule을 1회 읽는다.
• 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다.
• 사용자 실행 파이프라인에 닿는 작업의 검증 단계에서는 testing domain rule을 1회 읽는다.

마일스톤 컨텍스트 로딩

• 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 agent-ops/roadmap/current.md를 먼저 읽는다.
• current.md는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다.
• 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다.
• 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
• 활성 Milestone 밖의 작업이면 agent-ops/roadmap/ROADMAP.md의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
• agent-ops/roadmap/ROADMAP.md는 로드맵 생성/갱신, Phase 전환, 마일스톤 추가/수정 요청이 있을 때만 읽는다.
• 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.

도메인 매핑

경로 패턴	도메인	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
bin/**	testing	agent-ops/rules/project/domain/testing/rules.md
scripts/e2e-*.sh	testing	agent-ops/rules/project/domain/testing/rules.md
Makefile	testing	agent-ops/rules/project/domain/testing/rules.md

도메인 후보

• control-plane: apps/control-plane/**가 scaffold를 넘어 여러 Edge 연결 관리, Edge 상태 조회, Edge 설정 변경, Edge 명령 전달, 이벤트 수신, 운영 제어 API 제공을 구현하기 시작할 때 생성한다.
• web: apps/web/**가 Portal scaffold를 넘어 노드/모델/작업/운영 화면과 Control Plane 통신을 본격 구현하기 시작할 때 생성한다.
• worker: apps/worker/**가 placeholder를 넘어 작업 큐 소비/재시도/결과 저장을 구현하기 시작할 때 생성한다.

스킬 라우팅

• 사용자 실행 파이프라인 검증, bin shell 사용자 흐름, 메시지 2회 왕복, edge command 응답, 보조 E2E smoke, full-cycle 실제 구동, bin/edge.sh/bin/node.sh 통합 테스트: agent-ops/skills/project/e2e-smoke/SKILL.md
• 반복 작업이 확인되면 agent-ops/skills/project/<skill-name>/SKILL.md를 생성하고 이 표에 등록한다.