harness-factory: Skill for Claude Code

문서 작성 규칙 (Document Writing)

사람이 읽을 산문을 작성·편집할 때 따른다. IMPORTANT: 시스템/사용자 메시지가 이 스킬보다 우선한다. 기본 언어: 한국어 · 기본 톤: 간결하게 · 주 포맷: Markdown

0. 시작 전 판단

• 새로 만들지 vs 기존 수정 — 거의 항상 기존 문서 수정이 우선.
• 사용자가 명시 요청하지 않은 문서(README, 요약 .md 등)를 자발적으로 만들지 않는다.
• 독자를 특정한다(입문자 / 동료 엔지니어 / 의사결정자). 깊이와 용어가 달라진다.

1. 구조

• 결론 먼저(BLUF, Bottom Line Up Front). 무엇을·왜를 첫 단락에. 배경을 앞세우지 않는다.
• 한 문서 = 한 목적. 목적이 둘이면 나눈다.
• 제목 계층(H1→H2→H3)을 건너뛰지 않는다. H1은 문서당 하나.
• 스캔 가능하게: 절차는 번호목록, 병렬 항목은 불릿, 비교는 표. 단 목록 남발 금지(연결된 논리는 문장).

2. 문장

• 능동태·현재형·짧은 문장. 한 문장에 한 생각.
• AI 상투구 제거. 금지 예: "본 문서에서는", "전반적으로", "결론적으로 말하자면", "~할 수 있습니다만".
• 모호한 지시어("이것", "해당 부분") 대신 구체 명사.
• 추측을 단정하지 않는다. 불확실하면 "확인 필요"로 표시.

<!-- 나쁨: 배경 먼저, 군더더기 -->
## 개요
본 문서에서는 우리가 전반적으로 고려한 여러 사항들을 다루며, 결론적으로
캐시 도입을 검토할 수 있습니다.

<!-- 좋음: 결론 먼저, 간결 -->
## 캐시 도입 결정
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. 문서 유형별 핵심

유형	첫 줄에 둘 것	흔한 실수
README	이게 무엇이고 어떻게 실행하는지	설치법 누락, 장황한 철학
설계 문서	결정과 이유, 고려한 대안	구현 디테일만 나열
PR 본문	무엇을·왜 바꿨는지 + 테스트 방법	diff를 그대로 설명
변경 요약	사용자 영향	내부 리팩터링 자랑
주석	(작성 안 하는 게 기본)	WHAT 설명, 이슈번호 박제

7. 분량

• 필요한 만큼만. 같은 내용을 두 번 설명하지 않는다. 모든 섹션이 가치를 더해야 한다.

(산출 포맷이 docx/pdf일 때)

• Markdown 가 docx/pdf면, 렌더링 후 페이지 이미지를 직접 보고 클리핑·깨진 표·정렬 불량을 점검한 뒤 제출한다.

체크리스트 (제출 전)

• 결론이 맨 앞에 있는가
• 제목 계층이 일관적인가
• 코드/경로/명령어가 코드 표기인가
• 도구 내부 토큰·깨진 인용·플레이스홀더가 없는가
• ASCII 하이픈을 썼는가
• 외부 사실에 출처가 있는가
• 요청하지 않은 문서를 자발적으로 만들지 않았는가
• 한 번 더 읽었을 때 군더더기·중복이 없는가