[🛠] Operations Automation #4: 문서를 덜 고치면서 stale 상태를 막는 구조

✨ GPT-5.6 Sol의 요약 　

상태 변경을 여러 문서에 복사하던 방식을 버리고, 변동 상태의 단일 owner와 조건부 downstream, phase checkpoint로 문서 최신화 흐름을 다시 정리한 기록.

여러 문서를 최신화할수록 현재 상태가 갈라졌다

긴 작업이 압축되거나 다른 세션으로 넘어간 뒤, 예전 문서에 적힌 다음 작업을 현재 상태로 착각하는 일이 있었다. 이 문제를 막으려고 한동안 상태가 바뀔 때마다 관련 있어 보이는 문서를 전부 고쳤다.

README, 문서 router, 요구사항, 현재 방향, Runbook, TODO에 같은 완료 사실과 다음 작업을 반복해서 적었다. 빠뜨린 문서가 없으면 안전할 것 같았다.

하지만 상태 변경 하나를 여섯 군데에 쓰는 순간부터 여섯 군데를 계속 똑같이 유지해야 했다. 어떤 문서는 배포 전 상태에 머물고, 다른 문서는 실기기 검증까지 끝났다고 적었다. 문서를 많이 갱신한 것이 stale 상태를 막기는커녕 새로운 stale 상태를 만들었다.

작은 검증 하나가 끝날 때마다 문서 여러 개를 고치고 commit까지 남기니 Git history도 잘게 쪼개졌다. 구현이 어디서 끝났는지보다 문구를 몇 번 동기화했는지가 더 잘 보였다.

변동 상태는 한 문서만 소유하게 했다

문서 수가 문제가 아니라 같은 사실을 여러 문서가 소유하는 것이 문제였다. 그래서 먼저 사실의 종류마다 owner를 하나만 정했다.

바뀐 사실	owner	다른 문서를 고치는 조건
현재 Runtime, blocker, phase, 다음 작업	canonical current-state snapshot	다른 문서에 복사하지 않는다
안정된 제품 결정, 금지한 우회, 활성 Goal	current-direction 문서	제품 결정이나 Goal 자체가 바뀔 때만
동작, 데이터, 권한, acceptance	requirements 또는 contract	사용자·시스템 동작 계약이 바뀔 때만
운영 절차, gate, rollback, recovery	Runbook	운영자가 따라야 할 절차가 바뀔 때만
문서 관계, 제품 단계, 실행 진입점	README 또는 router	탐색 경로나 제품 관계가 바뀔 때만
상세 명령, 로그, 워커 검증	report, artifact, Git evidence	aggregate 문서에는 결론과 근거 링크만 남긴다

핵심은 관련 있다와 소유한다를 분리하는 것이다. 배포가 끝났다고 요구사항을 고칠 필요는 없다. 배포 과정에서 운영 rollback 절차가 바뀌었다면 Runbook을 고치고, 동작 계약까지 달라졌다면 그때 requirements를 고친다.

README와 router도 현재 revision, 기기 상태, 다음 작업을 따라다니지 않는다. 이 문서들은 어디에서 무엇을 읽고 실행해야 하는지만 안정적으로 가리킨다.

즉시 갱신과 durable checkpoint를 분리했다

단일 owner라고 해서 문서 갱신을 phase 끝까지 미루지는 않는다. 새 증거가 생기거나 Runtime 상태, blocker, 우선순위, 다음 작업이 달라지면 canonical current-state snapshot은 다음 구현 전에 바로 고친다. 그래야 중간에 압축되거나 인계돼도 다음 세션이 한곳에서 실제 상태를 복구할 수 있다.

반대로 commit은 상태가 한 줄 바뀔 때마다 만들지 않는다. 독립적으로 검토하고 다시 시작할 수 있는 경계에서만 current-state를 한 번 확인하고 checkpoint를 만든다.

