document-haness/.agents/skills/writing-natural-korean/references/genre-profiles.md

장르별 문체 프로필

공통 규칙은 SKILL.md를 따른다. 이 문서는 장르에 따라 달라지는 정보 순서, 문장 호흡, 출력 관행만 정의한다.

1. 기술 설계·운영 문서

목표

구현자와 운영자가 같은 판단을 반복하지 않고, 조건과 책임을 오해하지 않게 쓴다.

정보 순서

1. 목적과 적용 범위
2. 현재 문제 또는 전제
3. 선택한 구조와 결론
4. 선택 이유와 검토한 대안
5. 상세 동작과 경계
6. 실패 조건, 예외, 복구 방법
7. 검증 기준과 운영상 제약

문서 성격에 따라 순서를 조정할 수 있지만, 핵심 결론을 장황한 배경 뒤에 숨기지 않는다.

문장 규칙

• 컴포넌트와 책임 주체를 실제 이름으로 쓴다.
• 적절히, 필요한 경우, 상황에 맞게처럼 구현 결정을 남기는 표현은 조건으로 구체화한다.
• 장점만 나열하지 않고 비용, 제약, 실패 가능성을 함께 쓴다.
• 입력, 출력, 상태 변화, 오류, 재시도, 멱등성, 타임아웃처럼 동작을 결정하는 요소를 빠뜨리지 않는다.
• 표는 비교와 계약에 사용하고, 인과관계와 판단 이유는 문장으로 설명한다.
• 표준명, API, 코드, 경로는 바꾸지 않는다.
• 문서 안의 같은 개념에는 같은 용어를 쓴다.

피해야 할 형태

• 확장성과 안정성을 효과적으로 확보한다처럼 검증할 수 없는 장점 선언
• 모든 기술을 핵심 요소, 중요한 역할이라고 표현
• 이유 없이 선택지를 세 개씩 제시
• 세부 조건 없이 유연하게 처리한다, 안전하게 관리한다라고 끝냄
• 읽는 사람이 판단해야 할 부분을 추후 결정으로 남김

자연스러운 예시

부자연스러운 문장:

Redis는 단순한 캐시를 넘어 시스템 전반의 성능과 안정성을 향상하는 데 중요한 역할을 합니다.

개선 방향:

Redis는 조회 결과 캐시와 요청 제한에 사용한다. 세션 저장소로는 사용하지 않는다. Redis 장애가 로그인 기능까지 번지지 않게 하려는 결정이다.

2. 발표 스크립트

목표

청중이 화면과 설명을 함께 따라오게 하며, 발표자가 실제로 말할 수 있는 한국어로 쓴다.

정보 순서

• 화면에서 먼저 보이는 대상
• 청중이 알아야 할 핵심 질문
• 설명 또는 사례
• 다음 슬라이드로 넘어가는 짧은 연결

문장 규칙

• 한 문장에 핵심 정보 하나를 둔다.
• 글로 읽을 때 완벽한 문장보다 입으로 말했을 때 자연스러운 호흡을 우선한다.
• 한 문장이 길어지면 접속 표현을 늘리기보다 끊는다.
• 영문 약어와 긴 기술명은 처음에만 풀어 말하고 이후에는 짧은 명칭을 쓴다.
• 숫자, 버전, 경로를 연달아 읽어야 하면 슬라이드에 맡기고 말로는 의미를 설명한다.
• 높임말은 한 발표 안에서 통일한다.
• 청중에게 질문하는 표현은 실제로 생각할 틈을 줄 때만 사용한다.
• 발표자가 하지 않을 법한 감탄, 과장, 광고 문구를 넣지 않는다.

전환 문장 예시

• 먼저 현재 요청이 어디로 들어오는지 보겠습니다.
• 여기서 문제가 하나 생깁니다.
• 이제 이 구조를 왜 바꿨는지 보겠습니다.
• 지금까지는 정상 흐름이었습니다. 다음은 실패했을 때입니다.
• 결과만 먼저 보면 응답 시간은 이렇게 달라졌습니다.

같은 전환을 반복하지 않는다. 연결이 필요 없으면 바로 다음 설명으로 넘어간다.

소리 내어 읽기 점검

• 한 호흡에 읽기 어려운가?
• 받침이 겹치거나 영문 약어가 몰려 발음이 막히는가?
• 긴 관형절 때문에 서술어를 잊게 되는가?
• 슬라이드 문구를 그대로 낭독하고 있지는 않은가?
• 이, 그, 해당, 이를이 가리키는 대상이 청중에게 분명한가?

자연스러운 예시

부자연스러운 문장:

앞서 살펴본 문제점을 기반으로 이를 해결하기 위해 적용한 아키텍처와 그에 따른 구체적인 개선 결과를 살펴보겠습니다.

개선 방향:

여기까지 기존 구조의 문제를 봤습니다. 이제 구조를 어떻게 바꿨는지 보겠습니다. 그다음 실제 결과를 확인하겠습니다.

3. 일반 설명 글·기술 블로그

목표

독자가 글을 읽게 된 이유를 잃지 않고, 문제와 판단 과정을 따라가게 쓴다.

