템플릿 모음

이 부록은 본문 여러 장에 흩어져 있는 문서 양식을 한곳에 모은다. 문제 정의서에서 시작해 실험 계획서, 연구 노트, README, 데이터 카드, 재현 보고서, 리뷰 응답까지, 연구의 각 단계에서 쓰는 Markdown 뼈대를 복사해 바로 채울 수 있게 정리했다. 양식마다 그것을 설명하는 장을 링크한다. 칸이 왜 있는지, 칸을 어떻게 채워야 하는지는 그 장에 있다.

양식은 생각을 대신하지 않는다. 칸을 모두 채웠다고 좋은 문서가 되지는 않고, 칸 하나를 비워 둔 이유가 분명하면 그것으로 충분할 때도 있다. 양식의 쓸모는 빠뜨리기 쉬운 것을 빠뜨리지 않게 하는 데 있다. 실패 시의 결론, 기각한 대안, 기대 결과, 권장하지 않는 용도처럼 쓰기 불편한 칸이 대개 가장 중요한 칸이다.

학습 목표

  • 연구 단계마다 쓰는 문서 양식을 찾아 자신의 프로젝트에 맞게 채운다
  • 양식의 각 칸이 어떤 실패를 막기 위해 있는지 해당 장에서 확인한다
  • 문서를 저장소에서 버전 관리하고 실행 결과와 연결한다

사용법

어디에 두는가. 이 부록의 양식은 모두 Markdown 파일이다. 연구 저장소 안에 두고 코드와 함께 커밋하는 것을 기본으로 한다. 그래야 문서가 언제 바뀌었는지 git이 기록하고, 문서에서 커밋 hash와 run ID로 실행 결과를 가리킬 수 있다. 아래 표의 위치는 6.1장의 디렉터리 구조를 전제로 한 예시다.

양식 언제 쓰는가 저장소 안 위치(예) 원천 장
문제 정의서 데이터를 보기 전 docs/problem.md 1.3장
연구 질문 문서 방향을 정할 때 docs/research-question.md 23.4장
실험 계획서 실행 전 docs/plans/<날짜>-<주제>.md 23.5장
설정 파일 프로젝트 시작 configs/default.toml 6.3장
README 프로젝트 시작, 결과가 바뀔 때마다 README.md 6.7장
AGENTS.md·SKILL.md 에이전트와 함께 일할 때 저장소 루트, skills/<이름>/ 4.4장
연구 노트 매일 notes/YYYY-MM-DD.md 23.7장
결정 기록 결정할 때 노트 안, 큰 결정은 docs/decisions/NNNN-<제목>.md 23.7장, 6.7장
주간 보고 매주 notes/weekly/YYYY-WW.md 23.7장
데이터 카드 데이터를 만들거나 공개할 때 data/README.md 또는 docs/data.md 15.5장
모델 카드 모델을 넘기거나 공개할 때 docs/model.md 6.7장, 23.12장
CHANGELOG 결과에 영향을 주는 변경마다 CHANGELOG.md 6.7장
주장–근거 표 실험 중, 논문 전 docs/claims.md 23.6장, 23.8장
재현 보고서 남의 결과를 재현한 뒤 docs/repro/<BibTeX 키>.md 23.3장
리뷰·리뷰 응답 심사할 때, 심사를 받은 뒤 저장소 밖(비공개) 23.11장

세 가지 규칙. 어떤 양식을 쓰든 다음은 공통이다.

  • 날짜와 버전을 머리에 쓴다. 계획서·질문 문서처럼 "실행 전에" 써야 의미가 있는 문서는 작성일과 커밋이 그 증거다.
  • 고친 것은 지우지 않고 기록한다. 계획서의 변경 기록 절, 노트의 "고치지 않고 덧붙이기", ADR의 "대체됨" 상태가 모두 같은 원칙이다.
  • 숫자는 출처와 함께 쓴다. 문서에 적는 결과 숫자 옆에 run ID나 표를 만든 명령을 둔다(22.1장).

아래 양식에서 <꺾쇠>는 채울 자리, 괄호 안의 설명은 지우고 내용으로 바꿀 자리다.

