Zenn Book을 다층 AI 리뷰로 제작했더니, '수렴' 이후에 실제 버그가 남아있던 이야기

TL;DR

총 9장으로 구성된 Zenn Book을,
역할을 나눈 다층 리뷰 (셀프 / 역할별 AI 리뷰 3가지 관점 / 별도 모델 검토 [Codex・Gemini] / 실제 렌더링 검증 / 최종 추가 리뷰)를 통해 여러 번 검토하여 공개했다.
각 리뷰 계층은
서로 다른 종류의 문제를 포착했다. 특히 "Zenn이 markdown 이미지의 SVG를 표시하지 않는다"라는 공개 차단 요소(Blocker)는 리뷰 문장이 아니라 **실제 렌더링 검증 (Playwright로 실제 표시를 확인)**을 통해서만 나타났다.
AI 리뷰가 "더 이상 수정할 곳이 없다 (수렴)"라고 말한 뒤에 실행한
추가 전수 리뷰가, 그때까지 빠져나갔던 실제 버그 (복사해서 붙여넣으면 작동하지 않는 샘플 등)를 찾아냈다 ―― 모두 공개 전에 해소할 수 있었다.
동시에,
개선 제안을 적대적으로 채택 여부를 판단함으로써 "불필요한 개선(수량 늘리기)"을 기각할 수 있었다. 리뷰는 더하기가 아니라, 더해야 할 것과 기각해야 할 것을 구분하는 작업이었다.

서론: 왜 "리뷰 설계"를 기사로 쓰는가

AI 코딩 통제(AI Coding Enforcement) OSS의 문서를 Zenn Book (총 9장, 무료)으로 공개했습니다. 본 기사는 그 내용이 아니라, 어떻게 리뷰하여 품질을 보장했는가에 대한 이야기입니다.

AI에게 글을 쓰게 하면 빠르고, 대량으로, 그럴듯하게 출력됩니다. 문제는 그럴듯함이 정확성을 보장하지 않는다는 점입니다. 특히 기술서는 샘플 코드나 절차가 "작동하지 않거나" "최신 사양과 어긋나면" 단번에 신뢰를 잃습니다.

그래서 혼자서(＋AI)도 돌릴 수 있는 **다층 리뷰 (Multi-layer Review)**를 설계했습니다. 결론부터 말씀드리면, 리뷰는 "여러 번 읽는 것"이 아니라 "다른 종류의 눈으로 읽는 것"과 "실제로 작동시켜 확인하는 것"의 조합이 효과적이었습니다.

리뷰 체제: 역할을 나눈 다층 리뷰

각 계층에는 역할의 차이를 두었습니다.

계층	주로 포착하는 것
셀프	자신의 의도와의 괴리, 작성 누락
...

포인트는 같은 AI에게 여러 번 읽게 해도 동일한 맹점이 남는다는 것입니다. 집필 및 수정에 사용한 AI와 검증하는 AI를 나누고, 여기에 더해 별도의 계통(Codex/Gemini)을 투입함으로써 선입견을 무너뜨릴 수 있습니다.

계층마다 "다른 문제"가 나타났다

공개 차단 요소는 문장 리뷰에서는 나타나지 않았다

처음에는 도표를 보기 좋은 SVG로 준비했습니다. 문장 리뷰에서는 아무도 문제를 제기하지 않았습니다. 그런데 Playwright로 Zenn의 프리뷰를 실제로 렌더링해 보니, Zenn의 렌더러(Renderer)가 다음과 같이 출력했습니다.

/images/.../enforcement-architecture.svg 를 표시할 수 없습니다.
지원하는 이미지 확장자는 .png, .jpg, .jpeg, .webp, .gif 입니다.

Zenn은 markdown 이미지의 SVG를 표시하지 않습니다 (지원 포맷은 PNG/JPEG/WebP/GIF). 반면 mermaid 코드 블록은 그려집니다 (공개 시점의 Zenn에서 확인). 이는 "문장을 읽는" 리뷰에서는 절대 나타나지 않는, 실제로 작동시켜 보고 나서야 알 수 있는 종류의 문제였습니다.

→ 도표는 모두 mermaid로 교체하여 해소. 교훈은 "최종 출력 매체에서 실제로 렌더링하여 확인하라"는 것입니다. 또한 mermaid로의 전환은 부수적으로도 궁합이 좋아, 이미지 파일 관리가 불필요해지고, 텍스트이므로 나중에 AI로 수정하기 쉽다 (AI 집필과의 친화성이 높다)는 장점이 있었습니다.

보충: 표시 확인은

zenn preview

(로컬 프리뷰)를 Playwright로 렌더링하여 수행하였고, 공개 후 본 서버(zenn.dev)에서도 육안으로 확인했습니다.

"이미 수렴했다" 이후에, 추가 리뷰가 실제 버그를 찾아냈다

다층 리뷰를 여러 라운드 돌리고, 여러 리뷰가 "이 이상은 내용 늘리기이다"라고 판단하는 수렴 상태에 도달했습니다. 보통이라면 여기서 공개합니다.

