refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일

2026-09-04 18:56:01 +09:00
parent 4b9e7148b5
commit 43bccd08a8
121 changed files with 2861 additions and 534 deletions
@@ -33,6 +33,37 @@ Before the first rewrite in a task, read both references:
 Read the complete source and the nearby context needed to interpret pronouns, comparisons, and causes.
 Do not rewrite an isolated paragraph when its protected meaning depends on the surrounding section.

+## Required sequence
+
+This is an **editorial** pass. The source's facts, evidence, causal chain, uncertainty, decision status,
+and technical depth are the contract. Work in this order — the steps that have their own section are
+named here so the spine stays visible.
+
+1. **Read the whole record once without editing.** A paragraph fixed before you know how the piece ends
+   is fixed against the wrong context.
+2. **Mark the protected literals and the sentences that carry technical weight** — `Establish the meaning
+   contract` below, and `references/protected-content.md`.
+3. **Name the stylistic problems, and only those.** Repeated sentence frames, forced conversational tone,
+   abstract filler, too many headings, translated constructions, a conclusion restated in three places,
+   paragraphs of identical length, bolding that has stopped meaning anything.
+4. **Edit diction, sentence order inside a paragraph, paragraph boundaries, and headings.** Do not move a
+   fact between sections while doing it.
+5. **Re-read against the original** and restore every technical fact, limitation, condition, and evidence
+   detail that fell out. This step finds more than it seems it should.
+6. **Close with `Mechanical pass` then `Final check`.** The checkers read surface patterns; the read-aloud
+   test and the preservation questions decide.
+
+### Hard rules for this pass
+
+- Do not shorten merely to look more human.
+- **Do not remove implementation detail because the paragraph feels dense.** Density is not a style defect.
+- Do not create `처음에는`, `해보니`, `놀랍게도`, `저희는` or other experience language unless the source
+  records that experience.
+- **Do not imitate one company's or one author's voice.** `style_profile.mjs` measures against five
+  Woowahan articles because they are a *sample of engineering writing*, not a target to sound like. Apply
+  the cross-source patterns in `references/editorial-rules.md`; do not adopt a house style.
+- Do not make every section equally polished, equally long, or structurally symmetric.
+
 ## Establish the meaning contract

 Make an internal claim ledger before editing. Do not print it unless asked. Record:
@@ -444,6 +475,20 @@ remove.
 Clean output does not mean the rewrite is good. Both tools read surface patterns and cannot see meaning;
 every rule above still applies, and the read-aloud test below is the one that decides.

+## 참조
+
+- `references/regression-examples.md` — 고친 예와 실패 이유
+- `references/protected-content.md` — 옮길 때 한 글자도 바꾸면 안 되는 것
+- `references/editorial-rules.md` — 편집 규칙
+- `references/research-method.md` — 문체 기준값을 다시 재는 방법
+- `references/corpus/` — 한국어 기술 글 코퍼스 조사 노트
+
+문장 규칙 두 개는 `writing-tech-log-records` 스킬에 있다. 두 스킬이 같은 규칙을 쓰므로 사본을
+만들지 않는다.
+
+- `../writing-tech-log-records/references/explaining.md` — 설명하는 법
+- `../writing-tech-log-records/references/ai-tells.md` — 문서군 전체의 리듬
+
 ## Final check

 First, read every rewritten sentence aloud and ask: **would a Korean-speaking developer say this to a