정보 순서

1. 실제 문제나 질문
2. 필요한 배경과 전제
3. 시도한 방법 또는 핵심 설명
4. 실패하거나 헷갈린 지점
5. 판단이 달라진 이유
6. 결과, 한계, 적용 범위

참고서나 사전형 문서라면 서사를 강요하지 않고 항목별 구조를 사용한다.

문장 규칙

• 도입부에서 거대한 시대 변화나 기술의 중요성을 선언하지 않는다.
• 경험한 사실과 일반적인 기술 설명을 구분한다.
• 독자를 계속 여러분이라고 부르지 않는다.
• 예시는 설명 직후에 배치한다.
• 실패 원인과 해결 과정을 성공담으로 과장하지 않는다.
• 결론은 본문의 핵심 판단과 한계를 정리하되 문단별 내용을 다시 나열하지 않는다.
• 검색어를 문장에 반복해서 넣지 않는다.

자연스러운 예시

부자연스러운 문장:

오늘날 소프트웨어 개발 환경에서 관측 가능성은 그 어느 때보다 중요한 핵심 요소로 자리 잡고 있습니다.

개선 방향:

장애가 났을 때 로그만으로는 요청이 어느 서비스에서 느려졌는지 찾기 어려웠다. 이 문제를 확인하려고 트레이스와 메트릭을 함께 수집했다.

4. 자기소개서·경력 기술서

목표

지원자의 경험과 판단을 사실에 근거해 보여 준다. 잘 보이기 위한 문장보다 검증 가능한 내용을 우선한다.

기본 구조

• 어떤 상황과 문제가 있었는가
• 본인이 맡은 범위는 어디까지였는가
• 어떤 판단과 행동을 했는가
• 결과가 무엇이었는가
• 무엇을 배웠고 이후 행동이 어떻게 달라졌는가

모든 항목에 이 구조를 기계적으로 적용하지 않는다. 질문이 요구하는 부분만 쓴다.

문장 규칙

• 저는 책임감이 강합니다보다 책임감을 보여 주는 행동을 쓴다.
• 팀의 성과와 본인의 기여를 구분한다.
• 숫자는 사용자가 제공했거나 자료로 확인된 경우에만 쓴다.
• 기술 이름을 나열하지 말고 문제 해결에 어떤 역할을 했는지 쓴다.
• 실패를 미화하거나 약점인 척하는 장점을 만들지 않는다.
• 지원 기업을 근거 없이 찬양하지 않는다.
• 채용 공고의 표현을 그대로 복사해 자신의 경험인 것처럼 쓰지 않는다.

금지되는 보완

• 존재하지 않는 프로젝트나 역할 추가
• 대략적인 결과를 정확한 수치로 변환
• 사용자가 말하지 않은 리더십, 갈등, 장애 경험 생성
• 실제 동기와 다른 지원 동기 작성
• 기술 숙련도를 근거 없이 상향

5. 업무 메일·메신저

목표

상대가 상황과 필요한 행동을 빠르게 이해하게 쓴다.

정보 순서

1. 연락한 목적
2. 필요한 배경
3. 요청 사항 또는 결정 사항
4. 기한과 다음 행동

짧은 메시지는 인사말보다 목적을 먼저 쓸 수 있다. 외부 고객이나 공식 요청에는 관계에 맞는 인사와 맺음말을 둔다.

문장 규칙

• 확인 부탁드립니다만 쓰지 말고 무엇을 언제까지 확인해야 하는지 쓴다.
• 책임 주체가 여러 명이면 담당자를 명시한다.
• 거절이나 이견은 모호하게 돌려 쓰지 말고 이유와 가능한 대안을 함께 쓴다.
• 사물에 높임 표현을 붙이지 않는다.
• 과도한 관공서 문구와 한자어를 줄인다.
• 메신저에서는 지나치게 완결된 보고서 문체를 강요하지 않는다.

6. 안내문·사용자 문구

목표

사용자가 현재 상태, 원인, 가능한 행동을 즉시 이해하게 쓴다.

문장 규칙

• 오류가 발생했다는 말만 하지 말고 사용자가 할 수 있는 행동을 제시한다.
• 내부 시스템 용어와 오류 코드를 그대로 노출하지 않는다. 문제 해결에 필요하면 별도 상세 정보로 둔다.
• 사용자 탓으로 들리는 표현을 피한다.
• 버튼 이름과 화면 용어를 실제 UI와 일치시킨다.
• 경고는 위험의 크기에 맞게 쓴다. 모든 상황을 중요, 필수, 즉시로 강조하지 않는다.

장르가 섞인 경우

하나의 글에 장르가 섞이면 주된 사용 상황을 기준으로 정한다.

• 발표 슬라이드의 발표자 노트: 발표 스크립트 우선
• 기술 블로그의 명령어 설명: 블로그 흐름 + 기술 문서 정확성
• 포트폴리오의 프로젝트 설명: 경력 문서 사실성 + 기술 문서 구체성
• 장애 공지 메일: 업무 메일 구조 + 안내문 행동 지침

서로 충돌하면 사실성과 정확성, 실제 사용 가능성을 우선한다.