톤앤매너 정합 계획 — 문체 표준 + 검증 루프¶

목적: 위키 전체가 한 사람이 쓴 것처럼 읽히도록, ① 문체 표준을 명문화하고 ② 무료 거부 게이트를 만들고 ③ 최근 변경 6개 챕터를 루프로 정합시킨다. concept-loop-engineering의 원리(거부 신호·종료 조건 3종)를 위키 운영 자체에 적용한 계획.

진단 근거: 2026-07-02 에이전트 3병렬 분석 — (A) ch01·05·06 신설↔기존 대조, (B) ch07·08·09 대조, (C) 하우스 스타일 기준선 추출.

1. 진단 요약¶

결론: 최근 보강분(7/1~7/2 에이전트 배치 작업)에서 문체가 티 나게 갈라진다.

잘 맞는 것 (건드리지 말 것)¶

🎯 목표·✏️ 직접 해보기 스캐폴드, 예상 결과 텍스트 펜스, 실습 명령문(~하라체), em-dash·화살표 사용 — 신설·기존 모두 일관.

어긋난 것 (심각도순)¶

심각도	문제	위치
상	경어 산문 한가운데 평어체 실습 섬 — "…방식입니다" 문단 바로 뒤 "…서버를 붙잡는다"로 급전환	ch01·05·06·08·09 신설 섹션 전부
중	성공 확인 라벨 4종 혼재 — "성공 판정:" / "성공:" / "성공 출력:" / 무표기 + ch09만 "초록불" 은유	신설분 파일 간
중	OS 분기 표기 3형식 — 표(ch01) / 코드 내 주석(ch05·08) / 블록쿼트 콜아웃(ch06·09)	신설분 파일 간
중	Maven/Gradle 1차 도구 반대 — 같은 예제 저장소인데 ch08은 Maven 우선, ch09는 Gradle 우선	ch08 ↔ ch09
중	용어 흔들림 — 커맨드/명령, 폴더/디렉터리/디렉토리, 콘솔/터미널	전반
국소	ch09 L552 볼드 미종결 렌더 결함 · ch07 표 6·18~20 구조 이탈(제약조건 열에 값 예시, 인덱스 행 혼입, 곡선따옴표) · ch07 L507-515 원노트 파편	개별 수정

근본 원인¶

종결어미·지시형·성공확인·OS분기 같은 실질 문체 규칙이 guide-wiki-authoring-standards에 명문화돼 있지 않다. ch02(레슨 스캐폴드)·guide-harness-module1(Step 형식)·lecture-object-ch6(비유 산문) 등 개별 문서에 "사실상의 표준"으로만 흩어져 있어, 에이전트 배치가 돌 때마다 각자 톤으로 썼다. 파일만 고치면 다음 배치에서 재발한다.

2. 문체 정책 (확정 권장안)¶

전역 통일(전부 한다체)이 아니라 문서군별 표준 유지 + 신설 섹션을 소속 문서군에 맞추기. 챕터 신설 산문만 합니다체로 바꾸면 되므로 diff가 최소이고, 원문 강의의 목소리와 lecture 93편의 개조식을 건드리지 않는다.

문서군	산문 본문	예외 슬롯 (평어 유지)
챕터 `java-study-*`	합니다체	🎯 목표 한 줄(~한다) · ✏️ 직접 해보기 명령(~하라) · "따라 하는 법" 콜아웃 · `예상 결과` 펜스 내부 서술
가이드 `guide-*`	한다체	붙여넣기 프롬프트(~해줘) · 독자 안내 박스(~하세요)
강의노트 `lecture-*`	개조식	비유 인용박스만 경어 (장면+매핑 2문단)

3. 실행 구조 — 3층 (루프 엔지니어링)¶

Phase 1  스펙 명문화        guide-wiki-authoring-standards §7 문체 표준 신설   ← 거부 기준의 원본
Phase 2  무료 거부 게이트    scripts/style-lint.sh (grep 기반, 토큰 0)          ← "아니오"라고 말할 무언가
Phase 3  파일 단위 정합 루프  6개 파일 × [게이트→수정→검증→커밋] 사이클           ← 프롬프트 B
Phase 4  적대적 검수 + 마감   교차 검수(프롬프트 C) → 배포 → backlog/log 기록

종료 조건 3종 (guide-loop-engineering-demo Step 6.5):

goal — style-lint 0건 + 빌드 통과 + 검수 PASS
resource — 파일당 최대 3사이클, 초과 시 사람 에스컬레이션
budget — 동시 병렬 3파일 이하

실행 순서: 프롬프트 A → 프롬프트 B×6 (ch01·05·06·07·08·09, 병렬 3개씩 2배치) → 프롬프트 C → 배포·기록. 예상 커밋 7~8개.

4. 업무지시 프롬프트¶

프롬프트 A — 시스템 구축 (1회 실행)¶

위키 문체 표준을 명문화하고 무료 검증 게이트를 만든다.

