책을 Claude Code에 읽히고 자신의 리포지토리에 재현하기: 읽는 경로, 검증된 SHA, 개정 추적

이 글은 시리즈 「Claude Code로 기술 블로그를 무인 운영하기 — 무료 장부터 읽는 메커니즘 전체 개요」의 제 6회(총 6회)입니다. Claude Code의 스케줄 실행만으로 기술 블로그(Qiita 중심, Zenn 시험 투고, X 공지, 이미지 생성)가 사람의 손길 없이 계속 돌아가는 시스템을 운영하고 있는 리포지토리의 실측 로그와 커맨드 결과로 설명하는 연재물입니다. Zenn 원서 『Claude Code로 기술 블로그를 무인 운영하기』의 무료 장(제 1~3장, 제 18장, 제 20장)을 바탕으로 하고 있으며, 각 회차는 책의 해당 장으로 돌아갈 수 있는 연결고리를 가지고 있습니다. 게재하는 수치와 실행 결과는 각 회차 집필 시점에서 다시 취합합니다.

시스템 전체를 자신의 리포지토리에서 재구성하고 싶은 분들을 위해: 무료 장의 다음 내용(글의 형식・품질 게이트・Qiita/Zenn/X 공개 설계・무인 실행・측정)을 총 20장으로 된 매뉴얼로 작성한 Zenn Book을 공개했습니다(유료 500엔・체험 읽기 가능).

시리즈 전체 목차

• 제 1회 하루 4 스ล็อต의 스케줄 실행으로, 기술 블로그가 사람의 손길 없이 계속 나오는 시스템 전체 개요
• 제 2회 거버넌스의 기반은 공개 베이스를 설정하는 것만으로 충분하다. 그 위에 블로그 계층을 추가할 경계 설정하기
• 제 3회 무인 블로그의 현재 위치를 3곳에서 세기: 대장(台帳)・공개 로그・참여도 실적
• 제 4회 Zenn에서 배포 성공했는데 비공개・Qiita의 429: 무인 운영으로 겪은 7가지 증상
• 제 5회 X의 403・승인 대기 등으로 스ล็อต가 공염・git push가 403: 무인 운영 확산과 운영의 증상

제 6회 책을 Claude Code에 읽히고 자신의 리포지토리에 재현하기: 읽는 경로, 검증된 SHA, 개정 추적(이 글)

이 연재물에서는 Claude Code의 스케줄 실행만으로 기술 블로그가 계속 돌아가는 시스템을 5회에 걸쳐 살펴보았습니다.

재현 가능 여부를 가르는 것은 책의 작성 방식보다는, 다음 3가지가 갖춰져 있는지 여부입니다.

• 어디서 읽히게 할 것인가 (사람과 Claude Code에서 진입점이 다름)
• 게재된 출력이 언제 어느 코드로 얻었는지 추적할 수 있는가
• 소재 리포지토리가 전진했을 때, 책이 얼마나 오래되었는지를 기계적으로 말할 수 있는가

대상 독자는 이 연재물을 읽고 시스템을 자신의 리포지토리에서 재구성하고 싶은 사람, 그리고 「기술서는 사도 반년 만에 구식이 되는 것 아닌가」라고 망설이는 사람입니다.

게재된 출력은 2026-10-10 (JST)에 책 리포지토리의 main(커밋 bf4b107 )에서 취합한 것입니다. 실행 환경은 Linux 클라우드 실행 환경과 Node v22.22.0이며, 사용된 것은 --self-test

・check
・읽기만 합니다. 투고나 결제를 수반하는 처리는 실행하지 않았습니다.

원서 『Claude Code로 기술 블로그를 무인 운영하기』는 총 20장이며, 제 1장 「이 책의 걸음걸이」가 2가지 경로로 나뉩니다. 사람과 Claude Code에서는, 처음 필요로 하는 것이 역순이기 때문입니다. 사람은 전체 개요가 머릿속에 들어와야 개별 장의 판단을 추적할 수 있지만, Claude Code에게는 전체 개요 설명보다 순서와 계약 그리고 완료 조건이 먼저 필요합니다.

사람이 읽는 경로는 제 1~3장에서 전체 개요와 기반을 다지고, 나머지는 목적지 부로 직행하는 형태입니다.

• 글의 작성법을 알고 싶다면 제 4~7장
• 공개 상한 설계라면 제 8~10장
• 공지와 이미지는 제 11~14장
• 무인 운영 그 자체라면 제 15~17장
• 증상이 명확하다면 제 18장의 역추적

