docs(work): 운영 playbook 시험에서 나온 게이트 실행 빈틈 여섯을 닫는다

문제: 2026-11-07 합친 브랜치 전체 게이트를 매뉴얼만 보고 돌리게 했더니
(1회차 수정 전 매뉴얼) 여섯 곳에서 답이 없었다.
- gates.md 3절 묶음에 main job(configuration-cache, compose smoke,
  http3, notification pr)과 경로 필터 PR lane이 없어 "workflow와 같은
  명령"이 아니었다
- 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차가 없었다
- 집계 태스크 전체가 실제로 돌았음을 보이는 법이 없었다(--rerun은
  앞 태스크 하나만)
- lychee 대체 명령(--links docs)이 lychee 범위보다 좁았고, buf와
  dependency review는 대체 안내가 없었다
- compose bind mount가 tmp/heap-dumps를 root로 만들어 git worktree
  remove가 실패했다
- 결과 기록 형식이 게이트 하나 = Gradle 명령 하나를 가정했다

고른 방법:
- gates.md 3절을 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것,
  (다) 로컬 도구가 없는 것으로 나눈다. (가)에 workflow의 run 줄을
  더하고, (나)는 git diff --name-only를 on.pull_request.paths(glob)와
  pr-adapters.yml emit 줄(정규식)에 맞추는 절차로, (다)는 job마다
  로컬 대체와 대체가 못 보는 것을 적은 표로 둔다
- 실제 실행 증명: 새 worktree와 --no-build-cache, 로그의 FROM-CACHE 0
- 링크 검사 대체는 lychee와 같은 glob을 git ls-files로 넘긴다
- operate.md 4.1에 compose down과 root 폴더 지우기 한 줄
- gates.md 4절은 한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제
  실행」 칸
- 처리 표(evidence.md 9절)에 T6 여섯 행
버린 대안: workflow의 모든 job 명령을 gates.md에 옮겨 적기. workflow가
정본이라 옮긴 사본이 낡는다. 경로 필터 lane은 절차만 둔다.

위험·한계:
- (가)의 명령은 workflow의 사본이다. workflow를 바꾸면 이 블록도 고쳐야
  한다
- 경로 필터 맞추기는 손으로 한다. glob을 기계로 맞추는 도구는 없다
- 같은 범위 링크 검사는 지금 rc=1이다. src/README.md와 fileserver·
  objectstorage README의 상대 링크 3건이 기준 커밋부터 깨져 있다(이번
  범위 밖)

검증:
- python3 scripts/check-work-docs.py rc=0. improve.md 141/150,
  delegate.md 121/150, operate.md 131/150, 진입 경로 최대 290/350,
  본문 이력 0줄
- 바꾼 문서를 읽는 테스트: grep 결과 0(delivery-evidence.md 이름만
  걸림)
- desktop: 바꾼 것을 패치로 73d39212 위에 얹어 이 커밋과 같은 트리
  7e28874c를 만들고, flock 아래 :app-bootstrap:documentContractTest
  --rerun --no-build-cache rc=0, 66건 실패 0 건너뜀 0, FROM-CACHE 0,
  직전 1분 부하 5.64. 같은 트리에서 check-work-docs.py rc=0,
  --history docs/manual 16줄 rc=1(기대대로)
  (desktop ~/manual-gap-fix-2-logs/final-*.log)
- 링크 검사(lychee와 같은 범위) rc=1, 깨진 3건은 위 위험·한계의 것
  (desktop ~/manual-gap-fix-2-logs/links-lychee-scope.log)
This commit is contained in:
DongHyeonka
2026-11-07 00:35:12 +09:00
parent b619c44298
commit 447a77a35d
3 changed files with 67 additions and 19 deletions
+3 -2
View File
@@ -58,6 +58,7 @@ git worktree remove ~/workspace/<작업 이름>
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다.
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(`docker-compose.dev.yml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`docker-compose.infra.yml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
**push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.
@@ -76,7 +77,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
### 4.2 게이트 실행과 기록
1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절 묶음 전체다.
1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것, (다) 로컬 도구가 없는 것 전체다.
2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다.
3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다.
4. 결과를 [reference/gates.md](reference/gates.md) 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋.
@@ -126,5 +127,5 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
- desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다.
- 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다.
- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:a:test --rerun :b:test --rerun`).
- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:a:test --rerun :b:test --rerun`). `ci` 같은 집계 태스크는 새 worktree에서 `--no-build-cache`로 돌린다([reference/gates.md](reference/gates.md) 3절).
- 커밋하고 push한 뒤 desktop에서 돌려, 결과를 커밋 본문에 못 넣는다. push 전에 패치로 검증한다(4.1절).