Agentic-AI-Template/Writing/Gemini/docs/UI_GUIDE.md

Markdown 문서 스타일 가이드

원칙

1. 독자의 다음 행동이 분명해야 한다. 설명문이라면 이해, 보고서라면 판단, 가이드라면 실행이 가능해야 한다.
2. 근거와 의견을 섞지 않는다. 사실, 해석, 권고를 구분해 쓴다.
3. AI가 쓴 듯한 일반론보다 사용자의 목적과 키워드에 맞춘 구체성을 우선한다.

AI 문서 안티패턴

금지 사항	이유
"오늘날 빠르게 변화하는 시대에" 같은 상투적 도입	정보 밀도가 낮고 AI 생성문처럼 보인다
근거 없는 최상급 표현	신뢰를 떨어뜨린다
출처 없는 통계와 수치	검증할 수 없다
같은 의미의 문장을 반복해 분량 늘리기	독자의 시간을 낭비한다
목차와 본문 제목 불일치	리뷰와 유지보수가 어려워진다
PRD에 없는 독자나 목표 추가	사용자 의도를 벗어난다
ResearchNote에 없는 외부 주장 단정	출처 추적이 끊긴다
GEMINI.md와 Skill 지침 불일치	Gemini CLI 실행 맥락이 흔들린다

구조

• 문서 제목은 # 하나만 사용한다.
• 주요 섹션은 ##, 하위 섹션은 ###를 사용한다.
• 한 섹션에는 하나의 중심 메시지만 둔다.
• 긴 목록은 표로 바꿀 수 있는지 검토한다.
• 결론 문서라면 "요약 -> 근거 -> 판단/권고 -> 한계" 순서를 우선 고려한다.
• 설명 문서라면 "맥락 -> 핵심 개념 -> 절차/예시 -> 주의사항" 순서를 우선 고려한다.

문체

• 문장은 가능한 한 짧게 쓴다.
• 모호한 주어를 피한다.
• "중요하다", "효과적이다"처럼 평가를 쓸 때는 이유나 근거를 바로 붙인다.
• 불확실한 정보는 확률적 표현 또는 확인 필요 표시를 사용한다.
• 한국어 문서에서는 불필요한 영어 약어를 피하고, 처음 등장할 때 풀어쓴다.

출처 표기

• 외부 사실은 문장 끝이나 문단 끝에 출처 링크를 붙인다.
• 긴 직접 인용보다 요약과 해석을 우선한다.
• 같은 출처를 반복해서 사용할 때도 어떤 주장에 연결되는지 분명히 한다.
• 출처가 상충하면 docs/ResearchNote.md의 "쟁점/상반된 주장"에 기록한다.

표와 목록

• 비교, 분류, 의사결정 기준은 표를 우선 검토한다.
• 순서가 중요한 절차는 번호 목록을 사용한다.
• 단순 나열은 bullet을 사용한다.
• 표는 너무 넓어지면 섹션을 나누거나 요약 표와 상세 설명을 분리한다.

최종 점검

• PRD의 목적과 대상 독자에 맞는가?
• 모든 핵심 질문에 답했는가?
• 외부 주장에 출처가 있는가?
• 초안 피드백이 반영되었는가?
• 문서 제목, 섹션 제목, 파일명이 산출물 목적과 맞는가?
• 최종 문서는 final/ 아래에 있는가?
• Gemini CLI Skill, subagent, command, hook 지침과 충돌하지 않는가?