결과 기록 — 재현과 비교가 목적이다

이 스킬의 목적은 보고서를 예쁘게 쓰는 것이 아니다.

1. 재현 — 몇 달 뒤 그 폴더만 열어도 같은 결과를 다시 낼 수 있는가
2. 비교 — 다음 실험과 나란히 놓고 무엇이 달라졌는지 말할 수 있는가

이 둘을 만족하지 못하면 기록한 의미가 없다. 아래 규칙은 전부 이 둘에서 나온다.

1. 실험 하나 = 폴더 하나 (자족)

<실험 루트>/<expNN_이름>/
    output/     결과물 (그래프·표·산출 파일)
    logs/       실행 로그
    report.md   보고서

자족(self-contained)이 핵심이다. 그 폴더 밖을 뒤져야 알 수 있는 것이 있으면
재현이 깨진다. 사용한 데이터 경로·환경·명령을 report.md 안에 적는다.

2. 스크립트는 하나, 인자만 바꾼다

실험마다 스크립트를 복사하면 어느 것이 최신인지 알 수 없게 되고, 나중에
"이 실험은 어느 버전으로 돌렸나"를 복원할 수 없다.

# 공용 스크립트 1개 + CLI 인자로 분기
python <실험루트>/<task>_analysis.py --variant <조건> --out <expNN_이름>

코드는 공유하고 결과와 로그만 각 폴더에 쌓는다.

3. 로그는 반드시 남긴다 — 함정 둘

PYTHONIOENCODING=utf-8 python <스크립트> ... 2>&1 | tee <expNN>/logs/run.log

• 임시 폴더에 남기지 않는다. 세션이 끝나면 사라지고, 그 시점의 실행 근거가 없어진다.
• 고정 파일명(run.log)으로 덮어쓴다. 재실행마다 파일이 늘면 어느 것이 최종인지
  모르게 되고, 정리하려면 삭제가 필요해진다. 덮어쓰기는 삭제가 막힌 환경에서도 동작한다.
• ⚠️ 콘솔 기본 인코딩이 UTF-8이 아닌 환경(예: Windows cp949)에서는 로그의 한글이 깨진다.
  PYTHONIOENCODING=utf-8 을 붙인다. 로그가 깨지면 원인 추적이 사실상 불가능해진다.

4. 인덱스를 유지한다 — 비교는 여기서 일어난다

실험 루트에 README.md 하나를 두고 표로 누적한다. 이게 없으면 실험이 늘수록
서로 비교가 안 되고, 같은 실험을 두 번 하게 된다.

실험	방식	조건	핵심 결과	대표 산출
exp01	…	…	…	exp01/output/…
exp02	…	…	…	exp02/output/…

표 아래에 핵심 발견을 몇 줄로 유지한다. 표만 있으면 "그래서 무엇을 알게 됐는가"가 남지 않는다.

5. 보고서 골격 (이 형태를 그대로 쓴다)

여러 실험을 같은 골격으로 써야 비교가 된다. 형식이 실험마다 다르면 표로 못 모은다.

# <expNN> — <한 줄 제목>

| 항목 | 내용 |
|---|---|
| 작성일자 | YYYY-MM-DD |
| 대상 | <직전 실험 대비 무엇을 바꿨는가> |
| 환경 | <하드웨어 / 런타임 / 주요 라이브러리 버전> |
| 입력 | <데이터 규모·조건> |
| 산출 | `output/<…>` · 로그 `logs/run.log` |

## 1. 목적
<이 실험이 무엇을 확인하려는지. 직전 실험과의 연결.>

## 2. 방법 (<직전과 동일 + 변경점>)
1. <단계>
2. <단계>

## 3. 결과
<수치·그래프. 어디서 나온 값인지 경로 표기.>

## 4. 해석
<수치가 무엇을 뜻하는지. 한계도 함께.>

## 5. 다음
<이 결과가 다음 실험에 남기는 질문.>

"대상 = 직전 대비 무엇을 바꿨는가" 칸이 비교의 축이다. 이 칸을 비우면
실험 계열이 끊긴다.

6. 값은 한 곳에서만 온다

같은 의미의 값이 코드 상수와 측정 결과 두 곳에 있으면 언젠가 어긋난다.
실제로 전부 측정해 파일까지 만들어 놓고 결과물은 코드에 박힌 옛 값을 쓴 사고가 있었다.
값의 절반이 틀렸는데 에러는 0건이었고 그래프도 멀쩡해 보였다.

• 단일 출처를 정하고, 나머지 경로는 덮어쓰거나 없앤다.
• "산출물의 값 == 측정값" 대조를 완료 기준에 넣는다.
• 단위·기준이 섞일 수 있는 값은 출처 필드를 함께 기록해 나중에 혼용을 검출한다.

7. 외부 공유는 별도 단계다

로컬에 먼저 쓴다. 외부 문서·공유 채널 반영은 사용자 지시가 있을 때만 별도로 진행한다
(→ [[docs-append]]). 기록과 공유를 한 번에 하면 초안이 그대로 공개된다.

연계

• 설득·채택 요청이 목적이면 [[adoption-proposal]]
• 결과를 검증할 때는 [[work-review]]

이력 (필수 기록)

• 생성일: 2026-08-27
• 업데이트 횟수: 0
• 사용 이력:
  • 2026-08-27 — 프로젝트 전용 스킬을 일반화해 이관. 목적을 "보고서 작성"이 아니라
    재현·비교로 다시 세우고, 특정 과제의 기준 산출물·외부 문서 반영 절차는 걷어냈다.
    §6(값의 단일 출처)은 실제 사고에서 나온 조항이다.