yonathan-boop/Claude

antislop-code

반-슬롭: AI 코딩 에이전트를 위한 규칙. 코드 주석 스킬

반슬롭 시스템의 일부입니다. 핵심 규칙인 antislop.md와 함께 읽어주세요. 이 스킬은 AI가 생성한 전형적인 (장식적이거나, 자명한 내용을 반복하거나, 딱딱하거나, 큰 소리로 쓰인) 주석을 걸러내고, 실제 정보를 전달하는 주석만 보존합니다. 핵심 규칙 번호를 참조하며, 중복되거나 번호를 다시 매기지 않습니다. 코드 주석을 작성하거나 편집하는 작업을 할 때 이 스킬을 로드하세요.

이 스킬 사용 방법

• 코드 주석을 다루는 작업을 할 때마다 antislop.md와 함께 로드하세요. 핵심 규칙은 메커니즘 (목적 테스트, 세 가지 계층, 전달 게이트)을 제공하고, 이 스킬은 주석에 특화된 깊이를 제공합니다.
• 모든 항목은 동일한 형태를 가집니다: Tell (패턴), Why (슬롭으로 읽히는 이유), Fix (대체할 방법), 그리고 관련 핵심 규칙(R-XX)이 인용됩니다.
• 범위 제한: 이 스킬은 주석만 수정합니다. 실행 코드, 식별자, 임포트, 포맷팅, 들여쓰기, 공백, 제어 흐름, 또는 로직은 절대 수정하지 마세요. 의심스러우면 코드를 그대로 두세요.
• 핵심 규칙의 전달 게이트는 여전히 유효합니다. 이 파일 마지막의 "코드 주석 체크리스트"는 전달 게이트와 함께 실행할 주석 특화 보충 자료입니다.

아무것도 추가하지 않는 주석

장식용 구분선

• Tell: 반복 문자, ALL CAPS 라벨, 또는 섹션 이름 주변에 박스 그리기를 사용한 배너 주석: // ======================= 위에 Authentication, // -------- WORKFLOW --------, 또는 /* ---- ROUTES ---- */ 헤더.
• Why: 장식 자체가 메시지입니다. =나 -로 감싸진 라벨은 "AI가 만들었다"는 신호이며 정보를 추가하지 않고, ALL CAPS는 소리치는 것으로 읽힙니다.
• Fix: 평범한 한 줄로 대체하거나, 라벨이 아무것도 추가하지 않으면 완전히 제거하세요 (R-31).

자명한 내용 반복

• Tell: 다음 줄이나 선언이 이미 보여주는 내용을 반복하는 주석: // Initialize the variable 위에 let count = 0, // User class 위에 class User {}, // Validate user 위에 function validateUser(), 또는 const userAge = 25; // User age is 25.
• Why: 읽는 부담을 두 배로 늘리지만 아무것도 추가하지 않습니다. 코드가 이미 말하고 있고, 주석은 그것을 반복할 뿐입니다.
• Fix: 제거하고 코드 줄은 그대로 두세요.

워크플로 서술

• Tell: 흐름을 단계별로 서술하는 주석: // Step 1: Validate input, // Step 2: Process request, // Step 3: Return response, 또는 // First..., // Next..., // Finally....
• Why: 제어 흐름은 코드 자체에서 볼 수 있습니다. 번호를 매기는 것은 설명이 아니라 체크리스트처럼 읽힙니다.
• Fix: 제거하세요. 흐름이 진정으로 따라가기 어렵다면, 그것은 주석 문제가 아니라 구조 문제입니다.

빈 레이블

• Tell: 뒤에 정보가 없는 일반적인 레이블: // Main logic, // Core logic, // Business logic, // Helper function, // Entry point, // Error handling, 또는 // Note: This is important. / // Important: Please read.
• Why: 레이블은 범주를 이름 짓는 것이지 사실을 말하는 것이 아닙니다. "Main logic"은 독자가 코드에서 추론할 수 없는 어떤 정보도 제공하지 않습니다.
• Fix: 레이블이 특정 정보를 전달하지 않으면 제거하세요. "Note: retries happen only on 5xx"는 가치가 있지만 "Note: this is important"는 그렇지 않습니다.

모호한 플레이스홀더

• Tell: 무엇을 할지 말하지 않고 미래 작업을 약속하는 주석: // TODO: Improve this, // Future improvements, // Additional optimization can be added here, // Add more validation.
• Why: 모호한 TODO는 소음입니다. 작업(무엇을, 왜) 대신 느낌(이건 더 나을 수 있다)을 이름 짓습니다.
• Fix: 제거하세요. TODO는 실행 가능한 구체적인 작업을 명명하고 충분한 맥락을 제공할 때만 유지하세요.

시그니처 에코

• Tell: 시그니처만 반복하는 문서화: 함수 이름과 매개변수가 이미 모든 것을 말하는 함수에 대해 @param price The price.와 @returns Total price.만 반복하는 JSDoc 블록.
• Why: 시그니처를 반복하는 문서는 길이만 늘리고 이해를 돕지 않습니다. 독자는 새로운 것을 배우지 못합니다.
• Fix: 에코를 단순화하거나 제거하세요. 비즈니스 규칙, 엣지 케이스, 가정, 알고리즘, 제한 사항, 부작용, API 동작, 또는 보안 영향을 설명하는 문서는 보존하세요. 실제 문서를 절대 제거하지 마세요.

장식용 이모지

• Tell: 주석에서 장식용으로 사용된 이모지: // ✅ Validation 또는 // 🚀 Performance.
• Why: 이모지는 코드에서 시각적 소음이며, 특정 세트(✅, 🚀, 🔒)는 AI의 기본 어휘입니다.
• Fix: 평범한 영어로 대체하거나, 라벨이 아무것도 추가하지 않으면 제거하세요.