1) wiki/guide-wiki-authoring-standards.md에 "§7 문체 표준" 섹션 신설. 내용:
   - 종결어미 매트릭스: 챕터(java-study-*) 산문=합니다체 / 🎯 목표 한 줄·✏️ 직접 해보기
     명령문(~하라)·"따라 하는 법" 콜아웃·`예상 결과` 펜스 내부 서술=평어 /
     guide-*=한다체 / lecture-*=개조식(비유 인용박스만 경어)
   - 독자 지시: 챕터 실습=~하라, 가이드 내 붙여넣기 프롬프트=~해줘
   - 성공 확인 표준: 챕터는 ```text 펜스 첫 줄 "예상 결과" 형식이 기본.
     인라인이 불가피하면 "…가 출력되면 정상입니다" 완결 문장. 라벨形("성공 판정:" 등) 금지
   - OS 분기 3형식의 용도 규정: 명령 한 줄 차이=코드 내 트레일링 주석(# Windows: …) /
     도구·동작 자체가 다름=blockquote > **Windows**: … / 3항목 이상 비교=표
   - 용어 표준: 명령(커맨드 X), 디렉터리(폴더·디렉토리 X), 터미널(콘솔은 "콘솔 출력" 맥락만),
     실행한다(돌리다 X — 단 콜아웃 구어는 허용)
   - 표 규칙: 행=컬럼. 인덱스·제약은 표 아래 한 줄 부기. 곧은따옴표만
2) scripts/style-lint.sh 작성 — 인자로 받은 파일에서 기계 검출 가능한 위반만 grep으로 검사,
   위반 있으면 exit 1 + 위반 목록 출력:
   금칙 표기(커맨드|폴더|디렉토리), 라벨형 성공 문구(성공 판정:|성공:|성공 출력:),
   곡선따옴표(" "), 챕터 파일 한정 산문 평어 종결 밀도(코드펜스·인용박스·🎯·✏️ 슬롯 제외 후
   "다.$" 중 "니다.$"가 아닌 줄 비율 리포트)
3) 게이트 캘리브레이션(게이트 자체를 검증): 모범 파일 wiki/java-study-ch02.md에 돌려
   오탐 0 확인, wiki/java-study-ch08.md에 돌려 기지 위반(L97 평어 섬 등) 검출 확인.
   오탐이 나면 스크립트를 고치고 재검증 — 이 확인 전에는 완료 선언 금지.
4) CLAUDE.md "새 페이지 작성 후 셀프 체크"에 "bash scripts/style-lint.sh <파일> 통과" 1줄 추가.
완료 기준: §7 존재 + 캘리브레이션 2건 통과 + bash scripts/build-site.sh 통과. 커밋 1개.

프롬프트 B — 파일 정합 루프 (파일당 1회, 재사용)¶

대상: wiki/java-study-ch{NN}.md 의 톤앤매너를 §7 문체 표준(guide-wiki-authoring-standards)에
정합시킨다. 먼저 §7을 읽고 시작하라.

루프 (최대 3사이클):
1. bash scripts/style-lint.sh <대상파일> — 위반 0이고 아래 수동 점검도 깨끗하면 즉시 종료(수정 불필요)
2. 수정 — 린트 위반 + 기계 검출 불가 항목:
   - 신설 실습 섹션의 산문을 합니다체로 전환 (경어 산문 속 평어 섬 제거)
   - 라벨형 성공 문구를 "예상 결과" 펜스 또는 "…가 출력되면 정상입니다" 문장으로
   - OS 분기를 §7 용도 규정에 맞는 형식으로
   유지 영역(절대 불변): 🎯 목표·✏️ 직접 해보기 문구의 평어, 예상 결과 펜스 내부,
   코드블록 내용, 표 데이터, 원문 인용 블록, frontmatter(updated만 갱신)
3. 검증: style-lint.sh 재실행 + bash scripts/build-site.sh +
   git diff에서 코드블록·표 데이터 변경이 없는지 육안 확인
4. 통과 → 커밋(style: chNN 문체 정합) 후 종료. 실패 → 사이클 반복.
   3사이클 초과 → 수정 중단, 남은 위반과 원인을 보고하고 사람 판단 대기.

파일별 추가 지시:
- ch07: 표6 "Contents"→"contents", 곡선따옴표→곧은따옴표, content_type 제약조건 열의 값
  예시를 설명 열로 이동, 표18~20 인덱스 행을 표 아래 부기로. L507 부근 원노트 파편
  ("게시판." 등)은 삭제하지 말고 발견 사실만 보고(사용자 결정 대기)
- ch08·09: 예제 저장소의 실제 빌드 파일을 확인해 1차 도구를 통일(다른 쪽은 대안으로 병기)
- ch09: L552 볼드 미종결(`/api/admin/**` 와 ** 충돌) 수정 — 경로를 백틱으로 감싸 해결

프롬프트 C — 적대적 검수 (전체 완료 후 1회)¶

검수자 역할. wiki/java-study-ch01·05·06·07·08·09.md 를 읽고 §7 문체 표준 위반이 남았는지
적대적으로 찾아라. 특히: 한 소절 안에서 경어→평어로 꺾이는 지점, 성공 확인 라벨 잔재,
OS 분기 용도 규정 위반. 수정하지 말고 파일:라인 + 인용 + PASS/REJECT 판정만 반환하라.
불확실하면 REJECT로 기울여라. REJECT 항목은 프롬프트 B를 해당 파일에 재실행한다.

5. 진행 체크리스트¶

Phase 1+2 — 프롬프트 A 실행 (§7 신설 + style-lint.sh + 캘리브레이션 + CLAUDE.md 셀프체크) — 2026-07-02 완료
Phase 3 배치 1 — 프롬프트 B: ch01 / ch05 / ch06 — 2026-07-02 완료 (3파일 병렬, style-lint 전부 통과)
Phase 3 배치 2 — 프롬프트 B: ch07 / ch08 / ch09 — 2026-07-02 완료 (ch07은 표 구조 정합, ch08·09는 문체+도구순서+ch09 볼드 렌더 결함)
Phase 4 — 프롬프트 C 검수 → REJECT 4건: 편집 범위 내 2건(ch05 5.6·ch09 9.1) 즉시 수정, 범위 밖 2건(ch01 [참고 1]·ch05 5.8·ch07 Querydsl 7.5~7.9)은 후속 배치로 이어서 처리 — 2026-07-02 완료
Phase 5 (후속 배치) — 범위 밖 REJECT 3건 + ch07 잔여 위반 17건 + 원노트 파편 정리, 사용자 확인("완결 문장 목록으로 정리") 반영 — 2026-07-02 완료. 6개 챕터 파일 전체 style-lint 위반 0건 달성.
Phase 6 (§7 범위 확장) — 사용자가 guide-java-learning-path를 "군대식"이라 지적 → §7-1 재검토: guide-*뿐 아니라 concept-*·entity-*도 합니다체로 통일(기존엔 한다체). 58개 파일 8개씩 병렬 배치로 전환 — 2026-07-02 완료. 챕터 6 + guide/concept/entity 58 = 64개 파일 전체 style-lint 위반 0건.
마감 — 빌드·push·Firebase 배포 완료(wiki.wonslab.dev), 라이브 반영 확인 — 2026-07-02.

6. 실행 결과 요약 (2026-07-02)¶

커밋 18개: §7 표준+게이트(1) → ch01·05·06·07·08·09 1차 정합(6) → 검수 반영(1) → 기록(1) → 후속 배치 ch01·05·07(3) → 기록(1) → §7 범위 확장+게이트(1) → guide/concept/entity 배치(3) → 이 요약.

파일	변경 유형	비고
ch01	문체+용어(1.2, 18줄) + [참고 1] 절 개조식→합니다체	2회 커밋
ch05	문체+용어+성공확인+OS분기(5.5/5.6) + 5.8 개조식·구어체 정리	2회 커밋
ch06	문체+성공확인 (11줄)	6.1/6.2/6.3, 1사이클 통과
ch07	표 구조 4건 + 잔여 17건(곡선따옴표·평어체·용어) + 원노트 파편→완결 문장 목록	2회 커밋
ch08	문체+성공확인	8.0/8.3, 1사이클 통과
ch09	문체+도구순서+볼드결함+OS분기+금칙은유	9.1/9.2/9.3 + 검수 후속

사용자 결정 반영: ch07 원노트 파편("게시판." 등 명사형 단편, L507-520)을 "완결 문장 목록으로 정리" 선택에 따라 "### 추가로 설계해볼 수 있는 시나리오 아이디어" 불릿 목록(합니다체 완결 문장)으로 재작성.

7. §7 범위 확장 — guide-/concept-/entity-* 58개 (2026-07-02)¶

계기: 사용자가 guide-java-learning-path 산문("다진다. 끝낸다." 반복, "건너뛰지 말고 따라간다" 등)이 "군대식"으로 딱딱하다고 지적. 확인 결과 §7 기준(당시 한다체)대로 정확히 쓰인 상태였음 — 즉 표준 자체가 딱딱했던 것. 사용자 결정: guide-뿐 아니라 concept-·entity-*(독자 콘텐츠 전체)를 합니다체로 통일, backlog·plan류 저자 전용 메모는 예외.

실행: §7-1 매트릭스 개정(합니다체가 챕터 외 콘텐츠 전체로 확장) → style-lint.sh 검사 대상 확장(guide-/concept-/entity-*) → 표준 문서 자체 정합 → 나머지 47개 파일을 guide(8+7) / concept(9+8) / entity(8+7) 3개 카테고리, 카테고리당 2배치씩 총 6배치 병렬 실행.

카테고리	파일 수	비고
guide-*	16 (표준 문서 포함)	붙여넣기 프롬프트(~해줘)·안내 박스(~하세요)는 예외 유지
concept-*	17	비유 blockquote도 예외 없이 합니다체(lecture-*만 개조식 예외)
entity-*	15	실제 외부 원문 인용은 원문 언어 그대로 보존

검증: 챕터 6 + 이 58 = 64개 파일 전체 style-lint 위반 0건(표준 문서 자체의 자기참조 3건은 규칙표가 금지어를 예시로 인용하는 의도된 표기라 예외). 빌드·push·Firebase 배포 완료.