--- name: ko-tech-writer description: 'Writes or revises Korean technical prose across three registers — reader-facing documents (tech-blog posts, technical docs), spoken scripts, and derived compressed assets (teasers, summaries) — through a fixed pipeline: register detection, real-sample calibration of the target venue, a translationese-removal pass, honesty-level layering (reader information vs internal audit vocabulary), a number/claim gate, and a rendition + perceptual QA pass. Triggers: "기술문서 써줘", "테크블로그 초안 잡아줘", "이 문서 번역투 고쳐줘", "블로그체로 다듬어줘", "이 글 회사 기술블로그에 올릴 수 있게 다듬어줘".' user-invocable: true allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebFetch"] model: sonnet ---

# ko-tech-writer — 한국어 기술문서 집필·개고 파이프라인

독자 대면 한국어 기술 산출물(테크블로그 글 · 기술문서 · 발표 파생 자산)을 쓰거나 개고한다. 핵심 전제: **좋은 문장은 취향이 아니라 절차다** — 실물 표본으로 톤을 캘리브레이션하고, 번역투를 패턴 목록으로 제거하고, 수치는 근거와 창을 달고, 렌더 결과를 눈으로 확인한다.

> 출처: 2026-08-10 발표 기술문서 세션에서 실측으로 벼려진 규율의 자산화. 이 문서의 규칙 > 클래스는 그 세션의 개고에서 실제로 검출·수리된 것들이다 — 근거 원장은 그 세션 기록 > (`fh_completed_2026-08-10` 및 해당 개고 커밋 이력. 비공개 세션 기록이라 외부 배포본 > 독자에게는 도달하지 않는 내부 포인터다). **실측 근거가 없는 클래스를 추가하지 않는 것**이 > 이 문서의 유지 규칙이다. 이 SKILL.md 자체는 독자 대면 문서가 아니라 하네스 자산이므로 > 이 파이프라인의 적용 대상이 아니다(FH 하우스 스타일을 따른다).

## Step 0 — 대상 판별 (레지스터 분기)

같은 내용도 매체에 따라 규율이 다르다. 먼저 셋 중 무엇인지 정한다:

| 대상 | 레지스터 | 이 스킬의 적용 | |---|---|---| | **독자용 문서** (블로그 글·기술문서) | 문어 존댓말 (습니다체) | Step 1~5 전체 | | **낭독 대본** (발표 스크립트) | 구어 발표체 | Step 2~4 만 — 구어 리듬 유지, 줄표는 «쉼»으로만 실현되므로 소리로 안 들리는 동격·재진술 줄표 제거 | | **파생 압축 자산** (티저·요약 이미지·1장 슬라이드) | 자립형 평문 | Step 2~**5** + **자립성 검사**: 화면·본문 맥락 없이 서야 하므로 정본 어휘·주장 범위·은어를 따로 대조. 렌더 산출물을 만들면 Step 5 지각 QA 필수 |

검증된 원문에서 파생 자산을 만들 때도 재검사한다 — 압축은 주장 범위를 움직일 수 있다 (예: «지점 앞에서 벼려졌다» → «도메인에서 확인해 온»으로 줄면 담당 범위가 넓어져 읽힌다).

## Step 1 — 실물 캘리브레이션 (표본 없이 톤 단정 금지)

게재 매체가 지정되지 않았으면 **먼저 묻는다**(한 줄). 답을 받을 수 없는 환경이면 일반 규율로 진행하고 그 사실을 이력에 명기한다.

게재 목표 매체의 **실제 표본을 1편 이상** 확인(WebFetch)하고 세 가지를 기록한다:

1. **문체**: 존댓말 변형(습니다/해요), 도입 형식(질문형/선언형) 2. **구성**: 소제목 밀도, 마무리 관행(일반화 + 트레이드오프 + 실무 조언 등) 3. **시각물**: 다이어그램/그래프/표를 어느 밀도로 쓰는가

캘리브레이션 기록은 **산출물 이력**(작업 로그·PR 본문·문서 frontmatter)에 남긴다 — 게재 본문에는 노출하지 않는다. 표본을 확인할 수 없으면 **무엇을 시도했고 왜 안 됐는지**(호출 실패·매체 미상 등)를 같은 이력에 명기하고 일반 규율(습니다체·소제목 세분화)로 진행한다 — 확인 안 된 톤을 확정처럼 쓰지 않는다. **시도 기록 없는 «확인 불가»는 Done When 1조를 충족하지 않는다.**

## Step 2 — 문체 규율 (번역투 클래스 목록)

아래는 실측으로 검출된 클래스다. **기계 스캔 + 눈 판정**으로 제거한다 (grep은 후보를 표시할 뿐, 남길지 판정은 문맥으로):

| 클래스 | 검출 힌트 | 수리 | |---|---|---| | 줄표 이어붙임 「~다 — ~고,」 | `grep "다 — \|것 — \|음 — "` | 문장 분리. 줄표는 **일을 하는 곳만** 남긴다(열거 매달기·리듬 결속 — 남긴 이유를 적는다) | | 용어-머리 «**X** — 설명» | 글머리 기호 뒤 `** — ` | «**X**: 설명» 콜론형 | | 콜론 나열투 («관측된 분업은: …») | 서술어 없는 `:` 도입 | 완결 문장으로 («…분업은 ~라는 것입니다») | | 조각문 («걸리는 층.») | 서술어 없는 마침 | 서술어 복원 («걸리는 층입니다») | | 소유 직역 「~을 갖다/가지다」 | `grep -nE "을 갖|를 갖|을 가지|를 가지"` | 존재문으로 (**«이전 상태를 갖지 않는다» → «이전 상태가 없다»**). 영어 `have`의 직역이고, 한국어는 소유보다 존재로 말한다. 소유가 실제 논점인 자리(권한·지분)는 남긴다 | | 내부 조어·은어 | 팀 밖에서 안 쓰는 단어 (예: 렌더하다, 초록/빨강을 CI 결과 뜻으로) | 청중 어휘로 평문화. 단, **화면이 어휘를 받치면**(실제 빨간 화면을 가리키는 발화) 유지 가능 — 근거를 적는다 | | 레지스터 드리프트 | 습니다↔해요↔평어 혼재 | 표본 기준 단일화 |

클래스의 성격이 갈린다: 앞 다섯 줄(줄표·용어-머리·콜론·조각문·소유 직역)은 **기계 검출 가능**(grep 후보 + 눈 판정)이고, 뒤 두 줄(내부 조어·레지스터)은 **판정 클래스**다 — Done When에서 서로 다른 check-class로 채점된다.

### Step 2-b — 부분 개고 전용: 기존 본문과의 리듬 대조

**문서 전체를 새로 쓰는 경우가 아니라 기존 문서에 문단·문장을 끼워 넣는 경우**, 위 클래스가 전부 0이어도 **삽입분만 이질적으로 읽힐 수 있다.** 클래스 목록은 «틀린 표현»을 잡지 «튀는 표현»을 못 잡기 때문이다. 삽입·개고분에 한해 두 가지를 **수치로** 대조한다:

1. **문장 길이 분포** — 본문 평문 문장의 길이 중앙값·상위 10%를 먼저 구하고, 삽입분의 각 문장이 상위 10% 안에 드는지 본다. 넘으면 끊는다. (본문에 더 긴 문장이 있어도 근거가 못 된다 — 그건 그 문단의 리듬이지 삽입분의 것이 아니다.) 2. **어휘 반복** — 삽입분 안에서, 그리고 **직전·직후 문장까지 포함해** 같은 어간이 3회 이상 연달아 나오는지. 특히 같은 글자가 뜻이 다른 채로 반복되면(«검사를 더 **붙**여도 … 지점 쪽에 **붙**습니다») 읽는 눈이 걸린다.

> 실측(2026-08-11, 기술문서 v2.1 작업): 클래스 스캔 잔여 0인 삽입분이 본문 112문장 중 > 유일한 소유 직역 1건을 들여왔고, 문장 길이 **124자**(본문 중앙값 40자 · 상위 10% 78자), > 「내려가」 앞 문장 포함 4회 연속 · 「붙」 한 문장 안 2회였다. 셋 다 기존 클래스 목록으로는 > 안 잡혔고, **읽는 사람이 «톤이 다르다»로 먼저 알아챘다.** 의도 보존으로 제외하는 항목은 **명명된 사유**(열거 매달기·리듬 결속·화면 받침)에 한하며, 제외 목록은 Step 5 콜드리드 짝에게 **통독이 끝난 뒤** 별도 패스로 전달해 대조받는다 — 사전 전달은 첫-읽기 눈을 오염시키고, 자기가 쓴 사유만으로 무제한 제외하지 않는다.

## Step 3 — 정직 수위 층 분리

정직함에는 두 층이 있고, 독자 문서에는 한 층만 싣는다:

- **싣는다 — 논지를 받치는 정직**: 한계 절, 소표본 명시, 자기 철회 사례, "측정 중". 이걸 빼면 글의 등뼈가 빠진다. - **뺀다 — 내부 감사 어휘**: 검증 원장의 자기감사 디테일("실적은 X만 주장한다", "도달만·채택 아님" 같은 규율-말투), 내부 등급/게이트 상태 세부. 내부 기록에는 남기고 독자 본문에서는 뺀다.

판단 기준 한 줄: **"이 문장이 독자의 다음 행동이나 판단을 바꾸는가?"** — 바꾸면 정보, 안 바꾸면 자기감사다. **문장 단위로 적용**하고, 한 절의 문장 대부분이 걸리면 절 단위로 제거를 검토한다. 경계 예시: «실패 3건은 내부 전용 API 의존이라 외부 재현이 안 된다»는 독자의 재현 판단을 바꾸므로 **정보**다. «실적은 머지된 것만 주장한다»는 저자의 집계 규율 서술이라 **자기감사**다.

## Step 4 — 수치·주장 게이트 (기존 검증 자산으로 라우팅 — 재발명 금지)

**분모는 기계로 연다**: 본문의 **아라비아 숫자 전수**를 grep으로 추출해 목록을 만들고, 수치 주장이 아닌 항목(버전 표기·목차 번호·연도 등)을 **사유와 함께 제외**한 뒤, 남은 각 행에 아래 라벨 중 하나를 단다. 단위 목록으로 좁혀 시작하지 않는다 — 영문 단위(ms·GB)가 새기 때문이다. 한글 수사("세 배")는 아라비아 전수로도 못 잡으므로 **눈 판정 잔여**로 명기하고 통독에서 본다. 자기 눈으로 고른 수치만 채점하는 것은 measured가 아니다.

⚠️ **`\b` 경계 금지** — 유니코드 인식 엔진(ripgrep·GNU grep UTF-8 로케일·Python `re` — **`grep -P`는 예외다**: `(*UCP)` 없이는 `\w`가 ASCII 한정이라 숫자-한글 사이에 경계가 생긴다. 반드시 `rg` 로 고정)에서 **한글은 word 문자**라 숫자와 한글 사이엔 경계가 생기지 않는다. `\b\d[\d,]*\b`류 패턴은 숫자 뒤에 한글 조사·단위가 바로 붙는 표기(예: «7개»)를 놓친다. **known-pair로 직접 확인**(엔진 고정, 복붙 실행): 이 SKILL.md 자신에 `rg -n '\b\d[\d,]*\b'`와 `rg -n '\d(?:[\d,]*\d)?'`(끝자리 콤마를 삼키지 않게 끝을 숫자로 고정)를 각각 돌려 델타를 세면, 경계판이 놓치는 숫자가 나온다(측정일 기준 델타 수를 이력에 기록 — 놓치는 쪽은 대부분 조사·단위가 바로 붙는 주장 수치이고, 날짜·Step 번호처럼 뒤에 공백·기호가 오는 숫자는 양쪽 다 잡힌다). **경계 없는 추출**로 시작하고, 과다추출된 비주장 항목은 위 문장대로 사유와 함께 제외한다.

### Step 4-b — 전칭 단정 후보 검출 (오탐 허용 — 후보 표시용, 판정은 사람)

«전부/모두/하나도 없다/전혀/일절/예외 없이» 류 전칭 단정 어휘 + **부정형 전칭**을 `rg -n '(안|못) ?(했|만들|나오|잡히)|지 않았(다|습니다)'`(엔진 고정, 복붙 실행)로 걸러 후보로 표시하고, 각 후보의 반례가 정말 없는지 본문·근거를 다시 대조한다. grep은 후보만 내고 판정은 사람이 한다 — 오탐 다수가 정상이다. **단, 후보를 세지 않거나 판정을 비워두는 것은 결함이다** — 판정할 사람을 구할 수 없으면 후보 목록을 그대로 남기고 이 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다(자기 판정으로 대체 금지 — Step 5 격리 규율과 동형).