@@ -0,0 +1,78 @@
+# 2026-08-28 Korean Engineering Blog Corpus Notes
+
+## 조사 범위
+
+공개된 한국 기술 블로그 중 실제 서비스/시스템 개발 경험을 다루는 글을 중심으로 보았다.
+
+- NAVER D2 — 「네이버 통합 검색의 웹 성능 - 모니터링과 성능 개선」, 「생성형 AI 기반 실시간 검색 결과 재순위화 1편」, 검색 SRE 관련 글
+- 토스 기술 블로그 — 토스증권 실시간 데이터 파이프라인/Observability 시리즈, Gateway 관련 글
+- 우아한형제들 기술블로그 — 장시간 비동기 작업을 Kafka에서 RDB Task Queue로 재설계한 글, Kafka/분산락/개발환경 관련 글
+- 카카오테크 — 서버 개발자를 위한 운영툴 개발 등 실제 개발/운영 경험 글
+
+이 문서는 표현을 복사하는 자료가 아니라 공통 구조를 추출한 메모다.
+
+## 반복해서 보인 서술 관행
+
+### 1. 기술 이름보다 서비스 상황과 제약이 먼저 나온다
+
+글이 곧바로 프레임워크 장점을 나열하기보다 현재 시스템 규모, 기존 구조, 실제 운영 요구나 실패 상황을 먼저 설명한다. 기술 선택은 그 뒤의 문제 해결 수단으로 등장한다.
+
+편집 기준: 초안이 `X는 무엇인가`로 길게 시작하지만 실제 사건이 뒤에 있다면, 필요한 개념 설명만 남기고 사건/제약을 앞쪽으로 이동한다.
+
+### 2. 해결책 전에 요구조건을 명시한다
+
+토스의 Observability 글과 우아한형제들의 장시간 작업 재설계 글처럼 해결안이 만족해야 할 조건을 목록/표로 먼저 고정하는 패턴이 자주 보인다. 이러면 선택 이유가 일반론이 아니라 제약과 연결된다.
+
+편집 기준: 선택을 설명할 때 자료에 있는 `제약 → 요구조건 → 선택` 연결을 살린다. 자료에 없는 요구조건을 새로 만들지는 않는다.
+
+### 3. 문제는 관측된 현상과 원인 추적으로 이어진다
+
+NAVER D2의 웹 성능 글은 배포 시점의 변화, 지표, 원인 후보를 실제 관측 흐름에 연결한다. 우아한형제들의 Kafka 작업 글도 처리시간 증가 → poll 공백 → rebalance → 중복 처리로 사건을 이어 간다.
+
+편집 기준: `문제가 있었다` 뒤에 추상 평가를 늘리지 말고, 입력/상태 변화/관측 결과/원인 근거를 이어 쓴다.
+
+### 4. 수치는 주장 장식이 아니라 비교 축이다
+
+성능 수치나 규모가 나오면 무엇과 무엇을 비교하는지, 어느 시점/조건에서 측정했는지가 같이 나온다. 숫자만 굵게 강조해 결론을 대신하지 않는다.
+
+편집 기준: 수치 근처에 측정 조건과 비교 대상을 유지한다. 근거 없는 정량 표현은 삭제한다.
+
+### 5. 표와 그림은 산문을 대신할 축이 있을 때 쓴다
+
+요구사항, 전/후 비교, 구성요소, 여러 후보의 동일한 비교축처럼 행/열이 자연스러운 경우 표를 쓴다. 그림은 구조나 흐름을 보여주고, 본문은 그림에서 읽어야 할 변화나 의미를 설명한다.
+
+### 6. 실제 글은 모든 절의 길이와 문형이 같지 않다
+
+배경은 짧고 핵심 실패 원인은 길 수 있으며, 자명한 결과는 한두 문장으로 끝난다. 모든 절을 `문제 → 원인 → 해결 → 장점` 네 문장으로 맞추지 않는다.
+
+### 7. 1인칭은 실제 경험을 담을 때만 자연스럽다
+
+기업 기술 블로그는 `저희는`, `우리는`을 자주 쓰지만 이는 실제 작성자가 겪은 프로젝트 경험이 있기 때문이다. 코드 분석에서 그런 기록이 없는데 같은 장치를 흉내 내면 오히려 가짜 경험이 된다.
+
+편집 기준: source에 1인칭 경험이 없으면 객관적 관측 문장으로 쓴다.
+
+### 8. 한계를 숨기지 않는다
+
+새 구조가 해결한 범위와 아직 남은 문제를 분리하는 글이 많다. 이것이 기술 선택을 과장하지 않게 만든다.
+
+편집 기준: 상세 분석의 `확인하지 않은 것`, `남은 질문`, `운영에서 별도 검증할 것`을 삭제하지 않는다.
+
+### 9. 개념 설명은 현재 문제를 읽는 데 필요한 만큼만 끼워 넣는다
+
+Kafka, Gateway, LCP 같은 용어를 설명하더라도 백과사전식 장문이 아니라 이후 구조/문제를 이해하는 데 필요한 수준으로 제한한다.
+
+### 10. 제목은 읽을 이유를 주되 본문보다 앞서 결론을 과장하지 않는다
+
+문제/구조/변화를 드러내는 제목은 많지만, 모든 절을 질문형이나 자극적인 카피로 만들지는 않는다. 핵심 기술 문단은 비교적 직접적이다.
+
+## 조사한 공개 글
+
+- NAVER D2 — 네이버 통합 검색의 웹 성능 - 모니터링과 성능 개선: https://d2.naver.com/helloworld/8113611
+- NAVER D2 — 생성형 AI 기반 실시간 검색 결과 재순위화 1편: https://d2.naver.com/helloworld/2380720
+- 토스 기술 블로그 — 토스증권의 수 천개 실시간 데이터 파이프라인 운영방법 #2: https://toss.tech/article/MSA-observability
+- 토스 기술 블로그 — 토스는 Gateway 이렇게 씁니다: https://toss.tech/article/22910
+- 우아한형제들 기술블로그 — 장시간 비동기 작업, Kafka 대신 RDB 기반 Task Queue로 해결하기: https://techblog.woowahan.com/23625/
+- 우아한형제들 기술블로그 — 표준 개발 환경 개선 되돌아보기: https://techblog.woowahan.com/15572/
+- 카카오테크 — 서버 개발자를 위한 운영툴 개발: https://tech.kakao.com/posts/528
+
+URL은 조사 provenance를 남기기 위한 것이다. 특정 문장을 복사하거나 특정 필자의 어조를 목표로 삼지 않는다.
@@ -0,0 +1,7 @@
+# Korean Technical Writing Research
+
+한국어 엔지니어링 글의 편집 기준을 만들기 위한 공개 자료 조사 기록을 둔다.
+
+목적은 특정 회사나 필자의 문체를 복제하는 것이 아니다. 여러 기술 블로그에서 반복되는 **문제 제시, 근거 전개, 요구사항 명시, 측정 결과 연결, 한계 표기, 표/그림 사용 방식**을 추출해 `humanizing-korean-tech-writing` Skill에 반영한다.
+
+새 조사 결과는 날짜별 corpus note에 먼저 기록하고, 여러 출처에서 반복되는 패턴만 Skill의 durable rule로 승격한다.
@@ -19,7 +19,7 @@
 - [검색 성능 개선을 위한 Elasticsearch 인덱스 구조와 쿼리 최적화](https://techblog.woowahan.com/20161/) — `20161`
 - [나 4년 차 서버개발자, 배달의민족의 지리 체계를 뒤흔들다](https://techblog.woowahan.com/11238/) — `11238`

-이 다섯 편은 `scripts/style_profile.mjs`가 쓰는 기준선이기도 하다. 원문을 다시 받으려면
+이 다섯 편은 `scripts/style_profile.mjs`가 문체 수치를 재는 기준값이기도 하다. 원문을 다시 받으려면
 `node scripts/fetch_reference.mjs <디렉터리>`를 쓴다. 사이트가 curl과 리더 프록시를 403으로 막으므로
 실제 브라우저가 필요하고, `playwright-core`가 있어야 한다. 받은 뒤
 `node scripts/style_profile.mjs --baseline <디렉터리>/*.md`로 값을 다시 잰다.
@@ -0,0 +1,72 @@
+# Editorial Rules From Korean Engineering Writing
+
+These rules were distilled from multiple public Korean engineering blogs. They describe broad technical-writing habits, not a target author's style.
+
+## Lead with the engineering situation
+
+When a draft spends several paragraphs defining a technology before stating why it appears, move the concrete service/code situation, constraint, failure, or measurement earlier. Keep only the concept explanation needed to follow that situation.
+
+Do not fabricate a `background story` merely to create an opening.
+
+## Keep constraint → requirement → choice connected
+
+A credible choice is usually readable from its constraints. When the source contains requirements, put them close to the solution they rule in/out. Do not add generic benefits such as maintainability, scalability, security, or performance unless the source demonstrates that they mattered here.
+
+## Write the observed chain, not a summary slogan
+
+Prefer:
+
+```text
+input/condition → state change → observable result → evidence-backed cause
+```
+
+over a paragraph that repeatedly says the architecture has a problem or responsibility.
+
+## Make metrics carry context
+
+Keep the dataset, request shape, time window, before/after condition, or comparison axis next to a number. Do not turn a measurement into an adjective such as `크게`, `압도적으로`, `획기적으로` unless the source justifies that interpretation.
+
+## Use tables only when there is a real axis
+
+Good table candidates:
+
+- requirement → reason;
+- before → after;
+- option → same comparison dimensions;
+- environment → observed result;
+- defined → not defined verification coverage.
+
+If every row needs a paragraph of caveats, prose may be clearer.
+
+## Let section lengths differ
+
+Human engineering reports spend space where the difficult reasoning occurred. A two-line setup next to a long failure analysis is fine. Do not normalize all sections to the same number of paragraphs or bullets.
+
+## Do not manufacture first person
+
+Public engineering blogs often use first person because their authors participated in the project. A code-derived document has no such license. Use `코드에서는`, `실행 결과에서는`, `이 구성에서는`, or the concrete component name unless source material contains a real first-person account.
+
+## Preserve limitations
+
+Do not polish away `확인하지 않은 것`, `운영에서는 별도 검증`, failed attempts, excluded scope, or competing explanations. Those boundaries make the technical claim credible.
+
+## Explain concepts at the point of use
+
+Introduce PKCE, LCP, Kafka rebalance, keyset pagination, etc. only to the depth needed for the next piece of reasoning. Avoid detached encyclopedia sections unless the record itself is a Reference that requires them.
+
+## Prefer direct headings over forced questions
+
+Use headings that name the actual event, boundary, measurement, or change. Do not convert every heading to `왜 ...일까?`, `...해보자`, or rhetorical copy. A question heading is appropriate only when the section genuinely resolves that question.
+
+## Vary rhythm by content, not by randomization
+
+Do not mechanically alternate short and long sentences. Instead:
+
+- keep a consequence close to its cause;
+- split a sentence when it contains two independently important actions;
+- keep a short sentence when a measured fact can stand alone;
+- combine fragments that only make sense together.
+
+## Remove AI scaffolding
+
+Review expressions such as `중요한 점은`, `핵심은`, `결국`, `즉`, `다시 말해`, `이 지점에서`, `한편`, `정리하면`. They are not forbidden, but repeated use often means the previous sentence already said the same thing. Delete the scaffold before rewriting the substance.
@@ -0,0 +1,33 @@
+# Protected Content
+
+Editorial work must preserve these exactly unless the source itself is being corrected with new evidence:
+
+- numeric values and signs;
+- dates and times;
+- versions;
+- units;
+- commands and command arguments;
+- code and configuration;
+- file/module/class/method names when used as identifiers;
+- URLs and paths;
+- HTTP status/error codes;
+- test names and assertions;
+- observed terminal/browser output;
+- direct quotations;
+- decision/question status;
+- distinctions between observed fact, inference, assumption, unknown, and recommendation.
+
+## Meaning-preservation checks
+
+After editing, compare original and revised record and ask:
+
+1. Did any condition (`when`, `only if`, environment, topology, dataset) disappear?
+2. Did `can/may` become `does/will`?
+3. Did a local/test observation become a production/general claim?
+4. Did an unresolved question sound answered?
+5. Did a proposed decision sound adopted?
+6. Did a measured value lose its measurement context?
+7. Did a failure/limitation disappear because it made the paragraph less tidy?
+8. Did the rewrite invent a motivation or personal history?
+
+If yes, restore the lost distinction before further stylistic changes.
@@ -0,0 +1,10 @@
+# Research Method
+
+Use this when updating the editorial skill from public Korean engineering writing.
+
+1. Sample several companies and several technical domains; do not build rules from one writer.
+2. Prefer implementation/incident/performance/operations articles over recruiting or marketing posts.
+3. Record structural observations: how the problem is introduced, where constraints appear, how measurements are tied to claims, how alternatives and limitations are handled, and when tables/diagrams replace prose.
+4. Do not copy distinctive phrases, jokes, metaphors, or signature expressions.
+5. Promote a pattern into `editorial-rules.md` only when it appears useful across multiple sources and is compatible with evidence-preserving Tech Log writing.
+6. Keep source notes under `./research/korean-tech-writing/`; runtime editing must work even if the websites are unavailable later.
@@ -62,7 +62,12 @@ const ACRONYM_OK = new Set([
 function strip(src) {
  return src
    .replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, ' '))
-    .replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
+    .replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length))
+    // 표와 인용은 「쓰지 않는다」 예시가 사는 자리다. 규칙을 적은 문서가 그 규칙을 어긴 것으로
+    // 잡히지 않게 줄을 통째로 비운다. 줄 번호는 유지한다.
+    .split('\n')
+    .map((line) => (/^\s*(\||>)/.test(line) ? ' '.repeat(line.length) : line))
+    .join('\n');
 }

 function positiveChecks(text, lines, docMode, rulesMode) {