• 구현이 끝났을 때
• 배포와 사후 검증이 끝났을 때
• 실기기·사용자 진입점 E2E 결과가 나왔거나 blocker가 확정됐을 때
• interruption이나 handoff로 작업을 넘길 때

즉시 갱신은 resume 안전을 위한 것이고, phase checkpoint는 변경 묶음을 검토하고 되돌리기 위한 것이다. 둘을 같은 규칙으로 처리하니 micro-event commit이 늘어났다.

commit 권한이 없는 작업에서는 더 단순하다. 검토가 끝났다는 이유로 COMMITTED나 CLOSED 상태를 만들지 않는다. 통합 후보를 freeze한 상태로 유지하고, 실제 checkpoint가 생기기 전까지 durable한 완료인 것처럼 기록하지 않는다.

워커 검증은 report에 남기고 aggregate 문서에서 빼냈다

병렬 작업에서는 워커마다 실행한 명령, 검사 결과, 겹친 hunk, 남은 제약이 생긴다. 이 내용을 root TODO와 README, 요구사항에 다시 붙이면 coordinator가 읽어야 할 문서만 늘어난다.

워커 단위의 상세 증거는 immutable report와 Git diff에 남기고, current-state에는 통합된 결론과 현재 영향, 증거 경로만 둔다. coordinator는 report를 하나씩 검토하되 report 하나를 commit 하나로 취급하지 않는다. 같은 phase를 이루는 여러 report는 통합 검증 뒤 하나의 checkpoint를 공유할 수 있다.

이 구분 덕분에 aggregate 문서는 짧아지고, 상세 검증도 사라지지 않는다. 다음 세션은 현재 상태를 먼저 읽고, 판단 근거가 필요할 때만 연결된 report와 Git evidence를 내려간다.

resume 순서가 owner 규칙을 거스르고 있었다

규칙을 정리한 뒤 전체 흐름을 다시 검사하면서 의외로 기본적인 모순을 찾았다. 시작 절차가 README를 먼저 읽고 그다음 todo.md를 읽도록 되어 있었다.

README에는 변동 상태를 복제하지 말자고 적으면서, 실제 resume 절차는 router를 current-state보다 먼저 읽고 있었던 셈이다. 오래된 상태 문구가 남아 있으면 첫 판단부터 잘못된 방향으로 갈 수 있었다.

그래서 시작 순서를 바꿨다. 가장 먼저 canonical current-state에서 현재 Runtime, blocker, phase와 다음 작업을 확인한다. 그다음 README와 문서 router에서 repository 경계와 필요한 leaf 문서를 찾는다. 안정된 제품 결정은 current-direction에서, 실제 동작 계약은 requirements에서 읽는다.

문서 owner 표만 추가하는 것으로는 부족했다. 사람이든 Agent든 실제로 읽는 순서가 owner 관계를 따라야 했다.

현재 적용 범위와 남은 한계

이번 구조는 공용 작업 규칙, Operations Automation의 문서 routing, 변경 문서화 manifest, 병렬 coordination protocol에 반영했다. skill validator와 문서 동기화 검사, diff 검사는 통과했다. 다만 현재 변경은 아직 local working tree에 있고 commit이나 배포 상태는 아니다.

기존 문서 전체를 소급해서 다시 쓰지도 않았다. 과거 기록과 상세 report는 그대로 두고, active 문서에서 같은 current-state 사실이 충돌할 때만 owner 참조로 줄이는 방식이다. 오래된 문서가 남아 있다는 사실보다, 그것을 현재 작업의 authority로 다시 읽지 않게 만드는 것이 먼저였다.

이제 문서 최신화가 잘됐는지는 몇 군데를 고쳤는지로 판단하지 않는다. 압축이나 인계 뒤에 한곳만 읽고도 현재 단계와 다음 작업을 틀리지 않는지, 상세 근거가 필요할 때 다시 추적할 수 있는지가 기준이다.