yowu-write-wiki

yowu-write-wiki: 위키 글 풀어쓰기

위키 문서의 독자는 지금 이 문서를 검토하는 팀원이 아니다. 6개월 뒤 검색으로 유입되는, 맥락이 전혀 없는 미래의 동료다. (그 동료는 자주 미래의 나다.) 이 독자는 문서를 처음부터 끝까지 읽지 않는다. 훑고, 필요한 부분만 찾고, 못 찾으면 떠난다.

목표: 맥락 없는 독자가 훑어서 원하는 답을 찾는 문서. 문장 하나하나의 부하를 낮추고, 문서 전체를 스캔 가능하게 만든다.

스킬 분기와 범위 경계

• 위키·컨플루언스 등 검색으로 유입될 미래 독자용 문서 → yowu-write-wiki (이 스킬)
• 지금 이 팀이 읽을 기술 문장(설계 문서, PR 설명, 리뷰 코멘트) → yowu-write-tech. 장애 보고서는 위키에 올릴 최종본이면 yowu-write-wiki, 당장 공유할 보고면 yowu-write-tech
• 에세이·블로그·개인 회고 → yowu-write-essay
• 매체가 불분명한 요청 → 대상 매체를 먼저 확인한다
• 이 스킬은 글 품질만 다룬다. 위키/컨플루언스에 페이지를 실제로 생성·등록·발행하는 것은 별도 도구(위키 MCP 등)의 일이다. 사용자가 등록까지 원하면 글을 다듬은 뒤 해당 도구로 넘긴다.

용어 보존 규칙

• 도메인 언어와 기술 용어는 원형 유지. 팀이 쓰는 시스템명, 서비스 코드명, 도메인 용어(정산, 어드민, 세션 스토어…)를 다른 말로 바꾸지 않는다. 검색은 그 용어로 이루어진다.
• 첫 등장 시 한 줄 정의 또는 링크. 미래의 독자는 그 용어를 모를 수 있다. 용어를 없애는 대신 "X(한 줄 설명)" 또는 관련 문서 링크로 잇는다.
• 코드 식별자·설정 키·API 경로는 백틱으로 감싸고 변형하지 않는다.
• 푸는 것은 용어가 아니라 용어를 둘러싼 문장이다.

위키 고유의 3원칙

문장 규칙(아래) 이전에, 위키라는 매체가 요구하는 것:

1. 자기완결성 — 첫 문단만 읽어도 이 문서가 무엇에 관한 것이고 언제 필요한지 알 수 있어야 한다. "지난 회의에서 논의한 대로"처럼 문서 밖 맥락에 기대는 문장을 지운다. 필요한 맥락은 문서 안으로 가져오거나 링크한다.
2. 시점 독립성 — "최근", "현재", "이번에", "신규 시스템"은 6개월 뒤에 거짓말이 된다. → 날짜를 박고("2026-07 기준"), 시스템은 이름으로 부른다. 바뀔 수 있는 사실에는 기준 시점을 명시한다.
3. 검색성 — 제목과 첫 문단에 독자가 검색창에 칠 키워드를 넣는다. "트러블슈팅 가이드"가 아니라 "Redis 세션 스토어 OOM 트러블슈팅". 결론이 있는 문서(트러블슈팅, 원인 분석, 의사결정 기록)는 결론을 제목에 담는다: "배포 실패 원인 분석" → "values.yaml 인코딩이 배포 실패의 원인". 참조·온보딩·운영 문서는 결론이 없으니 검색 키워드를 앞세운 서술형 제목("결제 시스템 온보딩 가이드")이 낫다.

AI 문장의 병 (진단이 먼저다)

고치기 전에 병명을 붙인다. 위키에서 특히 치명적인 순서로:

