---
name: review-chapter
description: Node.js Deep Dive 챕터의 기술적 내용과 편집 마감 상태를 공식 문서 기반으로 검증한다
category: writing
required_tools:
  - Read
  - Bash
  - WebFetch
  - WebSearch
---

# 챕터 내용 검증 및 편집 마감 점검

## 역할

Node.js Deep Dive 책의 챕터를 검증하는 기술 에디터다. 두 가지 단계로 나뉜다.

1. **사실 검증** — 공식 문서 기반의 기술적 정확성 확인 (필수)
2. **편집 마감 점검** — 출간 직전 일관성·연결성 검사 (선택, args에 `polish` 포함 시 추가 실행)

## args 해석

- `{파일 경로 또는 챕터 번호}` — 사실 검증만 실행 (기본)
- `{파일 경로 또는 챕터 번호} polish` — 사실 검증 + 편집 마감 점검
- `{파일 경로 또는 챕터 번호} polish-only` — 편집 마감 점검만 실행 (사실 검증 생략)
- args가 없으면 사용자에게 어떤 파일을 검토할지 묻는다

챕터 번호(예: `1.3`)만 받으면 `posts/part{N}/{N.M}.*.md` 패턴으로 파일을 찾는다.

---

## Part 1: 사실 검증 (기본 단계)

### 1단계: 파일 읽기

args로 받은 경로/번호로 파일을 Read한다. 파일이 크면 offset/limit으로 나눠 읽되 *전체 본문을 한 번씩 훑는다*.

### 2단계: 기술적 주장 추출

파일 전체를 읽으며 다음 유형의 주장을 전부 목록으로 정리한다. 코드 예제는 제외하고 텍스트 주장만 대상으로 한다.

- **API/동작 설명**: "`fs.readFile()`은 libuv 스레드 풀을 사용한다"
- **내부 메커니즘**: "V8은 히든 클래스를 생성한다", "epoll은 엣지 트리거로 동작한다"
- **구체적 수치**: "기본 스레드 풀 크기는 4개", "힙 제한은 1.5GB", "4배 빠르다"
- **버전 주장**: "Node.js 22부터 지원", "Node.js 24에서 추가된"
- **비교 주장**: "cluster보다 Worker Threads가 메모리를 덜 사용한다"

### 3단계: 유형별 검증

각 주장을 아래 전략으로 검증한다. **검증은 병렬로 최대한 빠르게 진행한다.**

**구체적 수치 — 즉시 플래그, 조회 없음**
- 각주가 없으면 → ⚠️ 플래그 (조회 불필요, 출처 자체가 없으므로)
- 각주가 있으면 → 해당 URL WebFetch로 원문과 수치 일치 여부 확인

**API/동작 설명**
- WebFetch로 `https://nodejs.org/docs/latest/api/` 해당 섹션 직접 확인
- 문서에 없거나 다르면 → ❌

**V8 내부 메커니즘**
- WebSearch로 `site:v8.dev {키워드}` 검색 후 관련 글 WebFetch로 확인

**libuv 관련**
- WebFetch로 `http://docs.libuv.org/en/v1.x/` 확인

**버전 주장**
- WebFetch로 `https://nodejs.org/en/blog/release/` 릴리즈 노트 확인

**공식 문서로 검증 불가한 내용**
- 소스코드 수준의 구현 세부사항 등 → 🔍 표시

### 4단계: 결과 출력 (사실 검증)

아래 형식으로 출력한다. 각 항목에는 반드시 행 번호와 원문을 포함한다.

---

## 내용 검증: {파일명}

### ❌ 공식 문서와 불일치
- **{N}행**: "{원문 주장}"
  → {무엇이 다른지 설명}
  → 근거: {공식 문서 URL 및 관련 원문 직접 인용}

### ⚠️ 출처 없는 수치 / 표현 보강 권장
- **{N}행**: "{원문 주장}"
  → 각주 또는 직접 측정 결과(측정 환경 포함) 필요
  또는 → 사후 추측을 단정형으로 적은 경우 한정사("~로 보인다", "~라는 해석이 있다") 추가 권장

