AI 3. AI 가 같은 함정에 두 번 빠지지 않게: 작업 메모를 파일 하나에 한 가지씩 남기기

이번 주에 서버 여섯 대를 정리했습니다. 메일, 인증, 비밀번호 관리자, 채팅, 사업 사이트는 새 노드 세 대로 옮기고, 파일 서버는 백업한 뒤 껐습니다. 하루에 끝날 일이 아니라 세션을 여러 번 나눠서 AI 와 같이 했는데, 세션이 바뀔 때마다 걸리는 게 있었습니다. 앞 세션에서 겪은 함정을 다음 세션이 모른다는 겁니다.

Claude Code 에는 프로젝트별 메모리 폴더가 있고, 세션마다 그 폴더의 목차 파일을 읽고 시작합니다. 여기에 메모를 남기는 방식을 정해 두었습니다.

• 파일 하나에 사실 하나. 서버 하나의 이전 상태, 함정 하나, 결정 하나.
• 앞부분에 이름과 한 줄 설명. 목차에는 이 한 줄만 올라갑니다.
• 결정이나 작업 상태는 본문 끝에 Why(왜 남기는지)와 How to apply(다음에 어떻게 쓸지)를 붙입니다.
• 날짜는 “어제” 가 아니라 실제 날짜로.
• 관련 메모끼리는 이름으로 서로 가리킵니다.

예를 들면 메일 서버 이전 메모의 일부는 이렇습니다.

**Why:** 복원 중 발견한 함정 세 가지는 다음 세션이 다시 겪지 않아야 한다.
- backup_and_restore.sh restore 는 mailcow.conf 의 DOCKER_COMPOSE_VERSION=native 가 없으면 중단한다.
- 복원 스크립트는 -f docker-compose.yml 로 재기동해 override 가 빠진다.
- 비대화식 복원 입력은 printf '1\n0\nY\n' |

효과가 있었던 건 함정 메모였습니다. “plink 로 스크립트를 표준입력으로 넘기면 docker compose exec 가 뒷줄을 먹는다” 는 메모를 한 번 남기고 나니, 다음 서버 이전에서는 처음부터 스크립트를 파일로 올려 실행했습니다. “DNS 업체가 DNSSEC 질의에만 옛 값을 준다, 공용 반영 약 50분” 메모 덕분에 그 뒤로는 DNS 를 바꾸고 50분은 옛 서버를 넘김용으로 남겨 두는 게 기본이 됐습니다. 이 블로그의 트러블슈팅 글 상당수가 사실 이 메모에서 나왔습니다.

결정 메모도 쓸모가 있었습니다. “방화벽은 서버의 firewalld 를 끄고 OCI 보안 목록 한 곳에서만 관리한다(2단은 복잡해서 사용자가 거부)” 같은 줄이 있으면, 다음 세션이 같은 제안을 또 하지 않습니다.

남기지 않는 것도 정했습니다. 코드나 저장소 문서를 보면 알 수 있는 것, 그 대화에서만 의미 있는 것, 그리고 비밀값입니다. 지도 API 키를 넣던 날의 메모에는 “키 값은 저장하지 않는다, 서버의 설정 파일에 있다” 라고만 적었습니다.

메모가 틀릴 때도 있습니다. 채팅 서버 메모에 “접속 키 없음” 이라고 적혀 있었는데, 실제로는 다른 서버와 같은 키로 접속이 됐습니다. 확인한 뒤에 메모를 고치면서 “옛 기록의 ‘접속 키 없음’ 은 틀렸다” 를 같이 적었습니다. 틀린 메모를 조용히 지우기보다 틀렸다고 남기는 편이, 같은 기억을 가진 다음 세션에 덜 헷갈립니다. 메모에 파일 이름이나 경로가 나오면 쓰기 전에 실제로 있는지 확인하는 것도 규칙으로 두었습니다.

메모가 늘어나면 목차도 길어집니다. 지금은 열다섯 개 남짓이고, 서버 이전이 끝난 메모는 한 줄 요약만 남기고 정리할 생각입니다.