클라우드 구성을 바꿀 때 운영 설명서도 다시 써야 한다

초기 설계와 실제 운영을 한 장면으로 합치지 않는다

초기 구조 문서는 앞으로 사용할 앱과 저장소, 작업자의 관계를 계획한다. 후속 운영 기록은 그 계획과 다른 실행 방식이 등장한 시점을 보여 준다. 문서에 적힌 데이터베이스 종류를 지금 서비스 전체의 실제 값으로 읽으면 시간의 차이를 놓친다.

나는 시점과 증거의 종류를 비교표로 정리한 뒤 글을 썼다. 아래 요약도 설계와 역사적 운영, 현재 선택 응답을 나눈다. 같은 프로젝트 이름 아래의 문서라도 무엇이 계획이고 어떤 출력에서 실행을 확인했는지 함께 읽어야 한다.

1. 초기 구조 문서: 개발용 SQLite와 운영용 PostgreSQL, 앱과 별도 작업자를 계획한 설계다.
2. 8월 운영 기록: 워커와 컨테이너, 컨테이너 SQLite와 외부 영속 저장, 배포 버전과 백업 절차를 다뤘다.
3. 9월 26일 변경 기록: 로컬 SQLite와 실행 서비스, 터널 경로로 설명서를 고쳤다. 같은 발행 통로를 쓰는 원칙은 유지했다.
4. 현재 선택한 공개 응답: 주소와 본문을 읽은 결과다. 외부 응답만으로 현재 앱과 DB 전체를 확인한 것은 아니다.

바뀐 절차는 예전 안내의 반대가 될 수 있었다

9월의 문서 수정은 이전의 이중 쓰기와 백업 요청, 배포 도구를 새 운영 경로에 그대로 적용하지 않도록 정정했다. DB가 로컬 운영 파일이 되었어도 쓰기를 공통 통로에 모으는 원칙은 유지했다. 접근 방식이 바뀐 것과 규칙의 목적이 바뀐 것을 구별한 설명이다.

나는 더 이상 맞지 않는 명령을 문서 뒤에 그냥 남겨 두지 않으려 한다. 역사로 보존할 내용이면 시점과 상태를 표시하고, 현재 진입점은 어느 절차인지 명확하게 둔다. 새 작업자가 가장 먼저 발견한 옛 예제를 현재의 실행 지시로 오해하지 않아야 한다.

어떤 서비스가 무슨 일을 맡는지도 다시 적었다

변경 안내는 공개 서비스와 편집용 실행, 수집기와 백업, 터널의 책임을 나누었다. 수집은 정해진 실행 서비스가 맡고 편집 작업에서 다른 수집기를 함께 띄우지 않도록 설명했다. 배포만 바꿔 놓고 실행 책임을 그대로 두면 같은 작업이 겹칠 수 있었다.

이 기록은 현재 모든 서비스의 가동 상태를 새로 점검한 결과가 아니다. 당시 실행 파일과 문서가 어떤 역할을 설명하는지 읽은 근거다. 다른 사이트에서도 실제 실행 주체와 데이터 저장 위치, 백업 경로를 함께 바꾸어 설명해야 작업의 중복과 잘못된 복구 판단을 줄일 수 있다.

현재 공개 경로의 확인은 필요한 범위만 말한다

공개 주소에서 본문을 읽을 수 있다는 사실은 방문자의 경로를 확인하는 데 유용하다. 하지만 그 응답만으로 지금 어떤 DB를 쓰고 어떤 실행 서비스가 모든 작업을 처리하는지 알 수는 없다. 내부 구성과 외부 전달은 서로 다른 증거가 필요하다.

나는 이번 제작기에서 과거 실행 기록과 현재 공개 응답을 따로 남겼다. 옛 구조가 지금도 모두 그대로라는 단정도, 새 구조 전체를 외부에서 검증했다는 말도 하지 않는다. 원본 서비스를 다시 배포하거나 다른 운영 사이트를 수정한 결과로 소개하지 않는다.

문서는 현재 정본으로 들어가는 길이어야 한다

다른 컴퓨터와 AI가 이어 작업하려면 명령만 복사할 수 있는 문서로는 부족하다. 어느 시점의 구조인지, 먼저 읽을 정본은 무엇인지, 어떤 작업이 데이터를 바꾸고 무엇을 확인해야 하는지 찾아갈 수 있어야 한다. 비밀값은 그런 안내의 공개 예제와 분리한다.

나는 변경 이유와 폐기된 절차, 유지한 원칙을 함께 남기고 싶다. 홈페이지가 계속 자란다는 것은 코드와 데이터뿐 아니라 그 홈페이지를 다루는 설명도 함께 바뀐다는 뜻이었다. 운영 설명서의 정정은 새 기능을 붙인 뒤에 남는 부수 작업이 아니라 다음 작업의 정확한 출발점이었다.