From f33b13899083fe83a7e99b595a3e53a0710f9ce6 Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 30 May 2026 04:34:56 +0900 Subject: [PATCH] update rules and version --- AGENT_TEST_HANDOFF.md | 178 ++++++++++++++++++++++++++++++++ agent-ops/.version | 2 +- agent-ops/rules/common/rules.md | 13 ++- 3 files changed, 187 insertions(+), 6 deletions(-) create mode 100644 AGENT_TEST_HANDOFF.md diff --git a/AGENT_TEST_HANDOFF.md b/AGENT_TEST_HANDOFF.md new file mode 100644 index 0000000..2849c35 --- /dev/null +++ b/AGENT_TEST_HANDOFF.md @@ -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`가 읽히게 만들지 않는다. +- 로컬 모델까지 고려해야 하므로 홉을 늘리지 않는다. diff --git a/agent-ops/.version b/agent-ops/.version index 4a3a6e6..e6b36d1 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.85 +1.1.87 diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index 0a31a39..48c6dad 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -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`