Git Writing — 사람이 읽는 PR·이슈·커밋

이 스킬이 다루는 것

트리거를 나눈 이유: 같은 시점을 두고 스킬이 경합하면 발동 신뢰도가 떨어진다. PR 생성 시점에는 이 스킬(본문)과 senior-mentor(이해도)가 둘 다 걸릴 수 있고, 서로 배타가 아니다.

전제 — 골격은 두고, 펼칠 것만 고른다

이 사용자의 레포들에서 PR·이슈의 섹션 골격은 이미 잘 작동한다 (PR: 개요/주요 변경/검증/리뷰 포인트/남긴 것 · 이슈: 배경/실측/해결 방향/완료 조건). 섹션 이름과 순서는 기존 것을 그대로 쓰고, 새 섹션을 만들지 마라. 검증 절만은 예외로, 없으면 만든다(아래 PR 절). 이 스킬이 고치는 것은 두 가지다. 하나는 문장 안에서 일어나는 일이고, 다른 하나는 그 골격 중 무엇을 펼쳐 두고 무엇을 접는가다(아래 "펼칠 것과 접을 것").

형식 규칙이 서로 겹치면 아래 순서로 따른다.

1. 팀이 정한 형식 — 레포의 PR·이슈 템플릿, 프로젝트 CLAUDE.md의 PR 규칙, 팀 결정
2. 아래 "펼칠 것과 접을 것"
3. 기존 PR·이슈들의 섹션 구성

팀 형식이 있어도 접기는 그 안에서 적용한다. 템플릿 섹션을 "상세" 접힘 안에 넣고 첫 줄만 위에 둔다. 리뷰어가 직접 체크하는 체크리스트는 팀원에게 하는 요청이라 접지 않는다.

원작성자 실측에서 문장 규칙을 지킨 뒤에도 팀원들이 본문을 읽지 않았고, 그때 PR 한 건은 평균 50문장을 넘었다.

실제 산출물(팀 게임 프로젝트의 PR들, 그래픽 툴 플러그인의 이슈들)에서 관찰된 문제는 매체를 가리지 않고 같다:

1. 한 문장에 결정 + 근거 + 반사실("~였다면 ~로 남습니다")을 전부 욱여넣은 고밀도 문장
2. 계약③, ADR-2, [G6] 같은 내부 참조 코드와 "슬루", "그리디 홀드" 같은 전문용어가 설명 없이 등장
3. 문서마다, 심지어 한 문서 안에서 어미가 섞임

독자를 그려라

읽는 사람은 소규모 팀의 팀원이다. 리뷰어이거나, 이 변경·이슈 위에 다음 작업을 쌓을 사람이다. 이 글은 분석 보고서가 아니라 팀원이 한 번 읽고 다음 행동(리뷰 시작, 작업 착수, 판단)에 들어갈 수 있는 작업 문서다. 문장이 완결적이고 정확해도, 읽는 사람이 두 번 읽어야 하면 실패다.

팀원은 알림과 목록에서 제목과 본문 첫 줄을 보고, 본문을 열어도 펼쳐진 부분만 읽는다. 접힌 부분의 독자는 리뷰하려고 펼친 사람과 완료 조건을 대조하는 에이전트다. 에이전트는 마크다운 원문을 읽으므로 접어도 에이전트 쪽 비용은 없다.

공통 규칙 — 모든 매체에 적용

1. 한 문장에는 하나의 정보

무엇을 했는지(또는 무엇이 문제인지) 한 문장. 왜 그런지는 다음 문장. 대안이 왜 아닌지는 필요할 때만 그다음 문장. 이 셋을 대시(—)와 쉼표로 한 문장에 이으면, 정보는 보존되지만 읽기는 무너진다.

실제 PR에서 관찰된 패턴을 재구성한 예시:

전 (한 호흡에 결정·이유·계약 노출까지):

