# agent-test handoff

## 목적

다음 작업에서 `agent-test` 구조 설계를 이어갈 수 있도록 현재 논의와 결론을 빠짐없이 남긴다.

## 배경

- 여러 프로젝트에 테스트 환경과 검증 기준이 분산되어 있어 정형화가 필요하다.
- `../iop` 프로젝트에는 현재 `agent-ops/rules/project/domain/testing/rules.md`와 `agent-ops/rules/private/testing-env.md` 형태로 테스트 기준과 로컬 환경값이 관리되고 있다.
- 처음에는 `testing`을 domain rule로 보거나 `agent-test/rules.md` 같은 공통 test rule 파일을 두는 방향을 검토했다.
- 사용자는 테스트 환경 선언을 domain rule이 아니라 더 큰 단계/축으로 보고 있으며, `agent-ops/` 내부가 아니라 `agent-roadmap`, `agent-task`처럼 루트의 별도 디렉터리로 관리하길 원한다.
- 루트 디렉터리 이름은 `agent-test`로 결정했다.

## 핵심 제약

- 공통 진입점은 최대한 얇아야 한다.
- 테스트 관련 내용이 세션 시작부터 항상 컨텍스트에 올라오면 안 된다.
- 테스트 관련 작업일 때만 조건부로 읽어야 한다.
- 홉이 많아지면 작은 모델이나 로컬 모델이 지침을 놓칠 수 있으므로 중간 router 파일을 만들지 않는다.
- 역할별로 파일을 예쁘게 세분화하는 것보다, 읽힘과 준수 가능성이 우선이다.
- 같은 내용 반복이 있더라도 각 환경 파일이 self-contained인 편이 낫다.
- 환경은 실제 존재하는 것만 공통 진입점에 줄 단위로 추가한다.
- 로컬 환경 선언은 git ignore 대상이어야 한다.

## 최종 방향

`agent-test/rules.md`는 만들지 않는다.

공통 진입점에는 test 공통 rule이나 test router를 두지 않고, 환경별 라우팅 줄만 둔다.

예시:

```md
# 테스트

- local 테스트, 로컬 모델, 개인 CLI, 작업 완료 검증을 local 기준으로 판단할 때는 `agent-test/local.md`를 반드시 읽는다.
- dev 테스트, 공유 개발 환경 검증을 판단할 때는 `agent-test/dev.md`를 반드시 읽는다.
- qa 테스트, 릴리즈 전 검증을 판단할 때는 `agent-test/qa.md`를 반드시 읽는다.
- 테스트 환경이 명시되지 않으면 `agent-test/local.md`를 기본으로 읽는다.
```

prod 환경이 실제로 필요해질 때만 아래 한 줄을 추가한다.

```md
- prod 테스트, 운영 환경 검증을 판단할 때는 `agent-test/prod.md`를 반드시 읽는다.
```

## 디렉터리 구조

최소 구조:

```text
agent-test/
  local.md
  dev.md
  qa.md
```

prod가 생기면:

```text
agent-test/
  local.md
  dev.md
  qa.md
  prod.md
```

만들지 않을 것:

```text
agent-test/rules.md
agent-test/env/
agent-test/profiles/
agent-test/matrix.md
```

위 파일과 디렉터리는 현재 단계에서는 홉과 분산을 늘리므로 만들지 않는다.

## 환경 파일 원칙

- 각 환경 파일은 자기 환경에 필요한 테스트/검증 기준을 반복해서라도 자체 포함한다.
- 다른 `agent-test` 파일을 추가로 읽어야 이해되는 구조로 만들지 않는다.
- 공통 검증 기준이 조금 반복되더라도 환경 파일 안에 직접 적는다.
- local/dev/qa/prod 등 환경 수만큼 파일을 둔다.
- 환경이 없으면 파일도 만들지 않는다.
- 환경별 실제값, 명령, endpoint, 로컬 모델, CLI 로그인 상태, blocker 기준은 해당 환경 파일에 둔다.

## local 파일

`agent-test/local.md`는 local 테스트, 로컬 모델, 개인 CLI, 환경 미지정 테스트 검증의 기본 파일이다.

예시:

```md
# local test

## 읽기 조건

local 테스트, 로컬 모델, 개인 CLI, 또는 환경 미지정 테스트 검증을 판단할 때 이 파일을 읽는다.

## 검증 기준

- 작업 완료 검증은 변경 범위 기준으로 판단한다.
- 실행하지 못한 필수 검증은 생략하지 말고 blocker로 보고한다.
- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.

## 환경

- model endpoint:
- external cli:
- docker:
- gpu:

## 명령

- unit:
- smoke:
- e2e:
- local-model:
```

## git ignore

로컬 환경값은 git ignore 대상이어야 한다.

권장:

```gitignore
agent-test/local.md
```

필요하면 실행 로그도 ignore한다.

```gitignore
agent-test/runs/
```

dev/qa/prod 파일을 tracked로 둘지 ignore할지는 프로젝트 운영 방식에 따라 결정한다. 단, 실제 secret/token이 들어가는 파일은 추적하지 않는다.

## agent-ops common rule에 넣을 위치

`agent-ops/rules/common/rules.md`의 상단 공통 규칙들 아래, 세션 최초 로딩 목록보다 앞에 `# 테스트` 섹션을 짧게 둔다.

중요한 점:

- `agent-test/**`를 세션 최초 목록에 넣지 않는다.
- `agent-test/rules.md`를 만들거나 읽으라고 하지 않는다.
- 테스트 환경별 라우팅 줄만 둔다.
- 환경이 추가되면 줄만 추가한다.

샘플:

```md
# 테스트

- local 테스트, 로컬 모델, 개인 CLI, 작업 완료 검증을 local 기준으로 판단할 때는 `agent-test/local.md`를 반드시 읽는다.
- dev 테스트, 공유 개발 환경 검증을 판단할 때는 `agent-test/dev.md`를 반드시 읽는다.
- qa 테스트, 릴리즈 전 검증을 판단할 때는 `agent-test/qa.md`를 반드시 읽는다.
- 테스트 환경이 명시되지 않으면 `agent-test/local.md`를 기본으로 읽는다.
```

## 다음 작업 후보

1. `agent-ops/rules/common/rules.md`에 위 테스트 섹션을 추가한다.
2. `agent-test/` 디렉터리와 필요한 환경 파일만 만든다.
3. `.gitignore`에 local 환경 파일 ignore 규칙을 추가한다.
4. README 또는 GUIDE에는 큰 설명보다 `agent-test`의 존재와 적용 원칙만 짧게 반영한다.
5. `../iop`의 기존 testing/private 구조는 새 `agent-test` 설계의 pilot 사례로 보고, 이후 별도 작업에서 이관한다.

## 주의

- 다시 `agent-test/rules.md`를 제안하지 않는다.
- `env/`, `profiles/`, `matrix.md` 분리를 기본안으로 제안하지 않는다.
- 공통 진입점에 긴 test rule을 넣지 않는다.
- 테스트 관련 작업이 아닐 때 `agent-test`가 읽히게 만들지 않는다.
- 로컬 모델까지 고려해야 하므로 홉을 늘리지 않는다.