언내레이트(Unnarrate)
unslop의 동반 스킬입니다. unslop은 AI 문체가 어떻게 들리는지 개선하는 반면, 이 스킬은 아예 존재해서는 안 될 텍스트, 즉 메타 주석 — 산출물 자체를 그 대상 독자에게 서술하는 글 — 을 삭제합니다. 진행률 표시줄은 이미 진행 상황을 알리는데, 그 옆에 '진행률이 표시됩니다'라는 텍스트는 중복된 두 번째 표지입니다. 에이전트는 사고 과정을 닿는 모든 표면에 서술하기 때문에 이런 텍스트를 끊임없이 생성합니다.
삭제 테스트
다음 내용만 포함된 문장, 레이블, 주석은 삭제하십시오:
- 자신이 속한 산출물에 대한 설명("이 섹션에서는...에 대해 설명합니다"),
- 독자가 이미 볼 수 있는 내용(레이블을 다시 설명하는 툴팁, 다음 줄을 다시 설명하는 주석), 또는
- 해당 내용을 생성한 과정(
// 요청에 따라 헬퍼로 추출했습니다).
애매한 경우 두 가지 확인 사항으로 판단합니다:
- 정신적으로 삭제해 보십시오. 독자가 잃는 것이 없다면, 그것은 무연산(no-op) — 무언가 하는 것처럼 보이지만 아무것도 바꾸지 않는 텍스트입니다.
- 이식성. 그 문장이 다른 프로젝트, 다른 PR, 다른 코드 위에 변경 없이 나타날 수 있다면, 이 프로젝트에 대해 아무것도 말해주지 않습니다. 삭제하십시오.
표면별 삭제 대상
UI 사본
- 인터페이스가 이미 수행하는 동작을 설명하는 사본: "설치 중 진행률이 표시됩니다", "로딩 중 스피너가 나타납니다", "목록이 자동으로 업데이트됩니다". 위젯 자체가 표지이므로, 언어적 표지를 추가하지 마십시오.
- 눈에 보이는 스피너 옆에 "로딩 중..." 텍스트; "파일이 성공적으로 업로드되었습니다" → "파일 업로드됨".
- 레이블을 다시 설명하는 툴팁 및 도움말 텍스트: 필드 "출생 도시", 팁 "출생한 도시를 입력하세요".
- 위치 서술: "아래 버튼을 클릭하여 제출하세요", "드롭다운에서 옵션을 선택하세요".
- 모든 컨트롤을 나열하는 대신 하나의 명확하지 않은 동작만 가리키는 온보딩/코치마크 사본.
- 접근성 중복:
<button>에aria-label="제출 버튼",alt="차트 이미지"(스크린 리더는 이미 역할을 알려줍니다).
문서 및 README
- "이 문서에서는...에 대해 설명합니다", "이 가이드에서는...", "X 문서에 오신 것을 환영합니다". 내용으로 바로 시작하십시오.
- 뒤따르는 섹션만 나열하는 개요 섹션; 페이지 내용을 다시 설명하는 마무리 "요약" 문단.
- 시그니처를 다시 설명하는 독스트링(
get_user(id)— "아이디로 사용자 가져오기");<summary>X를 가져오거나 설정합니다</summary>. PEP 257이 이를 명시적으로 금지합니다. - 예제 위에 "다음 예제는...을 보여줍니다"; 인접한 코드 블록을 다시 설명하는 문장.
- 어떤 프로젝트에도 적용될 수 있는 기능 목록 및 섹션 소개.
코드 주석
- 다음 줄을 다시 설명:
// React 임포트,// 값 반환,// 항목 반복. - 섹션 배너:
// ===== 헬퍼 =====,// --- 3단계: 유효성 검사 ---. - 계획 및 단계 서술:
// 2단계: 리팩터링,// 새로 생성된 Foo 모델 사용. - 변경 내역 서술:
// useState에서 useReducer로 변경됨,// 이전 핸들러 제거됨. Git 히스토리가 이 정보를 보관합니다. - 미래의 독자 대신 리뷰어에게 전달하는 주석:
// 참고: 이 동작은 그대로 유지했습니다.
커밋 및 PR
- diff를 파일별로 다시 설명하는 목록; "이 PR은...을 추가합니다" 뒤에 제목이 그대로 따라옴.
- 반복으로 채워진 템플릿 섹션; "테스트 계획: 테스트 실행"(구체적인 내용 없음).
- 노력 서술: "포괄적인 리팩터링", "하위 호환성을 신중하게 유지했습니다". 리뷰어가 확인할 수 있는 사실을 명시하십시오.
유지 — 서술하는 모든 것이 무연산은 아닙니다
- 실시간 서술은 표지이지만, 정적 서술은 징후입니다. 에이전트가 작업 중 "의존성 설치 중…"을 스트리밍하는 것은 실제 피드백입니다. 그 피드백이 존재한다는 것을 설명하는 사본이 안티패턴입니다.
- '이유' 주석은 유지합니다: 근거, 불변 조건, 명확하지 않은 동작에 대한 경고, 이슈 및 장애 링크. 이 규칙은 주석 자체를 삭제하는 것이 아니라 반복을 삭제하는 것입니다 — 주변 코드의 주석 밀도를 따르십시오.
- 표면이 표시할 수 없는 정보를 전달하는 지시사항은 유지합니다: 형식("YYYY-MM-DD"), 제약 조건("8자 이상"), 부작용("이렇게 하면 팀에 이메일이 발송됩니다"), 되돌릴 수 없음 경고.
- 실제 대체 텍스트는 유지합니다. "이미지..." 접두사는 삭제하고, 이미지가 보여주는 내용에 대한 설명은 유지합니다.
- 추적 링크가 있는 TODO는 유지합니다; 링크 없는
// TODO: 개선 필요는 삭제합니다.
적용 방법
- 변경된 표면을 위 패턴에 대해 훑습니다. 삭제하십시오. 다시 쓰지 마십시오 — 대부분의 적중 항목은 대체가 필요하지 않습니다.
- 삭제로 인해 실제 결함이 발생한 경우, 서술이 아닌 산출물 자체를 수정하십시오(더 명확한 레이블, 자명한 컨트롤).
- 그런 다음 남은 내용에 unslop을 실행합니다.
reference/terminology.md는 현상을 커뮤니티별 용어(메타담론, 해피톡, 자명한 주석, 무연산)와 출처로 명명하여, 체크리스트를 인용하거나 확장할 때 사용할 수 있도록 합니다.