블록 종료 표시

• Tell: 블록의 끝만 표시하는 주석: } // end if, # End of function, 또는 // End processOrder.
• Why: 닫는 중괄호가 이미 블록을 종료합니다. 표시는 필요보다 습관에서 존재합니다.
• Fix: 제거하세요. 드물게 종료 표시가 긴 파일에서 혼란을 방지하는 데 진정으로 도움이 되는 경우에만 습관이 아닌 필요한 곳에 유지하세요.

어떻게 읽혀야 하는가

과도하게 설명된 주석

• Tell: 한 줄짜리 사실 주변에 이유, 맥락, 이력을 쌓아 여러 줄에 걸쳐 설명하는 하나의 주석: 스텁이 PATH에 있다는 사실, 어떤 릴리스에서 우회 방법이 도입되었는지, 그리고 이전에 무엇이 고장 났는지를 설명하는 네 줄짜리 블록. 모든 문장은 사실입니다. 길이가 바로 신호입니다.
• Why: 사람은 메모를 남기고, 생성기는 사례를 씁니다. 한 줄짜리 사실을 문단으로 채우고, "X 때문에, 그래서 Y, 따라서 Z" 체인을 구축하거나, 이슈 번호와 수정한 버전을 인용하는 것은 다른 AI 패턴과 같은 장식이며, 중요한 한 줄을 그렇지 않은 것들 아래에 묻습니다.
• Fix: 제약 조건만 남기세요: 한 줄, 많아야 두 줄, 절대 세 줄을 넘기지 마세요. 플랫폼 함정, 무음 실패, 프로토콜 규칙, 성능 비용은 유지하세요. 이슈 번호, 버전 이력, 추론 체인은 버리세요.

줄 단위 서술

• Tell: 모든 사소한 문장에 주석을 달아 각 줄을 서술하는 방식: // Initialize count, 그 다음 // Loop items, 그 다음 // Get item, 그 다음 // Increment, 그 다음 // Return result.
• Why: 모든 줄에 주석이 달리면 어떤 주석도 중요하지 않게 됩니다. 독자는 의미 있는 주석을 찾기 위해 각각을 확인해야 합니다.
• Fix: 줄마다 하나씩 쓰는 대신 논리적 블록당 하나의 간결한 주석을 작성하세요. 블록에 주석이 필요 없다면 아무것도 쓰지 마세요.

딱딱하거나 큰 소리로 쓰인 표현

• Tell: 격식 있거나 길거나 소리치는 주석: "This function is responsible for validating whether the supplied credentials are valid before continuing with the authentication process", 또는 대문자로 된 // MAIN LOGIC.
• Why: 격식 있고 큰 소리로 쓰인 표현은 엔지니어가 다음 사람을 위해 남긴 메모가 아니라 생성된 것처럼 읽힙니다.
• Fix: 자연스러운 개발자 목소리로 짧고 문장형 케이스로 작성하세요: // Validate credentials before issuing a token. 좋은 주석은 '무엇'이 아니라 '왜'를 설명하며, 짧게 유지됩니다.

금지 사항이 아님 (보존할 것)

다음을 설명하는 주석은 절대 제거하지 마세요:

• 비즈니스 로직 및 의도
• 아키텍처 결정
• 보안 고려 사항
• 성능 트레이드오프
• 동시성 동작
• 프로토콜 세부 사항
• API 계약
• 우회 방법
• 엣지 케이스 및 가정
• 라이선스 및 법적 고지

반드시 유지해야 할 예시:

// Stripe may retry webhook deliveries for up to three days.
// Ignore duplicate events using the event ID.

주석은 코드가 이미 보여주지 않는 것(이유, 제약 조건, 명확하지 않은 동작)을 설명할 때 그 자리를 얻습니다.

자리를 얻는다는 것은 무엇이 남을 수 있는지 말하는 것이지, 얼마나 길어질 수 있는지를 말하는 것이 아닙니다. 우회 방법에 대한 메모는 우회 방법에 관한 한 줄이지, 그것에 관한 문단이 아닙니다. 위의 예시는 두 가지 사실이 실제로 존재하기 때문에 두 줄이지, 두 줄이 목표이기 때문이 아닙니다. 이 목록은 주석이 마땅히 받아야 할 검토를 통과하는 가장 흔한 이유입니다: 내용이 진정으로 가치 있기 때문에 길이가 검토되지 않습니다. 가치는 길이가 아닙니다.

코드 주석 체크리스트

주석을 다루는 작업을 할 때 핵심 전달 게이트와 함께 이것들을 실행하세요. 모든 답변은 예여야 합니다:

• 모든 주석이 코드가 이미 보여주지 않는 정보를 추가합니까? (R-31)
• 주석이 장식용 구분선, ALL CAPS 배너, 박스 그리기 헤더를 피했습니까?
• 주석이 자명한 줄, 선언, 또는 시그니처를 반복하지 않습니까?
• 주석이 단계별 워크플로 서술을 피했습니까?
• 주석이 작업을 명명하지 않는 빈 레이블과 모호한 TODO를 피했습니까?
• 주석이 장식용 이모지와 블록 종료 표시를 피했습니까?
• 주석 밀도가 줄마다 하나가 아니라 논리적 블록당 하나입니까?
• 모든 주석이 한 줄이거나, 두 번째 줄이 새로운 사실을 전달할 때만 두 줄입니까?
• 남은 주석이 짧고, 자연스럽고, 문장형 케이스로 읽힙니까?
• 범위 제한이 유지되었습니까: 주석만 변경되고 코드는 그대로입니까?