ko-tech-writer
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: "기술문서 써줘", "테크블로그 초안 잡아줘", "이 문서 번역투 고쳐줘", "블로그체로 다듬어줘", "이 글 회사 기술블로그에 올릴 수 있게 다듬어줘".
chrono-meta · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add chrono-meta/forge-harness --skill ko-tech-writer技能说明
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)하고 세 가지를 기록한다:
- 문체: 존댓말 변형(습니다/해요), 도입 형식(질문형/선언형)
- 구성: 소제목 밀도, 마무리 관행(일반화 + 트레이드오프 + 실무 조언 등)
- 시각물: 다이어그램/그래프/표를 어느 밀도로 쓰는가
캘리브레이션 기록은 산출물 이력(작업 로그·PR 본문·문서 frontmatter)에 남긴다 — 게재 본문에는 노출하지 않는다. 표본을 확인할 수 없으면 무엇을 시도했고 왜 안 됐는지(호출 실패·매체 미상 등)를 같은 이력에 명기하고 일반 규율(습니다체·소제목 세분화)로 진행한다 — 확인 안 된 톤을 확정처럼 쓰지 않는다. 시도 기록 없는 «확인 불가»는 Done When 1조를 충족하지 않는다.
Step 2 — 문체 규율 (번역투 클래스 목록)
아래는 실측으로 검출된 클래스다. 기계 스캔 + 눈 판정으로 제거한다 (grep은 후보를 표시할 뿐, 남길지 판정은 문맥으로):
| 클래스 | 검출 힌트 | 수리 |
|---|---|---|
| 줄표 이어붙임 「~다 — ~고,」 | grep "다 — |것 — |음 — " | 문장 분리. 줄표는 일을 하는 곳만 남긴다(열거 매달기·리듬 결속 — 남긴 이유를 적는다) |
| 용어-머리 «X — 설명» | 글머리 기호 뒤 ** — | «X: 설명» 콜론형 |
| 콜론 나열투 («관측된 분업은: …») | 서술어 없는 : 도입 | 완결 문장으로 («…분업은 ~라는 것입니다») |
| 조각문 («걸리는 층.») | 서술어 없는 마침 | 서술어 복원 («걸리는 층입니다») |
| 소유 직역 「~을 갖다/가지다」 | `grep -nE "을 갖 | 를 갖 |
| 내부 조어·은어 | 팀 밖에서 안 쓰는 단어 (예: 렌더하다, 초록/빨강을 CI 결과 뜻으로) | 청중 어휘로 평문화. 단, 화면이 어휘를 받치면(실제 빨간 화면을 가리키는 발화) 유지 가능 — 근거를 적는다 |
| 레지스터 드리프트 | 습니다↔해요↔평어 혼재 | 표본 기준 단일화 |
클래스의 성격이 갈린다: 앞 다섯 줄(줄표·용어-머리·콜론·조각문·소유 직역)은 기계 검출 가능(grep 후보 + 눈 판정)이고, 뒤 두 줄(내부 조어·레지스터)은 판정 클래스다 — Done When에서 서로 다른 check-class로 채점된다.
Step 2-b — 부분 개고 전용: 기존 본문과의 리듬 대조
문서 전체를 새로 쓰는 경우가 아니라 기존 문서에 문단·문장을 끼워 넣는 경우, 위 클래스가 전부 0이어도 삽입분만 이질적으로 읽힐 수 있다. 클래스 목록은 «틀린 표현»을 잡지 «튀는 표현»을 못 잡기 때문이다. 삽입·개고분에 한해 두 가지를 수치로 대조한다:
- 문장 길이 분포 — 본문 평문 문장의 길이 중앙값·상위 10%를 먼저 구하고, 삽입분의 각 문장이 상위 10% 안에 드는지 본다. 넘으면 끊는다. (본문에 더 긴 문장이 있어도 근거가 못 된다 — 그건 그 문단의 리듬이지 삽입분의 것이 아니다.)
- 어휘 반복 — 삽입분 안에서, 그리고 직전·직후 문장까지 포함해 같은 어간이 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 어휘만으로 못 잡는 계열이 실재한다는 뜻이라 부정형 패턴을 함께 넣는다. **반례 탐색 없이 쓴 전칭
阅读完整来源 ↗