문제와 질문

문제 정의서

동료가 이 문서만 읽고 같은 실험을 설계할 수 있어야 한다. 데이터를 보기 전에 쓰고, 바꾸면 이유를 남긴다. → 1.3장 문제를 수학적으로 정의하기

# 문제 정의서: <제목>                       작성일 / 수정 이력

| 항목 | 내용 |
|---|---|
| 연구 질문 | (한 문장. 답이 예/아니오 또는 숫자로 나오게) |
| 문제 유형 | 정적 예측 · 시계열 예측 · 상태 추정 · 역문제 · 최적화 · 제어 · 생성 중 |
| 변수 | 입력 x, 출력 y, (있으면) 제어 u, 파라미터 θ, 상태 s, 잠재 z — 각각의 단위 |
| 정답 정의 | label을 어떻게 측정·계산했는가, label의 잡음 크기 |
| 정보의 시점 | 예측 시점, 각 입력을 그 시점에 어떻게 얻는가 |
| 범위 | 예측 구간, 공간 범위, 시간 해상도 |
| 일반화 대상 | 새 측정 · 새 개체 · 새 조건 · 새 장비 중 무엇인가 → 분할 단위 |
| 평가 단위와 지표 | 오차를 어떤 단위로 모아 어떤 지표로 보고하는가 |
| baseline | 평균 예측, 선형 모델, 분야의 물리 모델 등 |
| 성공 기준 | 무엇보다 얼마나 좋아야 하는가 (근거와 함께) |

## 변경 기록
- <날짜>: <무엇을, 왜 바꿨는가>

연구 질문 문서

양식의 칸 순서와 달리, "결과별 결론"을 "검증 방법"보다 먼저 정한다는 생각으로 쓴다. 실패 시의 결론을 쓸 수 없으면 가설이나 검증 방법을 고친다. → 23.4장 연구 질문과 가설

# 연구 질문 문서: <제목>                     작성일 / 수정 이력
## 문제
- 누구의 어떤 결정이 나아지는가 (실제 필요성)
- 입력 → 출력, 일반화 대상, 평가 단위 (문제 정의서 요약)
## 기존 한계
- 어떤 방법이, 어떤 조건에서, 얼마나, 왜 부족한가 (근거: 문헌 위치, 재현 보고서)
## 가설
- 관찰 → 원인 가설(경쟁 가설 포함) → 예측
- 반증 조건: 어떤 결과가 나오면 이 가설을 버리는가
- 주된 기여의 종류 (구조 · 학습법 · 데이터 · 분석 · 시스템 · 벤치마크 중 하나)
## 검증 방법
- 비교 대상, 분할, metric, seed 수, 경쟁 가설을 구별하는 실험 (상세는 실험 계획서)
## 성공 기준
- 의미 있는 최소 개선 Δ와 그 근거, 판정 규칙(성공·작은 개선·중단·보류)
## 결과별 결론
- 성공 시: 주장할 내용과 다음 단계
- 작은 개선·보류 시: 추가 실험의 범위
- 실패(중단) 시: 배운 것과 전환할 방향
## 중단 기준
- 계산 예산, 날짜, 그때까지 확인되지 않으면 멈출 조건
## 합의
- <날짜> 지도교수(또는 동료) <이름>과 성공 기준·실패 시 결론에 합의

실험 계획서

결과를 보기 전의 자신이 결과를 본 뒤의 자신에게 보내는 약속이다. 주 지표는 하나로 정하고, 계획서를 커밋한 hash를 실험 추적 기록에 남긴다. → 23.5장 실험 설계