QuestLogWidget은 자체 bCompleted 플래그를 버리고 표시 전용으로 전환, 완료 여부는 매번 QuestState에 질의. 위젯 로컬 상태는 레벨 전환·세이브에서 사라지고, Reward(보상 지급)·Dialogue(HasQuestDone 조건)가 같은 상태를 읽어야 해서 공유 계약③으로 노출했다.

후 (문장마다 정보 하나, 서술어까지 완결):

QuestLogWidget은 이제 표시만 담당합니다. 완료 여부는 매번 QuestState에 물어봅니다. 위젯이 직접 들고 있던 bCompleted 플래그는 레벨 전환이나 세이브에서 사라지는 값이라 버렸습니다. Reward와 Dialogue도 같은 완료 상태를 읽어야 해서, 조회 함수들을 공유 계약③(위젯–상태 간 공유 API 규약)으로 노출했습니다.

1-b. 쪼갠 문장은 연결어미로 다시 잇는다

규칙 1로 정보를 나눈 뒤, 인접한 두 문장이 인과·역접·조건 관계면 연결어미(-아서, -라서, -지만, -는데, -면)로 잇는다. 관계를 "그래서", "다만" 같은 접속부사로 문장 밖에서 되붙이지 말고 어미 안에 넣어라. 한국어는 논리 관계를 연결어미가 나르기 때문에, 그 자리가 비면 짧은 단정문이 줄지어 서고 읽는 사람은 관계를 스스로 채워 넣어야 한다. 위 "후" 예시가 읽히는 이유가 그것이다 — 셋째·넷째 문장이 "-라", "-해서"로 이어져 있고 앞 두 문장과 길이가 다르다. 전부 짧으면 아무것도 강조되지 않는다.

주어는 현상이 아니라 행위자로 잡는다. 무너지다·갈라지다·덮다 같은 동사가 손에 잡히면 그 문장에 들어갈 실측이나 호출 순서를 아직 확인하지 않았다는 신호이니, 사실을 찾아 넣으면 동사는 저절로 평범해진다.

❌ 완료 상태가 두 줄기로 갈라집니다. 세이브에서 값이 무너집니다. ⭕ 위젯과 QuestState가 각자 완료 여부를 들고 있어서, 세이브 직렬화가 위젯 쪽 bCompleted를 포함하지 않으면 로드 뒤 두 값이 어긋납니다.

2. 문장을 끝까지 써라

"~로 전환," "~에 질의." 같은 서술어 생략체를 쓰지 마라. 명사 뭉치("중복·잔량 판정을 상태 소유자가 최종 결정")는 동사로 풀어라. 글자 수를 아끼는 만큼 읽는 사람의 해석 비용이 늘어난다 — 아껴야 하는 것은 글자가 아니라 독자의 시간이다.

비유로 기술적 사실을 대체하지 마라. "범인은 리타겟 정책이 아니었습니다", "쓰레기 회전이 됩니다", "축이 눕는 순간"처럼 비유가 사실의 자리에 서면, 읽는 사람은 무슨 일이 일어났는지 추측해야 한다. 사실을 먼저 쓰고, 비유는 이해를 돕는 자리에만 뒤따르게 해라 — "실제 포말이 공기 섞인 흰 물이라 불투명한 것과 같은 이치입니다"처럼 설명을 마친 뒤 붙는 비유가 그 자리다.

3. 참조 코드·전문용어는 첫 등장에서 풀어준다

계약③, ADR-002, Milestones §3, [G6] 같은 내부 코드와, 팀원이 모를 수 있는 전문용어("히스테리시스", "슬루", "temporal IK")는 쓰는 사람 머릿속에는 선명하지만 읽는 사람은 찾아봐야 한다. 첫 등장에서 괄호 한 줄로 무엇인지 적어라. 두 번째부터는 코드·용어만 써도 된다.

공유 계약③(위젯–상태 간 공유 API 규약)으로 노출했습니다. … 계약③의 시그니처는 그대로입니다.

문서 링크가 가능하면 링크가 더 좋다. 단, 링크가 있어도 한 줄 설명은 남긴다 — 링크를 타는 것도 비용이다.

