DongHyeonkaandClaude Opus 5
2109f726fe
기록 84편을 계약 에이전트로 다시 썼다. 기존 71편(kss 25 · virt 46)과, 계약에만 있고 안 쓰여 있던 새 글감 13편이다. 원장 84개를 열어 단계마다 스킬 영수증과 관문 종료 코드를 적었고 verify-pipeline-run.py 가 error 0 으로 닫는다. SSOT 결함 둘을 고쳤다. - kss 의 `약 58일` 이 반입 중 `약 59일` 로 바뀌어 있었다. 원 증거 파일이 「남은 일수: 88일 … 실제 갱신까지 약 58일」로 산수를 직접 적는다. D-4a 쪽 `약 59일` 은 강제 갱신 뒤(`VALID: 89 days`)라 맞는 값이라 그대로 뒀다. - virt §198 의 `11.6GB` 는 §178 의 원 측정 `Mem: 11648`(MiB)과 어긋나는데 원 가이드의 표기 그대로라 고치지 않고 쓰이는 자리에 대조를 적었다. 기록의 수치 오류 셋을 고쳤다 — CASE 요약의 「게스트 셋에 8240MB」(5120+3120 은 둘이다), k3s 편이 같은 것을 여섯·일곱·여덟로 세던 것, no-docker 편의 「셋을 더 든다」(§281 의 표는 네 행이고 디스크 행이 빠져 있었다). 계약을 셋 고쳤다. - kss 의 sourceRepository 리비전이 cdac9b8 이었는데 그 커밋에는 docs/guides/** 28개가 아예 없다. 9465582b 로 바꾸고, 반입한 바이트가 어느 커밋과도 같지 않다는 것을 측정값과 함께 적었다 — 반입은 커밋이 아니라 그 시점의 작업 트리에서 떠 온 것이다(kss 297/306 · virt 12/14 가 작업 트리와 같고, 200 커밋을 거슬러 전수 대조했을 때 가장 가까운 커밋도 28개가 어긋났다). - virt 계약이 「2026-09-11 재배분」이라고 적는데 SSOT 는 재배분 날짜를 적지 않고 재배분 뒤 값은 이미 2026-09-10 측정에 찍혀 있다. - kss 후보 대장이 지나친 절 아홉에 처분을 적었다(warn 9 → 0). 새 글감은 0건이고 넷은 앵커가 h3 슬러그의 접두가 아니라 중간 토막이라 검사기가 못 본 것이었다. style_profile.mjs 의 결함 둘을 고쳤다 — frontmatter 가 문장으로 세어져 (실측 398자짜리 「문장」 하나) 평균 길이를 기준 안으로 밀어 올리고 있었고, engPerSent 의 분자는 목록을 포함한 글에서, 분모는 목록을 걷어낸 글에서 세고 있었다(Question 기록에서 11.94 → 3.86). verify-pipeline.py 전 항목 PASS · error 0 · unittest 334건 OK. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
7.9 KiB
kind, slug, title, topic, topicName, project, status, sourceRevision, source
| kind | slug | title | topic | topicName | project | status | sourceRevision | source | ||
|---|---|---|---|---|---|---|---|---|---|---|
| REFERENCE | verify-a-build-guide-in-execution-order | 단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다 | lab-environment-build | 실험대 환경 구성 | virtualization | 게시 전 | 9465582b5d1630eb4ae7c4e078021486919bf6b6 |
|
단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다
구축 가이드는 1단계의 환경에서 시작해 실행 순서로 검증한다. 단계마다 그 시점에 리소스가 이미 있는지와 그 명령을 어느 기계에서 치는지를 따로 본다. 기반 7단계 가이드를 순서대로 따라가자 결함 여섯이 나왔고, 틀린 명령은 하나도 없었다.
관계
- 엣지 nginx 를 호스트에서 게스트 VM 으로 옮긴다 — 성능이 아니라 더러워지는 층의 격리 이 기준이 검증하라는 가이드가 그 결정을 실제로 실행한 문서다. 결함 여섯 가운데 셋은 그 이동이 새로 요구한 일곱 가지와 같은 것을 다루는데, nginx 설치와 nginx 버전 차이와 인증서 경로다.
- 호스트 안에서는 404, 밖에서는 connection refused — 앞 체인의 accept 가 libvirt 의 reject 를 막지 못했다 같은 connection refused 라도 04 단계의 결함은 명령을 칠 셸이 틀려서 났고, 그 기록의 거절은 libvirt 방화벽이 냈다. 어느 셸에서 쳤는지로 좁힌 뒤에도 안 풀리는 막힘을 그 기록이 받는다.
- WiFi 전용 호스트에서 대용량 qcow2 를 옮기는 데 실제로 몇 시간이 걸리는가 그 물음의 답이 이 검증을 선택으로 둘지 전제로 둘지를 가른다. 파일을 옮기는 것보다 가이드를 다시 도는 편이 빠르다고 나오면, 이 실험대는 문서로만 복원된다.
목적
이 기준이 막는 것은 각 줄이 참인데 순서대로는 못 따라가는 문서다. §182 이 든 여섯 결함에서 틀린 명령은 하나도 없었고 전부 실제로 돌았던 것이다. 다만 구축이 끝난 뒤의 환경에서 확인한 출력이 앞 단계에 적혀 있었다. §178 은 이 여섯이 실린 부의 범위를 구축에서 실제로 막힌 지점으로만 그었고, 막히지 않은 단계는 가이드에 있으니 여기서 반복하지 않는다고 적었다. 그래서 여섯은 가이드를 검토해 골라낸 것이 아니라, 그 단계까지 실제로 따라가다 막혀서 드러났다.
03 단계에서 /etc/nginx: No such file or directory 가 난 것은 설정 블록이 틀려서가 아니라 그 시점에 nginx 가 아직 깔려 있지 않아서다. 둘 중 어느 쪽인지는 문서를 읽어서는 알 수 없고 실제로 돌려 봐야 드러난다.
§182 은 검사할 것도 시점과 셸 둘로 갈라 적었다. 하나로 뭉뚱그리면 막힌 단계에서 무엇을 고쳐야 하는지가 안 나오기 때문이다.
규칙
1. 검증 순서를 문서 작성 순서가 아니라 실행 순서에 맞춘다
문서를 쓴 사람은 구축이 끝난 환경에 있고 읽는 사람은 아무것도 없는 환경에서 1단계부터 시작하니, 검증도 1단계의 환경에서 시작한다.
2. 단계마다 그 시점에 리소스가 이미 존재하는지 따로 본다
여섯 중 셋이 여기서 깨졌다. 03 단계는 nginx 설치 단계가 없어 /etc/nginx: No such file or directory 로 막혔다. 00·03·05·06 단계는 저장소가 lab host 에 있다고 가정해 cp: cannot stat 'deploy/...' 로 막혔다. 05 단계는 BFF 가 한참 뒤에 뜨는데도 그 시점에 -l app=bff 로 리소스를 조회했다.
셋 모두 문서를 읽을 때는 보이지 않는다. 설치 명령이 빠졌다는 것도 파일이 그 기계에 없다는 것도 그 단계까지 실제로 와 봐야 드러나기 때문이다.
3. 단계마다 그 명령을 어느 기계에서 치는지 문서가 말하게 한다
04 단계의 확인 명령이 여기서 깨졌다. 게스트에는 Tailscale 이 없기 때문에 엣지 VM 안에서 tailnet 주소를 치면 connection refused 가 돌아온다. 명령 자체는 맞고 칠 위치가 틀렸다.
§178 의 구성에서 호스트는 Arch Linux 이고 게스트는 Debian 12 genericcloud 세 대다. 문서가 주체를 적지 않으면 읽는 사람은 직전 단계에서 쓰던 셸에 그대로 친다.
4. 나중 시점의 환경에서 확인한 명령과 출력을 앞 단계로 옮겨 적지 않는다
§182 이 여섯의 공통 원인으로 든 것이 이 하나다. 구축이 끝난 환경에서는 리소스가 전부 서 있고 저장소도 제 기계에 있으니 어떤 확인 명령이든 돈다. 그 출력을 앞 단계에 붙이면 문서의 각 줄은 참이 되고, 순서대로 따라가는 사람만 막힌다. 그래서 이 결함은 문서를 검토해서는 안 나오고 실행해야 나온다. §182 은 결함 여섯에는 observed 를, 이 공통 원인 하나에는 inferred 를 붙였다. 여섯은 따라가다 본 것이고, 그것을 한 원인으로 묶은 것은 여섯을 놓고 내린 판단이다.
적용 조건
- 사람이 한 단계씩 따라 실행하도록 쓴 구축·운영 문서
- 앞 단계의 결과 위에 뒤 단계가 서는 문서. 기반 7단계 가이드가 그런 문서다
- 명령을 칠 기계가 둘 이상인 문서. 호스트와 게스트가 갈리면 어느 셸에서 치는지를 따로 본다
- 단계가 하나 끼어들거나 대상 환경이 바뀐 뒤
예외
이 기준이 잡는 것은 순서와 위치이고 명령의 정확성은 아니다. §182 이 적었듯 개별 명령은 전부 실제로 돌았던 것이라, 이 검사를 통과해도 오타나 잘못된 플래그나 낡은 옵션은 그대로 지나간다. 04 단계의 인증서 경로가 그런 경우다. 와일드카드로 받은 인증서 묶음의 이름(lineage)은 live/hyeonworks.com/ 인데 문서에는 live/auth.hyeonworks.com/ 이라 적혀 있었다. 단계 순서를 맞춰도 그 줄은 틀린 채다.
배포판 차이도 이 두 검사로는 안 잡힌다. 03 단계의 설정 블록에 있던 http2 on; 은 Debian 12 의 nginx 1.22 에서 unknown directive 가 됐다. 순서를 맞춰도 같은 오류가 나므로 대상 배포판에서 실제로 돌려야 드러난다.
한 번 통과한 문서가 계속 통과하지도 않는다. 단계가 하나 끼어들거나 환경이 바뀌면 같은 검사를 다시 돌린다.
이 저장소에는 이 기준으로 가이드를 고친 뒤 처음부터 다시 따라가 본 기록이 없다. 규칙은 결함 여섯의 공통 원인에서 나왔고, 규칙이 결함을 막아 냈다는 관측은 아직 얻지 못했다.
다시 따라가 보지 않은 데는 까닭이 있다. §184 는 가이드 자신도 읽기 전용 확인만 실제로 돌려 출력을 실었고 만드는 명령은 구축할 때 친 것을 그대로 옮겼다고 적었다. VM 을 다시 만들거나 k3s 를 다시 깔면 지금 돌고 있는 실험대가 없어지기 때문이다. 그래서 단계마다의 생성 명령은 「그때 이렇게 쳤다」까지이고, 지금 다시 쳐도 같은 상태가 되는지는 확인되지 않았다.
예시
- 03 단계 : nginx 설치 단계가 없어 /etc/nginx: No such file or directory
- 03 단계 : 설정 블록이 http2 on; 이라 Debian 12 의 nginx 1.22 에서 unknown directive
- 04 단계 : 인증서 경로가 lineage 이름과 다르다. 와일드카드는 live/hyeonworks.com/ 인데 live/auth.hyeonworks.com/ 이라 적혀 있었다
- 00·03·05·06 단계 : 저장소가 lab host 에 있다고 가정해 cp: cannot stat 'deploy/...'
- 05 단계 : 그 단계에 없는 리소스를 -l app=bff 로 조회. BFF 는 한참 뒤에 뜬다
- 04 단계 : 확인 명령을 칠 위치가 틀렸다. 엣지 VM 안에서 tailnet 주소를 치면 connection refused
- 고친 뒤 처음부터 다시 따라가 본 기록 : x