Claude Code에게 읽히는 경로는 반대 방향으로, 시스템을 독자의 리포지토리에서 재현시키기 위한 사양 패키지, 즉 제 19장부터 시작합니다.

• 진입점은 제 19 장의 사양 패키지입니다.
• 개별적인 제약 사항은 각 장 끝에 있는 'Claude Code에 전달할 지시 요점'입니다.
• 검수는 자체 테스트 전체 항목 PASS 여부와 판정용 마커 문자열로 이루어집니다.

장 끝의 섹션이 실제로 모두 갖춰져 있는지 여부는 책 파일을 세어보면 알 수 있습니다. books/

하위 디렉토리에서 'Claude Code에 전달할 지시 요점'의 출현 횟수를 장별로 세어보면, 제 19 장만 0이고 나머지 19 장은 각각 1이었습니다 (제 1 장만 본문에서 이 섹션 이름에 언급했기 때문에 3입니다). 이는 제 1 장의 '이 섹션은 제 19 장을 제외한 모든 장에 있다'는 설명과 모순되지 않습니다.

경로를 분리한 효과는 검수 위치에 있습니다. 사람의 경로는 이해가 종점이지만, Claude Code의 경로는 '전체 항목 PASS'라는 외부에서 판정할 수 있는 종점을 가지므로, 에이전트가 작동한 것처럼 보이는 상태를 완료와 착각하지 않아도 됩니다.

검수 기준을 자체 테스트에 두면 다음 의문점이 생깁니다. 책에 실린 출력 자체가 진짜인지 하는 의문입니다. 이 책은 게재된 출력의 출처를 3단계로 가지고 있습니다.

판 표: 제 20 장의 '본서의 판'에는 v1.0 검증 SHA fe507ab와 촬영일 2026-09-18 (JST)가 적혀 있습니다. 장별 표도 있으며, 개정으로 일부 장만 재검증할 경우 해당 장의 행만 SHA가 새로워집니다.

대장: content/books/claude-code-unattended-tech-blog/base-map.json은 검증된 SHA와 '장별 참조 파일'을 가지고 있습니다. 촬영 시점의 값은 verifiedSha가 3bcaf6b, verifiedAt이 2026-09-18 (JST)이며, 장 수는 20이었습니다.

생 로그: content/books/claude-code-unattended-tech-blog/verification/에는 제 1 장부터 제 20 장까지의 촬영 로그가 장당 1개 파일로 총 20개의 파일이 있습니다.

여기서 판 표의 fe507ab와 대장의 3bcaf6b가 일치하지 않다는 것을 알아차릴 수 있을 것입니다. 이는 모순이 아니라 역할의 차이입니다.

본서 자체와, 본서가 설명하는 '본서 비정기 X 소개' 라인은 출력을 촬영한 후에 같은 리포지토리에 추가되었습니다. 촬영 SHA를 기점으로 차이점을 가져오면, 본서가 스스로 추가한 파일까지도 '주제 변경'으로 인식해 버립니다. 그래서 대장은 본서를 통합한 후의 main 커밋을 기점으로 합니다. 두 SHA의 차이점은 본서가 추가한 파일만이라고 제 20 장에 명시되어 있습니다. 3bcaf6b

커밋 메시지도 본서 집필과 X 소개 라인 추가 그 자체였습니다.

이렇게 3단계로 구성되어 있으면, '이 출력은 어디에서 왔는가'를 독자 스스로 추적할 수 있습니다. 책에 실린 출력과 자신의 출력이 다를 때 확인하는 순서는, 장의 검증 SHA를 보는 것, 거기서부터 자신의 HEAD까지 무엇이 바뀌었는지 보는 2단계입니다.

출처를 추적할 수 있다는 것과, 출력이 여전히 동일하다는 것은 별개의 문제입니다. 주제 리포지토리는 매일 움직이기 때문에, 책에 적힌 숫자는 오래됩니다. 촬영 SHA와 현재 main으로 제 1 장이 적고 있는 숫자를 다시 세어보았습니다.

| 항목 | 촬영 SHA fe507ab (2026-09-17) | 현재 bf4b107 (2026-10-10) |
|---|---|
| package.json의 npm 스크립트 수 | 123 | 191 |
| 그중 test:로 시작하는 자체 테스트 | 54 | 88 |
| npm run test:article-number 건수 | 10건 (제 1 장 게재) | 21건 |

촬영 SHA 쪽의 수는 git show fe507ab:package.json에서 센 것이며, 제 1 장의 설명(123개 중 54개가 자체 테스트)과 일치했습니다. 약 3주 만에 npm 스크립트는 68개, 자체 테스트는 34개 증가했습니다.

