| name | yowu-write-tech |
| description | 기술적인 글·문장을 장황하지 않게 풀어 쓰거나 감사(audit)할 때 사용한다. 설계 문서, 기술 설명, PR 설명, 코드 리뷰 코멘트, README, 장애 보고서, 기술 답변이 대상. 기술 용어·전문 용어·코드 식별자는 그대로 유지하고, 그 주변 문장만 사람이 읽기 쉽게 푼다. 위키·컨플루언스에 올릴 문서는 yowu-write-wiki, 에세이·블로그·회고는 yowu-write-essay를 쓴다. 트리거 - "기술 문서 풀어써", "기술 글 다듬어", "읽기 쉽게 써줘", "write tech", "기술 문장 정리", "설계 문서 작성", "PR 설명 작성", "장황한 문장 고쳐줘". |
yowu-write-tech: 기술 글 풀어쓰기
독자가 기술 글을 포기하는 이유는 내용이 어려워서가 아니다. 읽는 데 드는 노력이 너무 커서다. 한 문장에 절이 세 개, 동사가 명사로 굳어 있고, 수식어가 근거 없이 붙어 있으면 독자는 같은 문장을 두 번 읽는다. 이 스킬은 그 노력을 깎는다.
목표: 동료 개발자가 한 번 읽고 이해하는 문장. 내용의 깊이는 유지하고, 문장의 부하만 낮춘다.
대원칙: 문장 난이도만 낮춘다
아이디어는 정교하게 유지한다. 평이하게 만드는 것은 문장이다.
우선순위가 충돌하면: 정확 > 명료 > 간결 > 스타일. 정확성을 스타일과 바꾸지 않는다. 지루하지만 정확한 문장이 우아하지만 모호한 문장을 이긴다.
언어 범위: 이 스킬의 대상은 한국어 기술 글이다. 영어 등 다른 언어에는 언어 보편 규칙(두괄식, 모호성, 의미 인플레이션, 헤지, 부정 병렬)만 적용하고, 조사·피동·번역투 규칙은 한국어에 한정한다.
어체는 건드리지 않는다: 합니다체/한다체 같은 종결 어미와 격식(register)은 스타일이지 문장 부하가 아니다. 원문의 어체를 유지한 채 부하만 낮춘다. 이 문서의 예시가 한다체인 것은 표기 편의일 뿐, 한다체로 바꾸라는 지시가 아니다.
스킬 분기 (형제 스킬과의 경계)
- 지금 이 팀이 읽을 기술 문장(설계 문서, PR 설명, 장애 보고서, 리뷰 코멘트, 기술 답변) → yowu-write-tech (이 스킬)
- 위키·컨플루언스 등 검색으로 유입될 미래 독자용 문서 → yowu-write-wiki
- 에세이·블로그·포스트·개인 회고 → yowu-write-essay
- "글 다듬어줘"처럼 매체가 불분명한 요청 → 대상 매체를 먼저 확인한다. yowu-write-tech는 발행 매체와 무관하게 기술 문장의 부하만 낮춘다.
용어 보존 규칙 (이 스킬의 정체성)
- 기술 용어는 원형 유지: idempotent, race condition, backpressure, eventual consistency 같은 용어를 어설픈 한국어로 번역하지 않는다. 독자(동료 개발자)가 아는 용어는 그대로 쓴다.
- 코드 식별자는 백틱: 클래스명, 함수명, API 경로, 설정 키는
백틱으로 감싸고 절대 변형하지 않는다.
- 푸는 것은 용어가 아니라 용어 사이의 문장이다. "해당 API는 idempotent하게 설계되어 재시도 시에도 부작용이 발생하지 않도록 보장됩니다" → "이 API는 idempotent하다. 재시도해도 결과가 같다."
- 독자층이 불분명한 용어 하나가 문서 전체를 막을 수 있다. 그럴 때만 첫 등장에 한 줄 설명을 붙인다.
AI 문장의 5가지 병 (진단이 먼저다)
고치기 전에 병명을 붙인다. 병명이 붙으면 처방은 자명하다.
- 모호성 압축 — 범주만 말하고 실체를 말하지 않는다. "성능이 개선되었습니다" → "p99 응답이 120ms에서 45ms로 줄었다."
- 의미 인플레이션 — 평범한 사실에 "핵심적인", "획기적인", "중요한"을 붙인다. → 사실만 쓰고 판단은 독자에게 맡긴다.
- 헤지(hedge) — 입장이 있는데 확언하지 않는다. "~일 수도 있을 것으로 보입니다" → 판단을 내리거나, 모르면 "확인 못 했다"고 쓴다.
- 명사화 — 동사를 명사로 굳힌다. "검증의 수행이 필요합니다" → "검증해야 한다."
- 빌린 권위 — 컨설팅 보고서 말투. "시너지를 창출하며 확장성을 확보합니다" → 동료에게 말하듯 쓴다.
병명이 안 잡히면 소리 내어 읽듯 검사한다 — 호흡과 문장 길이를 시뮬레이션한다. 숨이 차거나 두 번 읽게 되는 문장이 환부다.
풀어쓰기 기술 (the moves)
- 한 문장 한 생각 — 절이 두 개 이상 겹치면 문장을 쪼갠다. "~하며, ~하고, ~하기 때문에 ~합니다"는 세 문장이다.
- 명사문을 동사문으로 — "장애의 원인 파악을 진행했다" → "장애 원인을 파악했다."
- 능동태 — "처리가 이루어집니다" → "서버가 처리한다." 행위 주체를 문장에 세운다.
- 이중피동 제거 — "~되어진다", "~라고 보여집니다" → "~된다", "~라고 본다."
- 번역투 제거 — "~에 있어서" → "~에서", "~을 필요로 한다" → "~이 필요하다", "~에 다름 아니다" → "~이다."
- 필러 삭제 — "기본적으로", "사실상", "일종의", "~라고 할 수 있습니다", "~하는 것이 중요합니다"는 대부분 지워도 뜻이 같다.
- 숫자와 조건으로 말하기 — "빠르다"가 아니라 "45ms", "대부분"이 아니라 "약 80%". 숫자가 없으면 없다고 쓴다. 지어내지 않는다.
- 두괄식 — 결론을 첫 문장에. 배경 설명으로 목을 가다듬지 않는다. 첫 문장을 지워도 글이 성립하면 그 문장은 목 가다듬기였다.
부정 병렬 금지 (AI 문체의 1번 신호)
"단순히 X가 아니라 Y입니다" 패턴과 그 변형들("X를 넘어 Y로", "X가 아닌, 진짜 문제는 Y"). 기각하는 프레임(X)을 세웠다가 무너뜨려 통찰처럼 보이게 하는 수사다. 대부분 요점이 없다는 사실을 숨기는 장치다.
처방: 기각된 절반(X)을 지우고, 남은 절반(Y)을 구체적인 직접 주장으로 다시 쓴다.
"이것은 단순한 리팩토링이 아니라 아키텍처의 근본적 개선입니다."
→ "모듈 간 순환 참조 3곳을 제거했다. 이제 auth 모듈을 독립 배포할 수 있다."
예외: Y가 구체적(숫자·메커니즘·실례)이고 본문이 그것을 실제로 증명하면 대비 구조를 써도 된다. Y가 "마인드셋", "패러다임" 같은 범주어면 즉시 삭제.
블록리스트 (시작점 — 원칙이 목록보다 오래간다)
원칙: 아이디어를 설명하는 대신 홍보하는 단어는 지운다. '어떻게'를 명시하지 않고 인상만 남기는 단어가 대상이다.
- 의미 인플레이션: 혁신적인, 획기적인, 강력한, 완벽한, 핵심적인, 최적의, 유연한, 원활한, 손쉽게, 간편하게 → 근거 숫자가 있으면 숫자로, 없으면 삭제
- 장황 접속: 또한, 더불어, 뿐만 아니라, 이를 통해, ~함으로써, 그리고 이는 → 논리적 역할이 있는 접속사만 남기고, 없으면 무접속
- 죽은 서두: "오늘날 ~환경에서", "~의 중요성이 대두되고 있다", "본 문서에서는 ~을 다룬다" → 첫 문장부터 본론
- 동사 우회: ~의 역할을 수행한다, ~을 가능하게 한다, ~을 제공한다(실체 없이) → 이다, 한다, 준다, 만든다
- 분사·연결어미 가짜 깊이: "~을 강조하며", "~을 방증하며", "~을 시사하며", "~을 뒷받침하며"(-며로 매달아 분석을 흉내) → 할 말이 있으면 독립된 문장으로 근거와 함께 쓰고, 없으면 삭제
- 죽은 비유: "시스템의 심장", "데이터의 혈관", "레고처럼 조립", "녹여내다/짜맞추다" → 기본은 직서. 비유는 대상이 정말 낯설고 직접 설명보다 짧을 때만
- 형식 tell: 불릿 벽(문단으로 전개할 논리를 불릿로 나열), 모든 목록이 3개, 과도한 볼드, 장식용 이모지
형식 규칙
- 불릿은 열거에만. 항목이 서로 독립일 때만 목록으로 쓴다. 논리가 흐르는 내용(원인→결과, 판단→근거)은 문단으로 쓴다.
- 표는 짧은 사실의 대조에만. 문장이 들어간 셀이 늘어나면 표를 해체해 문단으로.
- 목록 항목 수는 실제 개수대로. 이유가 2개면 2개, 4개면 4개. 3개로 맞추려는 반사를 의심한다.
- 제목은 주제가 아니라 결론. "성능 분석" → "인덱스 누락이 지연의 원인".
Writing mode (새로 쓸 때)
초안은 평소대로 쓴다. 블록리스트를 의식하며 쓰면 문장이 굳는다. 초안 완성 후 두 번의 패스를 돈다:
- 부하 패스: 가장 무거운 문장 2~3개를 찾아 쪼갠다. 명사문→동사문, 피동→능동, 필러 삭제.
- 정직 패스: 근거 없는 형용사, 부정 병렬, 헤지를 지운다. 남은 문장이 실제로 무언가를 말하는지 확인한다.
Audit mode (기존 글을 감사할 때)
문제 지점을 원문 그대로 인용해 표시하고, 수정안을 제시한다. 감사 대상은 5가지 병과 풀어쓰기 기술·블록리스트 위반 전부다. 아래는 형식 예시일 뿐이니 항목을 고정하지 말고 실제 발견된 것만 나열한다:
WRITE-TECH AUDIT:
명사화: FLAG — "장애 원인의 파악 및 재발 방지 대책의 수립을 진행함"
→ "장애 원인을 파악하고 재발 방지 대책을 세웠다"
모호성: FLAG — "성능이 크게 개선됨" → 수치 필요. 없으면 "개선 폭은 측정 전"
인플레이션: FLAG — "핵심적인 개선사항" → 근거 없는 수식 삭제, 사실만
피동: FLAG — "재시도가 수행되어집니다" → "클라이언트가 재시도한다"
부정 병렬: FLAG — "단순한 버그 수정이 아니라 구조적 개선" → 기각 절반 삭제, 무엇을 바꿨는지 직접 서술
헤지: FLAG — "~일 수도 있을 것으로 판단됨" → 판단을 내리거나 "미확인"으로
용어 보존: OK — `CircuitBreaker`, backpressure 원형 유지 확인
수정안: [원문의 기술적 내용을 보존한 재작성]
과교정 방지 (anti-overfitting)
- 규칙이 문장을 더 나쁘게 만들면 규칙을 어긴다. 정신이 조문을 이긴다.
- 모든 문장을 짧게 만들지 않는다. 그것은 단순화가 아니라 평탄화다. 쉬운 단어로 이루어진 긴 문장은 한 호흡에 읽히면 문제없다.
- 독자가 알고 기대하는 전문 용어를 제거하지 않는다. 기술 문서를 초등학생용으로 만드는 것이 아니다.
- 원문의 어체·격식을 바꾸지 않는다. 부하를 낮추는 데 필요 없는 어체 변경은 스타일 취향이다.
- 정밀함이 필요한 문장(경계 조건, 예외 명세)은 길어도 된다. 나눠서 뜻이 흐려지면 나누지 않는다.
최종 테스트: 대상 독자인 동료가 한 번 읽고 이해하면서, 동시에 자신의 지력이 존중받는다고 느끼는가? 유치하게 읽히면 과교정이다.
