ko-tech-writer git:20260810.31a7bf0A

Immutable. This exact content is served forever at /api/v1/blob/081c8169cc25b56a.

---
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 -E "을 갖\|를 갖\|을 가지\|를 가지"` | 존재문으로 (**«이전 상태를 갖지 않는다» → «이전 상태가 없다»**). 영어 `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가 아니다.

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

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

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

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

- **md 정본은 항상** 만든다. 다이어그램은 mermaid(GitHub·주요 뷰어 네이티브 렌더).
- **HTML/PDF 렌디션은 조건부** — 요청이 명시했거나 게재 채널이 요구할 때만 만든다(판단
  주체는 요청/채널이지 저자의 재량이 아니다): 자체완결 HTML(외부 의존 없는 인라인 SVG
  다이어그램, 시스템 한글 폰트 스택, `@page` 인쇄 규칙) → headless Chrome `--print-to-pdf`.
- **지각 QA(필수 — 렌더 산출물이 있을 때)**: 렌더 결과를 **전 페이지 눈으로** 확인한다 —
  라벨 잘림(한글 받침), 페이지 나눔, 표/그림 겹침, 다이어그램 텍스트 가림. 도구 exit 0은
  렌더 성공이지 가독성 판정이 아니다. 판정 짝은 **독립 2차 지각 패스**(다른 눈이 같은
  렌더를 봄)다 — 콜드리드는 내용을 읽지 렌더 결함을 보지 않으므로 짝이 될 수 없다.
- **발행 전 콜드리드 1패스**: 격리된 검토가 처음 읽는 눈으로 통독한다. 저자는 자기 글의
  전제 결손을 못 본다. **격리의 정의**: 저작 맥락을 상속하지 않는 실행이다. 같은 레포에서
  띄운 서브에이전트는 프로젝트 지침·메모리를 상속하므로 **완전 블라인드가 아니다** — 저작
  맥락 차단이 필요한 판정(전제 결손·자기 어휘 검사)은 레포 밖 cwd의 headless 실행 +
  컨트롤(알려진 결함 1건 동반)로 하고, 통독 수준 검토는 다른 에이전트로도 되지만 **어느
  격리 수준이었는지 이력에 적는다.** 에이전트 디스패치는 호출 세션의 권한·도구를 따른다
  (이 스킬의 allowed-tools 밖의 일이다). 강격리도 비저자 짝도 구할 수 없으면 해당 judged
  조건을 **미충족으로 명시**하고 발행 판단자에게 넘긴다 — 자기 검토로 대체하지 않는다.
- 🟥 **재콜드리드 — 지적을 반영해 고쳐 썼으면 고친 것을 다시 읽힌다.** 콜드리드 1회는
  *초안*을 검증할 뿐이고, **발행되는 것은 수리본**이다. 수리는 결함의 주된 출처라서
  «지적 반영»과 «통과»는 다른 사건이다. 본문이 바뀌었으면 라운드를 하나 더 돈다.
  **정지 조건은 라운드 수가 아니라 변경이다** — 그 라운드에 **새 지적이 없거나, 있어도
  본문을 안 고쳤을 때** 닫는다. 고쳤으면 아직 안 닫힌 것이다. 라운드마다 «지적 n건 · 반영
  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 |
| 본문 수치 전건(기계 추출 분모 기준)이 라벨(창 병기/재측정 대상/미확인) 동반 | measured |
| 렌더 산출물(HTML/PDF/이미지 — 파생 압축 자산 포함)이 존재하는 경우 전 페이지 지각 확인 — md-only 산출이면 N/A 명기 | judged — 짝: **독립 2차 지각 패스**(다른 눈이 같은 렌더를 봄) |
| 콜드리드가 **변경 없음으로 닫혔다** — 마지막 라운드에 새 지적이 없거나, 있어도 본문을 안 고쳤다. 지적을 반영해 고쳤으면 그 수리본으로 한 라운드 더. 라운드별 «지적 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 정본만 산출. 각 degrade는 산출물 이력에 적는다.

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