현재 main 브랜치에서의 자체 테스트 결과는 다음과 같습니다.

$ npm run test:article-number
...
✅ article-number self-test: 21 件 모두 PASS

제 1 장의 게재는 '10件 모두 PASS'입니다. 건수는 다르지만, 검수 형태(전체 PASS)는 동일하며, 책의 기술적 설명이 잘못된 것은 아닙니다. 채집 시점에서는 그 건수로 정확했고, 그 후에 테스트가 추가되었을 뿐입니다. 반대로 말하면, 책에 '10件'이라고 적혀 있다고 해서 현재 21건을 실패로 판단하는 것은 오류입니다. 이처럼 '숫자는 변하지만, 검수 형태는 변하지 않는' 상태를 독자와 에이전트 양쪽 모두가 구별할 수 있도록 하는 메커니즘이 필요합니다.

제 20 장은 개정(revision)을 떠올리는 것이 아니라 주제의 업데이트를 기점으로 한 4단계 프로세스로 진행하도록 정의하고 있습니다. 판정기는 scripts/check-book-base-drift.js입니다.

영향 장을 기계적으로 추출: 검증된 SHA부터 HEAD까지 변경 파일을 나열하여, 장의 참조 경로에 해당하는 장을 DRIFT로 표시합니다. 이 책은 주제를 자체 리포지토리에 지정하고 있으므로, 클론(clone)하지 않고 작업 트리의 git 히스토리만으로 판정합니다. -
해당 장만 재검증: 나열된 장의 커맨드를 다시 실행하여, 출력이 변경되었으면 본문을 교체하고 생 로그를 다시 채집합니다. 변함이 없으면 본문에는 손대지 않고 SHA만 진행시킵니다. -
장부(台帳) 업데이트: 판의 표 해당 행과 base-map.json의 verifiedSha를 수정합니다. 장의 참조 경로는 각 장 말미에 있는 '이 장이 참조하는 책 리포지토리 파일'에서 기계적으로 생성되는 규칙입니다. -
판의 표 기록: 장별 SHA가 다르면, 'v1.1에서는 제 8장과 제 11장만 새로운 SHA'와 같이, 어디가 변경된 개정인지 표를 통해 읽을 수 있습니다.

판정어는 3가지 값입니다. BOOK_DRIFT OK가 exit 0이고, DRIFT가 exit 10이며, 검증된 SHA에 도달할 수 없을 때의 UNKNOWN이 exit 2입니다. 판정 불능을 OK로 처리하지 않습니다. 판정기 자체의 자체 테스트는 다음과 같이 통과했습니다.

$ node scripts/check-book-base-drift.js --self-test
✅ check-book-base-drift --self-test PASSED（18 케이스）

그렇다면, 이 책은 현재 어떤 상태일까요? 2026-10-10에 실행한 결과가 이것입니다 (이 책의 행만 발췌).

$ npm run check:book-drift
BOOK_DRIFT DRIFT book=claude-code-unattended-tech-blog verified=3bcaf6b head=bf4b107 changed=743 chapters=20
- 01-how-to-read（이 책의 읽는 방법 — 사람이 읽거나 Claude Code에 읽히게 하는 것）
...

종료 코드는 10이었습니다. 3bcaf6b부터 HEAD까지 374 커밋(git log --oneline 3bcaf6b..HEAD | wc -l), 변경 파일은 743건이며, 20장 모두 개정 대기 상태입니다. 말미의 '대처(対処)'에 나오는 18-revision-log는 같은 판정기를 공유하는 기간 측 부록 장 이름으로, 이 책에서는 제 20장에 해당합니다.

20장이 모두 DRIFT라는 결과는 보기 좋은 숫자는 아니지만, 그대로 게재할 것입니다. 이유는 두 가지가 있습니다.

첫째, DRIFT는 '책의 기술적 설명이 잘못되었다'는 판정이 아닙니다. '이 장이 참조하는 파일이 검증 시점부터 변경되었으므로, 재검증이 필요하다'는 판정입니다. 위 제 1장의 행에 나와 있는 package.json과 scripts/lib/article-number.js는 앞 절에서 보았듯이 실제로 바뀌었습니다 (스크립트 수 123→191, 테스트 10건→21건). 그럼에도 검수 형태는 유지되고 있어, 제 1장의 절차 자체가 무너지지는 않습니다. 어느 정도까지 영향이 있는지를 결정하는 것이 단계 2의 재검증이며, DRIFT는 그 진입점입니다.

