분석 파일을 모두 넘겼는데 ‘어느 파일부터 실행하나요?’라는 질문이 돌아오는 상황을 가정해 볼게요. 담당자를 바꾸는 데 필요한 것은 파일의 개수보다 입력·명령·예상 결과의 연결이에요. 이번에는 8행의 합성 자료를 집계하는 작은 프로젝트를 만들고, 기존 결과 없이 새 임시 환경에서 다시 실행한 기록까지 붙였어요.
첨부 링크는 이 글의 예제 ZIP으로 연결돼요. 압축을 푼 뒤 링크에 표시된 파일을 열면 입력·코드·완성 자료를 함께 사용할 수 있어요.
인수인계 프로젝트 ZIP에는 README, 자료 사전, 코드, 기대 결과, 입력 해시가 들어 있어요. Codex가 작성하고 2026년 10월 13일 WSL의 Python 3.12.3에서 원래 폴더와 새 가상환경을 각각 실행했어요. 같은 호스트의 자체 자동 확인이며, 다른 사람이 받은 뒤 실행한 독립 인수인계 시험이나 다른 운영체제 검증은 아니에요.
남길 파일과 다시 만들 파일을 나눠요
예제의 질문은 ‘관측된 시행의 집단별 성공률은 얼마인가’예요. data/trials.csv에는 control 3행, treatment 5행이 있어요. 값은 성공 1·실패 0·빈칸 미측정으로 정의했어요. treatment의 마지막 시행 s8은 빈칸이므로 분모에서 제외하고 예외 파일에 남겨요.
handoff-project/
README.md
data/trials.csv
src/analyze.py
src/verify.py
expected/summary.csv
results/summary.csv
results/exceptions.json
docs/data-dictionary.md
docs/change-log.md
input-manifest.json
data는 입력 정본, src는 처리 규칙, results는 다시 만들 수 있는 결과예요. expected는 작은 자료를 손으로 계산한 정답이에요. 결과가 다르게 나왔다고 expected를 새 출력으로 덮어쓰면 검사의 기준이 사라져요. 입력과 규칙이 의도적으로 바뀌었을 때만 정답 변경 이유를 기록해야 해요.
이 구분은 과학계산 실무 지침의 원자료·프로젝트 설명·코드·결과 관리 권고를 작은 프로젝트로 구체화한 것이에요. 실제 프로젝트에 외부 DB가 있다면 자료를 무조건 복사하기보다 데이터 버전, 추출 조건, 필요한 접근권한과 담당자를 기록해야 해요. 이번 예제에는 계정이나 외부 자료 접근이 없어요.
‘성공률이 비슷하게 나오면 된다’ 대신 허용 차이를 적어요
기대 결과는 control 성공 2건/유효 3건=0.666667, treatment 성공 3건/유효 4건=0.750000이에요. 총 8행 중 유효 7행·예외 1행이에요. 빈칸을 실패 0으로 채웠다면 treatment는 3/5=0.6이 되므로, 결측 규칙이 결과를 크게 바꿔요.
| 집단 | 성공 수 | 유효 분모 | 저장할 성공률 |
|---|---|---|---|
| control | 2 | 3 | 0.666667 |
| treatment | 3 | 4 | 0.750000 |
코드는 소수 6자리에서 ROUND_HALF_UP으로 반올림하고 그룹 이름을 정렬해요. 줄바꿈도 고정했으므로 이번 시험은 결과 CSV가 기대 CSV와 바이트 단위로 정확히 같은지 확인해요. 부동소수 계산이나 무작위 모델이 있다면 이런 기준이 맞지 않을 수 있어요. 그때는 허용 절대·상대 오차와 난수 시드, 비교할 통계를 명시해야 해요. ‘거의 같다’는 판단을 수신자에게 남기지 않는 것이 핵심이에요.
이 자료에는 무작위 배정이나 독립 시행이라는 설계가 없어요. 따라서 0.75와 0.666667의 차이를 처치 효과나 통계적으로 유의한 개선으로 해석하지 않아요. 인수인계 파일에도 분석의 범위가 같이 들어가야 후속 사용자가 숫자의 의미를 확대하지 않아요.
처음 받는 상황을 흉내 낼 때 기존 결과를 가져가지 않아요
프로젝트 폴더에서 아래 명령을 차례로 실행해요. 외부 패키지는 없고 Python 표준 라이브러리만 사용하므로 pip 설치도 필요하지 않아요.
python3 -m venv --without-pip .venv
.venv/bin/python src/analyze.py
.venv/bin/python src/verify.py
가상환경은 기존 Python 위에 별도의 패키지 환경을 만드는 기능이에요. 환경 폴더 자체를 옮기는 대신 대상 위치에서 새로 만들라는 점은 Python 3.12 venv 문서에서 확인할 수 있어요. 이번에는 전체 운영체제가 새로 설치된 것은 아니에요. 패키지와 경로 의존성을 줄이는 검증 범위라고 이해하면 돼요.
실제 확인에서는 새로운 임시폴더에 프로젝트를 복사하되 results를 가져가지 않았어요. 다른 임시폴더에 venv를 새로 만들고, 프로젝트 루트 바깥을 작업 디렉터리로 삼아 코드를 실행했어요. 분석 코드가 현재 셸의 위치가 아니라 자기 파일의 위치를 기준으로 입력을 찾게 했기 때문에 이 조건에서도 실행됐어요.
실행 로그 (ZIP: clean-run-log.json)에는 원래 환경과 새 환경의 명령·종료 코드·출력이 있어요. 두 환경 모두 입력 SHA-256 일치, 기대 CSV 정확 일치, s8 미측정 예외 1행을 확인했어요. 기존 결과를 우연히 열어 놓고 재현됐다고 착각하는 경로를 피한 검사예요.
실패했을 때의 첫 행동도 README에 넣어요
파일이 없다는 오류라면 data와 src를 함께 받았는지 확인해요. 입력 해시가 다르면 새로 승인된 입력인지 확인하고 예전 정본을 보존해요. 출력만 다르다면 입력·코드·환경 버전을 대조하고, 중간 결과를 손으로 고치지 않아요. SHA-256 일치는 같은 파일을 썼다는 확인이지 자료 내용의 진실성을 보장하는 표시는 아니에요.
실패 대응이 실제 검사와 연결되는지도 다섯 조건으로 확인했어요. 재실행 코드 (ZIP: check-failure-scenarios.py)는 전달 ZIP을 매번 다른 임시폴더에 풀고 기존 결과를 지운 뒤 검사해요. 조건별 결과 (ZIP: failure-scenarios.json)에는 기대한 실패와 실제 종료 내용을 함께 남겼어요.
| 바꾼 조건 | 관측 결과 | 다음 행동 |
|---|---|---|
| 새 가상환경·프로젝트 밖에서 실행 | 정답과 일치 | 입력·코드·결과 연결 확인 |
| 가상환경 없이 표준 Python으로 실행 | 같은 정답과 일치 | 외부 패키지가 없는 이 예제의 대안으로 사용 |
| 입력에 빈 줄 추가 | 입력 해시 불일치로 중단 | 내용 변경인지 저장 형식 변경인지 확인 |
| 출력 성공률만 0.75→0.60으로 수정 | 정답 불일치로 중단 | 입력·규칙을 대조하고 출력 수작업 수정을 취소 |
| 입력 CSV 제거 | 파일 없음으로 중단 | 자료 폴더까지 다시 전달 |
가상환경 없이 실행하는 대안은 이 예제가 외부 패키지를 쓰지 않을 때만 성립해요. 필요한 패키지가 있는 프로젝트에서 설치 제약을 숨기는 우회책으로 쓰면 안 돼요. 입력에 빈 줄을 추가한 검사는 수치가 같아도 파일 바이트가 달라지면 걸린다는 확인이에요. 따라서 해시 실패를 곧바로 분석 결과의 오류라고 단정하지 않고, 정본 변경의 이유부터 확인해야 해요. 이 다섯 조건도 같은 호스트의 자동 검사이며 다른 운영체제나 실제 수신자 검증은 아니에요.
실제 인수인계에는 추가로 수신자가 실행 권한과 자료를 갖고 있는지, 외부 패키지를 설치할 수 있는지, 결과를 누구에게 확인받을지가 필요해요. 이번 README에는 Windows 경로의 형태를 참고로 적었지만 Windows Python 실행은 검증하지 않았어요. 사람에게 넘겼다면 ‘이 문서만 보고 처음부터 실행해 주세요’라는 확인을 별도 기록해야 해요.
이 예제의 완료 범위는 재실행 가능한 작은 묶음과 같은 호스트에서의 복원 확인이에요. 그 다음 인수인계에서 확인할 질문은 간단해요. 수신자가 내 설명 없이 올바른 입력을 골라 실행하고, 다른 결과가 나왔을 때 어디부터 확인할지 알 수 있는가예요.
인수인계 전에 계산 정답을 더 점검하려면 작은 정답 데이터로 코드 검증로 이어서 확인할 수 있어요.
예제 파일을 한 번에 받아 다시 확인해요
이 글의 입력·코드·완성 자료 ZIP을 새 폴더에 풀면 R29/README.txt, replay.py, assets 폴더가 함께 생겨요. 개별 코드 파일만 저장하면 보조 모듈이나 입력이 빠질 수 있으므로 처음에는 이 묶음을 사용하세요. R29 폴더에서 다음 명령을 실행하면 본문에 사용한 검사를 순서대로 수행해요.
python3 replay.py
확인할 결과는 새 venv/표준 Python 성공, 입력변경·출력변경·입력누락 검출예요. 명령이 성공해도 이 값과 본문의 적용 범위를 함께 대조하세요. 실행 안내 (ZIP: README.txt)에 필요한 파일과 개별 명령을 적었어요. 실행 코드는 check-failure-scenarios.py (ZIP: check-failure-scenarios.py)에서 직접 볼 수 있어요. Python3.12의 표준 라이브러리를 사용하며, 명령이 실패하면 ZIP의 폴더 구조와 오류에 나온 파일부터 확인해요. 실제 앱 실행에 필요한 프로그램은 원래 설명을 따르세요.
설명 삽화 2장은 GPT로 생성한 개념 설명이에요. 실제 예제의 작업 화면과 실행 결과는 기존 그림·첨부 자료에서 따로 확인할 수 있어요.