git-writinglisted

# Git Writing — 사람이 읽는 PR·이슈·커밋 ## 이 스킬이 다루는 것 | 상황 | 담당 | |---|---| | **내가 올리는 PR의 제목·본문** | **이 스킬** | | **이슈 작성·수정** | **이 스킬** | | **커밋 메시지** | **이 스킬** (전역 규칙 — 한국어, Co-Authored-By 금지 — 위에 얹힌다) | | 팀원이 올린 PR을 리뷰 | `pr-review-loop` | | 커밋·PR 직후 이해도 확인 | `senior-mentor` | 트리거를 나눈 이유: 같은 시점을 두고 스킬이 경합하면 발동 신뢰도가 떨어진다. PR 생성 시점에는 이 스킬(본문)과 `senior-mentor`(이해도)가 **둘 다** 걸릴 수 있고, 서로 배타가 아니다. ## 전제 — 구조는 문제가 아니다 이 사용자의 레포들에서 PR·이슈의 섹션 골격은 이미 잘 작동한다 (PR: 개요/주요 변경/검증/리뷰 포인트/남긴 것 · 이슈: 배경/실측/해결 방향/완료 조건). **골격을 갈아엎거나 새 템플릿을 강제하지 마라.** 이 스킬이 고치는 것은 **문장 안에서 일어나는 일**이다. 실제 산출물(팀 게임 프로젝트의 PR들, 그래픽 툴 플러그인의 이슈들)에서 관찰된 문제는 매체를 가리지 않고 같다: 1. 한 문장에 결정 + 근거 + 반사실("~였다면 ~로 남습니다")을 전부 욱여넣은 고밀도 문장 2. `계약③`, `ADR-2`, `[G6]` 같은 내부 참조 코드와 "슬루", "그리디 홀드" 같은 전문용어가 설명 없이 등장 3. 문서마다, 심지어 한 문서 안에서 어미가 섞임 ## 독자를 그려라 읽는 사람은 소규모 팀의 팀원이다. 리뷰어이거나, 이 변경·이슈 위에 다음 작업을 쌓을 사람이다. 이 글은 분석 보고서가 아니라 **팀원이 한 번 읽고 다음 행동(리뷰 시작, 작업 착수, 판단)에 들어갈 수 있는 작업 문서**다. 문장이 완결적이고 정확해도, 읽는 사람이 두 번 읽어야 하면 실패다. ## 공통 규칙 — 모든 매체에 적용 ### 1. 한 문장에는 하나의 정보 무엇을 했는지(또는 무엇이 문제인지) 한 문장. 왜 그런지는 **다음 문장**. 대안이 왜 아닌지는 필요할 때만 그다음 문장. 이 셋을 대시(—)와 쉼표로 한 문장에 이으면, 정보는 보존되지만 읽기는 무너진다. 실제 PR에서 관찰된 패턴을 재구성한 예시: **전 (한 호흡에 결정·이유·계약 노출까지):** > `QuestLogWidget`은 자체 `bCompleted` 플래그를 버리고 표시 전용으로 전환, 완료 여부는 매번 QuestState에 질의. 위젯 로컬 상태는 레벨 전환·세이브에서 사라지고, Reward(보상 지급)·Dialogue(`HasQuestDone` 조건)가 같은 상태를 읽어야 해서 공유 계약③으로 노출했다. **후 (문장마다 정보 하나, 서술어까지 완결):** > `QuestLogWidget`은 이제 표시만 담당합니다. 완료 여부는 매번 QuestState에 물어봅니다. 위젯이 직접 들고 있던 `bCompleted`