둘째, 모든 장이 나열되는 원인은 참조 경로가 일상적으로 업데이트되는 파일을 포함하고 있기 때문입니다. CLAUDE.md나 package.json

이 메커니즘은 변경될 때마다 업데이트되기 쉬운 파일이며, 374 커밋 동안 실제로 변경되었고 제1장의 행에도 나열되어 있습니다. 이 판별기는 변경된 파일이 장의 참조 경로에 해당하는지 여부만 보고 있으며, 변경 내용까지는 보지 않습니다. 참조 경로를 좁히면 DRIFT은 줄어들지만, 장의 근거가 되는 파일을 제거하면 그 장은 다시 감지되지 않습니다. 원장(ledger)의 ignore에는 매 슬롯마다 바뀌는 상태 파일, 트래커, 생성물 17가지 패턴이 들어 있습니다. 이것을 제거하면 이 책은 항상 DRIFT가 되어 판별 자체가 의미를 잃습니다. 탐지 누락과 과잉 탐지의 어느 쪽으로 기울어지느냐에 따라, 이 원장은 과잉 탐지 쪽에 기울어져 있습니다.

장별 검증 시점은 원장과 버전표에 남아 있으므로, DRIFT 상태에서도 '이 장의 출력은 언제 것인가'는 사라지지 않습니다. 오래되지 않는다는 것은 기술 설명이 영원히 최신이라는 의미가 아니라, 얼마나 오래되었는지 항상 말할 수 있다는 의미입니다.

개정은 Zenn의 책 배포 슬롯(8일에 1권)을 소모하지 않습니다. 기존 책의 챕터 업데이트는 상한 대상이 아니기 때문입니다. 반면, 게시 트래커에 행을 추가하면 신규 공개로 계산되어 다음에 책을 내놓을 날짜가 뒤로 밀리므로, 개정 시에는 트래커에 기록하지 않습니다.

Zenn의 책은 파일을 업데이트하여 GitHub에 푸시하면 동일한 URL로 반영되며, 추가 구매 없이 독자에게 전달됩니다. 다만, 업데이트되었다는 사실이 자동으로 통지되지는 않습니다. 이 책이 준비한 입구는 2가지입니다.

• 제20장 '본서의 버전표': 무엇을 언제 개정했는지에 대한 일차 정보입니다. 절차가 잘 안 될 때는 자신이 읽은 버전보다 새로운 행이 추가되지 않았는지 먼저 확인합니다. - X에서의 비정기 소개: 책 소개 게시물을 불규칙하게 올리며, 개정 시에는 '개정'이라는 제목으로 업데이트된 장을 첨부합니다. 이는 기사 신규 공지과는 별개입니다.

Claude Code에 책을 읽게 할 경우에도 확인 순서는 같습니다. 버전표에서 장별 SHA를 확인하고, 자신의 수동 테스트가 전 항목 PASS인지 봅니다. 건수가 책과 달라도 전 항목 PASS라면 계약은 유지되고, FAIL이 나오면 그 장이 개정 대기 중인지 버전표에서 확인합니다.

이 연재는 책의 무료 장을 기반으로, 수치와 출력을 매회 집필 시점에 다시 측정하여 작성해 왔습니다. 무료 장은 다음 5가지입니다.

맨 처음 질문으로 돌아가 봅시다. 책을 Claude Code에 읽게 했다면, 정말 자신의 리포지토리에서 재현할 수 있는가?

답변은 조건부입니다. 검수 기준과, 책의 오래됨을 측정하는 잣대 두 가지가 갖춰졌을 때만, 재현 가능 여부를 판별할 수 있습니다. 재현 그 자체를 보장하는 것은 책의 글이 아니라, 외부에서 판별 가능한 완료 조건입니다.

• 검수 기준: Claude Code는 제19장의 사양 패키지부터 시작하여, 자가 테스트 전 항목 PASS인지 마커 문자열로 종점을 판정합니다.
• 출처: 수집 SHA fe507ab

・검증된 SHA 3bcaf6b

・제20장 분량의 생 로그를 3단계로 추적할 수 있습니다. - 오래됨의 잣대: 소재는 3주가 채 안 되어 374 커밋이 진행되었고, npm 스크립트는 123개에서 191개로 늘어났습니다. 그럼에도 불구하고 check:book-drift가 재검증이 필요한 장을 exit 10과 장 목록으로 반환합니다. 2026년 10월 10일 시점에서는 20장 모두가 재검증 대기 상태이며, 이것이 매일 움직이는 리포지토리를 소재로 한 책의 실태입니다.