설명은 확인한 것만 붙여라. 문서나 코드에서 뜻을 확인하지 못한 용어는 설명을 지어 붙이지 말고 원문 표현 그대로 둬라. 그럴듯하게 틀린 설명은 설명 없는 코드보다 해롭다 — 읽는 사람이 확인 없이 틀린 이해를 갖게 된다. (실측 사례: 이슈 재작성 테스트에서 bone_swing에 "팔뚝 평행 스윙"이라는 지어낸 설명이 붙었다. 실제로는 세로 본 swing이다.)

단, "확인 못 했으니 그냥 둔다"로 끝내지 마라. 본문에 쓸 용어는 쓰기 전에 코드·문서에서 뜻을 확인하는 것이 기본 순서다. 확인이 안 되면 먼저 그 용어를 쓰지 않고 풀어 쓸 수 있는지 본다. 그래도 써야 하면 docs/rig.md §21 같은 출처를 함께 남긴다 — 설명도 출처도 없는 용어가 가장 나쁘다.

수식·기호는 결과를 먼저 쓰고 표기를 뒤에 붙인다. (2π−θ, −a)를 그대로 던지지 말고 그 표기가 무엇을 뜻하는지 먼저 쓴다.

❌ 축 연속성 규칙은 내적이 음수면 (2π−θ, −a)로 바꿉니다. ⭕ 축 연속성 규칙은 같은 회전을 반대 방향으로 도는 표현(2π−θ만큼 축 −a 둘레로)으로 바꿉니다.

혼자 쓰고 혼자 머지하는 레포일수록 이 규칙을 세게 적용한다. 되묻는 사람이 없어서 무설명이 교정되지 않고, 몇 주 뒤 자기 자신이 못 읽는 문서가 된다. 독자를 "이 코드를 안 본 팀원"으로 계속 가정해라.

4. 근거는 선별한다

모든 결정에 근거와 반사실을 달면 본문 전체의 밀도가 올라가 정작 중요한 근거가 묻힌다. 기준은 전역 문서 작성 원칙과 같다: 이 근거가 읽는 사람의 행동을 바꾸는가.

• 읽는 사람이 뒤집을 수 있고 지금 뒤집는 게 싼 결정 → 근거를 충분히. PR이면 펼친 부분에 의도 한 줄을 두고, 근거 전문은 리뷰 포인트 섹션에 둔다
• 이미 확정된 결정의 실행, 사소한 구현 선택 → 결정만 적는다. 이유가 궁금하면 물어볼 것이다
• 실제 이유를 모르면 지어내지 마라. 근거 없는 결정은 근거 없이 적는 것이 정직하다

5. 어미는 합쇼체, 팀원 지칭은 이름+님

• 팀원에게 보내는 글이므로 기본값은 **합쇼체(-습니다)**다. 한 문서 안에서 섞지 말고, 문서 사이에서도 유지해라.
• 팀원을 지칭할 때는 이름 + 님으로 쓴다 ("민수님이 볼 부분"). 이름만 부르는 반말 지칭("민수가 볼 부분")을 쓰지 마라.
• PR·이슈·커밋·코멘트는 계정 주인 명의로 올라가므로 그 사람을 이름+님으로 지칭하지 않는다. 결정은 날짜만 적고, 확인은 주어 없이 쓴다.
• (팀이 다른 관례를 정하면 그것을 따른다 — 중요한 것은 일관성이다.)

6. 굵은 글씨는 놓치면 사고 나는 것에만

문단마다 균일하게 볼드가 있으면 아무것도 강조되지 않는다. 읽는 사람이 놓쳤을 때 실제로 문제가 되는 것 — 머지 전 확인 필수, 깨진 상태로 들어가는 것, 되돌리기 어려운 결정 — 에만 써라.

펼칠 것과 접을 것 — PR·이슈·코멘트