실측(비공개 원장, 2026-08-14): 같은 개고 세션에서 반례 탐색 없는 전칭 단정을 두 번 썼고, 한 번은 위 어휘 목록에 없는 **부정형**("~을 안 만들었다")이었다 — grep 어휘만으로 못 잡는 계열이 실재한다는 뜻이라 부정형 패턴을 함께 넣는다. **반례 탐색 없이 쓴 전칭 단정은 원문보다 개고본에서 더 잘 나온다** — 다듬는 행위 자체가 근거 재확인 없이 서술을 넓히기 때문이다. Step 5 재콜드리드가 뒤늦게 잡을 수도 있지만, 앞단에서 후보를 먼저 좁혀두면 그 라운드의 비용이 준다.

수치·주장에는 **두 가지 라벨**이 있고 서로 다른 상태다 — 섞지 않는다:

- **«발행 직전 재측정 대상»** — 근거는 확인됐으나 **시간이 지나면 값이 변하는** 것 (다운로드·별 수·테스트 수). 측정 시점·조건(창)을 병기하고 이 라벨을 단다. - **«미확인»** — **근거 실물을 아직 확인하지 못한** 주장. 창을 지어 붙이지 않는다(조작된 정밀도). 라벨과 확인 경로(어느 저장소·로그를 보면 닫히는지)를 적고, 발행 전 해소를 필수로 남긴다. 미발견은 "미확인"이지 "없음"이 아니다.

기록에 없는 실적·사례는 1차 출처(저장소·PR·로그)를 직접 조회해 확인하고 나서 싣는다. - **출처 역추적이 필요하면** `/phantom-quench` 로, **차트를 그리게 되면** 차트 작성 전에 dataviz 스킬을 먼저 로드한다. 프로젝트에 금지·조건 수치 목록(원장)이 있으면 발행 전 1패스 대조한다. 이 스킬은 **외부 검증 도구를 재발명하지 않는다**(출처 검증·차트 검증은 위 라우팅으로) — 스킬 안의 grep 열거·스캔은 절차의 일부이지 검증기 신설이 아니다.

## Step 5 — 렌디션 + 지각 QA

- **md 정본은 항상** 만든다. 다이어그램은 mermaid(GitHub·주요 뷰어 네이티브 렌더). - **HTML/PDF 렌디션은 조건부** — 요청이 명시했거나 게재 채널이 요구할 때만 만든다(판단 주체는 요청/채널이지 저자의 재량이 아니다): 자체완결 HTML(외부 의존 없는 인라인 SVG 다이어그램, 시스템 한글 폰트 스택, `@page` 인쇄 규칙) → headless Chrome `--print-to-pdf`. - **md-only 예외의 범위는 좁다** — 게재 매체가 md 를 렌더하면(위키·GitHub 등) **md-only 산출물도 렌더 산출물이다.** N/A 는 게재 매체가 렌더를 하지 않음을 확인한 경우에만 쓴다. **매체가 미상이면**(Step 1 «확인 불가» 경로로 진행한 경우) N/A 자격이 없다 — GitHub 렌더를 기본 렌더러로 가정하고 지각 확인을 수행하며, 그 가정 사실을 산출물 이력에 남긴다. 실측(비공개 원장, 2026-08-14): 렌더된 표의 한 셀에 여러 항목이 뭉쳐 기호-뜻 대응이 깨졌는데, 원문엔 항목이 전부 적혀 있어 논리적 누락이 없었고 열 수·이스케이프 같은 기계 검사도 통과했다. 배경지식 0 콜드리드를 여러 라운드 돌렸는데도 **렌더된 표를 보는 사람만** 그 결함을 알아챘다 — «md-only니까 N/A»로 판단한 것이 오판이었다 — 위키가 md를 렌더하는 순간 렌더 산출물이 생긴다. - **지각 QA(필수 — 렌더 산출물이 있을 때, md-only라도 게재 매체가 렌더하면 포함)**: 렌더 결과를 **전 페이지 눈으로** 확인한다 — 라벨 잘림(한글 받침), 페이지 나눔, 표/그림 겹침, 다이어그램 텍스트 가림, **표 셀 안에 여러 항목이 한 줄로 뭉쳐 있는지**(구분자 반복 — 렌더된 표에서만 보이고 원문 grep으론 안 잡힌다). 도구 exit 0은 렌더 성공이지 가독성 판정이 아니다. 판정 짝은 **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄)다 — 콜드리드는 내용을 읽지 렌더 결함을 보지 않으므로 짝이 될 수 없다. - **발행 전 콜드리드 1패스**: 격리된 검토가 처음 읽는 눈으로 통독한다. 저자는 자기 글의 전제 결손을 못 본다. **격리의 정의**: 저작 맥락을 상속하지 않는 실행이다. 같은 레포에서 띄운 서브에이전트는 프로젝트 지침·메모리를 상속하므로 **완전 블라인드가 아니다** — 저작 맥락 차단이 필요한 판정(전제 결손·자기 어휘 검사)은 레포 밖 cwd의 headless 실행 + 컨트롤(알려진 결함 1건 동반)로 하고, 통독 수준 검토는 다른 에이전트로도 되지만 **어느 격리 수준이었는지 이력에 적는다.** 에이전트 디스패치는 호출 세션의 권한·도구를 따른다 (이 스킬의 allowed-tools 밖의 일이다). 강격리도 비저자 짝도 구할 수 없으면 해당 judged 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다 — 자기 검토로 대체하지 않는다. - 🟥 **재콜드리드 — 지적을 반영해 고쳐 썼으면 고친 것을 다시 읽힌다.** 콜드리드 1회는 *초안*을 검증할 뿐이고, **발행되는 것은 수리본**이다. 수리는 결함의 주된 출처라서 «지적 반영»과 «통과»는 다른 사건이다. 본문이 바뀌었으면 라운드를 하나 더 돈다. **정지 조건은 라운드 수가 아니라 변경이다** — 그 라운드에 **새 지적이 0건이고 본문 변경이 0건일 때만** 닫는다(어느 하나만으로는 안 닫힌다). 고쳤으면 아직 안 닫힌 것이다. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시(Step 5 다른 judged 조건과 동형 라우팅). 라운드마다 «지적 n건 · 반영 n건 · 본문 변경 여부 · **Step 4/4-b 스캔을 이 수리본에 재실행했는가(y/n)**»를 이력에 적는다 — 수리가 결함의 주된 출처인데 수치·전칭단정 게이트가 초안 기준에 머물면 바로 그 자리에서 새 결함이 태어난다. > 실측(2026-08-11): 1차 콜드리드가 초안의 삽입 지점 오류를 잡았고, **그 수리가 새 결함 > 3종**(소유 직역 · 문장 길이 124자 · 어휘 반복)을 낳았다. 재콜드리드를 안 돌아 그대로 > 발행될 뻔했고, 읽는 사람이 «톤이 다르다»로 먼저 잡았다. 돌려 보니 문체보다 큰 것까지 > 나왔다 — 삽입분의 주장이 **반례가 흔한 단정**이었고(«검사를 아무리 늘려도 잡히지 > 않는다»), 자리도 닫는 절이 아니라 한계 절이 맞았다. 문장 다듬기 라운드가 **주장 범위와 > 배치**를 되돌렸다.

## Done When

| 조건 | check-class | |---|---| | 대상 매체 실물 표본 확인 기록이 산출물 이력에 존재 — 불가 시 **시도 내용·사유 포함** 명기(시도 기록 없는 «불가»는 불충족) | mandatory-pass | | Step 2 **기계 클래스**(줄표·용어-머리·콜론·조각문·소유 직역) 스캔 잔여 0 — 컨트롤(알려진 양성 1건) 동반, 제외는 명명 사유와 함께 목록화 | measured | | Step 2 **판정 클래스**(내부 조어·레지스터) 통과 | judged — 짝: 콜드리드 통독(통독 후 제외 목록 대조) | | **부분 개고인 경우**(기존 문서에 삽입·수정): Step 2-b 리듬 대조 — 삽입분 각 문장이 본문 길이 상위 10% 이내 ∧ 어간 3회 연속 반복 0. 전문 신규 집필이면 N/A 명기 | measured | | 본문 수치 전건(기계 추출 분모 기준, `\b` 미사용 경계없는 추출, **발행 직전 최종본 기준**)이 라벨(창 병기/재측정 대상/미확인) 동반 + **한글 수사(세 배·두 배 등) 눈 판정 잔여 목록이 이력에 명기됨(0건이면 «0»으로 기록)** | measured | | 전칭 단정(부정형 포함) 후보 grep 스캔을 **발행 직전 최종본**에서 실행 — 후보 n건 수치 기록 | measured | | 위 후보 n건 각각에 반례 확인 결과(«확인함»/«확인 못 함»)가 붙음 — 미판정 0 | judged — 짝: Step 5 콜드리드(통독 후 후보 목록 대조) | | **파생 압축 자산인 경우**(Step 0 세 번째 레지스터): 자립성 검사(정본 어휘·주장 범위·은어 대조) 결과가 이력에 존재 — 해당 없으면 N/A 명기 | judged — 짝: 배경지식 0 콜드리드(원문 비열람) | | 렌더 산출물(HTML/PDF/이미지 — 파생 압축 자산 포함)이 존재하거나 **게재 매체가 md를 렌더하는 경우**(위키·GitHub 등) 전 페이지 지각 확인 — 게재 매체가 md를 렌더하지 않음을 확인한 경우만 N/A 명기(사유 기록). **매체 미상이면** GitHub 렌더 가정으로 지각 확인 수행(가정 기록) — N/A 불가. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄) | | 콜드리드가 **변경 없음으로 닫혔다** — 마지막 라운드에 **새 지적이 0건이고 본문 변경이 0건**일 때 닫는다(어느 하나만으로는 안 닫힌다). 지적을 반영해 고쳤으면 그 수리본으로 한 라운드 더. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시. 라운드별 «지적 n · 반영 n · 본문 변경 여부» + 격리 수준(강/약) 이력 기록. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: 격리 검토(Step 5 정의) | | 정직 수위 분리(Step 3)가 적용됨 | judged — 짝: 발행 승인자 확인 또는 격리 적대 검토. 둘 다 불가하면 **미충족으로 명시 보고**(자기 검토로 대체 금지) |

## 역할 경계 (중복 아님을 명시)

- `hub-persona-auditor` **에이전트** — 완성된 대외 초안의 **페르소나 감사**(검토). 이 스킬은 **저작·개고 절차**다. Step 5 콜드리드에서 그 에이전트를 짝으로 쓸 수 있다(라우팅 관계). - `harness-doctor --lint` — **하네스 자산**의 언어 패턴(자기마케팅) 검출. 이 스킬은 독자 대면 문서가 대상이고 번역투·레지스터·정직 수위까지 다룬다. - 플랫폼 내장 문서 기능 — 특정 문체 캘리브레이션·정직 수위 층 분리·지각 QA 파이프라인은 내장에 없다(이 스킬이 더하는 것은 거버넌스다).

독립 실행 및 degrade 경로: phantom-quench·dataviz 미설치 → 해당 라우팅을 수동 대조로 · WebFetch 불가 → Step 1 «확인 불가» 경로(시도 기록 의무) · headless Chrome 부재 → HTML/PDF 렌디션을 «미생성»으로 명기하고 md 정본만 산출 · **Step 4-b 판정 주체(사람) 부재 → 후보 목록을 그대로 두고 해당 Done When 을 미충족으로 명시**(자기 판정 대체 금지) · **독립 2차 지각 패스 부재 → 렌더 스크린샷을 산출물 이력에 첨부하고 해당 Done When 을 미충족으로 명시**(저자가 같은 렌더를 두 번 보는 것으로 대체 금지 — 생성자=평가자가 된다). 각 degrade는 산출물 이력에 적는다.

**언어 범위**: 이름 그대로 **한국어 전용**이다. Step 0·1·3·4·5의 구조는 언어 무관이지만 Step 2 문체 클래스가 전부 한국어 실측이라, 영어 지원은 영어 실측 클래스가 쌓인 뒤 별도 확장(`en-` 자매 또는 일반화)으로 간다 — 실측 없는 클래스를 미리 짓지 않는다(유지 규칙).