1. 모호성 압축 — "이슈가 있었습니다"는 미래 독자에게 아무 정보가 없다. → "5월 배포에서 session-store OOM으로 30분 장애."
2. 명사화·피동 남발 — "설정의 변경이 요구되어집니다" → "설정을 바꿔야 한다." 절차 문서에서 피동은 행위 주체(누가 하는가)를 지워버린다.
3. 의미 인플레이션 — "매우 중요한 설정입니다" → 왜 중요한지(안 하면 무슨 일이 나는지)를 쓰면 "중요한"은 필요 없다.
4. 헤지 — "~하는 것이 좋을 수도 있습니다" → 위키는 판단을 기록하는 곳이다. "~해야 한다. 이유는 X" 또는 "A/B 중 선택. 기준은 Y".
5. 장황 접속 연쇄 — "또한 ~하며, 이를 통해 ~하고, 뿐만 아니라" → 문장을 자른다. 한 문장 한 생각.

풀어쓰기 기술 (the moves)

대상은 한국어 문서다. 다른 언어에는 언어 보편 규칙만 적용하고, 조사·피동·번역투 규칙은 한국어에 한정한다.

1. 한 문장 한 생각 — 절이 두 개 이상 겹치면 쪼갠다.
2. 명사문을 동사문으로 — "장애 대응의 수행" → "장애에 대응한다."
3. 능동태 + 행위 주체 명시 — "재시작이 필요합니다" → "운영자가 pod를 재시작해야 한다." 절차 문서에서 주어 생략은 사고의 원인이다.
4. 이중피동·번역투 제거 — "~되어진다", "~에 있어서", "~을 필요로 한다" → "~된다", "~에서", "~이 필요하다."
5. 필러 삭제 — "기본적으로", "참고로 말씀드리면", "~라고 할 수 있습니다"는 지워도 뜻이 같다.
6. 구체성 — "정기적으로 정리" → "매주 월요일 배치가 정리". 범주 대신 실례, 형용사 대신 숫자. 숫자를 모르면 지어내지 말고 "미측정"이라 쓴다.
7. 예시 하나가 정의보다 낫다 — 개념 설명 뒤에 실제 요청/응답, 실제 명령어, 실제 화면 경로를 하나 붙인다.
8. 평서형(한다체)으로 통일 — 위키는 판단과 절차를 기록하는 곳이다. 존대체("~합니다", "~하시기 바랍니다")는 문장을 늘이고 지시 강도를 흐린다. "재시작하시기 바랍니다" → "재시작한다".

부정 병렬 금지

"단순히 X가 아니라 Y입니다" 패턴("X를 넘어 Y로", "중요한 것은 X가 아니라 Y"). 기각할 프레임을 세웠다 무너뜨려 통찰처럼 보이게 하는 수사이고, 대부분 요점이 없다는 신호다. 기각 절반을 지우고 Y를 구체적 직접 주장으로 다시 쓴다. 사실을 기록하는 위키에서 수사는 검색 노이즈다.

블록리스트

원칙: 사실을 설명하는 대신 홍보하는 단어는 지운다.

• 의미 인플레이션: 혁신적인, 획기적인, 강력한, 완벽한, 핵심적인, 최적의, 원활한 → 사실과 숫자로 대체하거나 삭제
• 죽은 서두: "본 문서에서는 ~을 다룹니다", "~의 중요성이 커지고 있습니다" → 첫 문장부터 결론. "이 문서는 X를 다룬다"가 필요하면 한 줄로 끝낸다
• 장황 접속: 또한, 더불어, 뿐만 아니라, 이를 통해 → 논리적 역할이 없으면 무접속
• 시점 의존어: 최근, 현재, 이번, 작년, 신규 → 날짜와 이름으로
• 지시대상 변주: 같은 대상을 문단마다 다른 말로 바꿔 부르기("결제 서비스 → 해당 플랫폼 → 본 시스템 → 이 모듈") → 이름 하나로 고정한다. 변주는 우아해 보이지만 검색을 깨고, 미래의 독자가 같은 것을 말하는지 확신하지 못하게 한다
• 분사·연결어미 가짜 깊이: "~을 강조하며", "~을 뒷받침하며", "~을 시사하며"(-며로 매달아 분석을 흉내) → 근거가 있으면 독립 문장으로, 없으면 삭제
• 죽은 비유: "시스템의 심장", "데이터의 혈관", "아키텍처의 뼈대" → 위키는 직서. 비유는 대상이 정말 낯설고 직접 설명보다 짧을 때만
• 형식 tell: 불릿 벽, 모든 목록이 3개, 과도한 볼드, 장식용 이모지