### ✅ 검증 완료
- **{N}행**: "{주장}" → {근거 URL}

### 🔍 검증 불가 (공식 문서 없음)
- **{N}행**: "{주장}"
  → 소스코드 확인 필요 또는 서술 삭제 권장

---

검증 완료 **N개** / 문제 **N개** / 출처 필요 **N개** / 검증 불가 **N개**

### 사실 검증 원칙

- 공식 문서 원문을 직접 인용해 근거를 명확히 한다
- "일반적으로", "보통" 같은 표현도 수치가 따라오면 ⚠️ 처리
- Node.js 24.13.0 이외 버전 기준으로 쓰인 내용은 ❌ 표시
- 코드 예제는 검증 대상 아님 (텍스트 주장만)
- 검증이 완료된 주장은 ✅에 반드시 포함해야 한다 (누락 금지)
- 시기/버전 매핑은 한 칸씩 어긋나기 쉬우므로 *공식 릴리즈 노트*로 한 번 더 교차 검증

---

## Part 2: 편집 마감 점검 (`polish` 인자 포함 시)

사실 검증과 다른 결의 점검이다. 외부 출처 조회 없이 *파일 내부 일관성* 과 *연결성* 을 확인한다.

### 5단계: 자동 점검 (Bash 일괄 실행)

5개 항목을 Bash로 일괄 점검한다. 가능하면 병렬로 실행한다.

#### 5.1 본문 수치 vs 실측값 일치

본문에서 *"N배 빠르다", "N% 감소", "Nms 걸렸다"* 처럼 단언한 수치가 같은 파일 안의 *측정 결과 블록* 출력값과 일치하는지 확인.

```bash
/usr/bin/grep -nE "([0-9]+(\.[0-9]+)?)(배|%|ms[^=]|ms$|초)" {파일경로} | /usr/bin/head -100
```

- 본문 주장(단언) vs 측정 결과 블록(실측)을 *수치 단위로* 매칭
- *반올림 차이* 는 허용 (예: 11.976ms → "12ms")
- 어긋나면 → 본문 수치를 실측치에 맞춰 수정하거나, 본문을 정성적 표현으로 완화

#### 5.2 각주 번호 일관성

본문 참조 `[^N]` 와 각주 정의 `[^N]:` 가 1:1로 매칭되는지, 임시 번호(`[^Nb]`, `[^Nx]`)가 남아있지 않은지 확인.

```bash
echo "[본문 참조]"; /usr/bin/grep -oE "\[\^[0-9a-z]+\]" {파일경로} | /usr/bin/grep -v ":$" | /usr/bin/sort -u
echo "[각주 정의]"; /usr/bin/grep -nE "^\[\^[^]]+\]:" {파일경로}
```

- 임시 번호 발견 시 → 정수 번호로 재정렬 (URL이 중복이면 기존 각주에 통합)
- 본문에 참조 없는 각주 정의는 *불필요한 각주* 로 표시

#### 5.3 코드 블록 언어 명시

` ``` ` 만 있고 언어가 명시되지 않은 코드 블록 시작 위치를 찾는다.

```bash
/usr/bin/awk '
  /^```/ {
    if (in_block) { in_block = 0 } else {
      in_block = 1; lang = $0; gsub(/^```/, "", lang)
      if (lang == "") print "  L"NR": [언어 없음]"
    }
  }
' {파일경로}
```

- 언어 없는 블록 발견 시 → 가장 가까운 적절한 언어(보통 `text`, `bash`, `javascript`) 명시

#### 5.4 예제 파일 경로 존재

본문에서 참조하는 `examples/...` 경로가 *실제 파일* 인지 확인.

```bash
/usr/bin/grep -ohE 'examples/[A-Za-z0-9./_-]+\.(js|mjs|cjs|ts)' {파일경로} | /usr/bin/sort -u > /tmp/refs.txt
while IFS= read -r path; do
  [ -f "$path" ] || echo "❌ 누락: $path"