--- name: ko-tech-writer description: 'Writes or revises Korean technical prose across three registers — reader-facing documents (tech-blog posts, technical docs), spoken scripts, and derived compressed assets (teasers, summaries) — through a fixed pipeline: register detection, real-sample calibration of the target venue, a translationese-removal pass, honesty-level layering (reader information vs internal audit vocabulary), a number/claim gate, and a rendition + perceptual QA pass. Triggers: "기술문서 써줘", "테크블로그 초안 잡아줘", "이 문서 번역투 고쳐줘", "블로그체로 다듬어줘", "이 글 회사 기술블로그에 올릴 수 있게 다듬어줘".' user-invocable: true allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebFetch"] model: sonnet ---

# ko-tech-writer — 한국어 기술문서 집필·개고 파이프라인

독자 대면 한국어 기술 산출물(테크블로그 글 · 기술문서 · 발표 파생 자산)을 쓰거나 개고한다. 핵심 전제: **좋은 문장은 취향이 아니라 절차다** — 실물 표본으로 톤을 캘리브레이션하고, 번역투를 패턴 목록으로 제거하고, 수치는 근거와 창을 달고, 렌더 결과를 눈으로 확인한다.

> 출처: 2026-08-10 발표 기술문서 세션에서 실측으로 벼려진 규율의 자산화. 이 문서의 규칙 > 클래스는 그 세션의 개고에서 실제로 검출·수리된 것들이다 — 근거 원장은 그 세션 기록 > (`fh_completed_2026-08-10` 및 해당 개고 커밋 이력. 비공개 세션 기록이라 외부 배포본 > 독자에게는 도달하지 않는 내부 포인터다). **실측 근거가 없는 클래스를 추가하지 않는 것**이 > 이 문서의 유지 규칙이다. 이 SKILL.md 자체는 독자 대면 문서가 아니라 하네스 자산이므로 > 이 파이프라인의 적용 대상이 아니다(FH 하우스 스타일을 따른다).

## Step 0 — 대상 판별 (레지스터 분기)

같은 내용도 매체에 따라 규율이 다르다. 먼저 셋 중 무엇인지 정한다:

| 대상 | 레지스터 | 이 스킬의 적용 | |---|---|---| | **독자용 문서** (블로그 글·기술문서) | 문어 존댓말 (습니다체) | Step 1~5 전체 | | **낭독 대본** (발표 스크립트) | 구어 발표체 | Step 2~4 만 — 구어 리듬 유지, 줄표는 «쉼»으로만 실현되므로 소리로 안 들리는 동격·재진술 줄표 제거 | | **파생 압축 자산** (티저·요약 이미지·1장 슬라이드) | 자립형 평문 | Step 2~**5** + **자립성 검사**: 화면·본문 맥락 없이 서야 하므로 정본 어휘·주장 범위·은어를 따로 대조. 렌더 산출물을 만들면 Step 5 지각 QA 필수 |

검증된 원문에서 파생 자산을 만들 때도 재검사한다 — 압축은 주장 범위를 움직일 수 있다 (예: «지점 앞에서 벼려졌다» → «도메인에서 확인해 온»으로 줄면 담당 범위가 넓어져 읽힌다).

## Step 1 — 실물 캘리브레이션 (표본 없이 톤 단정 금지)

게재 매체가 지정되지 않았으면 **먼저 묻는다**(한 줄). 답을 받을 수 없는 환경이면 일반 규율로 진행하고 그 사실을 이력에 명기한다.

게재 목표 매체의 **실제 표본을 1편 이상** 확인(WebFetch)하고 세 가지를 기록한다:

1. **문체**: 존댓말 변형(습니다/해요), 도입 형식(질문형/선언형) 2. **구성**: 소제목 밀도, 마무리 관행(일반화 + 트레이드오프 + 실무 조언 등) 3. **시각물**: 다이어그램/그래프/표를 어느 밀도로 쓰는가

캘리브레이션 기록은 **산출물 이력**(작업 로그·PR 본문·문서 frontmatter)에 남긴다 — 게재 본문에는 노출하지 않는다. 표본을 확인할 수 없으면 **무엇을 시도했고 왜 안 됐는지**(호출 실패·매체 미상 등)를 같은 이력에 명기하고 일반 규율(습니다체·소제목 세분화)로 진행한다 — 확인 안 된 톤을 확정처럼 쓰지 않는다. **시도 기록 없는 «확인 불가»는 Done When 1조를 충족하지 않는다.**

## Step 2 — 문체 규율 (번역투 클래스 목록)

아래는 실측으로 검출된 클래스다. **기계 스캔 + 눈 판정**으로 제거한다 (grep은 후보를 표시할 뿐, 남길지 판정은 문맥으로):

| 클래스 | 검출 힌트 | 수리 | |---|---|---| | 줄표 이어붙임 「~다 — ~고,」 | `grep "다 — \|것 — \|음 — "` | 문장 분리. 줄표는 **일을 하는 곳만** 남긴다(열거 매달기·리듬 결속 — 남긴 이유를 적는다) | | 용어-머리 «**X** — 설명» | 글머리 기호 뒤 `** — ` | «**X**: 설명» 콜론형 | | 콜론 나열투 («관측된 분업은: …») | 서술어 없는 `:` 도입 | 완결 문장으로 («…분업은 ~라는 것입니다») | | 조각문 («걸리는 층.») | 서술어 없는 마침 | 서술어 복원 («걸리는 층입니다») | | 소유 직역 「~을 갖다/가지다」 | `grep -nE "을 갖|를 갖|을 가지|를 가지"` | 존재문으로 (**«이전 상태를 갖지 않는다» → «이전 상태가 없다»**). 영어 `have`의 직역이고, 한국어는 소유보다 존재로 말한다. 소유가 실제 논점인 자리(권한·지분)는 남긴다 | | 내부 조어·은어 | 팀 밖에서 안 쓰는 단어 (예: 렌더하다, 초록/빨강을 CI 결과 뜻으로) | 청중 어휘로 평문화. 단, **화면이 어휘를 받치면**(실제 빨간 화면을 가리키는 발화) 유지 가능 — 근거를 적는다 | | 레지스터 드리프트 | 습니다↔해요↔평어 혼재 | 표본 기준 단일화 |

클래스의 성격이 갈린다: 앞 다섯 줄(줄표·용어-머리·콜론·조각문·소유 직역)은 **기계 검출 가능**(grep 후보 + 눈 판정)이고, 뒤 두 줄(내부 조어·레지스터)은 **판정 클래스**다 — Done When에서 서로 다른 check-class로 채점된다.

### Step 2-b — 부분 개고 전용: 기존 본문과의 리듬 대조

**문서 전체를 새로 쓰는 경우가 아니라 기존 문서에 문단·문장을 끼워 넣는 경우**, 위 클래스가 전부 0이어도 **삽입분만 이질적으로 읽힐 수 있다.** 클래스 목록은 «틀린 표현»을 잡지 «튀는 표현»을 못 잡기 때문이다. 삽입·개고분에 한해 두 가지를 **수치로** 대조한다:

1. **문장 길이 분포** — 본문 평문 문장의 길이 중앙값·상위 10%를 먼저 구하고, 삽입분의 각 문장이 상위 10% 안에 드는지 본다. 넘으면 끊는다. (본문에 더 긴 문장이 있어도 근거가 못 된다 — 그건 그 문단의 리듬이지 삽입분의 것이 아니다.) 2. **어휘 반복** — 삽입분 안에서, 그리고 **직전·직후 문장까지 포함해** 같은 어간이 3회 이상 연달아 나오는지. 특히 같은 글자가 뜻이 다른 채로 반복되면(«검사를 더 **붙**여도 … 지점 쪽에 **붙**습니다») 읽는 눈이 걸린다.

> 실측(2026-08-11, 기술문서 v2.1 작업): 클래스 스캔 잔여 0인 삽입분이 본문 112문장 중 > 유일한 소유 직역 1건을 들여왔고, 문장 길이 **124자**(본문 중앙값 40자 · 상위 10% 78자), > 「내려가」 앞 문장 포함 4회 연속 · 「붙」 한 문장 안 2회였다. 셋 다 기존 클래스 목록으로는 > 안 잡혔고, **읽는 사람이 «톤이 다르다»로 먼저 알아챘다.** 의도 보존으로 제외하는 항목은 **명명된 사유**(열거 매달기·리듬 결속·화면 받침)에 한하며, 제외 목록은 Step 5 콜드리드 짝에게 **통독이 끝난 뒤** 별도 패스로 전달해 대조받는다 — 사전 전달은 첫-읽기 눈을 오염시키고, 자기가 쓴 사유만으로 무제한 제외하지 않는다.

## Step 3 — 정직 수위 층 분리

정직함에는 두 층이 있고, 독자 문서에는 한 층만 싣는다:

- **싣는다 — 논지를 받치는 정직**: 한계 절, 소표본 명시, 자기 철회 사례, "측정 중". 이걸 빼면 글의 등뼈가 빠진다. - **뺀다 — 내부 감사 어휘**: 검증 원장의 자기감사 디테일("실적은 X만 주장한다", "도달만·채택 아님" 같은 규율-말투), 내부 등급/게이트 상태 세부. 내부 기록에는 남기고 독자 본문에서는 뺀다.

판단 기준 한 줄: **"이 문장이 독자의 다음 행동이나 판단을 바꾸는가?"** — 바꾸면 정보, 안 바꾸면 자기감사다. **문장 단위로 적용**하고, 한 절의 문장 대부분이 걸리면 절 단위로 제거를 검토한다. 경계 예시: «실패 3건은 내부 전용 API 의존이라 외부 재현이 안 된다»는 독자의 재현 판단을 바꾸므로 **정보**다. «실적은 머지된 것만 주장한다»는 저자의 집계 규율 서술이라 **자기감사**다.

## Step 4 — 수치·주장 게이트 (기존 검증 자산으로 라우팅 — 재발명 금지)

**분모는 기계로 연다**: 본문의 **아라비아 숫자 전수**를 grep으로 추출해 목록을 만들고, 수치 주장이 아닌 항목(버전 표기·목차 번호·연도 등)을 **사유와 함께 제외**한 뒤, 남은 각 행에 아래 라벨 중 하나를 단다. 단위 목록으로 좁혀 시작하지 않는다 — 영문 단위(ms·GB)가 새기 때문이다. 한글 수사("세 배")는 아라비아 전수로도 못 잡으므로 **눈 판정 잔여**로 명기하고 통독에서 본다. 자기 눈으로 고른 수치만 채점하는 것은 measured가 아니다.

⚠️ **`\b` 경계 금지** — 유니코드 인식 엔진(ripgrep·GNU grep UTF-8 로케일·Python `re` — **`grep -P`는 예외다**: `(*UCP)` 없이는 `\w`가 ASCII 한정이라 숫자-한글 사이에 경계가 생긴다. 반드시 `rg` 로 고정)에서 **한글은 word 문자**라 숫자와 한글 사이엔 경계가 생기지 않는다. `\b\d[\d,]*\b`류 패턴은 숫자 뒤에 한글 조사·단위가 바로 붙는 표기(예: «7개»)를 놓친다. **known-pair로 직접 확인**(엔진 고정, 복붙 실행): 이 SKILL.md 자신에 `rg -n '\b\d[\d,]*\b'`와 `rg -n '\d(?:[\d,]*\d)?'`(끝자리 콤마를 삼키지 않게 끝을 숫자로 고정)를 각각 돌려 델타를 세면, 경계판이 놓치는 숫자가 나온다(측정일 기준 델타 수를 이력에 기록 — 놓치는 쪽은 대부분 조사·단위가 바로 붙는 주장 수치이고, 날짜·Step 번호처럼 뒤에 공백·기호가 오는 숫자는 양쪽 다 잡힌다). **경계 없는 추출**로 시작하고, 과다추출된 비주장 항목은 위 문장대로 사유와 함께 제외한다.

### Step 4-b — 전칭 단정 후보 검출 (오탐 허용 — 후보 표시용, 판정은 사람)

«전부/모두/하나도 없다/전혀/일절/예외 없이» 류 전칭 단정 어휘 + **부정형 전칭**을 `rg -n '(안|못) ?(했|만들|나오|잡히)|지 않았(다|습니다)'`(엔진 고정, 복붙 실행)로 걸러 후보로 표시하고, 각 후보의 반례가 정말 없는지 본문·근거를 다시 대조한다. grep은 후보만 내고 판정은 사람이 한다 — 오탐 다수가 정상이다. **단, 후보를 세지 않거나 판정을 비워두는 것은 결함이다** — 판정할 사람을 구할 수 없으면 후보 목록을 그대로 남기고 이 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다(자기 판정으로 대체 금지 — Step 5 격리 규율과 동형).

