update rules and version
This commit is contained in:
parent
30447882f1
commit
f33b138990
3 changed files with 187 additions and 6 deletions
178
AGENT_TEST_HANDOFF.md
Normal file
178
AGENT_TEST_HANDOFF.md
Normal file
|
|
@ -0,0 +1,178 @@
|
|||
# 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`가 읽히게 만들지 않는다.
|
||||
- 로컬 모델까지 고려해야 하므로 홉을 늘리지 않는다.
|
||||
|
|
@ -1 +1 @@
|
|||
1.1.85
|
||||
1.1.87
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# 공통 규칙
|
||||
|
||||
- **현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
|
||||
**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
|
||||
|
||||
- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
|
||||
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
|
||||
- 요청 범위를 넘는 변경을 하지 않는다.
|
||||
|
|
@ -9,7 +10,6 @@
|
|||
- `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다.
|
||||
- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다.
|
||||
- tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다.
|
||||
- 환경별 값(host/port/token/compose/runbook)은 `agent-ops/rules/private/`에 두고, `rules.md`는 라우터로만 쓴다.
|
||||
|
||||
**세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다.
|
||||
|
||||
|
|
@ -19,10 +19,7 @@
|
|||
|
||||
# 프로젝트 간 잠금
|
||||
|
||||
- 프로젝트 상위 폴더에 `.agent-roadmap-sync/locks.yaml`이 있으면 프로젝트 간 Milestone 잠금 인덱스로 본다.
|
||||
- 외부 의존 잠금 생성/동기화 요청은 `.agent-roadmap-sync/locks.yaml`이 없어도 `update-roadmap`이 생성한다.
|
||||
- "이 Milestone은 X가 끝나야 가능하다", "A 전까지 B를 잠근다", "잠금 해제 조건은 X다", "현재 마일스톤은 X 프로젝트 작업 뒤에 진행되어야 한다", "의존성 설정해"는 `update-roadmap`으로 처리한다.
|
||||
- `plan`과 `code-review`는 `.agent-roadmap-sync`를 읽거나 갱신하지 않는다.
|
||||
|
||||
# 스킬 규칙
|
||||
|
||||
|
|
@ -37,3 +34,9 @@
|
|||
- 코드 리뷰 / review 진행
|
||||
- git commit / push
|
||||
- agent-ops 업데이트 / 진입 파일 재적용
|
||||
|
||||
# 테스트 규칙
|
||||
|
||||
**테스트 관련 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.**
|
||||
|
||||
- local: `agent-test/local/rules.md`
|
||||
|
|
|
|||
Loading…
Reference in a new issue