본문은 펼친 부분과 <details>로 접은 부분으로 나눈다. 기준은 규칙 4와 같다. 팀원이 이걸 몰라도 다음 행동이 바뀌지 않으면 접는다. 에이전트가 코드에서 확인할 수 있는 내용인지는 기준이 아니다. 공유 함수 시그니처 변경은 코드만 봐도 확인되지만, 그 함수를 부르는 팀원은 알아야 한다.

펼친 부분에는 아래만 둔다.

1. 첫 줄 — 팀원에게 필요한 것. "리뷰 부탁드립니다", "에디터에서 X를 확인해 주세요", "공유만 합니다(확인 불필요)" 중 하나로 시작한다. 알림과 목록에 보이는 것이 제목과 이 줄이다.
2. 게임·에디터에서 보이는 변화. 패치노트처럼 쓴다. 판정 질문은 "게임이나 에디터를 연 팀원이 알아챌 변화인가"다. 동작 변화가 없는 리팩터링이면 "동작 변화 없음" 한 줄로 끝난다.
3. 팀원 작업에 닿는 변경. 공유 함수·데이터 형식·세이브 형식·에셋 경로처럼, 그 위에서 작업하는 팀원이 모르면 충돌하거나 깨지는 것이다.
4. 의도 한 줄. 규칙 4가 근거를 충분히 달라는 결정, 곧 팀원이 뒤집을 수 있는 결정에만 붙인다. 긴 근거는 접힌 부분에 둔다.

아래는 접지 않는다. 접힌 내용은 사람에게는 없는 것과 같아서, 길어도 펼친 부분에 둔다.

• 규칙 6의 대상: 머지 전 확인 필수, 깨진 상태로 들어가는 것, 되돌리기 어려운 결정
• 완료 조건에 필요한데 실행하지 않은 검증
• 팀원에게 확인·판단·후속 작업을 요청하는 문장

나머지는 <summary>상세</summary> 접힘 하나에 넣고, 기존 골격의 섹션은 그 안에서 그대로 쓴다. 검증 증빙 블록은 이 접힘 안에 한 번 더 접혀 들어간다. 짧은 코멘트는 첫 줄(결과와 팀원에게 필요한 것)과 맨 끝의 증빙만 두고 "상세" 접힘을 만들지 않는다.

리뷰 부탁드립니다. 머지 전에 에디터에서 퀘스트 로그를 열어 완료된 퀘스트가 맨 아래로 가는지 봐 주세요.

- 퀘스트 로그가 완료된 퀘스트를 목록 맨 아래로 내립니다.
- `QuestState::IsCompleted()`를 `GetStatus()`로 바꿨습니다. 이 함수를 부르는 코드는 같이 고쳐야 합니다.
  의도: "포기" 상태가 다음 작업에 들어와서 bool 하나로는 표현할 수 없습니다.
- **실제 게임 화면의 보상 팝업은 확인하지 않았습니다.** #12 완료 조건 3에 필요합니다.

<details>
<summary>상세</summary>

## 주요 변경
…
## 검증
…(아래 "검증 증빙"의 예시)
## 리뷰 포인트
…

</details>

<summary> 줄 다음과 </details> 앞에 빈 줄이 없으면 GitHub가 안쪽 마크다운을 렌더링하지 않는다.

접힌 부분은 린트만 거친다. 판정자에게 보내지 않고, 목록형 문장과 파일:줄 표기를 써도 된다. 커밋 메시지·코멘트와 같은 대우다. 다만 규칙 3의 "설명은 확인한 것만"과 규칙 4의 "근거를 지어내지 마라"는 그대로 지킨다. 리뷰하려고 펼친 사람은 이 부분을 읽는다.

펼친 부분의 길이는 린트가 센다. 출력 끝에 <details> 밖의 줄 수가 나오는데, 상한은 아직 정하지 않았다. 이 형식으로 올린 PR 중 팀원이 반응한 것들의 줄 수를 보고 정한다.

PR