실측(비공개 원장, 2026-08-14): 같은 개고 세션에서 반례 탐색 없는 전칭 단정을 두 번 썼고, 한 번은 위 어휘 목록에 없는 **부정형**("~을 안 만들었다")이었다 — grep 어휘만으로 못 잡는 계열이 실재한다는 뜻이라 부정형 패턴을 함께 넣는다. **반례 탐색 없이 쓴 전칭 단정은 원문보다 개고본에서 더 잘 나온다** — 다듬는 행위 자체가 근거 재확인 없이 서술을 넓히기 때문이다. Step 5 재콜드리드가 뒤늦게 잡을 수도 있지만, 앞단에서 후보를 먼저 좁혀두면 그 라운드의 비용이 준다.

수치·주장에는 **두 가지 라벨**이 있고 서로 다른 상태다 — 섞지 않는다:

- **«발행 직전 재측정 대상»** — 근거는 확인됐으나 **시간이 지나면 값이 변하는** 것 (다운로드·별 수·테스트 수). 측정 시점·조건(창)을 병기하고 이 라벨을 단다. - **«미확인»** — **근거 실물을 아직 확인하지 못한** 주장. 창을 지어 붙이지 않는다(조작된 정밀도). 라벨과 확인 경로(어느 저장소·로그를 보면 닫히는지)를 적고, 발행 전 해소를 필수로 남긴다. 미발견은 "미확인"이지 "없음"이 아니다.

기록에 없는 실적·사례는 1차 출처(저장소·PR·로그)를 직접 조회해 확인하고 나서 싣는다. - **출처 역추적이 필요하면** `/phantom-quench` 로, **차트를 그리게 되면** 차트 작성 전에 dataviz 스킬을 먼저 로드한다. 프로젝트에 금지·조건 수치 목록(원장)이 있으면 발행 전 1패스 대조한다. 이 스킬은 **외부 검증 도구를 재발명하지 않는다**(출처 검증·차트 검증은 위 라우팅으로) — 스킬 안의 grep 열거·스캔은 절차의 일부이지 검증기 신설이 아니다.

## Step 5 — 렌디션 + 지각 QA

- **md 정본은 항상** 만든다. 다이어그램은 mermaid(GitHub·주요 뷰어 네이티브 렌더). - **HTML/PDF 렌디션은 조건부** — 요청이 명시했거나 게재 채널이 요구할 때만 만든다(판단 주체는 요청/채널이지 저자의 재량이 아니다): 자체완결 HTML(외부 의존 없는 인라인 SVG 다이어그램, 시스템 한글 폰트 스택, `@page` 인쇄 규칙) → headless Chrome `--print-to-pdf`. - **md-only 예외의 범위는 좁다** — 게재 매체가 md 를 렌더하면(위키·GitHub 등) **md-only 산출물도 렌더 산출물이다.** N/A 는 게재 매체가 렌더를 하지 않음을 확인한 경우에만 쓴다. **매체가 미상이면**(Step 1 «확인 불가» 경로로 진행한 경우) N/A 자격이 없다 — GitHub 렌더를 기본 렌더러로 가정하고 지각 확인을 수행하며, 그 가정 사실을 산출물 이력에 남긴다. 실측(비공개 원장, 2026-08-14): 렌더된 표의 한 셀에 여러 항목이 뭉쳐 기호-뜻 대응이 깨졌는데, 원문엔 항목이 전부 적혀 있어 논리적 누락이 없었고 열 수·이스케이프 같은 기계 검사도 통과했다. 배경지식 0 콜드리드를 여러 라운드 돌렸는데도 **렌더된 표를 보는 사람만** 그 결함을 알아챘다 — «md-only니까 N/A»로 판단한 것이 오판이었다 — 위키가 md를 렌더하는 순간 렌더 산출물이 생긴다. - **지각 QA(필수 — 렌더 산출물이 있을 때, md-only라도 게재 매체가 렌더하면 포함)**: 렌더 결과를 **전 페이지 눈으로** 확인한다 — 라벨 잘림(한글 받침), 페이지 나눔, 표/그림 겹침, 다이어그램 텍스트 가림, **표 셀 안에 여러 항목이 한 줄로 뭉쳐 있는지**(구분자 반복 — 렌더된 표에서만 보이고 원문 grep으론 안 잡힌다). 도구 exit 0은 렌더 성공이지 가독성 판정이 아니다. 판정 짝은 **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄)다 — 콜드리드는 내용을 읽지 렌더 결함을 보지 않으므로 짝이 될 수 없다. - **발행 전 콜드리드 1패스**: 격리된 검토가 처음 읽는 눈으로 통독한다. 저자는 자기 글의 전제 결손을 못 본다. **격리의 정의**: 저작 맥락을 상속하지 않는 실행이다. 같은 레포에서 띄운 서브에이전트는 프로젝트 지침·메모리를 상속하므로 **완전 블라인드가 아니다** — 저작 맥락 차단이 필요한 판정(전제 결손·자기 어휘 검사)은 레포 밖 cwd의 headless 실행 + 컨트롤(알려진 결함 1건 동반)로 하고, 통독 수준 검토는 다른 에이전트로도 되지만 **어느 격리 수준이었는지 이력에 적는다.** 에이전트 디스패치는 호출 세션의 권한·도구를 따른다 (이 스킬의 allowed-tools 밖의 일이다). 강격리도 비저자 짝도 구할 수 없으면 해당 judged 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다 — 자기 검토로 대체하지 않는다. - 🟥 **재콜드리드 — 지적을 반영해 고쳐 썼으면 고친 것을 다시 읽힌다.** 콜드리드 1회는 *초안*을 검증할 뿐이고, **발행되는 것은 수리본**이다. 수리는 결함의 주된 출처라서 «지적 반영»과 «통과»는 다른 사건이다. 본문이 바뀌었으면 라운드를 하나 더 돈다. **정지 조건은 라운드 수가 아니라 변경이다** — 그 라운드에 **새 지적이 0건이고 본문 변경이 0건일 때만** 닫는다(어느 하나만으로는 안 닫힌다). 고쳤으면 아직 안 닫힌 것이다. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시(Step 5 다른 judged 조건과 동형 라우팅). 라운드마다 «지적 n건 · 반영 n건 · 본문 변경 여부 · **Step 4/4-b 스캔을 이 수리본에 재실행했는가(y/n)**»를 이력에 적는다 — 수리가 결함의 주된 출처인데 수치·전칭단정 게이트가 초안 기준에 머물면 바로 그 자리에서 새 결함이 태어난다. > 실측(2026-08-11): 1차 콜드리드가 초안의 삽입 지점 오류를 잡았고, **그 수리가 새 결함 > 3종**(소유 직역 · 문장 길이 124자 · 어휘 반복)을 낳았다. 재콜드리드를 안 돌아 그대로 > 발행될 뻔했고, 읽는 사람이 «톤이 다르다»로 먼저 잡았다. 돌려 보니 문체보다 큰 것까지 > 나왔다 — 삽입분의 주장이 **반례가 흔한 단정**이었고(«검사를 아무리 늘려도 잡히지 > 않는다»), 자리도 닫는 절이 아니라 한계 절이 맞았다. 문장 다듬기 라운드가 **주장 범위와 > 배치**를 되돌렸다.

## Done When

| 조건 | check-class | |---|---| | 대상 매체 실물 표본 확인 기록이 산출물 이력에 존재 — 불가 시 **시도 내용·사유 포함** 명기(시도 기록 없는 «불가»는 불충족) | mandatory-pass | | Step 2 **기계 클래스**(줄표·용어-머리·콜론·조각문·소유 직역) 스캔 잔여 0 — 컨트롤(알려진 양성 1건) 동반, 제외는 명명 사유와 함께 목록화 | measured | | Step 2 **판정 클래스**(내부 조어·레지스터) 통과 | judged — 짝: 콜드리드 통독(통독 후 제외 목록 대조) | | **부분 개고인 경우**(기존 문서에 삽입·수정): Step 2-b 리듬 대조 — 삽입분 각 문장이 본문 길이 상위 10% 이내 ∧ 어간 3회 연속 반복 0. 전문 신규 집필이면 N/A 명기 | measured | | 본문 수치 전건(기계 추출 분모 기준, `\b` 미사용 경계없는 추출, **발행 직전 최종본 기준**)이 라벨(창 병기/재측정 대상/미확인) 동반 + **한글 수사(세 배·두 배 등) 눈 판정 잔여 목록이 이력에 명기됨(0건이면 «0»으로 기록)** | measured | | 전칭 단정(부정형 포함) 후보 grep 스캔을 **발행 직전 최종본**에서 실행 — 후보 n건 수치 기록 | measured | | 위 후보 n건 각각에 반례 확인 결과(«확인함»/«확인 못 함»)가 붙음 — 미판정 0 | judged — 짝: Step 5 콜드리드(통독 후 후보 목록 대조) | | **파생 압축 자산인 경우**(Step 0 세 번째 레지스터): 자립성 검사(정본 어휘·주장 범위·은어 대조) 결과가 이력에 존재 — 해당 없으면 N/A 명기 | judged — 짝: 배경지식 0 콜드리드(원문 비열람) | | 렌더 산출물(HTML/PDF/이미지 — 파생 압축 자산 포함)이 존재하거나 **게재 매체가 md를 렌더하는 경우**(위키·GitHub 등) 전 페이지 지각 확인 — 게재 매체가 md를 렌더하지 않음을 확인한 경우만 N/A 명기(사유 기록). **매체 미상이면** GitHub 렌더 가정으로 지각 확인 수행(가정 기록) — N/A 불가. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄) | | 콜드리드가 **변경 없음으로 닫혔다** — 마지막 라운드에 **새 지적이 0건이고 본문 변경이 0건**일 때 닫는다(어느 하나만으로는 안 닫힌다). 지적을 반영해 고쳤으면 그 수리본으로 한 라운드 더. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시. 라운드별 «지적 n · 반영 n · 본문 변경 여부» + 격리 수준(강/약) 이력 기록. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: 격리 검토(Step 5 정의) | | 정직 수위 분리(Step 3)가 적용됨 | judged — 짝: 발행 승인자 확인 또는 격리 적대 검토. 둘 다 불가하면 **미충족으로 명시 보고**(자기 검토로 대체 금지) |

## 역할 경계 (중복 아님을 명시)

- `hub-persona-auditor` **에이전트** — 완성된 대외 초안의 **페르소나 감사**(검토). 이 스킬은 **저작·개고 절차**다. Step 5 콜드리드에서 그 에이전트를 짝으로 쓸 수 있다(라우팅 관계). - `harness-doctor --lint` — **하네스 자산**의 언어 패턴(자기마케팅) 검출. 이 스킬은 독자 대면 문서가 대상이고 번역투·레지스터·정직 수위까지 다룬다. - 플랫폼 내장 문서 기능 — 특정 문체 캘리브레이션·정직 수위 층 분리·지각 QA 파이프라인은 내장에 없다(이 스킬이 더하는 것은 거버넌스다).

독립 실행 및 degrade 경로: phantom-quench·dataviz 미설치 → 해당 라우팅을 수동 대조로 · WebFetch 불가 → Step 1 «확인 불가» 경로(시도 기록 의무) · headless Chrome 부재 → HTML/PDF 렌디션을 «미생성»으로 명기하고 md 정본만 산출 · **Step 4-b 판정 주체(사람) 부재 → 후보 목록을 그대로 두고 해당 Done When 을 미충족으로 명시**(자기 판정 대체 금지) · **독립 2차 지각 패스 부재 → 렌더 스크린샷을 산출물 이력에 첨부하고 해당 Done When 을 미충족으로 명시**(저자가 같은 렌더를 두 번 보는 것으로 대체 금지 — 생성자=평가자가 된다). 각 degrade는 산출물 이력에 적는다.

**언어 범위**: 이름 그대로 **한국어 전용**이다. Step 0·1·3·4·5의 구조는 언어 무관이지만 Step 2 문체 클래스가 전부 한국어 실측이라, 영어 지원은 영어 실측 클래스가 쌓인 뒤 별도 확장(`en-` 자매 또는 일반화)으로 간다 — 실측 없는 클래스를 미리 짓지 않는다(유지 규칙).

