writing-voice-ff

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 코드 해설 패턴

코드 블록 앞뒤 산문은 다음 순서로:

1. 문제 설명 (Before 앞): "이 코드는 ~해서 ~하기 어려워요."
2. Before 코드 블록
3. 진단 (Before 뒤): "~할 때마다 ~를 확인해야 해요." 또는 "코드를 읽는 사람이 ~를 한 번에 고려해야 해요."
4. 개선 방향 (After 앞): "역할을 나눠서 ~하면 ~가 분명해져요."
5. After 코드 블록
6. 효과 (After 뒤): 불릿으로 "~이 줄어들었어요", "~가 분명해졌어요"

체크리스트 항목 어미

~인가요? 의문형보다 ~했어요? 회고형이 사이트 톤에 맞는다.

• ❌ "변수 이름이 의도를 드러내는가?"
• ✅ "변수 이름이 의도를 드러내나요?"
• ✅ (회고형) "변수 이름에서 의도가 드러나는지 한 번 더 봤어요?"

브릿지 문장 예시 (chapter-editor가 참조)

위치	브릿지 후보
요약 → VotingBar	"7명이 이 원칙에 준 점수는 다음과 같아요."
코드 → 토론	"코드로 끝나지 않는 원칙이에요. 현업에서는 이런 질문이 따라와요."
토론 → 멤버 의견	"원칙은 이론이에요. 실무에서 이게 어떻게 체감되는지 들어봐요."
체크리스트 → BestPick	"이 장에서 팀이 가장 인상 깊게 짚은 한 마디는 이거예요."

Common Mistakes

실수	예시	수정
격식체 혼용	"~예요. ~합니다. ~이에요."	한 문서에서 어미 통일
"우리는" 남발	"우리는 이 코드를 고쳐야 해요."	"이 코드는 ~한 방식으로 개선할 수 있어요."
이유 없는 금지	"any를 쓰지 마세요."	"any를 쓰면 타입 체커가 ~를 놓쳐요."
이모지 장식 남용	"🎉 🚀 ✨ 드디어 살펴볼 시간이에요!"	섹션 헤딩당 이모지 1개, 역할형
과잉 정중체	"~해보시는 건 어떨까요?"	"~해볼 수 있어요."

참고 원본

• https://frontend-fundamentals.com/code-quality/code/
• 리서치 시점: 2026-04-18

사이트가 업데이트되면 이 스킬도 같이 갱신. 변경 이력은 CLAUDE.md에 남긴다.