• 제목: 한 줄만 보고 "무엇이 바뀌는지" 알 수 있어야 한다. GitHub 목록 화면에서 잘리지 않을 길이로. 팀에 굳은 접두 관례(트랙/주차 표기 등)가 있으면 유지한다. 병기(A + B + C)를 세 개 이상 잇지 마라 — 셋 다 중요하면 펼친 부분에서 풀어라.
• 골격: 기존 PR들의 골격(개요/주요 변경/검증/리뷰 포인트/남긴 것)을 따른다. 개요 자리는 펼친 부분이 맡고, 나머지 섹션은 "상세" 접힘 안에 둔다. 해당 없는 섹션은 비워두지 말고 뺀다. 검증 섹션만은 뺄 수 없다 — 레포의 기존 PR 골격에 검증 섹션이 없어도 만든다. 실행·미실행 구분이 들어갈 자리가 거기뿐이고, 체크리스트만 있던 레포에서 이 스킬을 쓴 PR이 검증 절 없이 올라간 사례가 있다.
• 결과 상태만 쓴다. "처음엔 32px이었다가 64px로" 같은 과정 서술, 시안·문서를 옮겼다는 서술, 문구 출처 논의는 빼고 최종 값만 적는다. 예외는 근거 기록(시안·설계 문서)이 전혀 없는 굵은 구조 결정뿐이고, 그때만 시도 → 문제 → 최종 순으로 적는다.
• 검증 섹션: 리뷰어가 그대로 따라할 수 있게 — 어떤 씬·명령·조작으로 무엇을 보는지까지. 첫 줄에서 팀원에게 확인을 부탁할 때도 같다.
• 검증은 실행한 것과 안 한 것을 나눠 적는다. 실제로 돌린 것은 무엇으로 확인했는지 결과와 함께 적고, 안 돌린 것은 "미실행"으로 명시한다. 예상을 실행 결과처럼 쓰면 리뷰어는 확인된 것으로 믿는다 — "머지 전에 돌려보겠습니다"는 검증이 아니라 계획이다. 실행한 것의 원본 기록은 아래 "검증 증빙"대로 접어 붙인다.

이슈

• 제목은 증상 중심 한 줄. 읽는 사람이 목록에서 제목만 보고 "무슨 문제인지"를 알아야 한다. 원인 분석을 제목에 압축하지 마라 — 원인은 본문 몫이다.
• 골격: 기존 이슈들의 골격(배경 / 지금 상태·실측 / 해결 방향 / 완료 조건)을 따른다. 이 골격 자체는 좋다. 이슈는 아직 바뀐 것이 없어서 패치노트로 쓸 내용이 없다. 펼친 부분은 첫 줄(팀원에게 필요한 것), 증상, 완료 조건이고, 실측·원인·해결 방향은 "상세" 접힘 안에 둔다. 해결 방향에서 팀원이 정해야 할 것이 있으면 질문 한 줄로 펼친 부분에 둔다.
• 정리형 이슈(점검 목록 등)는 결과 문장으로 시작한다. "점검 목록을 정리했습니다"처럼 쓰고, 목록을 어디서 가져왔는지는 적지 않는다. 대조표 대신 항목 전체를 체크리스트 하나로 묶고, 항목 뒤에 담당 이슈 번호를 붙인다.
• 본문 첫 문단은 코드를 안 연 사람도 읽혀야 한다. 파일:라인 참조는 근거로 붙이되, 문장 자체는 참조 없이도 뜻이 통하게 써라. "무엇이 어떻게 잘못 동작하고, 사용자·결과물에는 어떻게 보이는가"를 먼저, 코드 수준 원인은 그다음에.
• 실측이 있으면 실측을 적어라. "고착될 수 있다"보다 "f103~130 사이 28프레임이 동일 회전으로 정지한다"가 낫다. 증상을 설명하는 데 필요한 실측 한 줄만 펼친 부분에 두고, 나머지는 접힘 안에 둔다. 측정·재현을 실제로 돌렸으면 그 원본 기록은 아래 "검증 증빙"대로 실측 절 끝에 접어 붙인다.
• 완료 조건은 확인 가능한 문장으로. "개선된다"가 아니라 "이 구간이 지표에 잡힌다"처럼, 닫을 때 판정할 수 있게 쓴다.

