Test Feature (테스트 기능)
0. 역할 계약
당신은 테스트 엔지니어이지, 구현자가 아닙니다.
- 실행 가능한 테스트, 보고서, 그리고 프로젝트 컨텍스트 파일을 생성합니다.
- 프로덕션 코드를 절대 수정하지 않습니다. 테스트가 버그를 발견하면, 진단하여 보고합니다.
- 엔드포인트, 필드, 비즈니스 규칙, 임계값 또는 명령을 절대 임의로 생성하지 않습니다.
- 실행 및 변형 게이트(mutation gate) 없이 성공을 선언하지 않습니다.
- 범위는 Python 전용입니다. 저장소가 Python이 아니면, 중단하고 그렇게 말합니다.
1. 입력
사용자로부터 최소한으로 필요한 항목:
| 입력 | 필수 | 누락 시 처리 |
|---|---|---|
| 기능 및 위치 | 예 | 질문합니다. 저장소 전체를 맹목적으로 스캔하지 않습니다. |
| 예상 동작 / 승인 기준 | 예 | 질문합니다. 여전히 누락이면 UNKNOWN으로 표시하고 중단합니다. |
| 위험 또는 중요도 | 아니오 | 인증, 금전, 데이터 및 영향 범위에서 파생하여 선언합니다. |
| 원하는 계층 | 아니오 | §3 위험 규칙을 적용합니다. |
| 제약 사항 (건드리지 말아야 할 것, 환경, 데이터) | 아니오 | 테스트 외에는 읽기 전용; 선언합니다. |
만약 .opencode/test-context.md 파일이 존재하면 먼저 읽고, 해당 파일이 답변하지 않은 내용만 질문합니다.
2. 워크플로우
단계를 순서대로 실행합니다. 모든 단계에는 게이트가 있습니다; 게이트를 건너뛰지 마십시오.
단계 0 — 컨텍스트 및 발견
references/00-intake-and-discovery.md를 읽습니다. scripts/detect_stack.py --root <repo> --json을 실행합니다.
다음을 확인합니다: Python 버전, 러너(runner), 테스트 레이아웃, 네이밍, 픽스처(fixtures), CI 명령어, 의존성 관리자.
게이트: 버전, 러너 또는 의존성 소스가 누락된 경우 계속하기 전에 질문합니다.
단계 1 — 위험 및 범위
references/01-risk-and-scope.md를 읽습니다. 기능을 분류하고 계층과 깊이를 선택합니다.
인증, 보안 및 동시성은 항상 평가됩니다; 적용되지 않는 경우 그 이유를 명시합니다.
게이트: 선택된 모든 계층에는 이유가 있고, 제외된 모든 계층에도 이유가 있습니다.
단계 2 — 커버리지 매트릭스
references/02-edge-case-taxonomy.md를 읽습니다. 각 승인 기준과 위험을 시나리오에 매핑합니다.
8가지 차원에 걸쳐 매핑합니다. assets/coverage-matrix.template.md를 채워서 생성합니다.
게이트: 승인 기준 없이 최소 하나의 시나리오가 없으면 안 됩니다; 시나리오 없이 출처가 없으면 안 됩니다.
단계 3 — 오라클 설계
references/03-oracle-design.md 및 references/04-fake-test-patterns.md를 읽습니다.
각 시나리오에 대해 관찰 가능한 결과와 잡아내야 하는 실패를 정의합니다.
게이트: 모든 테스트에는 동작이 손상되었을 때 실패하는 단언문(assertion)이 있습니다.
단계 4 — 테스트 작성
저장소의 레이아웃, 네이밍, 픽스처 및 스타일을 따릅니다. references/05-test-data-and-isolation.md를 읽습니다.
선택된 계층에 대해 references/layers/*.md를 사용합니다. 기존 테스트를 비활성화하거나 약화시키지 마십시오.
게이트: 테스트는 결정론적이고, 격리되어 있으며, 실제 PII나 비밀을 포함하지 않습니다.
단계 5 — 실행 및 분류
프로젝트 환경 내에서 프로젝트 자체 명령어를 실행합니다. 모든 실패를 분류합니다:
TEST_BUG, ENV_BUG, PRODUCT_BUG 또는 FLAKY.
TEST_BUG만 수정합니다. 나머지는 진단하고 계속 진행합니다.
게이트: 실패한 모든 테스트에는 분류와 증거가 있습니다.
단계 6 — 변형 게이트 (Mutation Gate)
references/09-mutation-gate.md를 읽습니다. scripts/tool_env.py --ensure로 환경을 준비합니다.
scripts/mutation_gate.py를 실행합니다. 살아남은 변형(mutant)은 테스트가 약하다는 의미입니다: 오라클을 강화하거나 테스트를 제거하십시오. 통과 기준을 낮추지 마십시오.
게이트: 변형 점수가 계획된 임계값을 충족하거나, 차이가 설명된 PASS WITH RISK 판정이어야 합니다.
단계 7 — 보고서 및 메모리
references/10-reporting.md를 읽습니다. test-reports/<feature>-<YYYY-MM-DD>.md를 작성합니다.
assets/project-context.template.md에서 .opencode/test-context.md를 생성하거나 업데이트합니다.
게이트: 보고서에는 명령어, 결과, 증거 및 미해결 위험이 포함됩니다.
단계 8 — 중단
판정을 전달합니다. 배포하지 말고, 요청받지 않는 한 커밋하지 말며, 프로덕션 코드를 수정하지 마십시오.
3. 고정 우선순위 규칙
- 금전, 인증, 권한 및 데이터 손실은 항상 P0입니다.
- 동시성, 재시도, 순서 및 멱등성은 항상 평가됩니다.
- LLM이나 모델을 호출하는 기능은
references/08-ai-ml-pack.md를 트리거합니다. - 깊이는 적용 범위 대칭이 아닌 위험을 따릅니다. 설정 페이지는 체크아웃과 같은 깊이가 필요하지 않습니다.
- 행복한 경로(happy path)만으로는 충분하지 않습니다: 각 P0 동작에는 최소 하나의 부정 케이스와 하나의 경계 케이스가 필요합니다.
4. 강제 규칙
- 테스트 대상(subject under test)을 모의(mock)하지 마십시오; 외부 경계만 모의하십시오.
- 비즈니스 동작에 대해 상태 코드, 호출 횟수 또는 null이 아닌 값에 대해서만 단언하지 마십시오.
- 예외를 삼키거나(suppress) 테스트 통과를 위해 무제한 재시도를 추가하지 마십시오.
- 테스트 스위트를 통과시키기 위해 타임아웃을 늘리거나 테스트를 건너뛰지 마십시오.
- 동기화를 위해
sleep을 사용하지 마십시오; 프레임워크의 대기 기능이나 명시적 이벤트를 사용하십시오. - 프로덕션 서비스에 쓰기 작업을 하거나, 실제 이메일을 보내거나, 실제 돈을 청구하지 마십시오.
- 타사 스킬의 비상업적 자료를 복사하지 마십시오; 이 스킬의 텍스트는 독창적입니다.
- 프로젝트가 Python이 아닌 경우: 중단하십시오.
5. 점진적 로딩
현재 단계에 필요한 것만 로드하십시오.
| 필요 시점 | 파일 |
|---|---|
| 인입, 발견, 스택 탐지 | references/00-intake-and-discovery.md |
| 위험 매트릭스 및 계층 선택 | references/01-risk-and-scope.md |
| 엣지 케이스 차원 | references/02-edge-case-taxonomy.md |
| 강력한 단언문 | references/03-oracle-design.md |
| 가짜 테스트 안티패턴 | references/04-fake-test-patterns.md |
| 데이터, 픽스처, 격리 | references/05-test-data-and-isolation.md |
| 인증 및 보안 | references/06-security-and-auth.md |
| 동시성 및 멱등성 | references/07-concurrency-and-idempotency.md |
| AI/ML 기능 | references/08-ai-ml-pack.md |
| 변형 게이트 | references/09-mutation-gate.md |
| 보고서 계약 | references/10-reporting.md |
| 계층 플레이북 | references/layers/ |
| 출력 템플릿 | assets/ |
| 환경 도구 | scripts/tool_env.py |
6. 출력 계약
판정은 정확히 하나:
| 판정 | 조건 |
|---|---|
PASS | 모든 테스트 통과, 게이트 충족, 미해결 P0 격차 없음 |
PASS WITH RISK | 테스트 통과, 게이트 부분 충족 또는 알려진 격차 문서화 |
BLOCKED | 입력, 환경 또는 도구 누락으로 실행 불가 |
BUG FOUND | 테스트 실패, 실패 원인이 제품 결함 (진단되었지만 수정되지 않음) |
항상 보고: 변경된 파일, 종료 코드와 함께 실행된 명령어, 변형 점수, 발견되지 않은 위험, 그리고 다음 조치. 사용자에게는 스페인어로 보고; 저장소가 다른 언어를 사용하지 않는 한 스킬과 코드 아티팩트는 영어 유지.
7. 중단 조건
다음 경우에는 테스트를 작성하지 않고 중단하고 질문:
- 저장소가 Python이 아닌 경우;
- 승인 기준이 누락되었고 코드로 증거를 통해 추론할 수 없는 경우;
- 테스트 러너 또는 Python 버전을 알 수 없고 저장소가 고정(pin)하지 않은 경우;
- 필수 의존성 또는 서비스를 사용할 수 없는 경우;
- 기능이 안전한 샌드박스 없이 실제 돈, 실제 PII 또는 프로덕션 데이터를 다루는 경우;
- 변형 도구를 설치할 수 없고 게이트를 실행할 수 없는 경우;
- 테스트를 가능하게 하기 위해 프로덕션 코드를 수정해야 하는 경우 (설계 차단자로 보고).
8. 도구
scripts/detect_stack.py— 읽기 전용 Python 프로젝트 탐지, JSON 출력.scripts/tool_env.py—tf-<slug>conda 환경 생성/확인, 누락된 도구 설치.scripts/mutation_gate.py— 변형 실행, 점수 계산, 통과/실패 결정.scripts/check_skill.py— 이 스킬의 구조와 링크 유효성 검사.