Communitygithub.com

T0mSIlver/skills

UI 사본, 문서, 코드 주석, 커밋 메시지, PR 설명에서 자기 서술적 메타 주석(자신이 속한 산출물을 설명하거나, 이미 보이는 내용을 반복하거나, 생성 과정을 서술하는 텍스트)을 제거합니다. 해당 표면을 작성하거나 검토할 때, 그리고 문장을 편집하기 전에 적용하세요.

skills란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor, Codex 등)가 생성한 콘텐츠에서 불필요한 메타 주석을 자동으로 식별하고 제거합니다. '언내레이트(Unnarrate)'는 '언슬롭(unslop)'의 동반 스킬로, AI의 어색한 문체를 개선하는 대신 아예 존재해서는 안 될 텍스트를 삭제하는 데 초점을 맞춥니다. 예를 들어 '진행률이 표시됩니다'라는 안내문은 실제 진행률 표시줄이 이미 그 역할을 수행하므로 중복입니다. 에이전트는 사고 과정을 모든 표면에 서술하는 경향이 있어 이런 주석을 끊임없이 생성합니다. 이 스킬은 UI 복사본, 문서, 코드 주석, 커밋 메시지, PR 설명 등에서 패턴 매칭을 통해 메타 주석을 탐지하고 제거하며, 'Why' 주석이나 필수 지시사항 등 유지해야 할 내용은 보존합니다. 참고 문서 `reference/terminology.md`에서 현상을 각 커뮤니티별 용어(메타담론, 해피톡, 자명한 주석, 무연산)로 정의하고 출처를 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/T0mSIlver/skills/tree/HEAD/unnarrate

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

언내레이트(Unnarrate)

unslop의 동반 스킬입니다. unslop은 AI 문체가 어떻게 들리는지 개선하는 반면, 이 스킬은 아예 존재해서는 안 될 텍스트, 즉 메타 주석 — 산출물 자체를 그 대상 독자에게 서술하는 글 — 을 삭제합니다. 진행률 표시줄은 이미 진행 상황을 알리는데, 그 옆에 '진행률이 표시됩니다'라는 텍스트는 중복된 두 번째 표지입니다. 에이전트는 사고 과정을 닿는 모든 표면에 서술하기 때문에 이런 텍스트를 끊임없이 생성합니다.

삭제 테스트

다음 내용만 포함된 문장, 레이블, 주석은 삭제하십시오:

  1. 자신이 속한 산출물에 대한 설명("이 섹션에서는...에 대해 설명합니다"),
  2. 독자가 이미 볼 수 있는 내용(레이블을 다시 설명하는 툴팁, 다음 줄을 다시 설명하는 주석), 또는
  3. 해당 내용을 생성한 과정(// 요청에 따라 헬퍼로 추출했습니다).

애매한 경우 두 가지 확인 사항으로 판단합니다:

  • 정신적으로 삭제해 보십시오. 독자가 잃는 것이 없다면, 그것은 무연산(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: 개선 필요는 삭제합니다.

적용 방법

  1. 변경된 표면을 위 패턴에 대해 훑습니다. 삭제하십시오. 다시 쓰지 마십시오 — 대부분의 적중 항목은 대체가 필요하지 않습니다.
  2. 삭제로 인해 실제 결함이 발생한 경우, 서술이 아닌 산출물 자체를 수정하십시오(더 명확한 레이블, 자명한 컨트롤).
  3. 그런 다음 남은 내용에 unslop을 실행합니다.

reference/terminology.md는 현상을 커뮤니티별 용어(메타담론, 해피톡, 자명한 주석, 무연산)와 출처로 명명하여, 체크리스트를 인용하거나 확장할 때 사용할 수 있도록 합니다.

관련 스킬