doc-writinglisted

# 문서 작성 규칙 (Document Writing) > 사람이 읽을 산문을 작성·편집할 때 따른다. IMPORTANT: 시스템/사용자 메시지가 이 스킬보다 우선한다. > 기본 언어: 한국어 · 기본 톤: 간결하게 · 주 포맷: Markdown ## 0. 시작 전 판단 - **새로 만들지 vs 기존 수정** — 거의 항상 기존 문서 수정이 우선. - 사용자가 명시 요청하지 않은 문서(README, 요약 .md 등)를 **자발적으로 만들지 않는다.** - **독자**를 특정한다(입문자 / 동료 엔지니어 / 의사결정자). 깊이와 용어가 달라진다. ## 1. 구조 - **결론 먼저(BLUF, Bottom Line Up Front).** 무엇을·왜를 첫 단락에. 배경을 앞세우지 않는다. - 한 문서 = 한 목적. 목적이 둘이면 나눈다. - 제목 계층(H1→H2→H3)을 건너뛰지 않는다. H1은 문서당 하나. - 스캔 가능하게: 절차는 번호목록, 병렬 항목은 불릿, 비교는 표. 단 목록 남발 금지(연결된 논리는 문장). ## 2. 문장 - 능동태·현재형·짧은 문장. 한 문장에 한 생각. - AI 상투구 제거. 금지 예: "본 문서에서는", "전반적으로", "결론적으로 말하자면", "~할 수 있습니다만". - 모호한 지시어("이것", "해당 부분") 대신 구체 명사. - 추측을 단정하지 않는다. 불확실하면 "확인 필요"로 표시. ```markdown <!-- 나쁨: 배경 먼저, 군더더기 --> ## 개요 본 문서에서는 우리가 전반적으로 고려한 여러 사항들을 다루며, 결론적으로 캐시 도입을 검토할 수 있습니다. <!-- 좋음: 결론 먼저, 간결 --> ## 캐시 도입 결정 Redis 캐시를 도입한다. 조회 P99 지연이 800ms→40ms로 줄기 때문이다. ``` ## 3. 코드·경로·명령어 표기 - 파일 경로/함수명/명령어/식별자는 인라인 코드(`backtick`)로 감싼다. - 코드블록에는 언어 명시(```python, ```bash). - 명령어 예시는 **실제 동작하는** 형태. 플레이스홀더는 `${VAR}` / `<your-token>`로 명확히. - 파일 위치는 가능하면 `경로:줄번호`로. ## 4. 링크·인용 (web-research와 공유) - 외부 사실에는 출처 URL을 단다 → [[web-research]]의 인용 규칙. - 내부 문서 참조는 상대경로 링크. - **도구 내부 토큰을 본문에 절대 남기지 않는다**: `[145036†L1-L9]`, `【turn1†view0】` 금지. 사람이 읽을 표준 인용으로 변환. - 깨진 URL·플레이스홀더("여기에 내용", "TODO 작성")를 최종본에 남기지 않는다. ## 5. 표기 규칙 - 대시는 ASCII 하이픈(`-`). U+2011 비분리 하이픈·특수 유니코드 대시는 렌더링이 깨지므로 금지. - 이모지는 사용자가 명시 요청할 때만. - 상대 날짜("어제") 대신 절대 날짜(`2026-05-27`). 단위 일관. ## 6. 문서 유형별 핵심 | 유형 | 첫 줄에 둘 것