writing

name	writing
description	문서 콘텐츠 작성 컨벤션. 문서를 새로 작성하거나 수정할 때, 기존 문서의 스타일 컨벤션 확인 요청 시, 본문 내용을 직접 작성할 때 사용한다.

/writing - 문서 콘텐츠 작성 컨벤션

Triggers

• 문서 콘텐츠를 새로 작성하거나 수정할 때
• 기존 문서의 스타일이 컨벤션에 맞는지 확인 요청 시
• /add 또는 직접 편집으로 본문 내용을 작성할 때

---

절대 금지

볼드(**) 사용 금지

**텍스트** 형식은 본문 어디에도 사용하지 않는다.

표(table) 정렬 및 간격 조절

• 표 추가 시 모든 셀은 가운데 정렬(:---:)을 원칙으로 한다. (단, 내용이 너무 길어 가독성이 떨어지는 경우에만 왼쪽 정렬을 허용한다.)
• 마크다운 표의 셀 너비를 맞추기 위해 공백을 추가하거나 구분선(---) 길이를 변경하지 않는다.
• 린트 경고가 발생해도 표 포맷은 작성자가 입력한 그대로 유지한다.

---

문체

~다. 또는 명사형 종결

서술은 ~다.로 끝내거나 명사형으로 끝낸다. ~입니다, ~합니다, ~요, ~습니다 형식은 사용하지 않는다.

# 잘못된 예
이 기능은 데이터를 처리합니다.

# 올바른 예
이 기능은 데이터를 처리한다.
이 기능의 역할: 데이터 처리.

문장 길이와 리스트

본문 문장은 ~다.로 끝낸다. 한 단락에는 본문 최대한 1문장만 작성하고, 세부 사항은 대시(-) 리스트로 분리한다. 대시 리스트 항목은 ~다.가 아닌 명사형으로 끝낸다.

2문장이 이어지는 경우 다음 기준으로 처리한다.

• 두 문장이 하나의 개념이면 1문장으로 합침
• 후반 문장이 부연·이유·결과이면 리스트 항목으로 분리

# 올바른 예
Mockito는 Java 단위 테스트 작성을 돕는 모킹 프레임워크로, 실제 의존 객체 대신 가짜 객체를 생성하고 제어하는 기능을 제공한다.

- 테스트 환경 격리: 외부 요인에 영향 없이 테스트 대상 로직에만 집중할 수 있도록 지원
- 행동 제어 및 검증: 원하는 상황을 시뮬레이션하고 메서드 호출 여부를 검증하는 기능 제공
- 가독성 높은 테스트: BDD 스타일을 지원하여 테스트 코드의 의도를 명확하게 표현

# 잘못된 예 1 (길어지는 문장을 리스트로 분리하지 않은 경우)
Mockito는 Java 단위 테스트 작성을 돕는 모킹 프레임워크로, 외부 요인에 영향 없이 테스트 대상 로직에만 집중할 수 있도록 테스트 환경을 격리하고, 원하는 상황을 시뮬레이션하거나 메서드 호출 여부를 검증하는 기능을 제공하며, BDD 스타일을 지원하여 테스트 코드의 의도를 명확하게 표현할 수 있도록 지원한다.

# 잘못된 예 2 (2문장이 이어지는 경우)
execute 단계에서 Critic을 호출하지 않는 것은 의도적인 설계다.
태스크 단위로 매번 판정하면 오버헤드가 크고, review 단계에서 일괄 판정하는 것이 더 효과적이다.

# 올바른 예 2 (후반 문장을 리스트로 분리)
execute 단계에서 Critic을 호출하지 않는 것은 의도적인 설계다.

- 태스크 단위로 매번 판정하면 오버헤드가 큼
- 전체 diff를 한 번에 보는 review 단계에서 일괄 판정하는 것이 더 효과적

단계·절차 서술 (용어 제목 + 하위 대시)

여러 단계로 이어지는 동작·흐름·절차를 설명할 때는 한 줄에 설명을 욱여넣지 않는다. 각 단계는 핵심 용어를 제목으로 두고, 부연이 필요할 때만 하위 대시(-)로 분리한다. 단어만으로 충분한 단계는 하위 대시 없이 제목 한 줄로 끝낸다.

# 잘못된 예 (한 줄에 용어 + 긴 설명을 전부 결합)
1. 관심 이벤트 등록: 가상 스레드가 외부 연동을 시작하면 소켓을 논블로킹 모드로 전환하고 완료 통지를 받도록 OS 이벤트 알림 메커니즘에 등록