이 판별기의 출력에서 읽을 수 있는 것은, 책의 개정을 사람의 주의력에 맡길 경우, 개정이 필요한지 여부를 판단하는 것 자체가 멈추기 쉽다는 것입니다. 소재가 매일 움직이는 이상, '아마 괜찮겠지'는 검증되지 않은 가정이 쌓이게 됩니다. 판별기가 모든 장을 DRIFT로 나열하는 상태는, 그 가정을 매번 눈에 보이는 형태로 만들고 있을 뿐입니다.

자신의 리포지토리에 가져가려면, 먼저 자신의 절차서(책이든 README 파일이든 상관없습니다)에 두 가지 항목이 있는지 확인해 주세요. 하나는 '이 절차의 완료를 어떤 커맨드의 어떤 출력으로 판정할 것인지', 다른 하나는 '이 절차를 어느 커밋에서 검증했는지'입니다. 이 두 가지가 비어 있는 상태로 Claude Code에 전달되면, 에이전트는 절차를 실행할 수는 있어도 그것이 재현되었는지 아무도 말할 수 없습니다.

이번 글은 Zenn의 책 『Claude Code로 기술 블로그 무인 운영하기』의 제1장 '책 읽는 방법'과 제20장 '개정 이력 및 검증된 SHA'를 바탕으로, 숫자와 판정 커맨드 출력을 모두 2026-10-10 날짜로 다시 작성한 것입니다. 두 장 모두 무료이며, 제1장과 제20장에서 읽을 수 있습니다. 연재 전체도 이 두 장에 제2장, 제3장, 제18장을 더해 총 다섯 개의 무료 장으로 구성되어 있습니다. 다음 내용은 유료 장으로, 제19장은 Claude Code에 읽히게 하여 자신의 리포지토리에서 같은 시스템을 구축하기 위한 사양 패키지이며, 제4장부터 제17장까지는 기사 형식, 품질 게이트, Qiita와 Zenn과 X의 공개 설계, 무인 실행, 측정 등의 각론입니다. 책의 개정 상황은 제20장의 버전 표에서 언제든지 확인할 수 있습니다.

본 리포지토리 내 파일(리포지토리가 비공개이므로 경로만 표시합니다):

• books/claude-code-unattended-tech-blog/01-how-to-read.md
  : 두 가지 읽는 경로, 전체 20장 지도, 게재된 출력 및 검증 SHA-
  books/claude-code-unattended-tech-blog/20-revision-log.md
  : 본서의 버전, 장별 검증된 SHA, 개정 진행 방식, 독자에게 개정을 알리는 경로-
  books/claude-code-unattended-tech-blog/19-reproduce-with-claude-code.md
  : 제19장 'Claude Code에 읽히게 하여 재현하기'(유료 장이므로 제목만)
  content/books/claude-code-unattended-tech-blog/base-map.json
  : 검증된 SHA와 장별 참조 파일 대장-
  content/books/claude-code-unattended-tech-blog/verification/
  : 장별 수집 로그 (20개 파일)
  scripts/check-book-base-drift.js
  : 개정이 필요한 장을 판정하는 도구 (npm run check:book-drift)
  scripts/lib/article-number.js
  : 기사 번호를 판정하는 도구 (npm run test:article-number)
  package.json
  : npm 스크립트 및 자체 테스트 목록

• ⬅️ 이전 글: 제5회 X의 403・승인 대기로 슬롯을 놓치다・git push가 403: 무인 운영 확산과 운영 증상

• ➡️ 다음 글: 없음 (총 6회, 이 글로 완결입니다)

공개된 회차 (4편, 어느 회차부터든 읽을 수 있습니다)

• 제1회 1일 4 슬롯의 스케줄 실행으로 기술 블로그가 사람 손 없이 계속되는 시스템의 전체 개요
• 제2회 거버넌스의 기반은 공개 베이스를 설정하는 것만으로 충분하다. 그 위에 블로그 계층을 추가할 경계 긋는 방법
• 제3회 무인 블로그의 현재 위치를 3곳에서 세어보기: 대장, 공개 로그, 참여도 실적
• 제4회 Zenn에 배포 성공했는데 비공개・Qiita의 429: 무인 운영으로 겪은 7가지 증상

시스템 전체를 자신의 리포지토리에 재구축하고 싶은 분은 무료 장의 다음 내용(기사 형식, 품질 게이트, Qiita/Zenn/X의 공개 설계, 무인 실행, 측정)을 총 20장의 절차서로 작성한 Zenn Book (유료 500엔・체험판 제공)으로 가보세요.