rara/agent-test/dev/rules.md

---
test_env: dev
last_rule_updated_at: 2026-07-18
---

# dev 테스트 규칙

**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
**dev는 RARA의 기본 테스트 환경이며 local host가 아니라 원격 Mac runner를 기준으로 한다.**

## 공통 규칙

- 사용자가 테스트 환경을 별도로 지정하지 않으면 이 `dev` 환경을 기본 기준으로 삼는다.
- local 검증은 원격 프리플라이트와 source 동기화를 대신하지 않는다.
- 작업 완료 검증은 변경 범위에 맞는 도메인 profile을 선택한다.
- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
- 최종 보고에는 원격 source identity, 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
- secret, token, password, private key, 개인 endpoint 원문은 tracked 파일이나
  shell 출력에 남기지 않는다.
- 원격 서비스는 기본적으로 runner loopback에 bind한다. 외부 공개 검증이 명시된
  경우에만 별도 접근 경계와 방화벽 상태를 확인한다.

## 기본 환경

- host: `ssh toki@toki-labs.com` 표준 원격 Mac runner
- repo root: 목표 checkout `/Users/toki/agent-work/rara-dev`
- checkout 상태: 2026-07-18 점검 시 아직 없음. 최초 원격 검증 전 생성이 필요하다.
- sync 기준: 검증할 exact source commit을 origin에서 fetch한 뒤 clean checkout하고,
  local 변경과 원격 HEAD가 동일한지 확인한다.
- runtime: macOS arm64. 2026-07-18 login shell에서 Go 1.26.3과
  Python 3.12.9(`python3.12`)를 확인했다.
- package manager: Go modules, Python venv/pip
- docker: login shell의 Docker Desktop/Engine 27.4.0을 사용한다. 일반 비대화형
  SSH PATH에는 Go와 Docker가 없으므로 원격 명령은 login shell 또는 검증된 explicit
  PATH로 실행한다.
- external service: readiness·통합 smoke에는 PostgreSQL이 필요하며, 준비되지 않으면
  source test/build까지만 수행하고 통합 검증은 차단으로 보고한다.
- model endpoint: 기본값 없음. adaptation/model 통합 검증 시 별도 승인된 endpoint가 필요하다.
- credential: secret/token/API key 원문은 문서에 기록하지 않는다.

## 포트 매핑

2026-07-18 기준 workspace 원장에 기존 `70` 슬롯 배정이 없고, 원격 runner의 아래
후보 포트가 listen 중이 아님을 확인한 뒤 RARA `dev` 전용으로 배정했다. 실행 직전
동일 검사를 반복한다.

| 용도 | local 호환값 | dev 원격값 | bind 기준 |
|---|---:|---:|---|
| Control Plane HTTP | `18080` | `18070` | `127.0.0.1:18070` |
| RAG API HTTP | `18081` | `18071` | `127.0.0.1:18071` |
| Go Worker HTTP | `18082` | `18072` | `127.0.0.1:18072` |
| Python Executor gRPC | `19090` | `19070` | `127.0.0.1:19070` |
| PostgreSQL host publish | `5432` | `15470` | `127.0.0.1:15470 -> 5432` |
| Frontend reserve | 해당 없음 | `13070` reserved | 현재 RARA runtime에 없음 |
| Cache reserve | 해당 없음 | `16370` reserved | 현재 RARA runtime에 없음 |
| Metrics / diagnostics reserve | 해당 없음 | `19170-19172` reserved | 현재 RARA runtime에 없음 |

- `18080-18099`와 `19080/19090`은 IOP shared field/runtime baseline이므로 RARA
  원격 dev 서비스에 재사용하지 않는다.
- repo의 `configs/*.yaml` 기본 listen 값은 local 호환값이다. 원격 dev에서는
  `RARA_LISTEN`과 `RARA_PYTHON_LISTEN_PORT`로 위 dev 값을 명시한다.
- PostgreSQL host publish가 필요하지 않으면 `15470`을 열지 않고 service와 DB를
  전용 network 또는 loopback으로만 연결한다.