# 올바른 예 (용어 제목 + 하위 대시 부연)
1. 관심 이벤트 등록 (readiness)
    - 외부 연동 시작 시 해당 소켓을 논블로킹 모드로 전환
    - 완료 통지를 받도록 OS 이벤트 알림 메커니즘(epoll/kqueue/IOCP)에 등록
2. 언마운트
    - 캐리어 스레드에서 내려와 멈춤
3. unpark

---

AI체 / 기계적 문체 회피

문법은 맞지만 사람이 쓴 글처럼 읽히지 않는 문체를 경계한다. 이런 문장은 정보를 더하지 않으면서 분량만 늘리고, 글 전체를 평면적으로 만든다.

거창한 도입·빈 강조어

도입부에서 주제의 중요성을 추상적으로 부풀리지 않는다. 무엇이 문제이고 무엇을 다루는지 바로 진술한다.

다음 표현은 대부분 알맹이 없는 강조이므로 구체적 진술로 대체한다.

• ~를 좌우한다, ~를 결정한다, ~에서 비롯된다, 결정적인 역할을 한다
• 핵심은 ~에 있다, 가장 ~한 순간/시점이다
• ~라는 점에 주목할 필요가 있다, 반드시 이해해야 한다

# 잘못된 예 (무엇이 달라지는지 없이 중요성만 부풀림)
어떤 프로토콜을 선택하는지가 시스템의 성능과 안정성을 좌우한다.

# 올바른 예 (구체적으로 무엇이 달라지는지 진술)
어떤 프로토콜을 쓰는지에 따라 직렬화 비용과 결합도가 달라진다.

클리셰 비유 금지

양날의 검, 진가를 발휘한다, 빙산의 일각, 두 마리 토끼 같은 상투적 비유는 사용하지 않는다. 비유 없이 동작이나 결과를 직접 서술한다.

# 잘못된 예
재시도는 잘못 쓰면 장애를 키우는 양날의 검이다.

# 올바른 예
잘못 설계한 재시도는 회복을 돕기는커녕 부하를 키워 장애를 가속한다.

마무리 문장: 되풀이면 삭제

마무리 문장 자체를 금지하는 것이 아니라, 앞 내용을 말만 바꿔 되풀이하는 문장을 금지한다. 판단은 삭제 테스트로 한다.

• 그 문장을 지웠을 때 독자가 잃는 정보가 없으면 되풀이이므로 삭제
• 판단 기준·트레이드오프·다음 단계·예외처럼 새 정보를 더할 때만 남김

# 잘못된 예 (앞 리스트를 말만 바꿔 되풀이 — 지워도 잃는 정보 없음)
- 즉시 롤백: 트래픽을 되돌리기만 하면 복구
- 인프라 비용: 두 환경 동시 유지

이처럼 Blue-Green은 롤백이 빠르지만 비용이 든다는 장단점이 있다.

# 올바른 예 (되풀이 대신 '언제 쓰는가'라는 새 정보를 더함)
- 즉시 롤백: 트래픽을 되돌리기만 하면 복구
- 인프라 비용: 두 환경 동시 유지

따라서 롤백 속도가 비용보다 중요한 결제·인증 서비스에 적합하다.

기계적 병렬 리듬 경계

모든 리스트 항목을 똑같은 X하여 Y하고 Z한다 구문으로 맞추면 글이 합성된 느낌을 준다. 항목마다 길이와 구조를 자연스럽게 달리하고, 억지로 운율을 맞추지 않는다.

---

구조

헤더 중심 구성

문서는 # 헤더를 기준으로 의미 단위를 나눈다. 산문형으로 이어지는 긴 단락 대신, 헤더와 짧은 설명의 조합으로 구성한다. 하나의 섹션 안에서 논점이 여러 개로 갈리면, ### 소제목을 적극적으로 추가하여 각 논점을 분리한다.

# 올바른 구조 예시

## 개념

설명 텍스트.

## 동작 원리

단계별 설명.

### 세부 항목

세부 내용.

서머리·아웃라인은 참고용

만약 요약이나 아웃라인이 제공된다면 구성 힌트로만 활용한다. 그 구조를 그대로 따르는 것이 아니라, 참고하는 수준으로 사용한다.

---

팩트 검증

검증되지 않은 내용 금지

확실하지 않은 내용은 작성하지 않는다. 다음 순서로 검증 후 작성한다.

1. 공식 문서 확인 (언어·프레임워크·툴의 공식 사이트)
2. 웹 검색으로 최신 정보 확인
3. 검증 불가한 내용은 작성 범위에서 제외하거나 다시 질의

버전·수치·동작 방식 등 세부 사항은 특히 주의한다.

---

심층 지식 통합

면접·실무 수준 지식을 흐름에 녹이기

