프로젝트 문서가 낡지 않게 하려면, 사람이 시간 날 때 고치는 문서 대신 매일 도는 자동화가 일을 마칠 때마다 그 문서를 함께 고치게 만들면 됩니다. 핵심은 두 가지입니다. 문서 맨 위에 「이 페이지를 어떻게 갱신하나」를 주석으로 적어 두고, 자동화가 고칠 칸(숫자·기록 표)에 이름표를 붙여 그 칸만 고치게 합니다. 이 글은 자동화가 고친 지침을 스스로 되돌리는 지난 편에 이어, 같은 자동화가 사람이 함께 보는 문서까지 키우게 한 이야기를 정리한 연재의 일곱 번째 편입니다.
AI 생성 이미지
왜 README 는 늘 한 달 전 이야기를 하고 있을까?
이 블로그를 포함한 개인 사이트 여러 개를 저장소 하나에서 관리합니다. 나중에 같이 개발할 사람이 생기면 무엇부터 보여 줄지 고민하다가, 구조·배포 흐름·매일 자동화가 하는 일을 한 장에 담은 HTML 페이지를 만들었습니다. 이름은 「사이트 지도」입니다.
처음 만든 날은 정확했습니다. 문제는 그다음 날부터였습니다. 매일 오전 자동화가 사이트 하나에 페이지나 글을 하나씩 더하는데, 지도의 숫자와 기록은 제가 손으로 고칠 때까지 그대로였습니다. 많은 사람이 「살아 있는 문서(living documentation)」를 찾는 이유가 이것입니다. 문서를 쓰는 것보다 계속 맞게 두는 것이 더 어렵습니다.
처음에는 어떻게 하려고 했나?
처음에는 문서를 코드에서 통째로 다시 만드는 방법을 생각했습니다. API 문서처럼 빌드할 때마다 생성하면 늘 최신이 됩니다. 하지만 이 지도에는 코드에서 뽑을 수 없는 내용이 많습니다. 「왜 이 순서로 배포하나」, 「처음 받으면 무엇부터 하나」 같은 시작 가이드와 운영 서비스 표는 사람이 쓴 문장입니다. 통째로 다시 만들면 그 문장이 사라집니다.
그래서 반대로 했습니다. 문서는 사람이 쓴 그대로 두고, 자동화가 고칠 수 있는 칸만 정해서 그 칸만 고치게 했습니다.
자동화가 엉뚱한 곳을 고치지 않게 하려면?
자동화에게 「지도를 갱신해」라고만 하면 매번 다른 곳을 고치거나 문장을 다시 써 버릴 수 있습니다. 그래서 두 가지 약속을 파일 안에 넣었습니다.
첫째, 파일 맨 위에 갱신 방법을 주석으로 적었습니다. 자동화는 이 파일을 열면 가장 먼저 이 줄을 읽습니다.
<!-- 갱신 방법: 회차 끝에 tbody#ledger 에 행 추가,
해당 사이트 카드·기준일(#base-date)·커밋(#base-commit) 갱신 후
같은 주소로 다시 발행 (새 페이지를 만들지 않는다) -->
둘째, 숫자가 들어가는 칸에 이름표(data-count)를 붙였습니다. 자동화는 이름표가 붙은 칸만 명령으로 잰 값으로 바꿉니다.
<span>블로그 <b data-count="blog">49</b>편</span>
ls src/content/blog/*.md | wc -l
기록 표는 맨 아래에 한 행씩만 더합니다. 기존 행은 고치지 않습니다. 이렇게 하면 사람이 쓴 문장과 자동화가 쓰는 칸이 섞이지 않습니다.
막힌 점은 무엇이었나?
두 번 막혔습니다.
하나는 발행 권한입니다. 지도는 공유 페이지로 올려 두었는데, 자동화가 도는 계정과 처음 페이지를 올린 계정이 다른 날에는 발행이 거부됐습니다. 원장 기준으로 이런 날이 2번 있었습니다. 이때 자동화가 새 페이지를 따로 만들면 주소가 여러 개로 갈라집니다. 그래서 규칙을 「새 페이지를 만들지 않는다, 실패하면 원장에 한 줄 남긴다」로 정했습니다. 주소가 하나로 남아야 함께 보는 사람이 헷갈리지 않습니다.
다른 하나는 조건이 붙은 칸입니다. 기록 표 행 추가는 매 회차 빠짐없이 됐습니다. 그런데 「페이지를 추가했으면 기준일도 고친다」처럼 조건이 붙은 칸은 놓치기 쉬웠습니다. 2026-10-30 기준으로 기록 표는 2026-10-30 행까지 있는데 맨 위 기준일은 2026-10-20 에 머물러 있습니다. 무조건 하는 일은 지켜지고, 조건부 일은 빠진다는 것을 이 칸이 보여 줬습니다. 다음에는 기준일도 매 회차 무조건 고치는 칸으로 바꿀 생각입니다.
지금은 하루가 어떻게 달라졌나?
지도 원본은 2026-10-30 기준 543줄이고, 이 파일을 바꾼 커밋은 15개입니다(git log 로 잰 값). 그중 10개가 자동화 회차 끝에 남은 기록 커밋입니다(제목에 회차 기록 표시가 붙은 커밋 수). 기록 표에는 2026-10-18 부터 8행이 쌓였습니다. 아무것도 추가하지 않은 날도 「추가 안 함 — 이유」로 한 행을 남기기 때문에, 지도를 열면 자동화가 쉬었는지 멈췄는지 바로 구분됩니다.
달라진 점은 「문서 고치기」가 제 할 일 목록에서 빠졌다는 것입니다. 저는 가끔 지도를 열어 숫자와 기록이 실제와 맞는지만 봅니다. 맞지 않는 칸을 찾으면 그 칸을 자동화 규칙에 더합니다.
대가도 있습니다. 자동화가 고칠 수 있는 칸만 최신이고, 시작 가이드나 운영 서비스 표 같은 사람 문장은 여전히 낡을 수 있습니다. 그래서 그런 문장 옆에는 「언제 기준」을 함께 적어 둡니다.
자주 묻는 질문
문서를 코드에서 자동 생성하면 되지 않나요?
코드에서 뽑을 수 있는 내용(API 목록, 페이지 수)은 생성하는 편이 낫습니다. 하지만 「왜 이렇게 하나」, 「처음엔 무엇부터 하나」 같은 문장은 생성할 수 없습니다. 그래서 사람 문장은 두고, 숫자와 기록 칸만 자동화가 고치게 나눴습니다.
자동화가 문장을 망가뜨리지 않게 하려면?
고칠 칸에 이름표를 붙이고, 파일 맨 위 주석에 「이 칸만 고친다, 기록은 맨 아래에 한 행씩」을 적어 둡니다. 기존 행을 고치거나 새 페이지를 만드는 일은 금지로 둡니다.
갱신이 실패하면 어떻게 알 수 있나요?
실패를 숨기지 않고 매일 쓰는 원장에 「갱신 실패: 이유」를 한 줄 남깁니다. 다음 회차는 그 줄을 보고 같은 실패를 반복하는지 확인할 수 있습니다.