178 lines
6.2 KiB
Markdown
178 lines
6.2 KiB
Markdown
# 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`가 읽히게 만들지 않는다.
|
|
- 로컬 모델까지 고려해야 하므로 홉을 늘리지 않는다.
|