# 실험 계획서: <연구 질문 문서 제목>                 작성일, 버전, 커밋
## 가설과 반증 조건            (연구 질문 문서에서)
## 주장–실험 대응
| 주장 | 실험 종류 | 처리군 | 대조군 | 통제 변수 | 주 지표 |
|---|---|---|---|---|---|
## 데이터와 분할                 판, 분할 단위와 방식, 분할 seed, leakage audit 결과
## 비교 대상                    baseline 목록과 선정 이유
## 공정성                       파라미터 수·계산량·데이터·탐색 예산(시도 횟수, 범위, 절차)
## 반복과 검정력                 seed·분할 수, 블록(짝짓기) 방식, 검정력 계산, 독립 단위
## 분석 계획                    주 지표, 보조 지표, 판정 규칙, 다중 비교 처리
## 결과별 결론                   성공 / 작은 개선 / 중단 / 보류 각각의 결론 (실행 전에 작성)
## test set 사용 계획            언제, 몇 번, 기록 위치
## 변경 기록                    계획을 바꾼 날짜, 이유, 변경 전후

프로젝트

디렉터리 구조와 설정

재사용되는 코드는 src/, 사람이 실행하는 진입점은 scripts/, 실행마다 바뀌는 값은 configs/에 둔다. data/와 outputs/는 커밋하지 않는다. → 6.1장 연구 프로젝트 구조

my-project/
├── README.md            # 목적 · 설치 · 실행 · 재현 방법
├── AGENTS.md            # 에이전트 지침 (4.4장)
├── CHANGELOG.md         # 결과에 영향을 준 변경 (6.7장)
├── pyproject.toml       # 패키지 메타데이터와 의존성 (lockfile과 함께)
├── configs/             # 실험 설정 파일 (6.3장)
├── src/my_project/      # data/ · models/ · training/ · evaluation/ · utils/
├── scripts/             # train.py · eval.py · predict.py
├── tests/               # 자동 테스트 (6.6장)
├── notebooks/           # 탐색 · 분석 (결과를 만드는 계산은 두지 않는다)
├── data/                # README.md만 커밋: 내려받기·링크 방법
├── outputs/             # outputs/<run-id>/ (커밋하지 않음, 22.1장)
├── notes/               # 연구 노트·주간 보고 (23.7장)
└── docs/                # 문제 정의서 · 계획서 · 데이터·모델 카드 · decisions/

설정 파일은 6.3장의 네 묶음(데이터·모델·학습·평가)으로 나눈다. 이 책의 예제는 값의 타입이 표기에서 바로 정해지는 TOML을 쓴다. YAML을 쓴다면 6.3장의 타입 추측 함정(1e-3이 문자열이 되는 로더 등)을 직접 로드해 확인한다. 어느 형식이든 읽은 값의 타입은 설정 객체에서 검증한다.

# configs/default.toml — 값은 예시
[data]
name = "cycles-v3"            # 데이터 판: manifest 해시와 함께 run.json에 기록된다
root = "data/processed"
split = "data/splits/cell-split-v1.csv"   # split manifest (15.5장)

[model]
width = 64
depth = 3

[train]
lr = 1e-3
epochs = 50
seed = 0

[eval]
metrics = ["rmse", "mae"]     # 첫 항목이 주 지표 (실험 계획서와 같게)

.gitignore의 최소 항목이다. 비밀값을 담은 파일(.env 등)도 여기에 넣고, 저장소에는 값이 없는 예시 파일만 둔다.

data/raw/
data/processed/
outputs/
__pycache__/
.venv/
.ipynb_checkpoints/
.env

README

처음 보는 사람이 그대로 따라 해 결과를 재현할 수 있어야 한다. 가장 자주 빠지는 칸은 기대 결과(숫자와 허용 범위, 실행 시간)다. 명령은 복사해서 그대로 실행되게 쓰고, 단계마다 확인 방법을 둔다. → 6.7장 연구 코드 문서화

# <프로젝트 이름>

<한두 문단: 무엇이고 무엇을 하지 않는가. 대응하는 논문·보고서. 현재 상태(진행 중 / 제출본은 태그 v1.0에 고정)>

### 설치
<Python·CUDA 등 시스템 요구사항과 확인 명령>
```bash
git clone <저장소 주소> && cd <프로젝트>
<lockfile로 설치하는 정확한 명령>
<환경 확인 명령>        # 기대 출력: <무엇이 나와야 하는가>
```

