NINI
55 lines
2.9 KiB
Markdown
55 lines
2.9 KiB
Markdown
# Markdown 문서 스타일 가이드
|
|
|
|
## 원칙
|
|
1. 독자의 다음 행동이 분명해야 한다. 설명문이라면 이해, 보고서라면 판단, 가이드라면 실행이 가능해야 한다.
|
|
2. 근거와 의견을 섞지 않는다. 사실, 해석, 권고를 구분해 쓴다.
|
|
3. AI가 쓴 듯한 일반론보다 사용자의 목적과 키워드에 맞춘 구체성을 우선한다.
|
|
|
|
## AI 문서 안티패턴
|
|
| 금지 사항 | 이유 |
|
|
|-----------|------|
|
|
| "오늘날 빠르게 변화하는 시대에" 같은 상투적 도입 | 정보 밀도가 낮고 AI 생성문처럼 보인다 |
|
|
| 근거 없는 최상급 표현 | 신뢰를 떨어뜨린다 |
|
|
| 출처 없는 통계와 수치 | 검증할 수 없다 |
|
|
| 같은 의미의 문장을 반복해 분량 늘리기 | 독자의 시간을 낭비한다 |
|
|
| 목차와 본문 제목 불일치 | 리뷰와 유지보수가 어려워진다 |
|
|
| PRD에 없는 독자나 목표 추가 | 사용자 의도를 벗어난다 |
|
|
| ResearchNote에 없는 외부 주장 단정 | 출처 추적이 끊긴다 |
|
|
| AGENTS.md와 Skill 지침 불일치 | Codex 실행 맥락이 흔들린다 |
|
|
|
|
## 구조
|
|
- 문서 제목은 `#` 하나만 사용한다.
|
|
- 주요 섹션은 `##`, 하위 섹션은 `###`를 사용한다.
|
|
- 한 섹션에는 하나의 중심 메시지만 둔다.
|
|
- 긴 목록은 표로 바꿀 수 있는지 검토한다.
|
|
- 결론 문서라면 "요약 -> 근거 -> 판단/권고 -> 한계" 순서를 우선 고려한다.
|
|
- 설명 문서라면 "맥락 -> 핵심 개념 -> 절차/예시 -> 주의사항" 순서를 우선 고려한다.
|
|
|
|
## 문체
|
|
- 문장은 가능한 한 짧게 쓴다.
|
|
- 모호한 주어를 피한다.
|
|
- "중요하다", "효과적이다"처럼 평가를 쓸 때는 이유나 근거를 바로 붙인다.
|
|
- 불확실한 정보는 확률적 표현 또는 확인 필요 표시를 사용한다.
|
|
- 한국어 문서에서는 불필요한 영어 약어를 피하고, 처음 등장할 때 풀어쓴다.
|
|
|
|
## 출처 표기
|
|
- 외부 사실은 문장 끝이나 문단 끝에 출처 링크를 붙인다.
|
|
- 긴 직접 인용보다 요약과 해석을 우선한다.
|
|
- 같은 출처를 반복해서 사용할 때도 어떤 주장에 연결되는지 분명히 한다.
|
|
- 출처가 상충하면 `docs/ResearchNote.md`의 "쟁점/상반된 주장"에 기록한다.
|
|
|
|
## 표와 목록
|
|
- 비교, 분류, 의사결정 기준은 표를 우선 검토한다.
|
|
- 순서가 중요한 절차는 번호 목록을 사용한다.
|
|
- 단순 나열은 bullet을 사용한다.
|
|
- 표는 너무 넓어지면 섹션을 나누거나 요약 표와 상세 설명을 분리한다.
|
|
|
|
## 최종 점검
|
|
- PRD의 목적과 대상 독자에 맞는가?
|
|
- 모든 핵심 질문에 답했는가?
|
|
- 외부 주장에 출처가 있는가?
|
|
- 초안 피드백이 반영되었는가?
|
|
- 문서 제목, 섹션 제목, 파일명이 산출물 목적과 맞는가?
|
|
- 최종 문서는 `final/` 아래에 있는가?
|
|
- Codex Skill, agent, hook 지침과 충돌하지 않는가?
|