| name | writing-voice-ff |
| description | Use when writing or reviewing Korean prose for Code Complete Docusaurus chapters — choosing sentence endings, addressing the reader, framing code before/after, picking section emoji, or transliterating English FE terms. Based on Frontend Fundamentals (frontend-fundamentals.com) voice. Apply to AI-editable zones (summary, code annotation, checklist), bridges between sections, and MDX headings. Do not apply to human_only member content. |
writing-voice-ff
Overview
Code Complete 챕터의 AI 집필 영역에 적용하는 공용 어투 가이드. 출처는 Frontend Fundamentals(토스 FE 챕터가 운영하는 오픈 가이드). 친근하되 경어를 유지하는 "해요체"와 "코드를 읽는 사람" 관점이 핵심.
이 스킬은 chapter-reorchestration, fe-content-enhance, mdx-render가 글을 쓸 때 참조하고, voice-ai-slop-detect는 반대로 이 가이드에서 벗어난 문장을 슬롭으로 탐지한다.
When to Use
- AI가 챕터 요약·코드 주석·체크리스트 해설·섹션 브릿지를 쓸 때
- 섹션 제목 이모지/헤딩 선택 시
- 영어 FE 용어를 한국어 본문에 녹일 때
- 이미 쓰인 문장이 "사이트 어투에 맞는지" 판단할 때
적용 금지 영역: human_only.* (멤버 의견, Devil's Advocate, Best Pick). 멤버 원문은 어투가 달라도 그대로.
7가지 어투 원칙
1. 해요체를 기본으로
문장 어미는 ~이에요 / ~해요 / ~죠 / ~어요 / ~네요 중 선택. 격식체(~입니다 / ~합니다)와 반말은 모두 지양.
- ❌ "좋은 프론트엔드 코드는 변경하기 쉬운 코드입니다."
- ❌ "좋은 프론트엔드 코드는 변경하기 쉬운 코드다."
- ✅ "좋은 프론트엔드 코드는 변경하기 쉬운 코드예요."
2. 독자 호명은 "코드를 읽는 사람"
"우리는 / 여러분은 / 여러분도"는 쓰지 않는다. 대신 일반화된 제3자 관찰로 쓴다.
- ❌ "여러분도 한 번 이 원칙을 적용해보세요."
- ❌ "우리는 이 코드에서 문제를 발견할 수 있어요."
- ✅ "코드를 읽는 사람이 한 번에 고려해야 하는 맥락이 많아요."
- ✅ "이 코드는 의도를 한눈에 파악하기 어려워요."
3. "왜" 중심 설명
규칙을 기계적으로 나열하지 않고 이유를 붙인다. 이유는 짧아도 좋다.
- ❌ "any 타입을 쓰면 안 돼요."
- ✅ "any 타입을 쓰면 타입 체커가 보호해주지 못해서, 런타임 오류가 그대로 드러나요."
4. 섹션 이모지는 역할형
장식형 이모지(✨, 🚀, 🎯)보다 어떤 행동을 하는 섹션인지 드러내는 이모지를 쓴다.
| 섹션 역할 | 권장 이모지 | 예시 헤딩 |
|---|
| 문제 진단 | 👃 | "👃 코드 냄새 맡아보기" |
| 개선·수정 | ✏️ | "✏️ 개선해보기" |
| 핵심 원칙 | 🧭 | "🧭 원칙 짚어보기" |
| 주의/함정 | ⚠️ | "⚠️ 놓치기 쉬운 지점" |
| 체크리스트 | ✅ | "✅ 실전 체크리스트" |
| 토론 | 🔥 | "🔥 토론 포인트" |
커스텀 MDX 컴포넌트 섹션(Verdict, MemberOpinion 등)은 기존 이모지 유지. 위 표는 챕터 서술용 H2/H3에만 적용.
5. 영어 용어 병기
FE 용어는 한국어(영어) 형태로 첫 등장 시 병기. 이후 등장에서는 한국어만.
- ✅ "**가독성(Readability)**이 낮으면, 새 팀원이 생산성에 도달하는 시간이 길어져요."
- ✅ "**응집도(Cohesion)**는 수정되어야 할 코드가 함께 수정되는 정도예요."
- 그 다음 문단부터는 "가독성", "응집도"만 써도 OK
API 이름·훅 이름처럼 코드 식별자는 영어 원문 유지: useEffect, useMemo, <Suspense>.
6. 단정보다 여지 남기기
"반드시", "항상", "무조건" 대신 가능성·상황 조건을 남긴다.
- ❌ "응집도는 반드시 높여야 해요."
- ✅ "응집도를 높이면 수정 범위를 예측하기 쉬워져요."
- ✅ "가독성과 응집도는 서로 상충할 수 있어요."
7. 짧은 문장 + 연결 표현
긴 복합문 하나보다 2~3개 문장으로 나눠서 리듬을 준다. 자주 쓰는 연결 표현:
- "예를 들어"
- "그래서"
- "동시에"
- "한 번에"
- "이때"
- "결국"
빠른 대비 (슬롭 vs 해요체)
| AI 슬롭 (금지) | Frontend Fundamentals 스타일 |
|---|
| "이제부터는 변수 네이밍에 대해 알아보겠습니다." | "변수 이름은 의도를 드러내야 해요." |
| "여러분도 이 원칙을 적용해보세요." | "이 원칙을 적용하면 수정이 쉬워져요." |
| "이 장에서는 ~을 살펴보았습니다." | (결론 섹션 자체를 생략. 본론에서 이미 드러냄) |
| "정말 중요한 개념입니다." | "이 개념이 없으면 코드 수정 비용이 빠르게 커져요." |
| "~라고 할 수 있겠습니다." | "~예요." |
Before/After 코드 해설 패턴
코드 블록 앞뒤 산문은 다음 순서로:
- 문제 설명 (Before 앞): "이 코드는 ~해서 ~하기 어려워요."
- Before 코드 블록
- 진단 (Before 뒤): "~할 때마다 ~를 확인해야 해요." 또는 "코드를 읽는 사람이 ~를 한 번에 고려해야 해요."
- 개선 방향 (After 앞): "역할을 나눠서 ~하면 ~가 분명해져요."
- After 코드 블록
- 효과 (After 뒤): 불릿으로 "~이 줄어들었어요", "~가 분명해졌어요"
체크리스트 항목 어미
~인가요? 의문형보다 ~했어요? 회고형이 사이트 톤에 맞는다.
- ❌ "변수 이름이 의도를 드러내는가?"
- ✅ "변수 이름이 의도를 드러내나요?"
- ✅ (회고형) "변수 이름에서 의도가 드러나는지 한 번 더 봤어요?"
브릿지 문장 예시 (chapter-editor가 참조)
| 위치 | 브릿지 후보 |
|---|
| 요약 → VotingBar | "7명이 이 원칙에 준 점수는 다음과 같아요." |
| 코드 → 토론 | "코드로 끝나지 않는 원칙이에요. 현업에서는 이런 질문이 따라와요." |
| 토론 → 멤버 의견 | "원칙은 이론이에요. 실무에서 이게 어떻게 체감되는지 들어봐요." |
| 체크리스트 → BestPick | "이 장에서 팀이 가장 인상 깊게 짚은 한 마디는 이거예요." |
Common Mistakes
| 실수 | 예시 | 수정 |
|---|
| 격식체 혼용 | "~예요. ~합니다. ~이에요." | 한 문서에서 어미 통일 |
| "우리는" 남발 | "우리는 이 코드를 고쳐야 해요." | "이 코드는 ~한 방식으로 개선할 수 있어요." |
| 이유 없는 금지 | "any를 쓰지 마세요." | "any를 쓰면 타입 체커가 ~를 놓쳐요." |
| 이모지 장식 남용 | "🎉 🚀 ✨ 드디어 살펴볼 시간이에요!" | 섹션 헤딩당 이모지 1개, 역할형 |
| 과잉 정중체 | "~해보시는 건 어떨까요?" | "~해볼 수 있어요." |
참고 원본
사이트가 업데이트되면 이 스킬도 같이 갱신. 변경 이력은 CLAUDE.md에 남긴다.