### 데이터 준비
```bash
<내려받기 명령>         # 크기 약 <N> GB, checksum 검사 포함
```
<생기는 파일과 개수. 접근 권한이 필요하면 신청 절차. 데이터 설명: docs/data.md>

### 실행
```bash
<학습 명령> --config configs/default.toml --seed 0
<평가 명령> --run outputs/<run-id>      # <run-id>는 학습 로그 첫 줄에 출력된다
```

### 결과 재현
| 결과 | 명령 | 기대 결과 | 시간·자원 |
|---|---|---|---|
| 표 <N>, <행> | `<명령>` | <metric> <평균> ± <표준편차> (<단위>, seed <k>개) | <장치> <시간> |

### 인용
<논문 서지 정보>. CITATION.cff를 참고한다. 라이선스: <라이선스 이름>

AGENTS.md와 SKILL.md

지침 파일에는 에이전트가 매번 필요로 하지만 코드만 읽어서는 알기 어려운 것을 쓴다. 정확한 명령, 작업이 끝났다는 기준이 되는 명령, 이유가 붙은 금지사항, 데이터 취급 규칙. 50줄 이내를 목표로 하고, 기계로 확인할 수 있는 규칙은 검사 스크립트로, 특정 작업의 절차는 skill로 옮긴다. 지침은 권한이 아니므로 되돌리기 어려운 행동은 권한 설정과 저장소 보호로 막는다. → 4.4장 에이전트 지침

# 에이전트 지침 — <프로젝트 이름>

<한 줄 소개: 무엇을 하는 프로젝트인가>. 코드는 `src/`, 테스트는 `tests/`, 설정은 `configs/`에 있다.

## 명령

모든 명령은 저장소 루트에서 실행한다.

```bash
<환경 설치 명령>
<테스트 명령>
<1분 안에 끝나는 smoke test 명령>
```

- 코드를 고친 뒤에는 테스트와 smoke test가 모두 통과해야 작업이 끝난 것이다.

## 규칙

- 원본 데이터(`data/raw/`)는 읽기만 한다. 수정·삭제·외부 전송을 하지 않는다. (이유: <…>)
- test split의 결과는 최종 보고 전에는 보지 않는다.
- `tests/`의 기대값을 바꾸지 않는다. 바꿔야 한다고 판단하면 이유를 보고하고 멈춘다.
- 새 의존성을 추가하지 않는다. 필요하면 제안만 한다.
- 물리량 변수에는 단위 접미사를 붙인다(`time_s`, `temp_c`).

## 데이터

- 위치: <프로젝트 기준 상대 경로 또는 설정 변수 이름>. 비밀값은 환경변수 <이름>으로 읽는다.
- 개인정보·공개 전 데이터는 외부 서비스로 보내지 않는다.

## 반복 작업

- <작업 이름>: `skills/<skill 이름>/SKILL.md`

CLAUDE.md처럼 다른 이름을 읽는 도구를 함께 쓴다면, 규칙을 복사하지 말고 그 파일에서 AGENTS.md를 불러오게 한다(불러오기 문법은 도구 문서에서 확인한다). skill 하나의 뼈대는 다음과 같다.

---
name: <소문자-하이픈-이름, 폴더 이름과 같게>
description: <무엇을 하는가>. 사용자가 <어떤 요청·상황>일 때 사용한다.
---

# <작업 이름>

## 절차
1. <입력을 받는다. 단위가 없으면 묻는다>
2. <무엇을 추가·수정한다. 바꾸지 않을 것>
3. <검증 명령을 실행한다. 모두 통과해야 끝난다>

## 보고
- 바꾼 파일, 실행한 명령과 결과. 실패하면 고치지 말고 실패 내용을 보고한다.

기록

연구 노트

실행하면서 쓰고, 고치지 않고 덧붙이고, 실패를 쓰고, 증거(run ID·커밋·설정 hash)와 연결하고, 사실과 추측을 구별한다. → 23.7장 연구 기록과 연구 노트

# YYYY-MM-DD (요일)