--- name: ko-tech-writer description: 'Writes or revises Korean technical prose across three registers — reader-facing documents (tech-blog posts, technical docs), spoken scripts, and derived compressed assets (teasers, summaries) — through a fixed pipeline: register detection, real-sample calibration of the target venue, a translationese-removal pass, honesty-level layering (reader information vs internal audit vocabulary), a number/claim gate, and a rendition + perceptual QA pass. Triggers: "기술문서 써줘", "테크블로그 초안 잡아줘", "이 문서 번역투 고쳐줘", "블로그체로 다듬어줘", "이 글 회사 기술블로그에 올릴 수 있게 다듬어줘".' user-invocable: true allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebFetch"] model: sonnet ---

# ko-tech-writer — 한국어 기술문서 집필·개고 파이프라인

독자 대면 한국어 기술 산출물(테크블로그 글 · 기술문서 · 발표 파생 자산)을 쓰거나 개고한다. 핵심 전제: **좋은 문장은 취향이 아니라 절차다** — 실물 표본으로 톤을 캘리브레이션하고, 번역투를 패턴 목록으로 제거하고, 수치는 근거와 창을 달고, 렌더 결과를 눈으로 확인한다.

> 출처: 2026-08-10 발표 기술문서 세션에서 실측으로 벼려진 규율의 자산화. 이 문서의 규칙 > 클래스는 그 세션의 개고에서 실제로 검출·수리된 것들이다 — 근거 원장은 그 세션 기록 > (`fh_completed_2026-08-10` 및 해당 개고 커밋 이력. 비공개 세션 기록이라 외부 배포본 > 독자에게는 도달하지 않는 내부 포인터다). **실측 근거가 없는 클래스를 추가하지 않는 것**이 > 이 문서의 유지 규칙이다. 이 SKILL.md 자체는 독자 대면 문서가 아니라 하네스 자산이므로 > 이 파이프라인의 적용 대상이 아니다(FH 하우스 스타일을 따른다).

## Step 0 — 대상 판별 (레지스터 분기)

같은 내용도 매체에 따라 규율이 다르다. 먼저 셋 중 무엇인지 정한다:

| 대상 | 레지스터 | 이 스킬의 적용 | |---|---|---| | **독자용 문서** (블로그 글·기술문서) | 문어 존댓말 (습니다체) | Step 1~5 전체 | | **낭독 대본** (발표 스크립트) | 구어 발표체 | Step 2~4 만 — 구어 리듬 유지, 줄표는 «쉼»으로만 실현되므로 소리로 안 들리는 동격·재진술 줄표 제거 | | **파생 압축 자산** (티저·요약 이미지·1장 슬라이드) | 자립형 평문 | Step 2~**5** + **자립성 검사**: 화면·본문 맥락 없이 서야 하므로 정본 어휘·주장 범위·은어를 따로 대조. 렌더 산출물을 만들면 Step 5 지각 QA 필수 |

검증된 원문에서 파생 자산을 만들 때도 재검사한다 — 압축은 주장 범위를 움직일 수 있다 (예: «지점 앞에서 벼려졌다» → «도메인에서 확인해 온»으로 줄면 담당 범위가 넓어져 읽힌다).

## Step 1 — 실물 캘리브레이션 (표본 없이 톤 단정 금지)

게재 매체가 지정되지 않았으면 **먼저 묻는다**(한 줄). 답을 받을 수 없는 환경이면 일반 규율로 진행하고 그 사실을 이력에 명기한다.

게재 목표 매체의 **실제 표본을 1편 이상** 확인(WebFetch)하고 세 가지를 기록한다:

1. **문체**: 존댓말 변형(습니다/해요), 도입 형식(질문형/선언형) 2. **구성**: 소제목 밀도, 마무리 관행(일반화 + 트레이드오프 + 실무 조언 등) 3. **시각물**: 다이어그램/그래프/표를 어느 밀도로 쓰는가

캘리브레이션 기록은 **산출물 이력**(작업 로그·PR 본문·문서 frontmatter)에 남긴다 — 게재 본문에는 노출하지 않는다. 표본을 확인할 수 없으면 **무엇을 시도했고 왜 안 됐는지**(호출 실패·매체 미상 등)를 같은 이력에 명기하고 일반 규율(습니다체·소제목 세분화)로 진행한다 — 확인 안 된 톤을 확정처럼 쓰지 않는다. **시도 기록 없는 «확인 불가»는 Done When 1조를 충족하지 않는다.**

## Step 2 — 문체 규율 (번역투 클래스 목록)

아래는 실측으로 검출된 클래스다. **기계 스캔 + 눈 판정**으로 제거한다 (grep은 후보를 표시할 뿐, 남길지 판정은 문맥으로):

| 클래스 | 검출 힌트 | 수리 | |---|---|---| | 줄표 이어붙임 「~다 — ~고,」 | `grep "다 — \|것 — \|음 — "` | 문장 분리. 줄표는 **일을 하는 곳만** 남긴다(열거 매달기·리듬 결속 — 남긴 이유를 적는다) | | 용어-머리 «**X** — 설명» | 글머리 기호 뒤 `** — ` | «**X**: 설명» 콜론형 | | 콜론 나열투 («관측된 분업은: …») | 서술어 없는 `:` 도입 | 완결 문장으로 («…분업은 ~라는 것입니다») | | 조각문 («걸리는 층.») | 서술어 없는 마침 | 서술어 복원 («걸리는 층입니다») | | 소유 직역 「~을 갖다/가지다」 | `grep -nE "을 갖|를 갖|을 가지|를 가지"` | 존재문으로 (**«이전 상태를 갖지 않는다» → «이전 상태가 없다»**). 영어 `have`의 직역이고, 한국어는 소유보다 존재로 말한다. 소유가 실제 논점인 자리(권한·지분)는 남긴다 | | 내부 조어·은어 | 팀 밖에서 안 쓰는 단어 (예: 렌더하다, 초록/빨강을 CI 결과 뜻으로) | 청중 어휘로 평문화. 단, **화면이 어휘를 받치면**(실제 빨간 화면을 가리키는 발화) 유지 가능 — 근거를 적는다 | | 레지스터 드리프트 | 습니다↔해요↔평어 혼재 | 표본 기준 단일화 |

클래스의 성격이 갈린다: 앞 다섯 줄(줄표·용어-머리·콜론·조각문·소유 직역)은 **기계 검출 가능**(grep 후보 + 눈 판정)이고, 뒤 두 줄(내부 조어·레지스터)은 **판정 클래스**다 — Done When에서 서로 다른 check-class로 채점된다.

### Step 2-b — 부분 개고 전용: 기존 본문과의 리듬 대조

**문서 전체를 새로 쓰는 경우가 아니라 기존 문서에 문단·문장을 끼워 넣는 경우**, 위 클래스가 전부 0이어도 **삽입분만 이질적으로 읽힐 수 있다.** 클래스 목록은 «틀린 표현»을 잡지 «튀는 표현»을 못 잡기 때문이다. 삽입·개고분에 한해 두 가지를 **수치로** 대조한다:

1. **문장 길이 분포** — 본문 평문 문장의 길이 중앙값·상위 10%를 먼저 구하고, 삽입분의 각 문장이 상위 10% 안에 드는지 본다. 넘으면 끊는다. (본문에 더 긴 문장이 있어도 근거가 못 된다 — 그건 그 문단의 리듬이지 삽입분의 것이 아니다.) 2. **어휘 반복** — 삽입분 안에서, 그리고 **직전·직후 문장까지 포함해** 같은 어간이 3회 이상 연달아 나오는지. 특히 같은 글자가 뜻이 다른 채로 반복되면(«검사를 더 **붙**여도 … 지점 쪽에 **붙**습니다») 읽는 눈이 걸린다.

> 실측(2026-08-11, 기술문서 v2.1 작업): 클래스 스캔 잔여 0인 삽입분이 본문 112문장 중 > 유일한 소유 직역 1건을 들여왔고, 문장 길이 **124자**(본문 중앙값 40자 · 상위 10% 78자), > 「내려가」 앞 문장 포함 4회 연속 · 「붙」 한 문장 안 2회였다. 셋 다 기존 클래스 목록으로는 > 안 잡혔고, **읽는 사람이 «톤이 다르다»로 먼저 알아챘다.** 의도 보존으로 제외하는 항목은 **명명된 사유**(열거 매달기·리듬 결속·화면 받침)에 한하며, 제외 목록은 Step 5 콜드리드 짝에게 **통독이 끝난 뒤** 별도 패스로 전달해 대조받는다 — 사전 전달은 첫-읽기 눈을 오염시키고, 자기가 쓴 사유만으로 무제한 제외하지 않는다.

## Step 3 — 정직 수위 층 분리

정직함에는 두 층이 있고, 독자 문서에는 한 층만 싣는다:

- **싣는다 — 논지를 받치는 정직**: 한계 절, 소표본 명시, 자기 철회 사례, "측정 중". 이걸 빼면 글의 등뼈가 빠진다. - **뺀다 — 내부 감사 어휘**: 검증 원장의 자기감사 디테일("실적은 X만 주장한다", "도달만·채택 아님" 같은 규율-말투), 내부 등급/게이트 상태 세부. 내부 기록에는 남기고 독자 본문에서는 뺀다.

판단 기준 한 줄: **"이 문장이 독자의 다음 행동이나 판단을 바꾸는가?"** — 바꾸면 정보, 안 바꾸면 자기감사다. **문장 단위로 적용**하고, 한 절의 문장 대부분이 걸리면 절 단위로 제거를 검토한다. 경계 예시: «실패 3건은 내부 전용 API 의존이라 외부 재현이 안 된다»는 독자의 재현 판단을 바꾸므로 **정보**다. «실적은 머지된 것만 주장한다»는 저자의 집계 규율 서술이라 **자기감사**다.

## Step 4 — 수치·주장 게이트 (기존 검증 자산으로 라우팅 — 재발명 금지)

**분모는 기계로 연다**: 본문의 **아라비아 숫자 전수**를 grep으로 추출해 목록을 만들고, 수치 주장이 아닌 항목(버전 표기·목차 번호·연도 등)을 **사유와 함께 제외**한 뒤, 남은 각 행에 아래 라벨 중 하나를 단다. 단위 목록으로 좁혀 시작하지 않는다 — 영문 단위(ms·GB)가 새기 때문이다. 한글 수사("세 배")는 아라비아 전수로도 못 잡으므로 **눈 판정 잔여**로 명기하고 통독에서 본다. 자기 눈으로 고른 수치만 채점하는 것은 measured가 아니다.

⚠️ **`\b` 경계 금지** — 유니코드 인식 엔진(ripgrep·GNU grep UTF-8 로케일·Python `re` — **`grep -P`는 예외다**: `(*UCP)` 없이는 `\w`가 ASCII 한정이라 숫자-한글 사이에 경계가 생긴다. 반드시 `rg` 로 고정)에서 **한글은 word 문자**라 숫자와 한글 사이엔 경계가 생기지 않는다. `\b\d[\d,]*\b`류 패턴은 숫자 뒤에 한글 조사·단위가 바로 붙는 표기(예: «7개»)를 놓친다. **known-pair로 직접 확인**(엔진 고정, 복붙 실행): 이 SKILL.md 자신에 `rg -n '\b\d[\d,]*\b'`와 `rg -n '\d(?:[\d,]*\d)?'`(끝자리 콤마를 삼키지 않게 끝을 숫자로 고정)를 각각 돌려 델타를 세면, 경계판이 놓치는 숫자가 나온다(측정일 기준 델타 수를 이력에 기록 — 놓치는 쪽은 대부분 조사·단위가 바로 붙는 주장 수치이고, 날짜·Step 번호처럼 뒤에 공백·기호가 오는 숫자는 양쪽 다 잡힌다). **경계 없는 추출**로 시작하고, 과다추출된 비주장 항목은 위 문장대로 사유와 함께 제외한다.

### Step 4-b — 전칭 단정 후보 검출 (오탐 허용 — 후보 표시용, 판정은 사람)

«전부/모두/하나도 없다/전혀/일절/예외 없이» 류 전칭 단정 어휘 + **부정형 전칭**을 `rg -n '(안|못) ?(했|만들|나오|잡히)|지 않았(다|습니다)'`(엔진 고정, 복붙 실행)로 걸러 후보로 표시하고, 각 후보의 반례가 정말 없는지 본문·근거를 다시 대조한다. grep은 후보만 내고 판정은 사람이 한다 — 오탐 다수가 정상이다. **단, 후보를 세지 않거나 판정을 비워두는 것은 결함이다** — 판정할 사람을 구할 수 없으면 후보 목록을 그대로 남기고 이 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다(자기 판정으로 대체 금지 — Step 5 격리 규율과 동형).