done < /tmp/refs.txt
```

- 누락 파일 발견 시 → 예제 파일을 실제로 생성하거나, 본문에서 해당 참조를 제거

#### 5.5 외부 링크 생존

각주의 외부 URL이 HTTP 200/301/302를 반환하는지 일괄 점검. *시간이 오래 걸리므로 마지막에 실행*.

```bash
/usr/bin/grep -ohE 'https?://[^ )>]+' {파일경로} | /usr/bin/sed 's/[.,)>;]*$//' | /usr/bin/sort -u > /tmp/links.txt
while IFS= read -r url; do
  code=$(curl -sILo /dev/null -w "%{http_code}" --max-time 8 -A "Mozilla/5.0" "$url")
  case "$code" in
    200|301|302) ;;
    *) echo "[$code] $url" ;;
  esac
done < /tmp/links.txt
```

- 4xx/5xx 발견 시 → 브라우저로 한 번 더 확인(curl 403은 봇 차단일 수 있음)하고, 실제 죽었으면 대체 URL 또는 Wayback Machine 링크로 교체

### 6단계: 수동 점검 (사람 눈)

자동화로 못 잡는 *문맥 의존* 일관성을 확인한다.

#### 6.1 "이 절에서 기억할 것" 박스 형식

박스 9개 이상이 있으면 모두 추출해서 비교한다.

```bash
/usr/bin/awk '
  /이 절에서 기억할 것/ { in_box=1; start=NR; lines=0; next }
  in_box && /^>/ { lines++; next }
  in_box && !/^>/ { in_box=0; print "  → "lines"줄, L"start"-L"(NR-1) }
' {파일경로}
```

- 박스 *형식*(줄 수, 항목 수, 글머리표) 통일성 확인
- 박스 *배치 빈도* 가 챕터마다 달라도 *디자인 결정* 으로 보고 강제하지 않음
- 단, 박스 안의 *항목 길이* 가 들쭉날쭉(1줄짜리 옆에 5줄짜리)이면 ⚠️ 표시

#### 6.2 cross-reference 표기 통일

*"X.Y장에서", "X.Y.Z절에서", "X.Y.Z 참고"* 같은 표기 변형을 확인.

```bash
/usr/bin/grep -nE '[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)*[ 에을는이가]' {파일경로} | /usr/bin/grep -vE '^[[:space:]]*##|예제 [0-9]'
```

- *"X.Y.Z" 다음에 "절" 누락* 자리만 통일 대상 (가장 흔한 변형)
- *"확인했듯이", "다뤘듯이", "살펴봤듯이"* 같은 자연어 동사 변형은 *톤 다양성으로 유지*, 강제 통일 금지

### 7단계: 결과 출력 (편집 마감)

---

## 편집 마감 점검: {파일명}

### 자동 점검 결과

| 항목 | 결과 |
|---|---|
| 본문 수치 vs 실측값 | ✅ / ⚠️ N건 |
| 각주 번호 일관성 | ✅ / ⚠️ 임시번호 N개 |
| 코드 블록 언어 명시 | ✅ / ❌ N개 누락 |
| 예제 파일 경로 존재 | ✅ / ❌ N개 누락 |
| 외부 링크 생존 | ✅ / ❌ N개 깨짐 |

### 발견된 수정 대상

각 항목을 *행 번호 + 원문 + 권장 수정* 형식으로 제시한다.

- **{N}행**: "{원문}"
  → 권장: "{수정안}"
  → 이유: {간단한 근거}

### 수동 점검 결과

- "이 절에서 기억할 것" 박스: N개 점검 / 형식 통일 여부
- cross-reference: N개 점검 / 누락된 "절" N자리

---

자동 점검 **N개 항목** / 발견 **N건** / 수동 점검 **N건**

### 편집 마감 원칙

- 점검 자체로 끝내지 말고 *권장 수정안* 까지 제시
- 자연어 다양성 영역(동사 변형, 톤 차이)은 *통일 대상이 아님* — 표기 형식과 사실/수치만 통일
- 임시 각주 번호(`[^Nb]`)는 *반드시* 정수로 재정렬
- ebook 출간 전제라면 외부 링크 점검을 *출간 직전에 한 번 더* 돌릴 것