면접이나 실무에서 중요한 지식은 별도 섹션으로 분리하는 것보단, 개념 설명 흐름 안에서 자연스럽게 언급한다. 단순한 기능 요약을 넘어 **"내부적으로 왜 그렇게 설계되었는가"**에 대한 공학적 근거를 제시한다.

# 잘못된 예
## 트랜잭션 격리 수준

격리 수준에는 READ COMMITTED, REPEATABLE READ 등이 있다.

### 면접 팁
면접에서는 각 격리 수준과 발생 가능한 이상 현상을 함께 설명하는 것이 좋다.

---

# 올바른 예
## 트랜잭션 격리 수준

격리 수준은 동시 접근 시 발생하는 이상 현상과 직결된다.
READ COMMITTED는 Dirty Read를 방지하지만 Non-Repeatable Read가 발생할 수 있고,
MySQL InnoDB의 기본값인 REPEATABLE READ는 갭 락으로 Phantom Read까지 방지한다.

내부 메커니즘(Internal Mechanism) 중심 서술

단순히 "결과적으로 무엇을 보장한다"는 식의 결과 중심 서술보다는, 시스템 내부에서 일어나는 물리적/논리적 변화를 구체적으로 다룬다.

• 컴파일/파싱 레이어: AST(추상 구문 트리)의 구조적 고정, 심볼 테이블 매핑, 최적화 단계의 차이를 언급한다.
• 네트워크/프로토콜 레이어: 데이터 전송 방식(바이너리 vs 텍스트 프로토콜), 패킷의 구조, 타입 바인딩 메커니즘을 포함한다.
• 메모리/저장소 레이어: 버퍼 풀의 페이지 변화, 로그(Redo/Undo) 기록 방식, 인덱스 리프 노드의 물리적 레이아웃 등을 연관 지어 설명한다.

---

시각적 요소 활용 (Mermaid & Table)

다이어그램이 텍스트 설명보다 이해에 실질적으로 도움이 되는 경우에만 사용한다. 모든 문서에 무조건 삽입하지 않는다. 단순 텍스트 설명보다 시각적 요소가 이해에 실질적으로 도움이 되는 경우 적극적으로 사용한다. 글이 지나치게 텍스트 위주로 흘러가 지루해지지 않도록, 적절한 위치에 예시 코드, 다이어그램, 표를 배치하여 콘텐츠의 완결성과 재미를 높인다.

• Mermaid Layout: 다이어그램 흐름은 반드시 위에서 아래로 향하는 수직 방향(direction TB)을 기본으로 한다. (블로그 렌더링 시 좌우 방향은 가독성이 떨어질 수 있음)
• Mermaid Styling: 노드에 배경색(fill)을 지정할 경우, 다크 테마에서의 가독성을 위해 반드시 명시적인 글자색(color)을 함께 지정한다. (예: classDef point fill:#f96,color:#000)
• Mermaid Node Text: 노드 내 텍스트는 불필요한 영어 대신 한글을 우선 사용한다. 단, 기술 용어(Knee Point 등)는 한글과 영문을 병기하거나 적절히 혼용한다.
• HTML 사용 금지: 본문 및 Mermaid 다이어그램 내에 <b>, <div>와 같은 HTML 태그를 절대 사용하지 않으며, 순수 마크다운 및 Mermaid 문법만 사용한다. "볼드 사용 금지" 규칙은 다이어그램 내부에도 동일하게 적용된다.
• Table: 개념 비교, 용어 정의, 상태값 설명 등 정형화된 정보를 전달할 때 사용한다. 모든 셀은 가운데 정렬(:---:)로 작성한다.

---

콘텐츠 보존 및 강화

기존 내용 누락 금지

지시가 있거나 문서를 보강(enhance)하거나 재작성할 때, 기존에 포함되어 있던 기술적 상세 내용이나 데이터가 누락되지 않도록 주의한다. 구조를 변경하더라도 정보의 총량은 유지하거나 늘려야 하며, 단순화를 이유로 구체적인 수치, 지표, 의사결정 가이드를 삭제하지 않는다.

---

기존 문서 수정 시

기존 문서를 수정할 때는 이 컨벤션을 완벽히 준수한다. 수정 범위가 일부라도, 해당 문서 전체가 컨벤션에 맞는지 함께 확인한다.

체크리스트:

• 볼드(**) 없음
• 문체가 ~다. 또는 명사형
• 헤더 단위로 의미 구분 (논점이 여러 개면 ### 소제목 추가)
• 한 단락에 본문 1문장 + 리스트 (2문장 이상 연속 금지)
• 검증된 내용만 포함
• AI체 없음 (빈 강조어·클리셰 비유·중복 마무리·기계적 병렬)