실측(비공개 원장, 2026-08-14): 같은 개고 세션에서 반례 탐색 없는 전칭 단정을 두 번 썼고, 한 번은 위 어휘 목록에 없는 **부정형**("~을 안 만들었다")이었다 — grep 어휘만으로 못 잡는 계열이 실재한다는 뜻이라 부정형 패턴을 함께 넣는다. **반례 탐색 없이 쓴 전칭 단정은 원문보다 개고본에서 더 잘 나온다** — 다듬는 행위 자체가 근거 재확인 없이 서술을 넓히기 때문이다. Step 5 재콜드리드가 뒤늦게 잡을 수도 있지만, 앞단에서 후보를 먼저 좁혀두면 그 라운드의 비용이 준다.

수치·주장에는 **두 가지 라벨**이 있고 서로 다른 상태다 — 섞지 않는다:

- **«발행 직전 재측정 대상»** — 근거는 확인됐으나 **시간이 지나면 값이 변하는** 것 (다운로드·별 수·테스트 수). 측정 시점·조건(창)을 병기하고 이 라벨을 단다. - **«미확인»** — **근거 실물을 아직 확인하지 못한** 주장. 창을 지어 붙이지 않는다(조작된 정밀도). 라벨과 확인 경로(어느 저장소·로그를 보면 닫히는지)를 적고, 발행 전 해소를 필수로 남긴다. 미발견은 "미확인"이지 "없음"이 아니다.

기록에 없는 실적·사례는 1차 출처(저장소·PR·로그)를 직접 조회해 확인하고 나서 싣는다. - **출처 역추적이 필요하면** `/phantom-quench` 로, **차트를 그리게 되면** 차트 작성 전에 dataviz 스킬을 먼저 로드한다. 프로젝트에 금지·조건 수치 목록(원장)이 있으면 발행 전 1패스 대조한다. 이 스킬은 **외부 검증 도구를 재발명하지 않는다**(출처 검증·차트 검증은 위 라우팅으로) — 스킬 안의 grep 열거·스캔은 절차의 일부이지 검증기 신설이 아니다.

## Step 5 — 렌디션 + 지각 QA

- **md 정본은 항상** 만든다. 다이어그램은 mermaid(GitHub·주요 뷰어 네이티브 렌더). - **HTML/PDF 렌디션은 조건부** — 요청이 명시했거나 게재 채널이 요구할 때만 만든다(판단 주체는 요청/채널이지 저자의 재량이 아니다): 자체완결 HTML(외부 의존 없는 인라인 SVG 다이어그램, 시스템 한글 폰트 스택, `@page` 인쇄 규칙) → headless Chrome `--print-to-pdf`. - **md-only 예외의 범위는 좁다** — 게재 매체가 md 를 렌더하면(위키·GitHub 등) **md-only 산출물도 렌더 산출물이다.** N/A 는 게재 매체가 렌더를 하지 않음을 확인한 경우에만 쓴다. **매체가 미상이면**(Step 1 «확인 불가» 경로로 진행한 경우) N/A 자격이 없다 — GitHub 렌더를 기본 렌더러로 가정하고 지각 확인을 수행하며, 그 가정 사실을 산출물 이력에 남긴다. 실측(비공개 원장, 2026-08-14): 렌더된 표의 한 셀에 여러 항목이 뭉쳐 기호-뜻 대응이 깨졌는데, 원문엔 항목이 전부 적혀 있어 논리적 누락이 없었고 열 수·이스케이프 같은 기계 검사도 통과했다. 배경지식 0 콜드리드를 여러 라운드 돌렸는데도 **렌더된 표를 보는 사람만** 그 결함을 알아챘다 — «md-only니까 N/A»로 판단한 것이 오판이었다 — 위키가 md를 렌더하는 순간 렌더 산출물이 생긴다. - **지각 QA(필수 — 렌더 산출물이 있을 때, md-only라도 게재 매체가 렌더하면 포함)**: 렌더 결과를 **전 페이지 눈으로** 확인한다 — 라벨 잘림(한글 받침), 페이지 나눔, 표/그림 겹침, 다이어그램 텍스트 가림, **표 셀 안에 여러 항목이 한 줄로 뭉쳐 있는지**(구분자 반복 — 렌더된 표에서만 보이고 원문 grep으론 안 잡힌다). 도구 exit 0은 렌더 성공이지 가독성 판정이 아니다. 판정 짝은 **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄)다 — 콜드리드는 내용을 읽지 렌더 결함을 보지 않으므로 짝이 될 수 없다. - **발행 전 콜드리드 1패스**: 격리된 검토가 처음 읽는 눈으로 통독한다. 저자는 자기 글의 전제 결손을 못 본다. **격리의 정의**: 저작 맥락을 상속하지 않는 실행이다. 같은 레포에서 띄운 서브에이전트는 프로젝트 지침·메모리를 상속하므로 **완전 블라인드가 아니다** — 저작 맥락 차단이 필요한 판정(전제 결손·자기 어휘 검사)은 레포 밖 cwd의 headless 실행 + 컨트롤(알려진 결함 1건 동반)로 하고, 통독 수준 검토는 다른 에이전트로도 되지만 **어느 격리 수준이었는지 이력에 적는다.** 에이전트 디스패치는 호출 세션의 권한·도구를 따른다 (이 스킬의 allowed-tools 밖의 일이다). 강격리도 비저자 짝도 구할 수 없으면 해당 judged 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다 — 자기 검토로 대체하지 않는다. - 🟥 **재콜드리드 — 지적을 반영해 고쳐 썼으면 고친 것을 다시 읽힌다.** 콜드리드 1회는 *초안*을 검증할 뿐이고, **발행되는 것은 수리본**이다. 수리는 결함의 주된 출처라서 «지적 반영»과 «통과»는 다른 사건이다. 본문이 바뀌었으면 라운드를 하나 더 돈다. **정지 조건은 라운드 수가 아니라 변경이다** — 그 라운드에 **새 지적이 0건이고 본문 변경이 0건일 때만** 닫는다(어느 하나만으로는 안 닫힌다). 고쳤으면 아직 안 닫힌 것이다. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시(Step 5 다른 judged 조건과 동형 라우팅). 라운드마다 «지적 n건 · 반영 n건 · 본문 변경 여부 · **Step 4/4-b 스캔을 이 수리본에 재실행했는가(y/n)**»를 이력에 적는다 — 수리가 결함의 주된 출처인데 수치·전칭단정 게이트가 초안 기준에 머물면 바로 그 자리에서 새 결함이 태어난다. > 실측(2026-08-11): 1차 콜드리드가 초안의 삽입 지점 오류를 잡았고, **그 수리가 새 결함 > 3종**(소유 직역 · 문장 길이 124자 · 어휘 반복)을 낳았다. 재콜드리드를 안 돌아 그대로 > 발행될 뻔했고, 읽는 사람이 «톤이 다르다»로 먼저 잡았다. 돌려 보니 문체보다 큰 것까지 > 나왔다 — 삽입분의 주장이 **반례가 흔한 단정**이었고(«검사를 아무리 늘려도 잡히지 > 않는다»), 자리도 닫는 절이 아니라 한계 절이 맞았다. 문장 다듬기 라운드가 **주장 범위와 > 배치**를 되돌렸다.

## Done When

| 조건 | check-class | |---|---| | 대상 매체 실물 표본 확인 기록이 산출물 이력에 존재 — 불가 시 **시도 내용·사유 포함** 명기(시도 기록 없는 «불가»는 불충족) | mandatory-pass | | Step 2 **기계 클래스**(줄표·용어-머리·콜론·조각문·소유 직역) 스캔 잔여 0 — 컨트롤(알려진 양성 1건) 동반, 제외는 명명 사유와 함께 목록화 | measured | | Step 2 **판정 클래스**(내부 조어·레지스터) 통과 | judged — 짝: 콜드리드 통독(통독 후 제외 목록 대조) | | **부분 개고인 경우**(기존 문서에 삽입·수정): Step 2-b 리듬 대조 — 삽입분 각 문장이 본문 길이 상위 10% 이내 ∧ 어간 3회 연속 반복 0. 전문 신규 집필이면 N/A 명기 | measured | | 본문 수치 전건(기계 추출 분모 기준, `\b` 미사용 경계없는 추출, **발행 직전 최종본 기준**)이 라벨(창 병기/재측정 대상/미확인) 동반 + **한글 수사(세 배·두 배 등) 눈 판정 잔여 목록이 이력에 명기됨(0건이면 «0»으로 기록)** | measured | | 전칭 단정(부정형 포함) 후보 grep 스캔을 **발행 직전 최종본**에서 실행 — 후보 n건 수치 기록 | measured | | 위 후보 n건 각각에 반례 확인 결과(«확인함»/«확인 못 함»)가 붙음 — 미판정 0 | judged — 짝: Step 5 콜드리드(통독 후 후보 목록 대조) | | **파생 압축 자산인 경우**(Step 0 세 번째 레지스터): 자립성 검사(정본 어휘·주장 범위·은어 대조) 결과가 이력에 존재 — 해당 없으면 N/A 명기 | judged — 짝: 배경지식 0 콜드리드(원문 비열람) | | 렌더 산출물(HTML/PDF/이미지 — 파생 압축 자산 포함)이 존재하거나 **게재 매체가 md를 렌더하는 경우**(위키·GitHub 등) 전 페이지 지각 확인 — 게재 매체가 md를 렌더하지 않음을 확인한 경우만 N/A 명기(사유 기록). **매체 미상이면** GitHub 렌더 가정으로 지각 확인 수행(가정 기록) — N/A 불가. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄) | | 콜드리드가 **변경 없음으로 닫혔다** — 마지막 라운드에 **새 지적이 0건이고 본문 변경이 0건**일 때 닫는다(어느 하나만으로는 안 닫힌다). 지적을 반영해 고쳤으면 그 수리본으로 한 라운드 더. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시. 라운드별 «지적 n · 반영 n · 본문 변경 여부» + 격리 수준(강/약) 이력 기록. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: 격리 검토(Step 5 정의) | | 정직 수위 분리(Step 3)가 적용됨 | judged — 짝: 발행 승인자 확인 또는 격리 적대 검토. 둘 다 불가하면 **미충족으로 명시 보고**(자기 검토로 대체 금지) |

## 역할 경계 (중복 아님을 명시)

- `hub-persona-auditor` **에이전트** — 완성된 대외 초안의 **페르소나 감사**(검토). 이 스킬은 **저작·개고 절차**다. Step 5 콜드리드에서 그 에이전트를 짝으로 쓸 수 있다(라우팅 관계). - `harness-doctor --lint` — **하네스 자산**의 언어 패턴(자기마케팅) 검출. 이 스킬은 독자 대면 문서가 대상이고 번역투·레지스터·정직 수위까지 다룬다. - 플랫폼 내장 문서 기능 — 특정 문체 캘리브레이션·정직 수위 층 분리·지각 QA 파이프라인은 내장에 없다(이 스킬이 더하는 것은 거버넌스다).

독립 실행 및 degrade 경로: phantom-quench·dataviz 미설치 → 해당 라우팅을 수동 대조로 · WebFetch 불가 → Step 1 «확인 불가» 경로(시도 기록 의무) · headless Chrome 부재 → HTML/PDF 렌디션을 «미생성»으로 명기하고 md 정본만 산출 · **Step 4-b 판정 주체(사람) 부재 → 후보 목록을 그대로 두고 해당 Done When 을 미충족으로 명시**(자기 판정 대체 금지) · **독립 2차 지각 패스 부재 → 렌더 스크린샷을 산출물 이력에 첨부하고 해당 Done When 을 미충족으로 명시**(저자가 같은 렌더를 두 번 보는 것으로 대체 금지 — 생성자=평가자가 된다). 각 degrade는 산출물 이력에 적는다.

**언어 범위**: 이름 그대로 **한국어 전용**이다. Step 0·1·3·4·5의 구조는 언어 무관이지만 Step 2 문체 클래스가 전부 한국어 실측이라, 영어 지원은 영어 실측 클래스가 쌓인 뒤 별도 확장(`en-` 자매 또는 일반화)으로 간다 — 실측 없는 클래스를 미리 짓지 않는다(유지 규칙).