## HH:MM <실험 제목>
- 질문: <이 실험이 답하려는 것>
- 가설: <예상한 결과와 그 이유 — 실행 전에 쓴다>
- 실행: <run ID> (seed <k>개), 커밋 <hash>(작업 트리 깨끗함 / 변경 있음), 설정 sha256:<hash>
  - 바꾼 것: <키 = 값> (나머지는 <기준 run ID>와 같음)

## HH:MM 결과
- <지표 변화> <점추정>, 95% 구간 [<하한>, <상한>] → <판정>
- 그림: outputs/<run-id>/<파일>
- 해석: <가설에 대해 말하는 것>
  (추측) <측정하지 않은 해석은 이렇게 표시한다>

## 다음
- [ ] <할 일> (<이유>)

결정 기록

노트 안의 결정 기록은 가볍고 잦다. 그중 프로젝트 전체에 영향을 주고 되돌리기 비싼 것만 ADR(Architecture Decision Record)로 승격한다. 두 양식 모두 기각한 대안이 핵심이다. → 23.7장 결정 기록, 6.7장 설계 문서

## 결정 YYYY-MM-DD: <무엇을 하기로(하지 않기로) 했는가>
- 근거: <노트 날짜, run ID, 문헌, 회의>
- 기각한 대안:
  - <대안 1>: <택하지 않은 이유>
  - <대안 2>: <택하지 않은 이유>
- 되돌릴 조건: <어떤 증거가 나오면 다시 검토하는가>
- 영향: <다시 계산·학습할 것, 바뀌는 표·그림>
# NNNN. <결정 제목>
- 상태: 제안 / 채택 / 대체됨(superseded by NNNN)
- 날짜: YYYY-MM-DD
### 맥락
<결정이 필요해진 상황과 제약>
### 결정
<무엇을 하는가. 재현에 필요한 값의 위치(설정 파일 등)>
### 검토한 대안
- <대안>: <장단점과 근거(실험 ID)>
### 결과
- <이 결정으로 보고하는 숫자의 의미가 어떻게 정해지는가>
- <감수하는 비용>

결정이 바뀌면 이전 ADR을 고치지 않는다. 새 ADR을 쓰고, 이전 것의 상태만 "대체됨"으로 바꾼다.

주간 보고

노트에서 뽑아 만든다. 결론을 먼저 쓰고, 숫자에 구간과 판정을 붙이고, 막힌 점과 구체적인 도움 요청을 숨기지 않는다. → 23.7장 주간 보고

# 주간 보고 YYYY-MM-DD ~ MM-DD

## 요약 (세 줄)
- <X를 해서 Y를 알았다 (숫자, 구간, 판정)>

## 진행
- 실험 <n>건: <run ID 목록> (노트 <날짜>)
- 핵심 그림: <경로>

## 막힌 점
- <무엇이 왜 막혔는가>

## 도움 요청
- <누구에게, 무엇을, 언제까지>

## 다음 주 계획
- <할 일>

작은 표 양식

본문 여러 장에서 쓰는 기록용 표의 머리줄이다. 노트나 별도 파일에 붙여 쓴다.

표 머리줄 원천 장
디버깅 기록 시각 · 가설 · 실험(바꾼 것 하나) · 예측 · 결과 · 결론 17.9장
test set 사용 기록 날짜 · 평가한 모델 · 이유 · 결과 · 보고 여부 23.5장
재현 불일치 표 # · 항목 · 논문 본문(위치) · 공개 코드(파일:줄) · 내 재현 설정 · 영향 추정 23.3장
누수 감사 점검 항목 · 확인 방법 · 근거(결과) 15.4장
데이터 통합 매핑 목표 열 · 단위 · 출처별 원래 열과 변환 15.5장
AI 도구 사용 기록 날짜 · 도구(버전·설정) · 용도 · 입력한 것 · 결과를 어디에 썼나 · 어떻게 검증했나 23.12장
협업 합의 역할 · 시간 · 각자의 목표 · 산출물 · 데이터 · 저자와 발표 경로 · 의사결정 23.13장
| 시각 | 가설 | 실험(바꾼 것 하나) | 예측 | 결과 | 결론 |
|---|---|---|---|---|---|
| HH:MM | | | (실행 전에 쓴다) | | |

