ai-tell-cleanup

AI가 생성한 코드나 텍스트에는 사람이 잘 쓰지 않는 패턴이 반복됩니다. 이 스킬은 코드 주석, 커밋 메시지, PR 본문에서 그 패턴을 찾아내고 수정합니다.

Phase 0 — 옵트아웃 확인

스킬 실행 전 가장 먼저 확인합니다:

test -f ~/.claude/.ai-tell-cleanup-disabled

파일이 존재하면 즉시 종료합니다. 아무것도 출력하지 않습니다.

옵트아웃 / 옵트인 방법

사용자가 다음 중 하나를 말하면:

• "ai-tell-cleanup 끄기", "ai 티 정리 꺼", "이 스킬 비활성화", "disable ai-tell-cleanup"

  touch ~/.claude/.ai-tell-cleanup-disabled

  그리고 "ai-tell-cleanup 비활성화됨 — 다시 켜려면 'ai-tell-cleanup 켜기'" 를 출력합니다.

사용자가 다음 중 하나를 말하면:

• "ai-tell-cleanup 켜기", "ai 티 정리 켜", "enable ai-tell-cleanup"

  rm -f ~/.claude/.ai-tell-cleanup-disabled

  그리고 "ai-tell-cleanup 활성화됨" 을 출력합니다.

대상 범위

• 소스 코드 인라인 주석 (//, #, /* */, /** */)
• 커밋 메시지 body
• PR title / body
• SKILL.md, README.md 같은 문서 파일

Phase 1 — Em dash 및 특수 구두점

AI가 가장 자주 남기는 타이포그래픽 패턴입니다.

Grep 패턴:

—|…|"|"

Phase 2 — 코드를 그대로 설명하는 주석

코드 자체가 이미 말하는 내용을 반복하는 주석은 제거합니다.

제거 대상 패턴:

// 사용자를 ID로 조회한다
User user = userRepository.findById(id);

// 결과를 반환한다
return result;

// 리스트를 초기화한다
List<String> items = new ArrayList<>();

판단 기준: 주석을 지워도 코드를 이해하는 데 전혀 지장이 없으면 제거.

Phase 3 — AI 필러 문구

주석이나 문서에서 정보 없이 길이만 늘리는 문구들입니다.

Phase 4 — 과도한 섹션 구분 주석

// =====================
// User Management
// =====================

// --- Validation ---

// ########################################
// Step 1: Initialize
// ########################################

주석을 제거하고 코드 구조 자체로 읽히도록 제안합니다.

Phase 5 — 과도한 docstring / Javadoc

시그니처와 타입이 이미 말하는 내용을 반복하는 @param/@return 나열은 제거합니다. WHY가 없는 docstring은 제거, WHY가 있다면 한 줄로 요약합니다.

Phase 6 — 커밋 메시지 패턴

Phase 7 — PR 본문 패턴

Phase 8 — Emit findings

[<severity>] <category>: <한 줄 요약>
  Where: <파일>:<줄 번호> 또는 커밋/PR 위치
  Original: <원문>
  Fix: <수정안>

Severity 기준:

• fix — 명확한 AI 패턴 (em dash, AI 푸터, 코드 그대로 설명 주석)
• consider — 제거하면 더 깔끔하지만 판단이 필요한 경우

자동 수정 가능한 항목 (em dash, AI 푸터)은 확인 없이 바로 수정합니다. 코드 주석 제거처럼 의도 파악이 필요한 항목은 제안만 합니다.

Non-goals

• 코드 로직은 건드리지 않습니다.
• 테스트 코드의 설명 주석은 기준을 완화합니다.
• 외부 라이브러리 / 서드파티 코드는 스캔 제외합니다.