--- name: ko-tech-writer description: 'Writes or revises Korean technical prose across three registers — reader-facing documents (tech-blog posts, technical docs), spoken scripts, and derived compressed assets (teasers, summaries) — through a fixed pipeline: register detection, real-sample calibration of the target venue, a translationese-removal pass, honesty-level layering (reader information vs internal audit vocabulary), a number/claim gate, and a rendition + perceptual QA pass. Triggers: "기술문서 써줘", "테크블로그 초안 잡아줘", "이 문서 번역투 고쳐줘", "블로그체로 다듬어줘", "이 글 회사 기술블로그에 올릴 수 있게 다듬어줘".' user-invocable: true allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebFetch"] model: sonnet ---

# ko-tech-writer — 한국어 기술문서 집필·개고 파이프라인

독자 대면 한국어 기술 산출물(테크블로그 글 · 기술문서 · 발표 파생 자산)을 쓰거나 개고한다. 핵심 전제: **좋은 문장은 취향이 아니라 절차다** — 실물 표본으로 톤을 캘리브레이션하고, 번역투를 패턴 목록으로 제거하고, 수치는 근거와 창을 달고, 렌더 결과를 눈으로 확인한다.

> 출처: 2026-08-10 발표 기술문서 세션에서 실측으로 벼려진 규율의 자산화. 이 문서의 규칙 > 클래스는 그 세션의 개고에서 실제로 검출·수리된 것들이다 — 근거 원장은 그 세션 기록 > (`fh_completed_2026-08-10` 및 해당 개고 커밋 이력. 비공개 세션 기록이라 외부 배포본 > 독자에게는 도달하지 않는 내부 포인터다). **실측 근거가 없는 클래스를 추가하지 않는 것**이 > 이 문서의 유지 규칙이다. 이 SKILL.md 자체는 독자 대면 문서가 아니라 하네스 자산이므로 > 이 파이프라인의 적용 대상이 아니다(FH 하우스 스타일을 따른다).

## Step 0 — 대상 판별 (레지스터 분기)

같은 내용도 매체에 따라 규율이 다르다. 먼저 셋 중 무엇인지 정한다:

| 대상 | 레지스터 | 이 스킬의 적용 | |---|---|---| | **독자용 문서** (블로그 글·기술문서) | 문어 존댓말 (습니다체) | Step 1~5 전체 | | **낭독 대본** (발표 스크립트) | 구어 발표체 | Step 2~4 만 — 구어 리듬 유지, 줄표는 «쉼»으로만 실현되므로 소리로 안 들리는 동격·재진술 줄표 제거 | | **파생 압축 자산** (티저·요약 이미지·1장 슬라이드) | 자립형 평문 | Step 2~**5** + **자립성 검사**: 화면·본문 맥락 없이 서야 하므로 정본 어휘·주장 범위·은어를 따로 대조. 렌더 산출물을 만들면 Step 5 지각 QA 필수 |

검증된 원문에서 파생 자산을 만들 때도 재검사한다 — 압축은 주장 범위를 움직일 수 있다 (예: «지점 앞에서 벼려졌다» → «도메인에서 확인해 온»으로 줄면 담당 범위가 넓어져 읽힌다).

## Step 1 — 실물 캘리브레이션 (표본 없이 톤 단정 금지)

게재 매체가 지정되지 않았으면 **먼저 묻는다**(한 줄). 답을 받을 수 없는 환경이면 일반 규율로 진행하고 그 사실을 이력에 명기한다.

게재 목표 매체의 **실제 표본을 1편 이상** 확인(WebFetch)하고 세 가지를 기록한다:

1. **문체**: 존댓말 변형(습니다/해요), 도입 형식(질문형/선언형) 2. **구성**: 소제목 밀도, 마무리 관행(일반화 + 트레이드오프 + 실무 조언 등) 3. **시각물**: 다이어그램/그래프/표를 어느 밀도로 쓰는가

캘리브레이션 기록은 **산출물 이력**(작업 로그·PR 본문·문서 frontmatter)에 남긴다 — 게재 본문에는 노출하지 않는다. 표본을 확인할 수 없으면 **무엇을 시도했고 왜 안 됐는지**(호출 실패·매체 미상 등)를 같은 이력에 명기하고 일반 규율(습니다체·소제목 세분화)로 진행한다 — 확인 안 된 톤을 확정처럼 쓰지 않는다. **시도 기록 없는 «확인 불가»는 Done When 1조를 충족하지 않는다.**

## Step 2 — 문체 규율 (번역투 클래스 목록)

아래는 실측으로 검출된 클래스다. **기계 스캔 + 눈 판정**으로 제거한다 (grep은 후보를 표시할 뿐, 남길지 판정은 문맥으로):

| 클래스 | 검출 힌트 | 수리 | |---|---|---| | 줄표 이어붙임 「~다 — ~고,」 | `grep "다 — \|것 — \|음 — "` | 문장 분리. 줄표는 **일을 하는 곳만** 남긴다(열거 매달기·리듬 결속 — 남긴 이유를 적는다) | | 용어-머리 «**X** — 설명» | 글머리 기호 뒤 `** — ` | «**X**: 설명» 콜론형 | | 콜론 나열투 («관측된 분업은: …») | 서술어 없는 `:` 도입 | 완결 문장으로 («…분업은 ~라는 것입니다») | | 조각문 («걸리는 층.») | 서술어 없는 마침 | 서술어 복원 («걸리는 층입니다») | | 소유 직역 「~을 갖다/가지다」 | `grep -nE "을 갖|를 갖|을 가지|를 가지"` | 존재문으로 (**«이전 상태를 갖지 않는다» → «이전 상태가 없다»**). 영어 `have`의 직역이고, 한국어는 소유보다 존재로 말한다. 소유가 실제 논점인 자리(권한·지분)는 남긴다 | | 내부 조어·은어 | 팀 밖에서 안 쓰는 단어 (예: 렌더하다, 초록/빨강을 CI 결과 뜻으로) | 청중 어휘로 평문화. 단, **화면이 어휘를 받치면**(실제 빨간 화면을 가리키는 발화) 유지 가능 — 근거를 적는다 | | 레지스터 드리프트 | 습니다↔해요↔평어 혼재 | 표본 기준 단일화 |

클래스의 성격이 갈린다: 앞 다섯 줄(줄표·용어-머리·콜론·조각문·소유 직역)은 **기계 검출 가능**(grep 후보 + 눈 판정)이고, 뒤 두 줄(내부 조어·레지스터)은 **판정 클래스**다 — Done When에서 서로 다른 check-class로 채점된다.

### Step 2-b — 부분 개고 전용: 기존 본문과의 리듬 대조

**문서 전체를 새로 쓰는 경우가 아니라 기존 문서에 문단·문장을 끼워 넣는 경우**, 위 클래스가 전부 0이어도 **삽입분만 이질적으로 읽힐 수 있다.** 클래스 목록은 «틀린 표현»을 잡지 «튀는 표현»을 못 잡기 때문이다. 삽입·개고분에 한해 두 가지를 **수치로** 대조한다:

1. **문장 길이 분포** — 본문 평문 문장의 길이 중앙값·상위 10%를 먼저 구하고, 삽입분의 각 문장이 상위 10% 안에 드는지 본다. 넘으면 끊는다. (본문에 더 긴 문장이 있어도 근거가 못 된다 — 그건 그 문단의 리듬이지 삽입분의 것이 아니다.) 2. **어휘 반복** — 삽입분 안에서, 그리고 **직전·직후 문장까지 포함해** 같은 어간이 3회 이상 연달아 나오는지. 특히 같은 글자가 뜻이 다른 채로 반복되면(«검사를 더 **붙**여도 … 지점 쪽에 **붙**습니다») 읽는 눈이 걸린다.

> 실측(2026-08-11, 기술문서 v2.1 작업): 클래스 스캔 잔여 0인 삽입분이 본문 112문장 중 > 유일한 소유 직역 1건을 들여왔고, 문장 길이 **124자**(본문 중앙값 40자 · 상위 10% 78자), > 「내려가」 앞 문장 포함 4회 연속 · 「붙」 한 문장 안 2회였다. 셋 다 기존 클래스 목록으로는 > 안 잡혔고, **읽는 사람이 «톤이 다르다»로 먼저 알아챘다.** 의도 보존으로 제외하는 항목은 **명명된 사유**(열거 매달기·리듬 결속·화면 받침)에 한하며, 제외 목록은 Step 5 콜드리드 짝에게 **통독이 끝난 뒤** 별도 패스로 전달해 대조받는다 — 사전 전달은 첫-읽기 눈을 오염시키고, 자기가 쓴 사유만으로 무제한 제외하지 않는다.

## Step 3 — 정직 수위 층 분리

정직함에는 두 층이 있고, 독자 문서에는 한 층만 싣는다:

- **싣는다 — 논지를 받치는 정직**: 한계 절, 소표본 명시, 자기 철회 사례, "측정 중". 이걸 빼면 글의 등뼈가 빠진다. - **뺀다 — 내부 감사 어휘**: 검증 원장의 자기감사 디테일("실적은 X만 주장한다", "도달만·채택 아님" 같은 규율-말투), 내부 등급/게이트 상태 세부. 내부 기록에는 남기고 독자 본문에서는 뺀다.

판단 기준 한 줄: **"이 문장이 독자의 다음 행동이나 판단을 바꾸는가?"** — 바꾸면 정보, 안 바꾸면 자기감사다. **문장 단위로 적용**하고, 한 절의 문장 대부분이 걸리면 절 단위로 제거를 검토한다. 경계 예시: «실패 3건은 내부 전용 API 의존이라 외부 재현이 안 된다»는 독자의 재현 판단을 바꾸므로 **정보**다. «실적은 머지된 것만 주장한다»는 저자의 집계 규율 서술이라 **자기감사**다.

## Step 4 — 수치·주장 게이트 (기존 검증 자산으로 라우팅 — 재발명 금지)

**분모는 기계로 연다**: 본문의 **아라비아 숫자 전수**를 grep으로 추출해 목록을 만들고, 수치 주장이 아닌 항목(버전 표기·목차 번호·연도 등)을 **사유와 함께 제외**한 뒤, 남은 각 행에 아래 라벨 중 하나를 단다. 단위 목록으로 좁혀 시작하지 않는다 — 영문 단위(ms·GB)가 새기 때문이다. 한글 수사("세 배")는 아라비아 전수로도 못 잡으므로 **눈 판정 잔여**로 명기하고 통독에서 본다. 자기 눈으로 고른 수치만 채점하는 것은 measured가 아니다.

⚠️ **`\b` 경계 금지** — 유니코드 인식 엔진(ripgrep·GNU grep UTF-8 로케일·Python `re` — **`grep -P`는 예외다**: `(*UCP)` 없이는 `\w`가 ASCII 한정이라 숫자-한글 사이에 경계가 생긴다. 반드시 `rg` 로 고정)에서 **한글은 word 문자**라 숫자와 한글 사이엔 경계가 생기지 않는다. `\b\d[\d,]*\b`류 패턴은 숫자 뒤에 한글 조사·단위가 바로 붙는 표기(예: «7개»)를 놓친다. **known-pair로 직접 확인**(엔진 고정, 복붙 실행): 이 SKILL.md 자신에 `rg -n '\b\d[\d,]*\b'`와 `rg -n '\d(?:[\d,]*\d)?'`(끝자리 콤마를 삼키지 않게 끝을 숫자로 고정)를 각각 돌려 델타를 세면, 경계판이 놓치는 숫자가 나온다(측정일 기준 델타 수를 이력에 기록 — 놓치는 쪽은 대부분 조사·단위가 바로 붙는 주장 수치이고, 날짜·Step 번호처럼 뒤에 공백·기호가 오는 숫자는 양쪽 다 잡힌다). **경계 없는 추출**로 시작하고, 과다추출된 비주장 항목은 위 문장대로 사유와 함께 제외한다.

### Step 4-b — 전칭 단정 후보 검출 (오탐 허용 — 후보 표시용, 판정은 사람)

«전부/모두/하나도 없다/전혀/일절/예외 없이» 류 전칭 단정 어휘 + **부정형 전칭**을 `rg -n '(안|못) ?(했|만들|나오|잡히)|지 않았(다|습니다)'`(엔진 고정, 복붙 실행)로 걸러 후보로 표시하고, 각 후보의 반례가 정말 없는지 본문·근거를 다시 대조한다. grep은 후보만 내고 판정은 사람이 한다 — 오탐 다수가 정상이다. **단, 후보를 세지 않거나 판정을 비워두는 것은 결함이다** — 판정할 사람을 구할 수 없으면 후보 목록을 그대로 남기고 이 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다(자기 판정으로 대체 금지 — Step 5 격리 규율과 동형).

