toki/agent-shell
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agent-shell/agent-ops/skills/common/update-test/SKILL.md

10 KiB
Raw Permalink Blame History

name description
update-test 기존 agent-test 환경 rules.md 또는 테스트 profile을 수정하고 파일 수정 없는 Verification Context를 제공한다. 테스트 규칙 수정·갱신, 테스트 컨텍스트 해석, Verification Context 생성 요청에 사용한다.

update-test

목적

기존 agent-test/<env>/rules.md 또는 agent-test/<env>/<test-profile>.md를 최신 테스트 기준에 맞게 갱신한다. 라우팅은 3홉 안에 유지하고, 도메인/검증 시나리오별 문서는 자체 완결되게 보완한다. resolve-context 모드에서는 해당 문서를 수정하지 않고 현재 task에 적용할 명령, 판정 기준, 제약, 외부 환경 preflight를 중립 Verification Context로 반환한다.

test-case는 기존 호출과의 호환을 위한 alias이며, 새 문서 기준 이름은 test-profile이다.

언제 호출할지

  • 기존 테스트 환경 규칙을 수정할 때
  • 도메인/검증 시나리오별 테스트 기준, 명령, 판정 기준을 보완할 때
  • 테스트 라우팅을 추가, 제거, 정리할 때
  • plan 또는 다른 소비자가 구현 범위에 맞는 테스트 환경/profile 정보를 필요로 할 때

입력

  • mode: update 또는 resolve-context. 기본값은 update (선택)
  • env: local, dev, qa, prod 중 하나. 기본값은 local (선택)
  • test-profile: 수정할 도메인/검증 시나리오별 테스트 문서 이름, kebab-case (선택)
  • test-case: test-profile의 호환 alias (선택)
  • domain: 대상 도메인 이름, kebab-case (선택)
  • change: 수정할 내용 요약. mode=update에서 필수 (선택)
  • task-summary: 검증할 동작과 완료 조건 요약. mode=resolve-context에서 필수 (선택)
  • scope-paths: 변경 후보 source/test 경로 목록. mode=resolve-context에서 선택
  • verification-type: 예: unit, smoke, integration, e2e. mode=resolve-context에서 선택

먼저 확인할 것

  • agent-ops/rules/common/rules.md의 스킬 규칙과 테스트 규칙이 분리되어 있는지 확인한다.
  • agent-ops/skills/common/router.md에 update-test 라우팅이 있는지 확인한다.
  • test-case가 있고 test-profile이 없으면 test-profile로 취급한다.
  • mode=update이면 change가 있는지, mode=resolve-context이면 task-summary가 있는지 확인한다.
  • agent-test/<env>/rules.md 존재 여부를 확인한다. mode=update에서 없으면 create-test 대상으로 보고 중단하고, mode=resolve-context에서는 rules_state: missing으로 반환한다.
  • agent-test/<env>/rules.md가 있으면 읽는다.
  • test-profile이 있으면 agent-test/<env>/<test-profile>.md 존재 여부를 확인한다. mode=update에서 없으면 create-test 대상으로 보고 중단하고, mode=resolve-context에서는 gap으로 기록한다.
  • test-profile 문서가 있으면 읽는다.
  • test-profile이 없으면 domain, change, task-summary, scope-paths, verification-type을 env rules의 ## 라우팅과 대조해 모든 matching profile을 찾는다.
  • 템플릿 구조 확인이 필요하면 agent-ops/rules/common/_templates/의 테스트 템플릿을 읽는다.
  • 기존 라우팅이 3홉 안에 있는지 확인한다.

실행 절차

  1. 모드 확정
    • mode=resolve-context이면 아래 resolve-context 절차만 수행하고 파일, .gitignore, last_rule_updated_at을 수정하지 않는다.
    • mode=update이면 아래 update 절차를 수행한다.

update 절차

  1. 대상 확정

    • 환경 공통 규칙 변경이면 agent-test/<env>/rules.md만 수정한다.
    • 특정 도메인/검증 기준 변경이면 해당 test-profile 문서를 수정한다.
    • 특정 대상이 암시되지만 라우팅에서 찾지 못하면 생성하지 말고 create-test 대상이라고 보고한다.
    • 대상 문서가 없으면 생성하지 말고 create-test 대상이라고 보고한다.

  2. 문서 갱신

    • 기존 환경값, 명령, 금지 사항을 보존한다.
    • 오래된 기준은 새 기준으로 교체하고 같은 뜻의 중복 문장은 줄인다.
    • 도메인/검증 시나리오별 문서는 읽기 조건, 적용 범위, 명령, 필수 검증, 판정 기준, 차단 기준을 자체 포함하게 유지한다.
    • last_rule_updated_at은 수정일 YYYY-MM-DD로 갱신한다.

  3. 라우팅 갱신

    • env rules의 ## 라우팅은 도메인/검증 시나리오별 문서로만 향하게 한다.
    • 맞지 않는 라우팅은 제거하거나 더 정확한 domain / verification-type / scope 설명으로 바꾼다.
    • 도메인/검증 시나리오별 문서에서 다른 테스트 문서로 이어지는 라우팅은 제거한다.
    • 공통룰에서 스킬 최종 진입까지의 경로는 rules.md -> router.md -> update-test/SKILL.md로 유지한다.

  4. local 추적 제외 확인

    • env가 local이면 .gitignore에 agent-test/local/과 agent-test/runs/가 있는지 확인하고 없으면 추가한다.

  5. 결과 보고

    • 수정한 파일
    • 바꾼 라우팅
    • 보존한 환경값
    • 남은 확인 필요 항목

