---
name: research-experiment-workflow
description: 연구 가설, 모델·전략·알고리즘 비교, benchmark, ablation, feasibility test, 학습 실험, 평가 계획과 실험 결과 문서화를 요청했을 때 사용합니다. 저장소와 기존 실험 근거를 조사해 검증 가능한 사전등록 계획을 작성하고, 별도 승인 후 실행 단위로 인계하며, 완료된 산출물에서 결과와 재사용 교훈을 기록합니다. 제품 PRD·기술 스펙 작성이나 일반 버그 수정에는 사용하지 않습니다.
---

# 연구 실험 워크플로우

## 출력 언어

사용자가 출력 언어를 명시적으로 지정하면 해당 언어를 사용합니다. 지정하지 않으면 이 스킬이 만드는 모든 사용자 대상 출력, 문서, 프롬프트, 보고서, 계획, 스펙 및 기타 산출물을 한국어로 작성합니다. 제목, 섹션, 레이블, 표, 체크리스트, 다이어그램과 템플릿에도 같은 언어를 사용합니다. 코드, 명령어, 파일 경로, 식별자, API 이름, 모델 ID, 프로토콜 이름과 필수 고유명사는 번역하지 않습니다.

## 목적과 경계

연구 질문을 제품 요구사항으로 바꾸지 말고, 반증 가능한 가설과 재현 가능한 실험 계약으로 바꿉니다.

- 연구·실험 계획에는 PRD와 기술 스펙을 만들지 않습니다.
- 제품에 영구적으로 추가할 기능이나 공개 계약은 `requirements-to-spec`으로 분리합니다.
- 관찰된 오류를 고치는 것이 목적이면 `bug-report-to-fix`를 적용합니다.
- 실험에 필요한 일회성 runner, 설정과 계측은 실험 계획에 포함할 수 있습니다. 재사용 제품 기능으로 승격하지 않습니다.
- 사용자가 지정한 지식 저장소나 문서 관리 스킬이 있으면 그 경로·정본·중복 규칙을 함께 따릅니다.

## 단계 판정

요청을 다음 단계 중 하나로 판정합니다.

| 요청 | 처리 |
| --- | --- |
| 가설의 사실성·현재 상태 확인 | 읽기 전용 조사 후 근거와 미검증 범위를 보고 |
| 실험 계획·검증 방법 요청 | 사전등록 실험 계획을 작성해 제시하고 현재 턴 종료 |
| 제시된 계획의 실행 승인 | 계획 문서를 다시 읽고 별도 실행 단위로 인계 |
| 완료된 실험의 해석·문서화 | 원시 산출물을 검증한 뒤 결과와 재사용 교훈 기록 |

한 요청에 여러 단계가 적혀 있어도 `계획 작성 후 실행` 같은 미래형 문장을 실행 승인으로 간주하지 않습니다. 계획 문서를 제시한 뒤 별도 사용자 메시지에서 해당 경로 또는 버전을 확인한 승인을 받습니다.

## 조사

1. 사용자의 실제 연구 질문과 첫 판정 대상을 한 문장으로 고정합니다.
2. 저장소의 기존 계획, 결과, 실패 기록, 실행 진입점, 설정, checkpoint와 평가 코드를 조사합니다.
3. 이미 답이 있는 질문, 재사용 가능한 runner와 과거의 반대 결과를 찾습니다.
4. 확인된 사실, 추정, 사용자 결정 필요 항목과 이번 실험의 비범위를 분리합니다.
5. 기존 결과를 새 가설의 증거로 재사용할 때 actor, dataset, 상대풀, 보상, seed, 평가 조건과 코드 버전이 같은지 확인합니다.

과거 지표가 높았다는 이유만으로 다른 분포의 실험에 그대로 적용하지 않습니다. baseline과 새 실험 사이에서 달라진 축을 명시합니다.

## 사전등록 실험 계획

계획에는 최소한 다음 계약을 둡니다.

1. **연구 질문과 가설**: 무엇이 어떤 기준보다 나아질 것으로 예측하는지 씁니다.
2. **기준선과 비교군**: 시작 상태와 대조군을 고정합니다.
3. **독립 변수와 통제 변수**: 바꾸는 축과 고정하는 축을 분리합니다.
4. **입력과 계보**: dataset, model, checkpoint, 상대풀, 규칙, 보상, 설정과 필요한 식별자·버전을 기록합니다.
5. **실행 설계**: 표본 수, seed, 반복 수, 균형 배정, checkpoint와 실행 순서를 정합니다.
6. **평가 설계**: 주지표, 보조지표, held-out 또는 fresh panel과 누수 방지 조건을 정합니다.
7. **판정 규칙**: 성공, 실패, 차단을 서로 배타적으로 정의합니다. 차단을 성능 실패로 세지 않습니다.
8. **중단 규칙**: hard failure, nonfinite, 계보 불일치와 안전 문제처럼 결과를 보기 전 고정 가능한 조건만 둡니다.
9. **산출물**: log, manifest, checkpoint, metric table과 결과를 기록할 정본 경로를 정합니다.
10. **비범위와 결과 뒤 분기**: 같은 결과를 본 뒤 변경하지 않을 항목과 후속 가설을 분리합니다.
11. **예상 비용**: 기존 처리량이나 smoke 측정 근거가 있을 때만 시간·자원 범위를 제시합니다.

