writing

name	writing
description	문서 콘텐츠(포스팅, 깃헙 위키, 리드미 등)를 작성하거나 수정할 때 사용한다. "글 써줘", "문서 작성", "포스팅 작성", "위키 작성", "리드미 작성", "본문 수정" 등의 요청 시 반드시 호출한다.

문서 작성 스킬

문서 콘텐츠를 작성하거나 수정할 때 이 스킬을 따른다. 작성 컨벤션은 .claude/skills/_shared/conventions/writing.md에 정의되어 있다.

---

컨벤션 요약

작성 전 반드시 .claude/skills/_shared/conventions/writing.md를 읽고 전체 규칙을 숙지한다. 핵심 규칙만 요약하면 아래와 같다.

문체

• ~다. 또는 명사형으로 종결한다.
• ~입니다, ~합니다, ~요, ~습니다 금지.
• 한 줄에 하나의 문장만 작성한다.
• 세부 항목이 여러 개면 대시(-) 리스트로 전환하고, 리스트 항목은 명사형으로 끝낸다.

구조

• # 헤더 기준으로 의미 단위를 나눈다.
• 산문형 단락 대신 헤더 + 짧은 설명 조합으로 구성한다.

표

• 모든 셀은 가운데 정렬(:---:)을 원칙으로 한다.
• 셀 너비 맞추기용 공백 추가나 구분선 길이 변경 금지.

시각적 요소

• 텍스트만 이어지지 않도록 적절한 위치에 코드 블록, Mermaid 다이어그램, 표를 배치한다.
• HTML 태그 사용 금지, 순수 마크다운만 사용한다.

용어 선택

• 도메인 클래스명·상태 enum은 백틱으로 표기하되, prose 본문에는 메서드 호출(X.foo()) 패턴을 노출하지 않는다.
• 메서드 시그니처 대신 도메인 행위로 묘사한다(process() → "복구 사이클 실행").
• 표준 라이브러리 API와 디자인 패턴 식별 메서드는 보존 가능 (예외).
• 동의어는 한 표기로 통일 (재고 복구 / 보상 TX / Worker / 건너뜀 / 락 / 종결).
• 약어는 첫 등장 시 1회 풀어쓰기 후 약어로 사용 (예: FCG(격리 전 최종 확인)).

팩트 검증

• 확실하지 않은 내용은 작성하지 않는다.
• 공식 문서 → 웹 검색 → 검증 불가 시 제외 순서로 검증한다.

---

작성 절차

1. 요구 분석

사용자 요청에서 문서 유형과 목적을 파악한다.

문서 유형	특징
포스팅	경험·사례·트러블슈팅, 내러티브 형식
깃헙 위키	프로젝트 설명·가이드, 레퍼런스 형식
리드미	프로젝트 소개·설치·사용법, 간결한 안내

2. 아웃라인 작성

헤더 단위로 문서 구조를 잡고 사용자에게 확인한다. 서머리나 아웃라인이 제공되면 참고만 하고 그대로 따르지 않는다.

3. 본문 작성

컨벤션을 준수하며 본문을 작성한다. 작성 중 다음을 점검한다.

• 문체가 ~다. 또는 명사형인가
• 한 문장이 너무 길지 않은가 (길면 리스트 전환)
• 헤더 단위로 의미가 구분되는가
• 시각적 요소가 적절히 배치되었는가

4. 검수 요청

작성이 완료되면 doc-review 스킬로 검수를 진행한다. 검수에서 FAIL 항목이 나오면 수정 후 재검수한다.

---

기존 문서 수정 시

수정 범위가 일부라도 해당 문서 전체가 컨벤션에 맞는지 함께 확인한다.