인프라 3연타 뒤의 문서 빚 청산 — 자동 로드 문서가 낡으면 생기는 일

지난 닷새 동안 인프라가 세 번 크게 움직였다. 개인 백엔드를 EC2에서 노트북으로 내렸고(09-03), Arda 팀 백엔드는 신규 인스턴스로 분리했고 (09-04), 노트북 프로덕션을 k3s 1단계로 컷오버했다(09-07). 오늘은 코드 대신 문서를 정리했다 — 그 세 번의 변화를 문서들이 하나도 따라오지 못하고 있었기 때문이다.

진단 — 배치는 멀쩡했고, 시점이 문제였다

루트 _docs/ 10개 문서를 전수로 훑었다. 폴더 배치나 역할 분리는 규칙대로 잘 굴러가고 있었다. 문제는 전부 시점 불일치였다:

문서	낡은 서술	실제
루트 CLAUDE.md	“EC2가 개인 프로덕션, compose로 폴백”	프로덕션은 노트북 k3s, compose는 삭제됨
CLAUDE.md 주의사항	“EC2 디스크 30GB 대응법”	개인 EC2는 중지 보관 — 대상 자체가 소멸
PROGRESS	“EC2 개인 스택 down·t3.small 축소 남음”	09-04 결정 변경으로 폐기된 할 일
서브도메인 계획서	“개인 EC2를 Arda용으로 재활용”	신규 arda-api 생성으로 뒤집힘
EXAONE 셋업 문서	fp16 hf 서빙	09-02부터 llama.cpp GGUF

왜 CLAUDE.md부터인가

이 중 제일 위험한 건 루트 CLAUDE.md였다. 하위 문서는 필요할 때만 읽히지만 CLAUDE.md는 매 세션 자동으로 전제에 깔린다. “EC2가 프로덕션”이라는 낡은 전제를 갖고 있으면, 에이전트가 존재하지 않는 30GB 디스크 문제에 대응하거나 이미 삭제된 docker compose 폴백 명령을 실행하려 들 수 있다. 문서 갱신의 우선순위는 “최신 정보 순”이 아니라 “자동 로드되는 것 먼저”라는 걸 이번에 체감했다.

고치면서 k8s 쪽 함정도 하나 명문화했다: .env 값을 바꾸고 deploy.sh를 다시 돌려도 파드에는 반영되지 않는다. Secret은 갱신되지만 파드는 기동 시점에 env를 주입받고, 같은 태그(latest) 재적용은 spec이 안 바뀌어 자동 rollout도 없다. env만 바꿨으면 kubectl rollout restart를 직접 실행해야 한다 — compose 시절 up -d --force-recreate 한 방에 익숙하면 반드시 밟는 지뢰다.

삭제 요청 앞에서 — “필요 없는 것”의 판정 기준

중간에 “docs에 필요 없는 건 삭제하자”는 요청이 왔다. 결론부터: 파일 단위 삭제 대상은 없었다. 유일한 후보였던 서브도메인 계획서는 이행이 끝난 문서지만, 워크로그가 노트북 이전의 검증값·원복 절차를 “상세는 계획서 참고”로 위임하고 있는 유일 기록이라 지우면 포인터가 깨진다.

대신 파일 안에서 잘라냈다. “팀 인프라 이전: 순서” 절(초안 55줄)은 ARDA 배포 가이드가 확정본으로 완전히 대체했고, 결정적으로 초안의 “개인 EC2 재활용” 전제가 결정 변경으로 오정보 함정이 돼 있었다. 이 저장소의 삭제 원칙 — 다른 곳에 최신판이 있는 중복·폐기본만 삭제 — 을 충족하는 유일한 덩어리였다.

폐기된 백로그(“EC2 전체 재빌드 불가”)는 지우는 대신 취소선 + 폐기 사유 한 줄로 남겼다. 흔적 없이 지우면 나중에 같은 결정(EBS 증설 vs 로컬 빌드 전송)을 다시 검토하는 낭비가 생긴다. 완료된 것은 워크로그 날짜 포인터로 압축, 뒤집힌 것은 취소선과 사유로 — 두 처리를 구분하는 게 재개용 문서를 가볍게 유지하는 요령이다.

오늘의 교훈

• 인프라를 움직인 날은 문서 빚이 생긴 날이다. 미루면 이자가 붙는다 — 낡은 서술이 자동 로드 문서에 있으면 매 세션이 이자다.
• 문서 삭제의 기준은 “오래됐나”가 아니라 “다른 곳에 최신판이 있나”다. 워크로그가 위임하고 있는 문서는 오래돼도 유일 기록이다.
• k8s에서 Secret 갱신과 파드 반영은 별개 사건이다. rollout restart까지가 env 변경이다.

산출물: CLAUDE.md + _docs/ 6개 파일 정리 커밋 1건, 워크로그 09-08, 인터뷰 질문 5문항.