iop/agent-test/dev/rules.md

test_env	last_rule_updated_at
dev	2026-06-12

dev 테스트 규칙

현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다. dev 테스트 환경은 local 테스트 조건을 그대로 따르되, 같은 원격 host에서 local/test stack과 공존하도록 host publish 포트와 compose project/network를 분리한다.

공통 규칙

• dev 테스트/검증은 이 파일을 기준으로 판단한다.
• 작업 완료 검증은 변경 범위 기준으로 선택한다.
• 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
• 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
• 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
• token/secret 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다.
• 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose networks, IPAM subnet, static IPv4, extra_hosts, host publish 문서 어디에도 192.168.0.0/24 (192.168.0.X) 대역을 사용하지 않는다.
• 새 Docker 테스트 subnet이 필요하면 기존 프로젝트 포트/네트워크 표준을 먼저 따르고, 불가피한 경우 host LAN/VPN과 충돌하지 않는 192.168.0.0/24 밖의 private subnet만 사용한다.

기본 환경

• host: dev runtime evidence는 원격 runner ssh toki@toki-labs.com의 /Users/toki/agent-work/iop-dev 기준으로 수행한다.
• repo root: 명령은 원격 checkout /Users/toki/agent-work/iop-dev 기준으로 실행한다.
• sync 기준: 원격 runner를 사용하는 경우 local uncommitted 변경은 원격 repo에 자동 반영되지 않는다. 동기화되지 않았으면 현재 변경분 검증으로 보지 않는다.
• env file: dev stack은 docker compose --env-file .env.dev.example ...로 명시한다.
• compose identity: COMPOSE_PROJECT_NAME=iop-dev-agent, IOP_COMPOSE_NETWORK=iop-dev-agent-net.
• port: web/dev preview 13001, Control Plane HTTP 18001, Portal/Control Plane wire test endpoint 19001, CP-Edge wire 19002, Edge-Node TCP transport 19003, Postgres host publish 15401, Redis host publish 16301.
• optional dev field ports: artifact/bootstrap HTTP 18082, Edge OpenAI-compatible HTTP 18083, Edge metrics 19101. 이 값은 compose 기본 stack에 publish되지 않으며 field/bootstrap 또는 Edge direct dev profile이 필요할 때만 사용한다.
• runtime: Go quick check는 local toolchain을 우선한다. Flutter client 포함 검증과 Docker/code-server/full-cycle runtime은 원격 runner를 사용한다.
• package manager: Go modules / Makefile / Flutter pub
• docker: 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않는다. Docker compose 검증은 원격 runner 또는 code-server 환경에서 수행한다.
• external service: dev compose Control Plane HTTP http://toki-labs.com:18001, dev Client wire ws://toki-labs.com:19001/client.
• model endpoint: dev Edge OpenAI-compatible profile을 별도로 띄우는 경우 http://toki-labs.com:18083/v1.
• credential: token/secret 원문은 문서에 기록하지 않는다.

포트 매핑

용도	local/test	dev
Web preview	13000	13001
Control Plane HTTP	18000	18001
CP Client WS	19080	19001
CP-Edge wire	19081	19002
Edge-Node TCP	19090	19003
Edge artifact/bootstrap	18080	18082
Edge OpenAI-compatible	18081	18083
Edge metrics	19092	19101
PostgreSQL host publish	15400	15401
Redis host publish	16300	16301

라우팅

• node / smoke / node 실행 파이프라인 baseline: agent-test/dev/node-smoke.md
• edge / smoke / edge 실행 그룹과 입력 표면 baseline: agent-test/dev/edge-smoke.md
• control-plane / smoke / control-plane health와 wire baseline: agent-test/dev/control-plane-smoke.md
• client / smoke / Flutter client와 IOP console package baseline: agent-test/dev/client-smoke.md
• platform-common / smoke / 공통 설정과 protobuf 계약 baseline: agent-test/dev/platform-common-smoke.md
• testing / smoke / 테스트 도구와 full-cycle 검증 baseline: agent-test/dev/testing-smoke.md

라우팅 규칙

• 여러 항목이 맞으면 모두 읽는다.
• 도메인 매핑이나 domain rule이 있으면 각 도메인의 <domain>-smoke 문서를 기본 baseline으로 둔다.
• 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다.
• 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.