나날랩스 블로그"소프트웨어 연구노트"나 "SW 연구노트 작성법"을 검색하면 나오는 글 대부분은 특정 서비스가 깃허브 레포지토리를 연동해 커밋 이력·이슈·코멘트를 자동으로 모아준다는 소개다. 편리해 보이지만, 정작 실무자가 궁금한 건 그다음이다 — 그렇게 모인 커밋 로그가 정부 R&D 과제나 기업부설연구소가 요구하는 연구노트 요건을 실제로 만족시키는가, 아니면 나중에 실태조사·세액공제 사후관리에서 따로 걸리는 부분이 남아 있는가. 이 글은 국가연구개발사업 연구노트 지침이 요구하는 항목을 기준으로, 커밋 이력이 채우는 부분과 채우지 못하는 부분을 나눠서 정리한다.
지침은 매체를 가리지 않는다 — 그런데 왜 SW팀에서 헷갈리나
국가연구개발사업 연구노트 지침(과학기술정보통신부 고시, 원문)은 연구노트를 "연구개발과제의 수행 과정과 연구개발성과를 기록하는 자료"로 정의하고, 서면 또는 전자문서 형태를 모두 인정한다. 2021년 개정으로 형식 요건이 완화되면서 영상·음성·사진 같은 기록도 허용 범위에 들어왔고, 구체적인 요건과 방식은 연구개발기관이 자체 규정으로 정하도록 위임돼 있다. 이 때문에 "레포지토리 자체가 기록 매체 아닌가"라는 질문이 자연스럽게 나온다.
문제는 지침이 매체를 가리지 않는 대신, 매체와 무관하게 요구하는 성질이 있다는 점이다 — 즉시성(작업 직후 시간순 기록), 정정 흔적 보존(고치더라도 원문이 남아야 함), 기록자·점검자 확인(누가 쓰고 누가 확인했는지). 커밋 이력은 이 세 가지를 자동으로 만족시키는 부분도 있고, 구조적으로 만족시키지 못하는 부분도 있다.
커밋 이력이 채우는 것과 못 채우는 것
| 지침 요구사항 | 커밋 이력이 자동으로 채우는가 | 비고 |
|---|---|---|
| 즉시성(작업 직후 시간순 기록) | 부분적으로 O | 커밋 시각은 로컬 시스템 시계 기준이라 조작 가능 — 원격 저장소 수신 시각과 다를 수 있다 |
| 기록자 확인 | O | 커밋 author·committer로 자동 식별 |
| 정정 흔적 보존 | X — 오히려 위험 | force-push·rebase·squash는 이전 이력을 지운다. 브랜치 보호 없이 쓰면 "정정 없이 삭제"가 된다 |
| 실험 목적·방법·해석 | X | "fix bug", "wip" 같은 커밋 메시지는 목적·해석을 담지 않는다 — 별도로 채워야 한다 |
| 실패한 실험 기록 | X | 되돌린 작업의 커밋 자체를 지우면 실패 이력이 로그에서 사라진다 |
| 점검자 확인 | 부분적으로 O | PR 리뷰·승인이 대응될 수 있으나, 리뷰어 지정을 기관 규정에 명시해야 "점검자"로 인정받기 쉽다 |
가장 큰 함정은 정정 흔적이다. 지침이 요구하는 정정 방법은 "원문이 보이게 두 줄을 긋고 서명·날짜를 남기는 것"에 해당하는데, git의 기본 워크플로 (특히 force-push로 히스토리를 다시 쓰는 습관)는 정반대로 작동한다 — 원문을 지우고 새 이력으로 덮어쓴다. 실태조사나 세액공제 사후관리에서 "이 시점 기록이 왜 사라졌나"라는 질문에 답하지 못하면, 커밋 이력 전체의 신뢰성이 흔들릴 수 있다.
SW 연구노트로 인정받으려면 최소한 이것부터
- 메인·릴리스 브랜치는 force-push·히스토리 재작성 금지로 보호한다
(GitHub 기준 branch protection). 정정이 필요하면 새 커밋으로 덧붙이고, 사유를 커밋 메시지에 남긴다.
- 커밋 메시지에 "무엇을·왜"를 남긴다. "fix", "update" 대신 실험 목적과
결과 요약을 한 줄이라도 적는다 — 나중에 지침이 요구하는 "실험명·목적"· "결과와 해석" 항목을 커밋 로그에서 재구성할 수 있어야 한다.
- PR 리뷰어 지정을 팀 규정에 명시해, 리뷰 승인이 "점검자 확인"에
대응한다는 근거를 남긴다.
- 실패한 실험은 revert 커밋으로 남기고 사유를 적는다 — 브랜치를 통째로
삭제하거나 force-push로 지우지 않는다.
- 레포지토리 자체의 보존을 별도로 챙긴다. 서비스 계정 해지·조직 이전·
비공개 전환에 대비해, 과제 규정이 요구하는 보존기간 동안 접근 가능한 백업을 확보한다 — 이는 전자연구노트 백업이 실제로 요구하는 것과 같은 문제다.
- 데이터셋 버전·하이퍼파라미터 같은 코드 밖의 조건은 별도로 기록한다.
커밋은 "무엇을 바꿨는가"는 남기지만, 실험을 재현하는 데 필요한 외부 조건 (데이터 출처, 실행 환경)까지는 자동으로 담기지 않는다.
결국 커밋 이력은 SW 연구노트의 뼈대는 될 수 있어도, 지침이 요구하는 성질 (특히 정정 흔적과 실패 기록)을 만족시키려면 팀 차원의 워크플로 규칙이 따로 필요하다. 적용 전에는 소속 기관·과제의 자체 연구노트 규정을 함께 확인하는 것이 안전하다.