# agent-test 환경 확장 기준

이 디렉터리는 테스트 환경별 실행 기준과 도메인/검증 시나리오별 profile을 둔다.
새 환경(`qa`, `staging`, `dev-gpu`, `dev-team-a` 등)을 추가할 때는 기존 환경을 임의로 복사하지 말고 이 기준과 `_templates/`를 먼저 따른다.

## 환경 선택 기본값

- 사용자가 테스트 환경을 별도로 지정하지 않으면 기본 테스트/검증 환경은 `dev`다.
- `dev-corp`는 fallback, 자동 탐색 경로, 접근 가능한 대체 runtime이 아니다. 사용자가 `dev-corp`, 회사망 dev-corp, public `iop.ai.kr` Edge, 또는 동등하게 명시한 경우에만 `agent-test/dev-corp/**`를 읽고 접근한다.
- 사용자가 단순히 `dev`, 테스트 환경, 배포, rollout, runtime 검증이라고 말한 경우에는 `agent-test/dev/**` 기준을 사용하고 `dev-corp` host, runner, port에는 접근하지 않는다.

## 환경 디렉터리

- 환경 디렉터리는 `agent-test/<env>/` 형식을 사용한다.
- `<env>`는 소문자 영문, 숫자, 하이픈만 사용한다.
- 각 환경에는 반드시 `agent-test/<env>/rules.md`를 둔다.
- 도메인/검증 시나리오별 문서는 `agent-test/<env>/<test-profile>.md` 형식을 사용한다.
- 기본 도메인 smoke profile은 기존 도메인 이름을 유지해 `node-smoke.md`, `edge-smoke.md`, `control-plane-smoke.md`, `client-smoke.md`, `platform-common-smoke.md`, `testing-smoke.md`처럼 둔다.

## rules.md 표준 섹션

새 `rules.md`는 아래 섹션 순서를 유지한다.

1. `공통 규칙`
2. `기본 환경`
3. `포트 매핑`
4. `런타임 프로필`
5. `프리플라이트`
6. `노드/Provider 인벤토리 위치`
7. `Field/bootstrap 반복 테스트 기준`
8. `라우팅`
9. `라우팅 규칙`

섹션이 해당 환경에 직접 필요하지 않더라도 삭제하지 말고 `없음`, `해당 없음`, 또는 대상 profile 링크를 남긴다.

## 확장 원칙

- 환경 공통값은 `rules.md`에 둔다.
- 실제 노드, provider, bootstrap, model endpoint, workspace, SSH user/IP 같은 상세 인벤토리는 agent가 구조적으로 읽어야 하면 `inventory.yaml`에 두고, 사람용 설명과 도메인별 판정 기준은 해당 도메인 profile에 둔다.
- 상위 `rules.md`에는 상세값을 복제하지 말고 `노드/Provider 인벤토리 위치`와 `라우팅`으로 연결한다.
- compose, native Edge, dev-runtime provider pool처럼 같은 환경 안의 실행 모드는 `런타임 프로필`에서 분리한다.
- 같은 포트 이름은 모든 환경에서 같은 행 이름을 쓴다. 값이 없으면 `해당 없음` 또는 `후보 <port>`로 둔다.
- shared remote runner를 쓰는 환경은 `repo root`, `sync 기준`, `프리플라이트`를 반드시 명시한다.
- secret, token, API key, private credential 원문은 `agent-test/`, `docs/`, `agent-roadmap/`에 기록하지 않는다.
- private IP와 SSH user는 테스트 접속에 필요한 환경값이면 기록할 수 있다. 단, 잘못된 user가 발견되면 해당 env rules/profile과 사람용 guide를 함께 정정한다.
- `agent-test/local/`은 local/private 기준이라 git 추적 제외될 수 있다. 추적 여부와 상관없이 현재 workspace의 운영 기준으로는 같은 구조를 유지한다.

## 새 환경 추가 절차

1. `_templates/env-rules-template.md`를 `agent-test/<env>/rules.md`로 복사한다.
2. `<env>`, 날짜, runner, repo root, 포트, runtime profile을 채운다.
3. agent가 반복해서 읽어야 하는 host/node/provider 값이 있으면 `_templates/inventory-template.yaml`을 사용해 `agent-test/<env>/inventory.yaml`을 만든다.
4. 기존 도메인 smoke profile이 필요하면 `_templates/test-profile-template.md`를 사용해 `agent-test/<env>/<domain>-smoke.md`를 만든다.
5. `rules.md`의 `노드/Provider 인벤토리 위치`와 `라우팅`에 생성한 inventory와 profile을 연결한다.
6. remote runner나 external provider를 쓰면 `프리플라이트`에 확인할 항목을 구체화한다.
7. local/test/dev 등 기존 환경과 공존해야 하면 `포트 매핑`에 충돌하지 않는 값을 기록한다.
8. `rg --no-ignore`로 잘못된 SSH user, workspace, port 재사용, secret 원문이 없는지 확인한다.

## 현재 표준 구현

- `agent-test/local/rules.md`
- `agent-test/dev/rules.md`
- `agent-test/dev-corp/rules.md`