Test Drive II를 SNES에서 PC로 포팅하기, 파트 5: 생성된 증거를 의도적으로 만들기

Source: Dev.to

이 저장소에서 다음 정리 작업은 눈에 띄는 것이 아니었습니다.
그것은 **git status**였습니다.

3월 19일 현재, asmdump는 이미 충분한 고고학 도구를 갖추어 다음을 생성할 수 있었습니다:

• 프로브 트레이스
• 프레임 덤프
• 시퀀스 매니페스트
• 디자인 팩
• 렌더러 픽스처
• 게임플레이‑스윕 출력
• 레이트‑인트로 진단

이는 좋은 진전이지만, 새로운 실패 모드를 만들기도 합니다. 역공학 저장소가 실험당 수백 개의 파일을 작성한다면, “generated”(생성된)라는 카테고리는 더 이상 유용하지 않게 됩니다.

• 일부 생성 파일은 버려도 되는 임시 파일입니다.
• 일부는 문서와 체크포인트가 의존하는 승격된 증거 아티팩트입니다.
• 일부는 하루 정도만 중요한 로컬 중간 실행 파일이며, 그 후에는 사라져야 합니다.

저장소가 이러한 카테고리를 명확히 표시하지 않으면, 진행 상황을 신뢰하기가 어려워집니다.

Source: …

실제 문제는 모호함이었다

현재 포트 계획은 유지보수성을 일류 실행 트랙으로 다루고 있으며, 이는 올바른 판단입니다.

문제는 레포에 정리 스크립트가 없었기 때문이 아니라 작업 표면이 모호해졌다는 점이었습니다:

• tools/out 에는 실제 증거와 일회성 실험이 모두 섞여 있었고
  • 에뮬레이터 출력이 가변적인 로컬 폴더에 쌓일 수 있었으며
  • 의미 있는 변화가 없더라도 새로운 로컬 실행이 작업 트리를 범람시킬 수 있었습니다

그러한 모호함은 이와 같은 프로젝트에서 위험합니다. 이 레포는 단순히 게임을 만드는 것이 아니라 게임에 대한 논증을 구축하고 있습니다:

• 어떤 프레임 동작이 이해되는가
• 어떤 산출물이 권위 있는가
• 어떤 격차가 아직 남아 있는가
• 어떤 실험이 단지 스크래치에 불과한가

작업 트리가 이러한 구분을 전달하지 못한다면, 고고학적 분석은 금방 시끄러워집니다.

무차별 정리는 잘못된 해결책이었을 것이다

이와 같은 레포지토리에는 유혹적인 정리 방법이 있습니다:

“tools/out을 그냥 삭제한다.”

하지만 여기서는 실수가 되었을 것입니다. tools/out은 단순히 캐시가 아닙니다. 여기에는 승인된 증거도 포함되어 있습니다:

• SDL 런타임에서 사용되는 시퀀스 매니페스트
• 문서에서 참조되는 프로프 번들
• 렌더러 픽스처
• 브리지‑가시 인트로 아티팩트
• 이제 특정 레이트‑인트로 프레임의 진실된 소스로 작동하는 OAM‑델타 보고서

따라서 올바른 질문은 **“출력을 더 많이 삭제하는 방법은?”**이 아니라
**“레포가 자체 증거를 삭제하도록 만들지 않으면서 일일 작업‑트리 잡음을 어떻게 줄일 수 있을까?”**였습니다.

그 차이가 중요합니다.

이번 체크포인트에서 레포‑위생 작업은 실제로 가장자리 문제를 직접 드러냈습니다. tmp_*와 test_* 같은 명명 규칙만으로는 충분하지 않았는데, 그 이름을 가진 일부 파일이 의도적으로 이미 트래킹되고 있었기 때문입니다. 바로 이 때문에 정리 정책은 열망적인 것이 아니라 명시적인 것이어야 합니다.

체크포인트에서 무엇이 바뀌었나요

리포지터리‑위생 커밋 8b2e3fc가 2026‑03‑19에 적용되면서 경계가 훨씬 명확해졌습니다. 변경 사항 자체는 간단하지만, 그 뒤에 있는 모델이 핵심입니다.

1. tools/out이 이제 기본적으로 무시됩니다

• tools/out 아래에서 새로 생성된 로컬 실행 결과가 더 이상 git status에 떠서 방해하지 않습니다.
• 이미 tools/out에 추적되고 있는 파일은 여전히 정상적으로 동작합니다.

여기가 핵심 포인트입니다: 리포는 프로모션된 생성 아티팩트를 지원하지 않게 된 것이 아니라, 매번 새로 생성된 파일이 즉시 의미 있는 작업 트리 잡음으로 나타나는 것을 더 이상 가장하지 않게 된 것입니다.

2. 프로모션이 이제 명시적입니다

