기록 메모. 이 글은 변경이 쌓일수록 왜 이 코드가 여기 있는가를 다시 찾는 시간이 커져서 남겼다. 문서를 설명서로 두기보다, 새 논문·실험·구현이 같은 지도를 갱신하도록 정본으로 삼았다.
코드는 남아 있는데, 왜 이 변경을 했는지는 어디에서 다시 찾을 수 있을까? 프로젝트가 커지면서 논문 노트, 환경 설정, 학습 코드, 실험 결과가 서로 다른 곳에 쌓였다. 처음에는 각 자료를 잘 보관하면 충분하다고 생각했지만, 시간이 지나자 자료 사이의 연결이 더 큰 문제라는 것을 알게 됐다. 이 글은 Theory.md를 긴 설명서가 아니라, 현재의 구현을 다시 이해하기 위한 지도로 쓰게 된 이유를 기록한다.
문제가 된 것은 정보 부족이 아니라 기준점의 부재였다
새로운 논문을 읽거나 실험을 하나 추가할 때마다 관련 자료는 늘어났다. 하지만 코드를 열었을 때 그 변경이 어떤 가설에서 나왔는지, 결과가 다시 어떤 판단을 바꿨는지는 파일 하나만 보고 알기 어려웠다. 모든 내용을 하나의 문서에 복사하는 방법도 생각했지만, 같은 설명이 여러 곳에 생기면 어느 것이 최신인지 다시 불분명해진다. 그래서 모든 내용을 모으는 대신, 각 내용의 정본과 관계를 보여 주는 지도 한 장을 유지하기로 했다.
이론 지도는 설계와 구현 사이를 잇는다
Theory.md에는 로봇을 움직이는 방식의 세부 코드를 적기보다, 현재 프로젝트가 어떤 질문에서 어떤 단계로 이어지는지를 남긴다. 논문에서 얻은 근거는 연구 노트에, 실제 환경과 학습의 구현은 각각의 작업 공간에 두고, 이 문서에서는 서로 어디에서 만나는지 연결한다. 이렇게 나누면 문서가 코드를 대체하지도, 코드가 판단의 이유를 숨기지도 않는다. 내가 이 구조를 고른 이유는 새로운 사람이 보기 좋게 만들기보다, 나 자신이 몇 주 뒤에도 같은 결정을 검토할 수 있게 하기 위해서였다.
변경이 생길 때마다 지도를 고치는 이유
구현을 바꾸는 순간에는 코드가 먼저 바뀌고 기록은 나중으로 밀리기 쉽다. 그러나 기록을 미루면 다음 실험에서 “무엇을 바꿨는가”만 남고, “무엇이 달라질 것이라 예상했는가”가 빠진다. 그래서 새 논문을 채택하거나 환경·정책·평가 기준을 손볼 때는 이론 지도와 실험 기록도 같은 판단의 일부로 고치기로 했다. 이 규칙은 문서 작업을 늘리기 위한 것이 아니라, 변경의 영향 범위를 작게 나누어 확인하기 위한 장치였다.
실험 결과는 숫자가 아니라 다음 질문으로 남긴다
숫자 하나가 좋아졌다고 해서 어떤 설계가 옳다고 단정하기는 어렵다. 결과가 기대와 달랐을 때는 관측이 부족했던 것인지, 환경의 조건이 달랐던 것인지, 평가가 질문을 놓친 것인지 다시 봐야 한다. 그래서 실험 기록에는 결과뿐 아니라 그 결과를 어떻게 해석했고 다음에 무엇을 비교할지를 함께 남긴다. Theory.md는 이 기록들이 흩어지지 않게 하며, 같은 문제가 이전에도 있었는지를 찾아볼 기준점이 된다.
지도는 완성본이 아니라 계속 고치는 작업물이다
처음부터 완벽한 이론 지도를 만들 수는 없었다. 실제로 구현하면서 새 연결이 생기고, 처음에 중요하다고 생각했던 항목이 덜 중요해지기도 했다. 그래서 이 문서를 결론 모음집으로 만들기보다, 바뀐 이유가 남아 있는 변경 가능한 지도로 유지한다. 오늘의 결론은 간단하다. 문서는 구현이 끝난 뒤 붙이는 해설이 아니라, 구현이 길을 잃지 않도록 곁에서 같이 고쳐야 하는 기준이다.
다음에는 코드와 데이터, 모델처럼 성격이 다른 결과물을 왜 같은 방식으로 보관하지 않았는지 적어 보려 한다.