인수인계 문서

프로젝트를 다른 사람에게 넘길 때 쓰는 문서다. 새로 쓰는 문서라기보다 이미 있는 문서로 가는 지도다. README·노트·결정 기록·데이터 카드가 갖춰져 있으면 이 문서는 한 쪽으로 끝난다. 쓰다가 막히는 칸이 있다면 그 칸에 해당하는 원천 문서가 빠져 있다는 뜻이다. 이 양식은 6.7장과 23.7장의 문서를 묶은 것이다.

# 인수인계: <프로젝트 이름>                  작성일, 넘기는 사람 → 받는 사람

## 지금 상태
- 연구 질문과 현재까지의 결론 (연구 질문 문서, 최신 주간 보고 링크)
- 진행 중인 실험과 그 run ID, 결과가 나오면 볼 것

## 재현
- README의 "결과 재현" 절로 대표 결과 하나를 받는 사람이 직접 재현했는가: 예 / 아니요(막힌 곳)

## 자원과 권한
- 데이터 위치와 접근 권한(신청 절차), 계산 자원 계정, 공유 저장소
- 비밀값은 이 문서에 쓰지 않는다. 어디서 발급받는지만 쓴다.

## 결정과 이유
- 결과에 영향을 준 결정 목록 (docs/decisions/, 노트의 결정 기록 링크)

## 알려진 문제와 다음 할 일
- <버그, 미해결 질문, 시도했지만 효과가 없었던 것(노트 날짜)>

## 연락
- 질문을 받을 수 있는 기간과 방법

데이터와 모델 문서

데이터 카드

"알려진 한계"와 "권장하지 않는 용도"는 쓰기 불편하지만 가장 중요한 칸이다. 각각 두 개 이상 쓴다. 데이터셋 문서화의 질문 목록은 datasheets for datasets 제안(Gebru 외, 2021)을 따른다. → 15.5장 데이터셋 버전·문서화·라이선스

# 데이터 카드: <데이터셋 이름> <버전>          manifest 해시 sha256:<…>

## 동기
- 왜, 누가, 어떤 연구 질문을 위해 만들었는가

## 구성
- 단위별 개수: entity <n> · group <n> · sample <n>
- 열의 의미·단위·결측 표기: (데이터 사전 링크 또는 표)
- label의 생성 과정과 잡음 크기

## 수집
- 장비, 기간, 조건, 프로토콜
- 선정 기준: 무엇이 포함되고 무엇이 빠졌는가

## 전처리
- raw → processed 단계와 코드 버전(커밋)
- 제외한 샘플과 그 이유

## 분할
- split manifest 경로와 해시, 분할 단위, 그 근거

## 알려진 한계
- 다루지 않는 조건 범위
- 알려진 편향, label 잡음

## 용도
- 권장 용도
- 권장하지 않는 용도

## 배포·유지
- 라이선스와 이용 조건(재배포·상업적 이용·인용 의무), 민감정보 처리와 접근 조건
- 인용 방법, 연락처
- 변경 이력: <날짜> <무엇을, 왜>

모델 카드

모델을 다른 사람이 쓰게 될 때 붙인다. 이 책은 6.7장의 "모델 설명"과 23.12장의 artifact 문서화에서 요구한 칸(입력·출력의 shape과 단위, 학습 데이터의 범위, 평가 조건, 조건별 성능, 쓰면 안 되는 범위)을 중심으로 쓴다. 모델 카드를 제안한 Mitchell 외(2019)는 모델 정보, 의도한 용도, 성능을 나눠 볼 요인(factors), 지표, 평가 데이터, 학습 데이터, 정량 분석, 윤리적 고려, 주의와 권고의 절을 둔다. 아래 양식은 그 순서를 과학 모델에 맞게 줄인 것이다.

# 모델 카드: <모델 이름> <버전>                커밋 <hash>, 학습 run <run ID>