하지만 쐐기를 박기 위해 장(Chapter)별로 병렬 리뷰를 진행하고, 외부 링크의 실재 확인 및 개선 제안에 대한 적대적인 채택 여부 판단까지 수행하는 추가 리뷰를 실행한 결과, 이미 수렴된 책에서도 놓치고 있었던 실제 버그가 나왔습니다. 대표적인 예:

승인 기록 JSON 샘플이 스키마 필수 항목( 독자가 복사하면 검증에서 걸려 작동하지 않음. task_id / phase...

）를 결여하고 있었다. -
어떤 자동 승인 기능에 대한 설명이 '전제 조건'을 누락하고 있었다. "저위험(Low risk)이라면 기본적으로 자동 승인"이라고 읽힐 수 있어, 책의 핵심(인간의 승인 게이트)과 모순되었다.

두 가지 모두 "문장으로서는 자연스러웠기에" 여러 라운드의 리뷰를 빠져나갔습니다. 포괄적으로 병렬 검증을 수행하고 나서야 비로소 겉으로 드러났습니다.

적대적 검증(Adversarial Verification)이 '내용 부풀리기'를 거부해 주었다

흥미로웠던 점은, 이 추가 리뷰가 개선 제안을 거부하기도 했다는 것입니다. 각 제안을 "이것이 정말로 독자 가치를 높이는가, 아니면 단순히 내용을 부풀리는 것인가"라고 적대적으로 검증하여, 예를 들어 다음과 같은 것들을 **거부(Reject)**했습니다.

"권두에 버전 차이에 대한 주석을 추가한다" → 동일한 설명이 참조 대상인 doc에 이미 존재하여 중복됨. 본서의 "변하지 않는 원리를 다룬다"는 방침에 반함.
"부록에도 도표를 추가한다" → 기존 표로 정보가 충분하며, 장식적인 내용 부풀리기에 불과함.

리뷰를 거듭하다 보면 "무언가 고쳐야 한다"는 생각에 개선을 위한 개선을 덧붙이기 쉽습니다. 적대적 검증은 그 충동에 브레이크를 걸어주었습니다. **리뷰의 질은 '추가한 수'가 아니라 '추가해야 할 것과 거부해야 할 것을 구분할 수 있었는가'**로 결정된다는 것을 실감했습니다.

설계해서 좋았던 3가지

1. 역할을 나눈 다각도 관점 (동질적인 다수결로 만들지 않기)

"3명에게 묻기"보다 "기술적 정확성 · 독자 경험 · 공개 준비라는 별개의 축으로 묻기"가 중복되지 않는 지적을 모으는 데 효과적이었습니다. 서로 다른 모델(Codex/Gemini)을 섞는 것도 단일 모델의 사각지대(Blind spot)를 방지하는 데 효과가 있었습니다.

2. 실제 렌더링 검증을 반드시 포함할 것

문장 리뷰와 최종 매체에서의 실제 표시 확인은 별개의 문제입니다. SVG 미지원과 같은 매체 사양은 Playwright를 사용하여 실제 환경과 유사하게 렌더링하지 않으면 잡아낼 수 없습니다. 공개 전 체크리스트에 "실제로 표시하기"를 반드시 포함해야 했습니다.

3. '수렴'을 의심하는 최종 패스(Final Pass)

여러 번의 리뷰가 "이제 충분하다"라고 말하더라도, 포괄적으로 병렬 검증을 수행하는 최종 패스는 별도의 가치가 있었습니다. 다만, 거기서 나온 제안을 그대로 전부 수용하면 과잉 연마(Over-polishing)가 되므로, 적대적 검증을 통해 선별합니다. "파헤쳐 내는 것"과 "너무 많이 더하지 않는 것"을 양립시키는 것이 요령입니다.

주의사항 및 한계

멀티 에이전트(Multi-agent) 리뷰는 토큰 비용이 많이 듭니다. 모든 작업에 전력을 다하기보다는, 기술서처럼 "오류가 신뢰를 무너뜨리는" 결과물에 집중하는 것이 현실적입니다.
AI 리뷰는 구현의 정본(코드나 스키마)과 대조할 때 비로소 의미를 갖습니다. 대조 대상을 제공하지 않으면 그럴싸해 보이기만 하는 지적도 섞이게 됩니다.
마지막 공개 판단(외부로 향하는 액션)은 인간이 가져야 합니다. 리뷰는 어디까지나 판단 재료를 늘려가는 과정이었습니다.

요약

기술서 리뷰는 "몇 번 읽느냐"가 아니라 "다른 종류의 눈으로 읽기 × 실제로 구동하기"이다.
역할을 나눈 다각도 관점 + 서로 다른 모델 + 실제 렌더링 + 포괄적 리뷰를 통해 각기 다른 문제가 드러났다. 특히 매체 사양(SVG 미지원)은 실제 렌더링을 통해서만 발견되었다.
"수렴한" 이후의 포괄적 패스가 놓치고 있던 실제 버그를 찾아냈다.
적대적 검증은 내용 부풀리기를 거부하여 과잉 연마를 방지했다.

리뷰는 단순한 덧셈이 아니라, 추가해야 할 것과 거부해야 할 것을 구분하는 설계라는 것을 배웠습니다.