toki/agentic-framework

Fork 0

toki f33b138990 update rules and version

2026-05-30 04:34:56 +09:00

6.2 KiB

Raw Blame History

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를 두지 않고, 환경별 라우팅 줄만 둔다.

예시:

# 테스트

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

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

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

디렉터리 구조

최소 구조:

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

prod가 생기면:

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

만들지 않을 것:

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, 환경 미지정 테스트 검증의 기본 파일이다.

예시:

# local test

## 읽기 조건

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

## 검증 기준

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

## 환경

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

## 명령

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

git ignore

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

권장:

agent-test/local.md

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

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를 만들거나 읽으라고 하지 않는다.
테스트 환경별 라우팅 줄만 둔다.
환경이 추가되면 줄만 추가한다.

샘플:

# 테스트

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

다음 작업 후보

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

주의

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

6.2 KiB Raw Blame History