## 모델 정보
- 구조 요약, 파라미터 수, 학습 방법, 만든 사람·날짜, 라이선스
- 입력: <이름> shape (<축>) [단위] / 출력: <이름> shape (<축>) [단위], 부호 규약

## 의도한 용도
- 의도한 사용자와 결정
- 권장하지 않는 용도, 평가하지 않은 조건 (예: "저온(< 10 °C) 조건은 평가하지 않았다")

## 학습 데이터
- 데이터 카드 링크와 버전, 조건 범위(온도·재료·장비 등)

## 평가
- 평가 데이터와 분할 단위(일반화 대상), 주 지표와 보조 지표
- 조건별(요인별) 성능 표: 조건 · n · 지표 · 구간
- 불확실성: 보정 여부와 평가 방법(21.2장)

## 한계와 권고
- 알려진 실패 모드, 분포 이동에 대한 민감도, 해석의 주의점
- 이중 용도·민감정보 검토 결과(해당하면)

CHANGELOG 항목

결과에 영향을 준 변경은 따로 표시한다. 무엇이 바뀌었는가, 어떤 결과가 얼마나 영향을 받는가, 어느 버전·커밋부터인가. → 6.7장 변경 기록

## [Unreleased]

### [X.Y.Z] - YYYY-MM-DD
#### Changed
- **[결과 영향]** <무엇을 바꿨는가>(<근거: ADR NNNN, 이슈>).
  <어떤 출력이 얼마나 바뀌는가>. <다시 계산해야 하는 표·그림>.