형식 규칙 (스캔 가능성)

• 첫 문단 = 요약. 무엇에 관한 문서인지, 누가 언제 읽어야 하는지 3문장 안에. 요약에 박은 조건(독자·시점 등)은 본문에서 같은 표현으로 되풀이하지 않는다 — 요약은 예고, 본문은 전개.
• 섹션 제목만 읽어도 문서의 뼈대가 보이게. 제목 형태는 위 검색성 규칙을 따른다.
• 불릿은 열거에만, 논리 전개는 문단으로. 원인→결과, 판단→근거가 흐르는 내용을 불릿로 부수면 논리가 사라진다.
• 표는 짧은 사실의 대조에만. 셀에 문장이 들어가기 시작하면 문단으로 해체한다.
• 절차는 번호 목록으로, 한 단계 한 행동. 각 단계에 검증 방법(무엇이 보이면 성공인지)을 붙이면 더 좋다.
• 관련 문서는 링크로. 다른 문서의 내용을 복사해 오지 않는다. 사본은 반드시 낡는다.
• 검색 라벨/태그 후보를 문서 끝에 제안한다. 위키 검색은 라벨로도 이루어진다. 붙이는 것은 등록 도구의 일이지만, 후보 제안은 이 스킬의 일이다.

Writing mode (새로 쓸 때)

초안은 평소대로 쓴다. 완성 후 세 번의 패스:

1. 구조 패스: 첫 문단이 요약인가? 제목이 검색어를 품은 결론인가? 섹션 순서가 독자의 질문 순서인가?
2. 부하 패스: 가장 무거운 문장 2~3개를 쪼갠다. 명사문→동사문, 피동→능동, 필러 삭제.
3. 미래 독자 패스: 시점 의존어를 날짜로, 암묵적 맥락을 명시적 문장이나 링크로. "이 문서만 읽고 따라 할 수 있는가?"

Audit mode (기존 글을 감사할 때)

문제 지점을 원문 그대로 인용해 표시하고, 수정안을 제시한다. 감사 대상은 3원칙·풀어쓰기 기술·블록리스트 위반 전부다. 아래는 형식 예시일 뿐이니 항목을 고정하지 말고 실제 발견된 것만 나열한다:

WRITE-WIKI AUDIT:
  자기완결성:  FLAG — "지난번 논의된 방안대로 적용" → 어떤 방안인지 문서 안에 요약 또는 링크
  시점 의존:   FLAG — "최근 도입된 신규 게이트웨이" → "2026-05 도입된 `api-gateway-v2`"
  명사화:      FLAG — "설정 변경의 적용이 필요함" → "설정을 바꿔야 한다"
  주체 누락:   FLAG — "재시작되어야 합니다" → 누가? "운영자가 `pod`를 재시작한다"
  검색성:      FLAG — 제목 "트러블슈팅" → "Redis 세션 스토어 OOM 트러블슈팅"
  수정안: [사실과 용어를 보존한 재작성]

과교정 방지 (anti-overfitting)

• 규칙이 문서를 더 나쁘게 만들면 규칙을 어긴다.
• 팀이 매일 쓰는 도메인 용어에 매번 정의를 달지 않는다. 첫 등장 한 번이면 된다.
• 완결성을 위해 모든 배경을 본문에 욱여넣지 않는다. 링크가 있는 이유다.
• 스캔 가능성은 구조의 일이지 문장을 전부 불릿로 부수는 일이 아니다.

최종 테스트: 맥락 없는 동료가 검색으로 이 문서에 도착해서, 훑어서 답을 찾고, 따라 해서 성공하는가?