새로운 tools/out 아티팩트가 실제로 리포지터리의 증거 집합에 포함되어야 한다면, 이제는 git add -f와 같은 의도적인 행동을 통해 진행합니다.
이는 수동적인 프로모션보다 더 건강한 방식입니다. 증거는 팀이 권위 있다고 판단했을 때 프로모션되어야 하며, 단순히 또 하나의 실험 후에 우연히 나타났다고 해서 자동으로 포함되어서는 안 됩니다.

3. 정리는 보수적으로 유지됩니다

생성 아티팩트 정리 도구는 다음과 같은 명백한 임시 출력은 처리하지만:

• tmp*
• test_*
• 오래된 smoke / makecheck / designtest 결과물

추적된 경로는 건너뜁니다. 이 방어 장치는 추가 패턴보다 더 중요합니다. 즉, 정리 도구가 프로모션된 증거 아티팩트를 조용히 파괴하지 않으면서도, 불필요한 잡동사니를 회수할 수 있다는 의미입니다. 이는 이 리포에 적절한 균형입니다. 정리는 증거 표면에 대한 신뢰를 높이기 위해 존재하며, 이를 지우기 위해 존재하지 않습니다.

실제 포트 작업에 이것이 중요한 이유

이는 단순히 청소를 위한 것이 아닙니다. 현재 남아 있는 기술적 차단 요소들은 여전히 다음과 같습니다:

• 958..977 부트스트랩 격차 해소
• 986+ 최종 화면 구성 격차 수정
• 샘플링된 attract 구간을 네이티브 콜백/상태 재생으로 계속 교체
• 은행 및 콜백 계약을 지속적으로 강화

이 작업들은 모두 다음과 같은 지루하지만 중요한 질문에 답할 수 있어야 진행할 수 있습니다:

“지금 어떤 아티팩트를 신뢰해야 할까?”

이 체크포인트 이후로 레포지토리는 그 질문에 더 잘 답할 수 있는 위치에 있습니다. 현재 작업 모델은 다음과 같이 명확해졌습니다:

• 추적된 생성 아티팩트 → 의도된 증거
• 추적되지 않은 생성 실행 → 로컬 작업 상태
• 정리 → 증거가 아닌 임시 파일 제거

이렇게 하면 나중에 고고학 작업을 수행할 때 비용이 줄어듭니다. 파일이 다음 중 어느 상태인지 재평가하는 데 소요되는 시간이 감소하기 때문입니다:

• 최신 여부
• 오래됨 여부
• 권위 있음 여부
• 폐기 가능 여부

프로젝트에 여러 동시에 진행되는 작업 표면이 존재하는 지금, 이는 특히 중요합니다:

• ROM 고고학
• C/SDL 런타임 재생
• 브리지 추출
• 렌더러 검증
• 게임플레이 프레임 추적

위생이 없으면 이러한 표면들이 서로 뒤섞이게 됩니다. 위생을 유지하면 서로를 강화시킬 수 있습니다.

다음 정리 대상은 이식성

이 체크포인트는 정리 트랙을 마무리하는 것이 아니라, 중요한 한 부분을 마감합니다: 생성된 증거가 이제 더 의도적입니다.

로드맵에서 다음 이식성 측 작업은 여전히 명확합니다:

• 승격된 스크립트와 Makefile에서 하드코딩된 개인 Mesen 경로를 제거합니다
• 검증 출력이 격리되고 재현 가능하도록 유지합니다
• …에 대한 intro‑side 고고학을 계속 진행합니다

(…계획의 나머지는 다음 체크포인트에서 계속됩니다.)

더 깔끔한 워크플로우

그것이 올바른 순서입니다.

리포는 먼저 모든 로컬 생성 파일에 대해 소리를 지르는 것을 멈춰야 했습니다. 이제는 프로모션된 도구를 덜 기계에 의존하도록 만들 수 있습니다.

왜 이것이 전체 체크포인트에 해당했는가

이와 같은 프로젝트는 종종 정리를 직접적으로 더 나은 프레임을 만들지 않기 때문에 그 가치를 낮게 평가합니다. 이는 단기적인 사고입니다.

레포의 출력 결과가 불분명하면 이후의 모든 성공을 신뢰하기 어려워집니다. 승격이 명확하고 정리가 보수적일 때, 레포는 다음을 구분하는 데 훨씬 능숙해집니다:

• 증거
• 시도
• 진행
• 잡음

그 구분은 제품의 일부입니다.

리버스 엔지니어링을 기반으로 한 포트 프로젝트의 경우 목표는 프레임을 올바르게 보이게 하는 것만이 아닙니다. 목표는 그 프레임 뒤의 추론을 읽기 쉽고, 재현 가능하며, 유지 보수 가능하게 만드는 것입니다.

이 체크포인트는 레포를 그 방향으로 움직이게 합니다.