독자 중심 목소리 (Reader-Centered Voice)
이 정원의 글은 하네스·루프 엔지니어링처럼 IT 전문가에게도 낯선 개념을 다룬다. 상정 독자는 "AI를 이미 잘 아는 사람"이 아니라 **"AI에 관심을 가진 IT 입문자"**다.
[[writing-modes]]가 참조하는 규칙의 정본. 두 부분으로 이루어진다 — ① 독자 호명, ② 입문 독자 렌즈.
1. 독자 호명 (Reader Call-out)
인트로(1절 또는 3줄 요약 직후)에서 독자의 문제를 먼저 호명한다. 1인칭 기고든 3인칭 서술이든 같다 — '우리의 무용담'이 아니라 '같은 문제를 가진 당신을 위한 안내'로 프레이밍한다.
- 형식: "~한 팀이라면 / ~해 본 사람이라면 — 이 편은 그 자리의 기록이다"
- 위치: 첫 절 말미까지. 3줄 요약에 암시만 있는 것은 불충분
2. 입문 독자 렌즈 (Beginner Lens)
상정 독자: AI 도구를 써 봤고 더 알고 싶지만, 에이전트·하네스·루프 엔지니어링은 처음 듣는 IT 입문자. 이전 편을 읽지 않았다. 링크를 열지 않는다.
2-1. 여섯 가지 점검
| # | 점검 | 통과 기준 |
|---|---|---|
| ① | 은유 자족성 | 시리즈 은유(정원·꽃·물길·물레방아·수문·원탁·래칫·씨앗)가 이 편 안에서 한 줄로 풀린다. 이전 편 링크로 대신하지 않는다 |
| ② | 핵심 개념 조기 정의 | 하네스 · 에이전트 · 루프 엔지니어링(또는 그 편의 척추 개념 3개)이 본문 첫 1/4 안에 한 문장씩 정의된다 |
| ③ | 미정의 전문어 밀도 | 절마다 정의·병기 없는 개발 용어(도구명·인프라·형상관리 어휘)가 3개 이하. 약어 병기([[technical-terminology]])와 별개로 일반 명사형 전문어(티켓·브랜치·롤아웃·웹훅 등)도 센다 |
| ④ | 시리즈 회수 밀도 | 첫 절에서 이전 편 참조가 3문장을 넘지 않는다. 회수는 한 문장 + 괄호 링크로 압축한다 |
| ⑤ | 건너뛰기 안내 | 배경·고증·도구 세부처럼 입문자와 숙련자의 필요가 갈리는 절에는 "아는 독자는 N절로" / "세부는 건너뛰어도 좋다" 한 줄 |
| ⑥ | "쉽게 말해" 문장 | 제품·도구·체계를 소개하는 절에 기술어 없는 한 문장 요약이 있다 |
2-2. 척도 — 입문자 통과율 (1~5)
| 점수 | 기준 |
|---|---|
| 5 | 시리즈 첫 편처럼 읽힌다 — 이전 편·링크 없이 끝까지 통과 |
| 4 | 1~2곳 멈칫하나 문맥으로 회복 |
| 3 | 은유·낱말 안내 박스가 있으면 통과, 없으면 반복 막힘 |
| 2 | 핵심 개념이 뒤늦게 정의되거나 이전 편 전제 — 절반쯤에서 이탈 |
| 1 | 이전 편 없이는 요지 추출 불가 |
2-3. 처방 패턴
- 낱말 박스: 3줄 요약 직후 "이 편의 낱말 N개" 인용 블록 — 은유 ↔ 실제 뜻을 한 줄씩
- 회수 압축: "17~19편이 담장 너머(다른 회사·방법론)를 답사했다면, 이번엔 담장 안이다" 한 문장 + 링크
- "쉽게 말해": 기술 정의 뒤에 생활 언어 한 문장 ("쉽게 말해, 카카오톡으로 온 문의를 회사의 AI 상담원에게 넘기고 답을 되돌려 보내는 중계다")
- 도구 세부 격리: 명령·래퍼·환경 이야기는 절 끝으로 모으고 "여기부터는 도구 세부 — 건너뛰어도 흐름은 이어진다" 표시
- 표 앞 한 줄: 이전 편의 표를 재사용할 때 열 이름의 뜻을 한 줄로 되풀이
2-3-b. 독자에게 알리지 않는 것 — 메타 문장 금지
입문자 다리를 놓다 보면 집필 사정을 본문에 적게 되기 쉽다. 그것은 독자의 정보가 아니다.
| 쓰지 않는다 (편집 메타) | 대신 |
|---|---|
| "이전 편을 몰라도 읽히도록 썼다" · "특별편 안내" | 그냥 읽히게 쓴다 — 낱말 박스는 **"이 편의 낱말 N개"**로만 |
| "링크를 열지 않는 독자도 있어서 …" | 이유 없이 내용을 준다 |
| "검수를 거쳐" · "리비전으로 보강했다" · "독자 피드백을 반영해" | 본문에 쓰지 않는다 — 로그와 버전 문서의 몫 |
| "이 절은 씨앗 글을 그대로 옮겼다" 류의 출처 표기는 예외 | 출처 귀속은 독자의 정보다 — 유지 |
허용되는 안내(독자의 행동에 쓸모가 있는 것): 건너뛰기 안내("아는 독자는 N절로"), 낱말 박스, 정직 고지(시리즈가 독자에게 한 약속의 상태), 출처 귀속, "여기부터는 도구 세부다". 판별 질문: "이 문장이 없으면 독자가 손해를 보는가?" — 아니면 지운다.
선례: 20편 v1.22.3 에서 "특별편 안내 — 이전 편을 몰라도 읽히도록 썼다"를 낱말 박스 제목과 description·1절·2절 네 곳에 썼다가 사용자 지적으로 제거(v1.22.4). 다리를 놓는 것과 다리를 놓았다고 말하는 것은 다르다.
2-4. 검수 절차 (doc-reviewer)
- 입문 독자로 처음부터 끝까지 한 번 읽으며 "이게 뭐지?" 하고 멈춘 낱말·문장을 위치와 함께 적는다
- ①
⑥ 표로 판정, 통과율 15 산정 - 처방 패턴으로 개선 후보를 낸다 — 본문의 깊이를 줄이지 않는다. 입문자 배려는 삭제가 아니라 다리(정의·요약·안내)를 놓는 일이다
- 메타 문장 검출(§2-3-b) — "썼다/반영했다/독자도 있다" 류 집필 사정이 본문·description 에 남아 있으면 지적한다
3. 경계
- 이 렌즈는 명확성/구조 축을 대체하지 않는다 — 그 축이 "숙련 독자가 한 번에 닿는가"라면, 이 렌즈는 "입문 독자가 이탈하지 않는가"다
- 시리즈 은유를 없애라는 뜻이 아니다. 은유는 이 정원의 자산이다 — 다만 매 편 안에서 스스로 풀려야 한다
- 첫 적용: 20편 2차 검수(2026-09-07) —
harness/logs/full-review/2026-09-07-10-30-200-second-review.md§입문 독자 렌즈