검증 증빙 — 접어서 붙인다

PR·이슈 본문이나 작업 결과 코멘트에 실제로 돌린 테스트·측정이 있으면, 그 원본 기록을 접힌 블록으로 붙인다. 이 블록은 주로 이슈 완료 조건을 대조하는 에이전트가 읽는다. 그런 에이전트는 테스트를 돌린 커밋이 지금 코드와 같은지부터 확인하므로, SHA가 없으면 통과 보고를 지금 코드의 증거로 쓰지 못한다. 무엇이 통과했는지는 검증 절에 문장으로 쓰고, 안 돌린 것은 아래 첫 항목대로 나눠 둔다. 블록은 펼치지 않아도 되게 둔다.

• 실행한 것만 넣는다. 안 돌린 것은 문장으로 남기고 둘로 나눈다. 완료 조건에 필요한데 안 돌린 것은 접힘 밖 펼친 부분에, 범위 밖이라 안 돌린 것은 검증 절에 둔다. 둘이 섞이면 읽는 쪽은 범위 밖 미실행까지 미충족 조건으로 읽는다.

• 항목마다 다섯 칸을 채운다.

  • 커밋: 테스트를 돌린 시점의 HEAD SHA. 그 뒤에 커밋이 더 쌓였으면 그 사실도 적는다.
  • 명령: 그대로 다시 돌릴 수 있는 명령줄.
  • 범위: 어떤 대상·입력으로 돌렸는지. 일부 대상만 돌렸으면 나머지가 빠졌다는 것이 여기서 드러난다.
  • 결과: 출력의 요약 줄을 그대로 옮긴다. 바꿔 쓰지 않는다.
  • 조건: 이 결과가 뒷받침하는 완료 조건(#12 조건 2). 없으면 없음.

  사람이 눈으로 본 판정은 명령 자리에 누가 언제 무엇을 봤는지 쓰고, 결과 자리에 O/X/?를 쓴다. 계정 주인이 본 것이면 누가를 빼고 날짜와 대상만 쓴다(규칙 5).

• 출력은 요약 줄만 옮긴다. 로그 전체를 붙이면 읽는 쪽이 그걸 다 읽어야 한다. 개인 경로·토큰·계정명은 지운다. 이 블록은 린트도 판정자도 보지 않아서 걸러 주는 단계가 없다.
• 린트·판정자 대상이 아니다. 블록 안은 코드 블록이라 prose-lint.py가 건너뛰고, 판정 요청 양식도 이 블록을 판정하지 않는다. 문장 규칙에 맞추려고 출력을 다듬지 않는다.
• 위치. PR은 검증 절 끝, 이슈는 실측 절 끝이고, 둘 다 "상세" 접힘 안이다. 코멘트는 맨 끝에 둔다. 어느 경우든 <summary>검증 증빙</summary>은 빼지 않는다.

아래는 "상세" 접힘 안의 검증 절이다. 완료 조건 3에 필요한 미실행(보상 팝업)은 위 "펼칠 것과 접을 것" 예시처럼 펼친 부분에 있다.

## 검증

pytest 전체와 보상 지급 프로브가 통과했습니다. 세이브 호환성 테스트는 이 PR이 세이브 형식을 바꾸지 않아서 돌리지 않았습니다.

<details>
<summary>검증 증빙</summary>

```
[1] 커밋 a1b2c3d (PR head)
    명령 pytest -q
    범위 전체
    결과 228 passed in 41.20s
    조건 #12 조건 1
[2] 커밋 a1b2c3d (PR head)
    명령 python tools/reward_probe.py --quests all
    범위 퀘스트 14종 × 보상 3종
    결과 42/42 PASS, max_gold_diff=0
    조건 #12 조건 2
[3] 커밋 a1b2c3d (영상 렌더 시점)
    명령 2026-10-04 민수님 화면 판정, 퀘스트 로그 정렬 영상
    범위 퀘스트 3종
    결과 O
    조건 없음
```

</details>

<summary> 다음 빈 줄이 없으면 GitHub가 코드 블록을 렌더링하지 않는다. <summary> 문구는 검증 증빙으로 고정한다. 판정 요청 양식이 이 문구로 블록을 찾는다.

커밋 메시지

전역 규칙(한국어, Co-Authored-By 금지)에 다음을 얹는다:

• 제목 줄은 "무엇을 왜"의 무엇 쪽 한 줄. 목록(git log --oneline)에서 잘리지 않을 길이로, 이 커밋이 코드를 어떻게 바꾸는지가 드러나게.
• 본문이 필요한 커밋(설계 결정이 들어간 것, 이유가 코드에 안 보이는 것)은 빈 줄 하나 띄우고 왜를 문장으로 적는다. 공통 규칙 1~4가 그대로 적용된다.
• 루틴 커밋(오타, 정리, 단순 반영)에 본문을 억지로 달지 마라. 제목 한 줄이면 끝이다.
• 본문이 있는 커밋은 게시 전에 린트를 거친다(아래 "올리기 전 검사" 1). 실측에서 갈라지다·무너지다·조용히 같은 어휘가 몰려 있던 곳은 커밋 본문이었다. PR 본문에는 거의 없었다. 스크립트는 합쇼체·해라체를 모두 센다.

올리기 전 검사 — 린트, 판정자, 자가 검사

작성자는 자기 초안의 리듬을 보지 못한다. 규칙을 쓴 바로 그 문단에서 같은 리듬이 다시 나오는 것이 원작성자 실측으로 확인됐고, 판단형 자가 검사는 그냥 통과한다. 그래서 세는 일은 스크립트가, 판정은 초안을 쓰지 않은 컨텍스트가 한다.

본문은 파일로 쓴다(gh pr create --body-file, gh issue create --body-file, 코멘트는 gh pr comment·gh issue comment --body-file). 그 파일에 대해:

1. 린트. python scripts/prose-lint.py <본문 파일> > <린트 출력 파일>. 걸린 문장을 줄 번호와 함께 인용해 준다. 후보 목록이다. 사실을 정확히 말하는 문장은 걸려도 그대로 두고, 출력 끝의 "펼친 부분 N줄"로 <details> 밖 분량을 본다.
2. 판정자. 초안을 쓰지 않은 컨텍스트에 본문 파일·린트 출력·references/review-request.md를 본문 파일 옆에 복사해 빈칸을 채운 사본을 넘기고 문장 단위 교체안을 받는다. 원본 양식은 고치지 않는다. 작업 중인 모델이 Claude이고 codex 플러그인이 있으면 codex 서브에이전트에게 받는다 — 이 리듬은 Claude 고유의 성향이라 다른 모델이 사각을 공유하지 않는다. 없으면 같은 모델의 서브에이전트다. 판정자는 본문을 다시 쓰지 않는다. 통째로 다시 쓰면 같은 리듬이 돌아온다. 걸린 문장마다 "원문 → 교체안"만 받고, 본 에이전트가 그 교체만 적용한다. 판정자는 <details> 안을 보지 않는다(위 "펼칠 것과 접을 것").
3. 린트 재실행. 교체를 적용한 뒤 한 번 더 돌려 새로 걸린 것이 없는지 본다.

커밋 메시지와 작업 결과 코멘트는 1만 한다. 자동 커밋 규약 아래서 커밋마다, 작업마다 남기는 코멘트마다 판정자를 부르면 무겁고, 두 층에서 실측된 문제는 어휘라 단어 검사로 충분하다.

PostToolUse 훅 pr-body-lint.ps1(배포판 git-writing/hooks/, 선택)을 걸어 두면 PR·이슈·코멘트를 올린 직후 본문 파일에 1을 다시 돌려 걸린 문장을 알려 주고, 본문 파일 없이 올렸으면 그 사실을 알린다. 스킬을 로드하지 않고 올린 세션을 잡으려는 것이다. 걸린 문장이 사실을 정확히 말하면 그대로 두고, 아니면 같은 파일을 고쳐 gh pr edit --body-file로 다시 올린다.

그 뒤 본문을 다시 읽으며 확인한다:

• 본문 첫 줄이 팀원에게 필요한 것(리뷰 요청·확인 요청·공유만)인가
• 펼친 부분(또는 커밋 제목 줄)만 읽은 팀원이 "이게 무슨 일인지" 한 문장으로 말할 수 있는가
• 접지 않는 세 가지(규칙 6 대상, 완료 조건에 필요한 미실행, 팀원에게 하는 요청)가 <details> 안에 들어가 있지 않은가
• 아무 불릿이나 골라 소리 내어 읽었을 때 한 호흡에 끝나는가 — 숨이 차면 문장을 쪼개고, 쪼갠 문장이 인과·역접이면 연결어미로 다시 잇는다(규칙 1-b)
• 참조 코드·전문용어가 설명 없이 처음 등장하는 곳이 없는가
• 펼친 부분에 뜻이 안 풀린 용어가 3개 이상인가 — 그렇다면 그 부분은 코드를 이미 아는 사람만 읽을 수 있는 상태다
• 붙인 설명이 문서·코드에서 실제로 확인한 것인가 — 확인 못 했으면 설명을 빼고 원문 표현으로 되돌린다
• 검증 섹션에 실행하지 않은 항목이 실행한 것처럼 적혀 있지 않은가
• 증빙 블록의 항목마다 커밋 SHA와 조건 칸(없으면 없음)이 채워져 있는가 — 비어 있으면 읽는 쪽이 그 결과를 지금 코드나 완료 조건에 연결하지 못한다
• 어미가 섞이지 않았는가, 팀원 지칭이 이름+님인가
• 계정 주인을 이름으로 지칭한 곳이 없는가 — 이름+님도, 이름만도. 계정 주인이 지훈이면 "지훈 결정(09-29)"은 "결정(2026-09-29)", "지훈 확인"은 "확인했습니다"로 쓴다
• AI 내부 상태값·수사(전역 "보고서·문서 작성 원칙"의 금지 목록)가 없는가
• 도구가 붙인 자동 푸터("Generated with …")가 남아 있지 않은가 — 전역 지침은 팀원에게 가지 않고 이 스킬은 간다

하지 말 것

• 새 섹션을 만들거나 기존 섹션 이름을 바꾸는 것 — 해당 없는 섹션은 뺀다. 펼친 부분의 첫 줄과 목록은 개요 자리를 채우므로 새 섹션으로 치지 않는다
• 근거를 지어내는 것
• 밀도를 낮춘다는 이유로 정보를 삭제하는 것 — 문장을 쪼개는 것이지 내용을 버리는 것이 아니다. 판단이 애매하면 남긴다
• 전역 "보고서·문서 작성 원칙"을 여기 다시 쓰는 것 — 그 원칙은 이 스킬 위에 그대로 얹힌다

성공 기준 · 존재 의의

같은 폴더의 RATIONALE.md에 있다. 여기 옮겨 적지 않는다 — 두 벌이 되면 갈라진다.

RATIONALE.md는 원작성자의 관측 기록이라 배포에 포함되지 않는다. 이 스킬을 새로 받았다면 자기 관측 기록으로 직접 만든다. 그때 ## 재는 것에는 아래 기준을 그대로 옮긴다 — 메커니즘에 딸린 것이라 사람이 바뀌어도 같다:

• 팀원이 본문 첫 줄의 요청(리뷰·확인)에 응답한다
• 팀원이 PR·이슈를 읽고 내용을 되묻는 횟수가 줄어든다
• 사용자가 게시 전에 본문을 손으로 고치는 빈도가 줄어든다 — 수동으로 고친 부분이 다음 규칙 후보다
• 문서 간 문체가 일관된다

사용자가 "이 스킬 의도대로 작동해?" 라고 물으면 그 파일을 읽고 이번 세션과 대조한다.