## 런타임 프로필

- source validation: 원격 checkout에서 `make test && make build`를 기본 완료 검증으로 사용한다.
- service smoke: PostgreSQL이 준비된 경우 Control Plane `18070`, RAG API `18071`,
  Go Worker `18072`를 각각 dev override로 실행하고 health/readiness를 확인한다.
- Python executor smoke: `RARA_PYTHON_LISTEN_HOST=127.0.0.1`과
  `RARA_PYTHON_LISTEN_PORT=19070`을 사용한다.
- compose candidate: 향후 remote compose를 추가할 경우
  `COMPOSE_PROJECT_NAME=rara-dev-agent`, network `rara-dev-agent-net`,
  subnet `10.89.7.0/24`, PostgreSQL host publish `15470`을 기준으로 한다.
  2026-07-18 기존 remote Docker network와 subnet이 겹치지 않음을 확인했지만,
  현재 compose에는 dev override와 network 정의가 없으므로 실제 구성으로 간주하지 않는다.
- artifact: runner-local filesystem artifact root를 사용하며 공개 artifact HTTP 포트는 없다.

## 프리플라이트

- 원격 검증 전 runner 접속, `/Users/toki/agent-work/rara-dev` 존재 여부, branch,
  HEAD, dirty 상태, local 변경과 source 동기화 여부를 확인한다.
- login shell에서 `go version`, `python3.12 --version`, `docker version`, 필요한
  tool/version, `.venv`의 Python identity를 확인한다. 기본 `python3`은 2026-07-18
  기준 3.14.6이므로 Python 3.12 venv라고 추정하지 않는다.
- `13070`, `18070-18072`, `15470`, `16370`, `19070`, `19170-19172`가 다른
  process에 점유되지 않았는지 확인한다. 미사용 후보까지 함께 확인해 `70` 슬롯의
  부분 재사용을 방지한다.
- service smoke 전 config path, `RARA_LISTEN`, `RARA_DATABASE_URL`,
  artifact root, process identity를 확인한다.
- Docker daemon과 PostgreSQL container가 실제로 준비되지 않았으면 설치 상태만으로
  통합 검증 가능하다고 추정하지 않고 integration blocker로 보고한다.
- checkout 부재, source 불일치, stale binary, port 점유, runtime version 불일치는
  setup/sync/rebuild 후 해소하거나 차단 사유로 보고한다.

## 노드/서비스 인벤토리 위치

- machine-readable runner·port 기준: `agent-test/dev/inventory.yaml`
- Control Plane 기준: `agent-test/dev/control-plane-smoke.md`
- RAG API 기준: `agent-test/dev/rag-data-plane-smoke.md`
- Go/Python worker 기준: `agent-test/dev/workflow-execution-smoke.md`
- 공통 config·database·artifact·배포 기준: `agent-test/dev/platform-common-smoke.md`

## 반복 테스트 기준

- 원격 evidence는 current source와 동일한 remote checkout에서만 수집한다.
- source test/build와 PostgreSQL 의존 service smoke를 구분해 보고한다.
- 여러 RARA 서비스를 동시에 실행할 때 각 프로세스에 다른 `RARA_LISTEN`을 명시한다.
- test 종료 후 장기 runtime으로 승인되지 않은 프로세스는 정리하고, 포트가 반환됐는지 확인한다.
- secret이 포함될 수 있는 database URL과 외부 endpoint는 값 대신 주입 여부만 보고한다.

## 라우팅

- control-plane / smoke / 수명주기 API와 제어 상태 원격 검증:
  `agent-test/dev/control-plane-smoke.md`
- rag-data-plane / smoke / retrieve·answer 계약 원격 검증:
  `agent-test/dev/rag-data-plane-smoke.md`
- workflow-execution / smoke / Go worker와 Python executor 원격 검증:
  `agent-test/dev/workflow-execution-smoke.md`
- platform-common / smoke / config·database·artifact·배포 원격 검증:
  `agent-test/dev/platform-common-smoke.md`

## 라우팅 규칙

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