resolve-context 절차

  1. 환경 규칙 상태 판정

    • env rules를 missing, blank-skeleton, structured-incomplete, usable 중 하나로 판정한다.
    • missing 또는 blank-skeleton이어도 생성하거나 보완하지 않는다.
    • 실제 파일에 없는 명령, endpoint, credential, 판정 기준을 추측하지 않는다.

  2. matching profile 해석

    • 명시된 test-profile 또는 env rules의 ## 라우팅에서 domain / verification-type / scope가 맞는 모든 profile을 선택한다.
    • 매칭 근거가 없는 profile은 읽거나 반환하지 않는다.
    • route가 가리키는 profile이 없거나 구조적으로 비어 있으면 gap으로 기록한다.

  3. 검증 사실 추출

    • env rules와 matching profile에서 실행 위치, 명령, 필수 순서, 기대 결과, 차단 기준, cache 허용 여부, 외부 서비스/secret 요구 여부를 원문 의미를 바꾸지 않고 추출한다.
    • 명령이 여러 profile에 걸치면 profile별 출처와 적용 범위를 유지한다.
    • <확인 필요> 또는 서로 충돌하는 값은 확정하지 않고 gap으로 기록한다.
    • env rules와 matching profile이 usable이고 적용 명령·판정 기준에 gap이 없으면 confidence를 high, 일부 값에 repository-native 확인이 더 필요하면 medium, rules가 missing/blank이거나 핵심 값이 unresolved이면 low로 판정한다.

  4. 외부 환경 preflight 구성

    • 현재 checkout 밖의 runner, field/bootstrap, external provider, Docker/code-server, emulator/device, shared runtime이 필요한 검증만 read-only preflight 대상으로 삼는다.
    • env/profile에 적힌 범위 안에서 repo root/workdir, branch/HEAD/dirty state, source sync, binary/artifact, command help/version, config path, runtime identity, ports/process, external host, OS/arch 확인 항목을 구성한다.
    • 안전한 read-only probe를 현재 환경에서 실행할 수 있으면 실제 결과를 반환하고, 실행할 수 없으면 필요한 probe와 blocker를 구분해 반환한다.
    • secret, token, credential 원문은 읽거나 출력하지 않는다.

  5. 중립 handoff 반환

    • 소비 스킬 이름이나 문서 section 이름에 결합하지 않고 아래 출력 형식을 그대로 반환한다.
    • test rule 유지보수는 사용자가 요청했거나 확인된 구조 결함이 있을 때만 create-test 또는 update-test 후보로 표시한다. resolve-context 실행 중 직접 호출하거나 수정하지 않는다.

실행 결과 검증

  • 수정 대상 문서가 여전히 필수 섹션을 포함하는가
  • rules.md -> router.md -> update-test/SKILL.md 경로가 끊기지 않는가
  • env rules 라우팅이 3홉 제한을 넘기지 않는가
  • 도메인/검증 시나리오별 문서가 다른 테스트 문서로 라우팅하지 않는가
  • local 수정 시 .gitignore에 local 경로가 반영되었는가
  • resolve-context에서 파일과 .gitignore를 수정하지 않았는가
  • resolve-context가 읽은 env/profile 경로와 각 명령의 출처를 정확히 반환하는가
  • 외부 검증이 있으면 read-only preflight 결과 또는 실행 불가 blocker가 구분되어 있는가
  • 누락, <확인 필요>, 충돌 값을 확정된 명령이나 기준으로 반환하지 않았는가
  • secret, token, 개인 endpoint 원문이 tracked 파일에 추가되지 않았는가
  • 검증 실패 시: 문제 문서만 다시 보완한다.

출력 형식

## 수정 완료

- 환경: <env>
- 수정 파일: <path>
- 라우팅 변경: <내용 또는 없음>
- 보존한 환경값: <요약>
- 확인 필요: <항목 또는 없음>

mode=resolve-context:

## Verification Context

- Environment: <env>
- Rules State: <missing|blank-skeleton|structured-incomplete|usable>
- Sources Read:
  - <env rules/profile path 또는 없음>
- Scope Match:
  - <domain / verification-type / scope와 매칭 근거 또는 없음>
- Commands:
  - `<command>`: source=`<path>`; scope=`<scope>`; expected=`<result>`; cache=`<allowed|fresh|required|unspecified>`
- Preconditions:
  - <필수 순서, 실행 위치, config/runtime 요구 또는 없음>
- Read-only Preflight:
  - `<probe>`: <PASS|BLOCKED|NOT_RUN>; <actual result or reason>
- Constraints:
  - <금지 사항, 외부 서비스/secret 요구 여부 또는 없음>
- Gaps:
  - <missing profile, blank value, `<확인 필요>`, conflict 또는 없음>
- Confidence: <high|medium|low>; <판정 근거>
- Maintenance: <not-needed|create-test-candidate|update-test-candidate>; <근거>

금지 사항

  • 기존 local 환경값을 추측으로 바꾸지 않는다.
  • 확인되지 않은 테스트 명령을 필수 검증으로 단정하지 않는다.
  • 도메인/검증 시나리오별 문서를 router처럼 쓰지 않는다.
  • resolve-context에서 테스트 문서 생성, 수정, .gitignore 갱신을 수행하지 않는다.
  • resolve-context 출력에 특정 소비 스킬 전용 필드나 파일명을 강제하지 않는다.
  • secret, token, 개인 endpoint 원문을 tracked 파일에 기록하지 않는다.