홈페이지가 브라우저에 보이면 일단 만들어진 것처럼 느껴진다. 그런데 다음 수정을 하려는 순간 질문이 달라졌다. 이 화면을 만드는 원본은 어디에 있고, 어느 폴더를 고쳐야 하며, 다시 만들면 같은 결과가 나오는가.
내 작업에는 공개 페이지를 내려받아 확인한 경우와 직접 만든 소스를 배포한 경우가 함께 있었다. 공개 결과물을 검토했던 한 작업에서는 주소와 canonical을 고칠 수 있었지만, 그 파일만으로 원래의 프레임워크나 개발 저장소까지 확보했다고 말할 수는 없었다. 수정할 수 있다는 사실과 제작 원본을 갖고 있다는 사실은 달랐다.
내가 고객이라면 먼저 묻고 싶은 것
수정이 필요할 때 다시 처음부터 만들게 되는가. 나는 이 질문에 답할 수 있는 홈페이지를 남기고 싶다. 제작물을 건네는 일에는 다음 수정의 출발점까지 설명하는 책임이 있다고 생각한다.
내가 먼저 구별하기 시작한 세 가지
원본은 사람이 다음 변경을 이어갈 곳이다. 빌드 결과는 원본에서 만들어진 공개 파일이다. 배포는 그 결과를 특정 주소에서 제공하는 상태다. 세 가지를 같은 폴더 이름으로만 기억하면, 파일을 수정하고도 실제 사이트에 반영되지 않거나 생성물을 다음 빌드가 덮어쓴다.
이번 홈페이지는 주요 문구를 content.mjs에 두고 정적 HTML을 빌드하도록 만들었다. 공개 페이지에서 보이는 문구와 다음 AI가 고칠 파일의 관계를 남기는 것이 운영 준비의 시작이었다.
내가 남기는 인수인계 절차
- 원본 폴더와 공개 결과 폴더를 구별해서 적는다. src와 dist라는 이름 자체보다 생성 관계가 중요하다.
- 설치가 필요한 의존성, 빌드 명령, 출력 폴더를 기록한다. 정적 사이트라면 불필요한 서버를 추가하지 않는다.
- 원본의 문구 한 줄을 수정한 뒤 빌드 결과에서 같은 변경을 확인한다.
- 파일 수와 자산 경로를 점검하고, 배포 ID와 당시 결과의 해시를 기록한다.
- 다른 사람이 문서만 보고 한 번 빌드할 수 있는지 확인한다. 그 사람이 다시 질문해야 하는 부분을 지침에 보충한다.
주소 확인은 마지막 비교다
Pages Direct Upload는 미리 만든 결과물을 올리는 방식이다. 원본을 대신 보관해주는 기능이라고 생각해서는 안 된다. 배포 전에는 원본을 별도로 보존하고, 복구할 때는 기존 성공 버전과 소스 수정의 관계도 확인한다.
코드와 구현 살펴보기
읽기 전용 확인 예시 · 실제 프로젝트 경로로 변경
npm run build
Get-ChildItem -LiteralPath '.\dist' -Recurse -File |
Measure-Object Length -Sum
Get-FileHash -LiteralPath '.\dist\index.html' -Algorithm SHA256이 장의 완료 기준
새로운 사람이 원본을 찾아 수정하고, 같은 명령으로 빌드하고, 어느 배포에 반영됐는지 확인할 수 있어야 한다. 사이트가 한번 열린다는 사실보다 이 반복 가능한 연결이 오래 남는다. 공개 다운로드만 확보했다면 그 범위를 정확히 기록한다.