실측(비공개 원장, 2026-08-14): 같은 개고 세션에서 반례 탐색 없는 전칭 단정을 두 번 썼고, 한 번은 위 어휘 목록에 없는 **부정형**("~을 안 만들었다")이었다 — grep 어휘만으로 못 잡는 계열이 실재한다는 뜻이라 부정형 패턴을 함께 넣는다. **반례 탐색 없이 쓴 전칭 단정은 원문보다 개고본에서 더 잘 나온다** — 다듬는 행위 자체가 근거 재확인 없이 서술을 넓히기 때문이다. Step 5 재콜드리드가 뒤늦게 잡을 수도 있지만, 앞단에서 후보를 먼저 좁혀두면 그 라운드의 비용이 준다.

수치·주장에는 **두 가지 라벨**이 있고 서로 다른 상태다 — 섞지 않는다:

- **«발행 직전 재측정 대상»** — 근거는 확인됐으나 **시간이 지나면 값이 변하는** 것 (다운로드·별 수·테스트 수). 측정 시점·조건(창)을 병기하고 이 라벨을 단다. - **«미확인»** — **근거 실물을 아직 확인하지 못한** 주장. 창을 지어 붙이지 않는다(조작된 정밀도). 라벨과 확인 경로(어느 저장소·로그를 보면 닫히는지)를 적고, 발행 전 해소를 필수로 남긴다. 미발견은 "미확인"이지 "없음"이 아니다.

기록에 없는 실적·사례는 1차 출처(저장소·PR·로그)를 직접 조회해 확인하고 나서 싣는다. - **출처 역추적이 필요하면** `/phantom-quench` 로, **차트를 그리게 되면** 차트 작성 전에 dataviz 스킬을 먼저 로드한다. 프로젝트에 금지·조건 수치 목록(원장)이 있으면 발행 전 1패스 대조한다. 이 스킬은 **외부 검증 도구를 재발명하지 않는다**(출처 검증·차트 검증은 위 라우팅으로) — 스킬 안의 grep 열거·스캔은 절차의 일부이지 검증기 신설이 아니다.

## Step 5 — 렌디션 + 지각 QA

- **md 정본은 항상** 만든다. 다이어그램은 mermaid(GitHub·주요 뷰어 네이티브 렌더). - **HTML/PDF 렌디션은 조건부** — 요청이 명시했거나 게재 채널이 요구할 때만 만든다(판단 주체는 요청/채널이지 저자의 재량이 아니다): 자체완결 HTML(외부 의존 없는 인라인 SVG 다이어그램, 시스템 한글 폰트 스택, `@page` 인쇄 규칙) → headless Chrome `--print-to-pdf`. - **md-only 예외의 범위는 좁다** — 게재 매체가 md 를 렌더하면(위키·GitHub 등) **md-only 산출물도 렌더 산출물이다.** N/A 는 게재 매체가 렌더를 하지 않음을 확인한 경우에만 쓴다. **매체가 미상이면**(Step 1 «확인 불가» 경로로 진행한 경우) N/A 자격이 없다 — GitHub 렌더를 기본 렌더러로 가정하고 지각 확인을 수행하며, 그 가정 사실을 산출물 이력에 남긴다. 실측(비공개 원장, 2026-08-14): 렌더된 표의 한 셀에 여러 항목이 뭉쳐 기호-뜻 대응이 깨졌는데, 원문엔 항목이 전부 적혀 있어 논리적 누락이 없었고 열 수·이스케이프 같은 기계 검사도 통과했다. 배경지식 0 콜드리드를 여러 라운드 돌렸는데도 **렌더된 표를 보는 사람만** 그 결함을 알아챘다 — «md-only니까 N/A»로 판단한 것이 오판이었다 — 위키가 md를 렌더하는 순간 렌더 산출물이 생긴다. - **지각 QA(필수 — 렌더 산출물이 있을 때, md-only라도 게재 매체가 렌더하면 포함)**: 렌더 결과를 **전 페이지 눈으로** 확인한다 — 라벨 잘림(한글 받침), 페이지 나눔, 표/그림 겹침, 다이어그램 텍스트 가림, **표 셀 안에 여러 항목이 한 줄로 뭉쳐 있는지**(구분자 반복 — 렌더된 표에서만 보이고 원문 grep으론 안 잡힌다). 도구 exit 0은 렌더 성공이지 가독성 판정이 아니다. 판정 짝은 **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄)다 — 콜드리드는 내용을 읽지 렌더 결함을 보지 않으므로 짝이 될 수 없다. - **발행 전 콜드리드 1패스**: 격리된 검토가 처음 읽는 눈으로 통독한다. 저자는 자기 글의 전제 결손을 못 본다. **격리의 정의**: 저작 맥락을 상속하지 않는 실행이다. 같은 레포에서 띄운 서브에이전트는 프로젝트 지침·메모리를 상속하므로 **완전 블라인드가 아니다** — 저작 맥락 차단이 필요한 판정(전제 결손·자기 어휘 검사)은 레포 밖 cwd의 headless 실행 + 컨트롤(알려진 결함 1건 동반)로 하고, 통독 수준 검토는 다른 에이전트로도 되지만 **어느 격리 수준이었는지 이력에 적는다.** 에이전트 디스패치는 호출 세션의 권한·도구를 따른다 (이 스킬의 allowed-tools 밖의 일이다). 강격리도 비저자 짝도 구할 수 없으면 해당 judged 조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다 — 자기 검토로 대체하지 않는다. - 🟥 **재콜드리드 — 지적을 반영해 고쳐 썼으면 고친 것을 다시 읽힌다.** 콜드리드 1회는 *초안*을 검증할 뿐이고, **발행되는 것은 수리본**이다. 수리는 결함의 주된 출처라서 «지적 반영»과 «통과»는 다른 사건이다. 본문이 바뀌었으면 라운드를 하나 더 돈다. **정지 조건은 라운드 수가 아니라 변경이다** — 그 라운드에 **새 지적이 0건이고 본문 변경이 0건일 때만** 닫는다(어느 하나만으로는 안 닫힌다). 고쳤으면 아직 안 닫힌 것이다. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시(Step 5 다른 judged 조건과 동형 라우팅). 라운드마다 «지적 n건 · 반영 n건 · 본문 변경 여부 · **Step 4/4-b 스캔을 이 수리본에 재실행했는가(y/n)**»를 이력에 적는다 — 수리가 결함의 주된 출처인데 수치·전칭단정 게이트가 초안 기준에 머물면 바로 그 자리에서 새 결함이 태어난다. > 실측(2026-08-11): 1차 콜드리드가 초안의 삽입 지점 오류를 잡았고, **그 수리가 새 결함 > 3종**(소유 직역 · 문장 길이 124자 · 어휘 반복)을 낳았다. 재콜드리드를 안 돌아 그대로 > 발행될 뻔했고, 읽는 사람이 «톤이 다르다»로 먼저 잡았다. 돌려 보니 문체보다 큰 것까지 > 나왔다 — 삽입분의 주장이 **반례가 흔한 단정**이었고(«검사를 아무리 늘려도 잡히지 > 않는다»), 자리도 닫는 절이 아니라 한계 절이 맞았다. 문장 다듬기 라운드가 **주장 범위와 > 배치**를 되돌렸다.

## Done When

| 조건 | check-class | |---|---| | 대상 매체 실물 표본 확인 기록이 산출물 이력에 존재 — 불가 시 **시도 내용·사유 포함** 명기(시도 기록 없는 «불가»는 불충족) | mandatory-pass | | Step 2 **기계 클래스**(줄표·용어-머리·콜론·조각문·소유 직역) 스캔 잔여 0 — 컨트롤(알려진 양성 1건) 동반, 제외는 명명 사유와 함께 목록화 | measured | | Step 2 **판정 클래스**(내부 조어·레지스터) 통과 | judged — 짝: 콜드리드 통독(통독 후 제외 목록 대조) | | **부분 개고인 경우**(기존 문서에 삽입·수정): Step 2-b 리듬 대조 — 삽입분 각 문장이 본문 길이 상위 10% 이내 ∧ 어간 3회 연속 반복 0. 전문 신규 집필이면 N/A 명기 | measured | | 본문 수치 전건(기계 추출 분모 기준, `\b` 미사용 경계없는 추출, **발행 직전 최종본 기준**)이 라벨(창 병기/재측정 대상/미확인) 동반 + **한글 수사(세 배·두 배 등) 눈 판정 잔여 목록이 이력에 명기됨(0건이면 «0»으로 기록)** | measured | | 전칭 단정(부정형 포함) 후보 grep 스캔을 **발행 직전 최종본**에서 실행 — 후보 n건 수치 기록 | measured | | 위 후보 n건 각각에 반례 확인 결과(«확인함»/«확인 못 함»)가 붙음 — 미판정 0 | judged — 짝: Step 5 콜드리드(통독 후 후보 목록 대조) | | **파생 압축 자산인 경우**(Step 0 세 번째 레지스터): 자립성 검사(정본 어휘·주장 범위·은어 대조) 결과가 이력에 존재 — 해당 없으면 N/A 명기 | judged — 짝: 배경지식 0 콜드리드(원문 비열람) | | 렌더 산출물(HTML/PDF/이미지 — 파생 압축 자산 포함)이 존재하거나 **게재 매체가 md를 렌더하는 경우**(위키·GitHub 등) 전 페이지 지각 확인 — 게재 매체가 md를 렌더하지 않음을 확인한 경우만 N/A 명기(사유 기록). **매체 미상이면** GitHub 렌더 가정으로 지각 확인 수행(가정 기록) — N/A 불가. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄) | | 콜드리드가 **변경 없음으로 닫혔다** — 마지막 라운드에 **새 지적이 0건이고 본문 변경이 0건**일 때 닫는다(어느 하나만으로는 안 닫힌다). 지적을 반영해 고쳤으면 그 수리본으로 한 라운드 더. **미반영 지적이 남으면** 각 건에 명명된 사유 + 발행 판단자 수락 기록을 붙인다 — 없으면 미충족으로 명시. 라운드별 «지적 n · 반영 n · 본문 변경 여부» + 격리 수준(강/약) 이력 기록. Step 5 미적용 레지스터(낭독 대본)는 N/A 명기 | judged — 짝: 격리 검토(Step 5 정의) | | 정직 수위 분리(Step 3)가 적용됨 | judged — 짝: 발행 승인자 확인 또는 격리 적대 검토. 둘 다 불가하면 **미충족으로 명시 보고**(자기 검토로 대체 금지) |

## 역할 경계 (중복 아님을 명시)

- `hub-persona-auditor` **에이전트** — 완성된 대외 초안의 **페르소나 감사**(검토). 이 스킬은 **저작·개고 절차**다. Step 5 콜드리드에서 그 에이전트를 짝으로 쓸 수 있다(라우팅 관계). - `harness-doctor --lint` — **하네스 자산**의 언어 패턴(자기마케팅) 검출. 이 스킬은 독자 대면 문서가 대상이고 번역투·레지스터·정직 수위까지 다룬다. - 플랫폼 내장 문서 기능 — 특정 문체 캘리브레이션·정직 수위 층 분리·지각 QA 파이프라인은 내장에 없다(이 스킬이 더하는 것은 거버넌스다).

독립 실행 및 degrade 경로: phantom-quench·dataviz 미설치 → 해당 라우팅을 수동 대조로 · WebFetch 불가 → Step 1 «확인 불가» 경로(시도 기록 의무) · headless Chrome 부재 → HTML/PDF 렌디션을 «미생성»으로 명기하고 md 정본만 산출 · **Step 4-b 판정 주체(사람) 부재 → 후보 목록을 그대로 두고 해당 Done When 을 미충족으로 명시**(자기 판정 대체 금지) · **독립 2차 지각 패스 부재 → 렌더 스크린샷을 산출물 이력에 첨부하고 해당 Done When 을 미충족으로 명시**(저자가 같은 렌더를 두 번 보는 것으로 대체 금지 — 생성자=평가자가 된다). 각 degrade는 산출물 이력에 적는다.

**언어 범위**: 이름 그대로 **한국어 전용**이다. Step 0·1·3·4·5의 구조는 언어 무관이지만 Step 2 문체 클래스가 전부 한국어 실측이라, 영어 지원은 영어 실측 클래스가 쌓인 뒤 별도 확장(`en-` 자매 또는 일반화)으로 간다 — 실측 없는 클래스를 미리 짓지 않는다(유지 규칙).