표본 수나 성공 임계값의 통계적 근거를 확인할 수 없으면 임의로 확정값을 만들지 말고 diagnostic인지 confirmatory인지 표시합니다.

첫 실험은 사용자 질문에 답하는 최소 충분 비교로 제한합니다. 기존 기준선으로 판정할 수 있으면 새 대조군을 자동으로 늘리지 않습니다. 여러 변수의 개별 기여를 분리하는 것이 명시된 연구 질문일 때만 factorial이나 ablation arm을 추가하고, 그렇지 않으면 후속 가설로 분리합니다.

## 문서 위치

저장소에 연구 문서 정본과 명명 규칙이 있으면 이를 우선합니다. 없으면 다음 경로를 사용합니다.

```text
.codex/temp/YYYYMMDD-HHMM-research-<topic>-experiment-plan.md
.codex/temp/YYYYMMDD-HHMM-research-<topic>-experiment-result.md
```

- 계획과 결과는 책임이 다르므로 별도 문서로 유지합니다.
- 기존 실험결과 색인이나 실패·교훈 정본이 있으면 결과 확정 후 링크와 요약을 갱신합니다.
- 문서를 작성하거나 갱신한 최종 응답에는 `[문서 이름](절대 경로)` 링크를 제공합니다.

## 계획 제시와 실행 승인

계획 문서를 제시할 때 연구 질문, 핵심 비교, 판정 규칙, 예상 비용과 경로를 요약하고 현재 턴을 끝냅니다. 코드 수정, 긴 학습, benchmark와 평가를 시작하지 않습니다.

실행을 막는 열린 질문이 없고 실행 승인·취소만 남으면 `../../references/workflow-confirmation-ui.md`에 따라 버튼형 승인 카드를 제시합니다. 버튼이 게시한 후속 메시지는 별도 사용자 실행 승인 메시지로 처리합니다.

별도 사용자 메시지에서 계획 경로 또는 버전을 확인하며 실행을 승인하면 다음을 수행합니다.

1. 계획을 파일에서 다시 읽고 Git 상태와 필요한 입력 산출물의 존재를 확인합니다.
2. 반영되지 않은 피드백, 미해결 필수 결정과 계보 불일치가 없는지 확인합니다.
3. 사용자가 별도 새 Codex 작업으로 인계하라고 명시했을 때만 새 작업을 만듭니다. 그 외에는 승인된 계획을 현재 작업에서 실행합니다.
4. 새 작업을 승인한 경우 목표, 계획 문서 경로, 고정 입력, 실행 단계, 성공·실패·차단 기준, 산출물 경로와 비범위를 전달합니다.
5. 사용자가 모델이나 추론 강도를 지정했으면 지원 여부를 확인해 사용합니다. 지정하지 않았으면 임의의 override를 추가하지 않습니다.
6. 사용자가 승인한 새 작업 도구가 없거나 생성에 실패하면 동일한 실행 프롬프트를 코드 블록으로 제공합니다.

## 결과 문서화

1. 완료 marker, manifest, log, metric과 checkpoint를 원시 산출물에서 직접 확인합니다.
2. 계획된 표본·seed·평가 panel과 실제 실행의 차이를 기록합니다.
3. 결과를 `성공`, `실패`, `차단`, `부분 완료` 중 하나로 판정합니다.
4. 관측값과 해석을 분리하고, 실행하지 않은 평가나 중단된 epoch를 완료 결과처럼 쓰지 않습니다.
5. 재사용 교훈은 다음 실험 전에 행동을 바꾸는 규칙으로 기록합니다.
6. 결과를 본 뒤 생긴 새 가설은 현재 계획을 소급 수정하지 말고 후속 실험으로 분리합니다.

## 완료 점검

- [ ] 연구 요청을 제품 PRD 흐름으로 보내지 않았는가
- [ ] 기존 실험과 새 실험의 분포·계보 차이를 확인했는가
- [ ] 가설, 비교군, 통제 변수와 판정 규칙이 실행 전에 고정됐는가
- [ ] 성공·실패·차단을 분리했는가
- [ ] 계획 제시와 실행 승인을 서로 다른 사용자 메시지에서 받았는가
- [ ] 결과가 원시 산출물과 실제 완료 범위를 넘지 않는가
- [ ] 생성·갱신한 문서를 절대 경로 링크로 제시했는가