#### Fixed
- **[결과 영향]** <고친 버그>(#<이슈>). 영향받는 run: <범위>.
- <결과에 영향이 없는 수정>

논문과 심사

주장–근거 표

실험이 끝난 뒤가 아니라 실험 중에 쓴다. 근거 열이 빈 주장은 실험이 필요하거나 지워야 하고, 어떤 주장에도 연결되지 않은 그림은 부록으로 가거나 빠진다. → 23.6장 결과 분석과 주장의 범위, 23.8장 논문 작성

# 핵심 기여
우리는 <문제>에서 <방법>이 <조건>에서 <지표>로 <크기>만큼 낫다는 것을 보인다.

| 주장 | 근거 실험(run ID) | 데이터·조건 | 지표 | 짝지은 차이와 95% 구간 | 판정 | 위치 |
|---|---|---|---|---|---|---|
| C1. | | | | | 우세 / 열세 / 판정 보류 | 표 <N> |

## 대안 설명
- <대안 설명> → 배제한 실험 / 배제하지 못함

재현 보고서

한 논문에 한 문서. 결론 절은 "재현됨/안 됨" 판정 하나로 끝내지 않고 조건과 근거를 함께 쓴다. → 23.3장 논문 재현

# 재현 보고서: <논문 제목> (<BibTeX 키>)
## 1. 대상
- 재현한 주장: <표·그림 위치와 숫자> (<논문이 말하는 조건>)
- 재현의 종류: <공식 코드 실행 / 재구현 / 불일치 조건 실험>
## 2. 원 논문 조건
- 데이터·판, 분할, 전처리, metric, 하이퍼파라미터, 학습 예산, seed (논문 위치와 함께)
## 3. 실제 조건
- 내가 쓴 값과 환경 (코드 커밋, 라이브러리 버전, 하드웨어, 데이터 체크섬)
## 4. 차이
- 불일치 표 (논문 / 공개 코드 / 내 설정 / 영향 추정 — 영향 추정은 실험 전에)
## 5. 결과
- seed 수, 평균 ± 표준편차, 보고값과의 비교 방법(단일 실행 예측구간 등), 판정
- 불일치 조합 실험의 표, 주효과와 교호작용
## 6. 결론
- 무엇이 어떤 조건에서 재현되었고, 무엇이 재현되지 않았는가
## 7. 한계
- 맞추지 못한 조건, 확인하지 못한 것, 계산 예산의 차이
## 8. 저자와의 소통
- 문의 날짜, 받은 답, 반영 여부

리뷰 쓰기

약점마다 무엇이 문제인지, 왜 결론에 영향을 주는지, 무엇을 하면 해소되는지를 쓴다. 평가할 수 없는 부분은 확신도와 범위로 밝힌다. 심사 중인 원고와 리뷰는 기밀이므로 저장소나 외부 도구에 올리지 않는다. → 23.11장 투고와 동료 심사

## 요약
<저자가 "맞다, 그게 우리 주장이다"라고 할 수 있게, 주장과 방법을 자기 말로>

## 강점
- <구체적으로: 무엇이 어떤 주장을 뒷받침하는가>

## 약점 (결론에 영향을 주는 순서대로)
- W1. 문제: <…> / 영향: <어떤 결론이 왜 흔들리는가> / 해소: <어떤 실험·서술이면 되는가>

## 질문
- Q1. <답에 따라 평가가 바뀔 수 있는 것>

## 사소한 지적
- <오타, 표기, 그림>

## 종합 의견
- 점수: <점수>, 확신도: <확신도>. 평가하지 못한 범위: <…>
- <어떤 약점이 해소되면 점수를 올리는가>

리뷰 응답

목표는 심사자를 이기는 것이 아니라 결정권자가 정확한 정보로 판단하게 하는 것이다. 핵심 약점부터 답하고, 지적을 인용하고, 증거(추가 실험·본문 위치·수정 문장)로 답한다. 심사자가 오해했다면 서술이 불분명했던 탓도 인정하고 해당 문장을 고치며, 할 수 없는 것은 인정하고 주장의 범위를 줄인다. 글자 수·새 결과·외부 링크·익명성 규칙은 투고처 지침을 따른다. → 23.11장 리뷰 받기

# 응답 준비 표 (제출하지 않는다)
| 지적 | 분류 | 대응 | 근거·수정 위치 | 상태 |
|---|---|---|---|---|
| R2-W1 | 오해 / 타당·해결 가능 / 타당·해결 불가 / 범위 밖 / 사소 | | | |

# 저자 응답
## 공통 응답
- <여러 심사자가 지적한 핵심 문제와 답, 추가 실험 결과>

## R1
- R1-W1: "<지적 인용>"
  - 답: <증거와 함께>. 수정본에서 <절·표·쪽·줄>을 다음과 같이 고친다: "<수정 문장>"
- R1-Q1: "<질문 인용>"
  - 답: <…>

## R2
- R2-W1: …

저널의 response letter도 같은 구조다. 지적마다 원문을 인용하고, 답과 함께 수정본에서 바뀐 위치(쪽·줄 번호)를 적는다. 추가 실험의 결과가 불리하게 나와도 그대로 보고한다.

실패 사례

  • 양식을 채우는 것을 목적으로 삼는 것. 모든 칸이 차 있지만 "결과별 결론"이 "성공하면 논문을 쓴다" 한 줄이고, "알려진 한계"가 "없음"이다. 칸은 질문이다. 답할 수 없으면 그 칸이 바로 연구가 덜 된 곳이다.
  • 실행 전에 써야 할 문서를 결과를 본 뒤에 쓰는 것. 계획서·질문 문서·노트의 가설을 사후에 쓰면 양식은 그대로인데 의미가 사라진다. 작성일과 커밋이 그 문서가 언제 쓰였는지 증명하게 한다.
  • 문서를 저장소 밖에 두어 코드와 따로 낡게 하는 것. 공유 드라이브의 README와 저장소의 코드가 서로 다른 시점을 가리킨다. 문서는 코드와 같은 커밋으로 바꾼다.
  • 문서에 비밀값·개인 경로·기밀을 쓰는 것. README·AGENTS.md·인수인계 문서는 공유되고 커밋된다. 비밀값은 환경변수 이름이나 발급 경로로, 경로는 프로젝트 기준 상대 경로로 쓴다. 심사 중인 원고와 리뷰는 저장소에 넣지 않는다.
  • 양식을 바꾸지 않고 계속 쓰는 것. 주간 보고를 쓰는 데 노트 밖의 기억이 필요했다면 노트 양식에 칸이 빠진 것이다. 양식도 프로젝트에 맞게 고치고, 고친 이유를 남긴다.