제품 문구의 화자와 독자 어휘 - make-interfaces-feel-better
출처
- 원문: write.md. 에이전트 스킬 make-interfaces-feel-better 안의 제품 문구 규칙 문서다.
- 저장소: 115dkk/make-interfaces-feel-better. Jakub Krehel의 원 스킬을 fork해 Qt·색·문구·게임 텍스트 등을 확장했다. write.md는 일부를 jakubkrehel/skills의 better-writing(MIT)에서 가져왔고, 나머지는 저자가 출시한 제품의 문구 수정 사례에서 왔다고 밝힌다.
- 작성자: 115dkk(GitHub 계정, 실명 미공개). 커밋에 Claude 공동 작성 표기가 있다.
- 확인 버전: write.md 최종 변경 커밋
c18df57e2bceef507e53e72047ad3105296edde4(2026-10-05), 저장소 mainc3d394c23cf98e869391049777c3c6e22ef1660d. - 라이선스: MIT
- 확인일: 2026-10-10
- 요약 작성자: Claude
내 말로 요약
생성된 인터페이스 문구가 반복해서 틀리는 방식을 넷으로 정리한다. 이미 보이는 것을 되풀이하는 군더더기, 개발자 어휘(설정 키·프로세스 이름·상태 기계 용어)가 화면에 드러나는 것, 예외 문자열을 그대로 보여 주는 오류, 제품에 인격을 입히는 것이다. 고치는 방향은 하나로 모인다. 화면의 사용자 쪽에서, 사용자가 보는 것·얻는 것·다음에 할 일을 쓴다.
제품에 인격을 입히지 않는다
문서의 중심 진단이다. 언어 모델은 누군가로서 글을 쓰기 때문에 생성 문구에 화자가 생긴다. 형태는 셋이다.
- 친구: 묻고, 위로하고, 호의를 베풀고(-해 두었습니다, -해 드립니다), 다음 방문을 약속하고, 질문형 제목과 대답형 선택지로 대화한다. 사용자의 목소리(“내가 할 일”)로 말하기도 한다.
- 판매원: 표어와 시 같은 태그라인, 확인할 수 없는 형용사, 기능 화면에 입힌 세계관 의상, 아무도 묻지 않은 방어 문장(“~하지 않습니다”)을 쓴다.
- 작가: 조작의 동사(저장·기록·표시·보고) 대신 이미지나 감정을 실은 동사(담다·남기다·알려 주다)를 고른다.
판별 질문은 “누가 누구에게 말하고 있는가”다. 화면의 모든 줄은 이름(label)·지시(instruction)·사실(fact)·결과(result) 중 하나여야 하며, 친구·고객·산문 독자에게 말하는 줄이면 넷 중 하나로 다시 쓴다. 판매원 문구는 형용사를 그것을 뒷받침하는 사실로 바꾸거나 지운다.
독자가 쓰지 않는 단어는 화면에 두지 않는다
내부 어휘의 판별 질문은 “이 화면의 독자가 그 단어를 스스로 쓰는가”다. 단위, 사용자가 일하는 분야의 용어, 제품명은 내용이다. 독자가 쓰지 않는 개발 어휘는 로그·상세 패널·문서로 옮긴다. 표시 이름은 바꾸되 그 아래 식별자는 그대로 둔다.
오류는 두 방향을 함께 지킨다
원문 예외·HTTP 본문·오류 코드는 화면 메시지로 쓰지 않고 로그·상세 보기·복사 버튼으로 보낸다. 그렇다고 구체적인 원인을 “문제가 발생했습니다”로 삼켜서도 안 된다. 시스템이 이유를 알려 줬다면 사용자의 말로 무엇이 일어났고 무엇을 하면 되는지 전한다. 상태 표시도 정직해야 한다.
README는 광고가 아니라 문서다
README의 독자는 쓸지 말지 정하는 사람과 고치려는 사람이고, 고객이 아니다. 무엇인지·요구 사항·설치·사용·한계·빌드와 테스트·라이선스를 평범한 사실로 쓴다. 한계를 분명히 밝힌 README가 신뢰를 얻는다고 본다.
그 밖의 규칙
설정은 동작 방식이 아니라 사용자에게 생기는 효과로 이름 붙인다. 여러 단계 흐름에서 같은 동작에는 같은 낱말을 쓴다. 다른 화면으로 가라는 안내보다 그 자리의 컨트롤이나 그 컨트롤로 바로 가는 링크를 둔다. 모든 로캘에 모든 문자열을 번역한다. 한국어 UI는 문장을 합니다체, 상태·라벨을 명사구, 지시를 -세요로 쓰고, 단계·요구 사항은 독자가 해야 하는 일(-해야 합니다)로 쓴다.
적용 경계
- 원문의 대상은 제품 화면 문구와 README다. 팀에게 보이는 글(PR·이슈·코멘트·채팅)과 기술 자료로 넓힌 것은 아래 대조 절에서 DanzzaN이 채택한 해석이다.
- 한국어 어체 규칙(해요체 금지, 문서 전체 한 어체, -둡니다 대신 -해야 합니다)은 제품 UI·README에만 적용한다. 팀 채팅·PR 본문·에이전트 지침은 각자의 관례로 어체를 정하므로 이 규칙을 채택하지 않았다.
- 게임 속 캐릭터 대사는 원문도 예외로 둔다. 관련 문서 game-write.md는 이번에 읽지 않았다.
- 원문의 보고 형식과 심각도 구분은 이 Vault의 작업 지침으로 채택하지 않았다.
DanzzaN의 교정과의 대조 — 2026-10-10 Claude 대화
2026-10-10 DanzzaN과 Claude(Claude Code, Vigilantis 작업 디렉터리)의 대화다. DanzzaN이 write.md를 “내가 자주 지적하던 거랑 관련된 스킬”로 가져왔고, Claude가 기존 교정과 대조한 결과를 보고 증류를 지시했다. 대조한 교정은 Claude Code의 Vigilantis 프로젝트 메모리에 남은 기록이며, 원대화는 대조하지 않았다.
| write.md의 진단 | DanzzaN이 교정한 사례 |
|---|---|
| 판매원 — 표어·도입 문구 | 2026-09-24 테스트 서버 조작 덱의 표어식 제목과 표지 색 전환(“발표용 말고 담백하게 기술 가이드처럼”), 2026-09-28 기술 레퍼런스 사이트의 헤드라인형 제목과 숫자 줄(“광고문구같은건 빼고 technical writer처럼”) |
| 판매원 — 확인할 수 없는 주장 | 2026-09-24 이슈 배경의 “~할 수 있어야 한다”(“있었으면 좋겠다 싶어서 시작한거지”), 2026-09-03 “구체화”는 두루뭉술한 표현을 사실로 바꾸는 것이라는 정정 |
| 친구 — 위로·인사·되묻기 | 2026-08-14 Slack 초안의 “재촉 아니니 천천히요~”(“너무 짜치잖아”)와 PR 답글의 “확인 감사합니다 👍”, 2026-09-01 경계 공지 코멘트의 “말씀해 주세요” 꼬리(“문제 있으면 말하겠지”) |
| 화자 — 누가 말하는가 | 2026-09-24 PR 리뷰 요청 줄의 “제가 같이 고쳤습니다”(“네가 했지.. 난 시키기만 했고”) |
| 내부 어휘 | 2026-09-03 이슈 제목의 세션 어휘 “본문”(“본문이 뭐 어쨌다는 건데”), 2026-10-09 이슈 코멘트의 “③”과 “#434 5-1” 같은 맨번호 참조 |
| 군더더기 — 이미 보이는 것 | 2026-09-24 GitHub이 assignees·체크 영역으로 보여 주는 담당 줄과 CI 결과 줄을 본문에서 뺌(“assignees로 확인할 수 있는걸 왜넣어”) |
사례마다 매체(덱·웹페이지·Slack·PR·이슈)가 다르고 메모리에도 사례별로 따로 기록돼 있어서, 새 매체에서 같은 편향이 다시 나왔다. 덱에서 교정한 광고 톤이 나흘 뒤 웹페이지에서 반복된 것이 그 예다. write.md의 화자 판별 질문은 이 사례들을 하나의 판단으로 묶는다. 이 해석은 Claude가 제시했고 DanzzaN이 증류를 지시해 채택했다.