clean-code-guard은(는) 무엇을 하나요?
당신은 생성되거나 변경된 코드를 출시하기 전에 검토하고 있습니다. 아래 규칙을 첫 번째 구현 패스 이후의 가드 패스로 적용하십시오. 이 스킬이 활성화된 후에는 같은 세션에서 이후의 모든 코드 변경에 계속 적용하고, 각 편집 후 전달 전에 자체 점검을 다시 실행하십시오. 사용자가 코드를 작성하기 전에 이 스킬을 명시적으로 호출하면, 작성 중에도 동일한 규칙을 적용하고 전달 전에 자체 점검을 실행하십시오.
에이전트 팀 통합
저장소의 규칙, 수락된 계약, 역할 권한 및 사용자 범위가 이 가이드와 그 참조보다 우선합니다. DEV는 자체 변경 사항에 가드 패스를 사용합니다. CR은 읽기 전용 리뷰 모드를 사용하며 구현을 편집하지 않습니다. 수치 제한, 이름 금지, 인수 형태, 추상화 규칙을 자동 편집 또는 차단이 아닌 조사 신호로 취급하십시오. 발견 사항은 구체적인 정확성 또는 유지보수 비용을 맥락에 맞게 설명해야 합니다. 응집력 있는 코드를 분할하거나, 인터페이스를 깨뜨리거나, 단지 개수를 맞추기 위해 예외 주석을 추가하지 마십시오. 변경된 코드와 직접적인 영향을 받는 호출자만 검토하고, 관련 없는 부채는 검토하지 마십시오.
이 패키지에서 사용하는 모든 지침과 체크리스트는 로컬에 있습니다. 외부 간행물 이름은 귀속 표시용일 뿐입니다. 저장소 증거와 번들된 참조를 사용하고 브라우징하지 마십시오. 이 작업이 스킬 범위를 벗어나면 저장소의 일반 프로세스를 따르십시오. 형제 스킬이 필요하지 않습니다.
호환성
이것은 포터블 인스트럭션 스킬입니다. MCP 서버, 네트워크 액세스, API 키, 셸 명령, 로컬 실행 파일 또는 번들 스크립트가 필요하지 않습니다. SKILL.md와 직접 연결된 references/ 파일을 지원하는 모든 런타임에서 사용할 수 있습니다. agents/openai.yaml은 가벼운 디스플레이 메타데이터입니다.
이 스킬은 프로젝트의 린터, 포매터, 타입 검사기 또는 테스트 러너를 대체하지 않습니다. 기계적 검증에는 프로젝트 자체 도구를 사용하고, 코드 품질 및 리뷰에 대한 판단 레이어에는 이 스킬을 사용하십시오.
이 스킬 사용 방법
이 스킬에는 세 가지 모드가 있습니다. 사용자의 요청에 따라 선택하십시오.
가드 패스 모드 (권장): 코드가 생성, 편집, 리팩터링 또는 수정된 후, diff 또는 대상 파일을 항상 적용되는 명령에 대해 확인하십시오. 작업을 제시, 커밋 또는 병합하기 전에 위반 사항을 수정하십시오.
라이브 모드 (명시적): 사용자가 위험한 코드 편집 전에 이 스킬을 호출하면, 작성 중에 동일한 명령을 적용한 다음 전달 전 자체 점검 체크리스트를 실행하십시오. 규칙을 위반한 경우 사용자에게 보여주기 전에 수정하십시오.
리뷰 모드 (사용자가 코드를 검토, 감사, 비평 또는 평가하도록 요청할 때 트리거): references/review-checklist.md를 대상 파일에 대해 실행하고 구조화된 발견 보고서를 생성하십시오. 요청하지 않는 한 리뷰 모드에서 코드를 편집하지 마십시오.
세 가지 모드 모두에서 규칙 본문은 references/에 있습니다. 다음 경우에 관련 참조 파일을 읽으십시오:
- 완전히 기억하지 못하는 규칙의 근거가 필요할 때.
- 사용자가 규칙에 반대하고 출처 인용이 필요할 때.
- 리뷰 모드에서 전체 체크리스트가 필요할 때.
- 검토 중인 코드가 특정 원칙(예: 서브클래싱 → references/solid.md; 중복 제거 → references/dry-kiss-yagni.md)과 관련될 때.
참조 파일은 다음과 같습니다:
- references/naming-and-functions.md — 이름, 함수 크기, 매개변수, 명령/쿼리 분리.
- references/comments-and-formatting.md — 주석을 달 시기, 삭제할 시기, 이웃 스타일 일치.
- references/solid.md — SRP, OCP, LSP, ISP, DIP (현대적인 표현 및 감지 냄새 포함).
- references/dry-kiss-yagni.md — 지식 대 코드 중복, Sandi Metz의 재인라인 규칙, McCabe 복잡도, Fowler의 YAGNI 비용 범주.
- references/ai-failure-modes.md — LLM이 잘못된 코드를 생성하는 14가지 체계적인 방식. 이 스킬을 읽는 AI 에이전트라면 이것을 먼저 읽으십시오. 이것은 이 스킬에서 가장 영향력이 큰 파일입니다.
- references/review-checklist.md — 리뷰 모드를 위한 구조화된 워크스루.
- references/sources.md — 출처 URL의 중앙 참고 문헌. 외부 출처를 확인하거나 인용해야 할 때만 읽으십시오.
예시
- 코딩 에이전트가 엔드포인트를 구현: 작업이 제시되거나 커밋되기 전에 diff에 대해 가드 패스 모드를 사용하십시오.
- 사용자가 "이 PR을 리뷰해줘" 또는 "이걸 병합해도 될까?"라고 요청: 리뷰 모드를 사용하고 references/review-checklist.md에서 발견 사항을 보고하십시오. 요청하지 않는 한 편집하지 마십시오.
- 사용자가 "clean-code-guard를 사용하여 이 엔드포인트를 구현해"라고 요청: 작성 중에는 라이브 모드를 사용하고, 전달 전에 자체 점검을 실행하십시오.
- 사용자가 "이 함수를 리팩터링해, 동일한 동작 유지" 요청: 관찰 가능한 동작을 정확히 유지하고 버그 수정은 별도의 변경 사항으로 취급하십시오.
성공 기준
이 스킬은 코드 작성 작업이 나열된 실패 모드를 피하고, 코드 리뷰 작업이 구체적인 증거와 함께 우선순위가 매겨진 발견 사항을 생성하며, 사용자가 명시적으로 동작 변경을 요청하지 않는 한 리팩터링이 동작을 유지할 때 작동합니다. 머리말 제외 사항에 해당하는 개념적, CI, git 워크플로, 산문, 데이터 분석 및 테스트 실행 작업에는 침묵해야 합니다.
이 스킬이 존재하는 이유
LLM이 생성한 코드에는 일반적인 "클린 코드 따르기" 지침이 포착하지 못하는 측정 가능하고 체계적인 실패 모드가 있습니다. 출판된 연구에 의해 뒷받침되는 예시:
- 코드 중복이 2021년에서 2024년 사이에 추적된 코드베이스에서 8배 증가 (GitClear 2025 보고서).
- 패키지 환각 비율은 16개 모델 평균 19.6% (Spracklen et al., USENIX Security '25).
- LLM은 위험한 작업을 오류를 삼키는 광범위한 catch-all 핸들러로 자주 래핑합니다 (Karpathy).
- AI 에이전트는 "테스트 실패에도 불구하고 성공을 선언"하며 하드코딩된 픽스처 값을 반환합니다 (Fowler, Patterns for Reducing Friction).
- AI 지원 커밋에서 함수 크기가 142줄에서 267줄로, 순환 복잡도가 4.2에서 8.1로 증가 (GitClear).
고전적인 원칙(Clean Code, SOLID, DRY/KISS/YAGNI)은 여전히 기초입니다. 그러나 이 스킬은 대부분의 규칙 팩이 놓치는 AI 특화 레이어를 추가합니다.
항상 적용되는 명령
다음은 모든 코드 변경 시 따라야 할 규칙입니다. 제안이 아닌 명령입니다.
함수와 이름
- 이름은 의도를 드러냅니다. 절대
data,data2,result,result_final,item,temp,value,obj,info,helper,manager,utils또는handle_*/process_*/do_*를 수식어 없이 사용하지 마십시오. 이름은 왜 존재하는지와 무엇을 하는지에 답해야 합니다. (Clean Code 2장) - 함수는 작게 유지합니다. ≤20줄, 하나의 추상화 수준, 한 가지 일을 목표로 합니다. 함수 본문을 다시 설명하지 않는 이름으로 함수를 추출할 수 있다면, 부모가 한 가지 이상의 일을 하고 있었던 것입니다. (Clean Code 3장)
- 네 개의 인수가 상한선입니다. 다섯 개가 되면 중단하고 요청/설정 객체(레코드, 구조체, DTO 또는 이에 상응하는 것)를 도입하십시오. 절대 부울 플래그 인수를 사용하지 마십시오. 대신 두 개의 함수로 분할하십시오.
- 출력 인수는 없습니다. 함수는 값을 반환(쿼리)하거나 부수 효과(명령)를 가져야 합니다. 둘 다 가져서는 안 됩니다. 명령 이름은 동사를 사용하고, 쿼리 이름은 명사 또는 getter 스타일 이름을 사용합니다. (CQS)
주석과 구조
- 주석은 왜를 설명하고, 무엇을 설명하지 않습니다. 아래 줄을 의역하는 주석은 삭제하십시오. 단계 번호 발판(scaffolding) 주석은 삭제하십시오. 주석 처리된 코드는 삭제하십시오. 버전 관리가 존재합니다. (Clean Code 4장)
- 파일의 기존 스타일과 일치시킵니다. 작성하기 전에 편집할 파일과 최소한 하나의 이웃 파일을 읽으십시오. 대소문자, 임포트 순서, 오류 처리, 로깅, HTTP/DB 클라이언트 선택을 반영하십시오. 두 번째 패턴을 도입하지 마십시오.
SOLID
- 모듈당 하나의 행위자. 클래스는 하나의 이해관계자 그룹(회계, 인증, 보고)에 응답해야 합니다. 두 개의 관련 없는 하위 시스템이 동일한 클래스에 도달하면 분할하십시오. (SRP, Uncle Bob 2014)
- 새 코드를 통한 확장, 편집이 아닌. 새 변형을 추가하기 위해 기존 함수에 또 다른 타입-태그 분기가 필요하면, 먼저 레지스트리, 전략 또는 다형성 디스패치로 리팩터링하십시오. (OCP)
- 서브클래스는 부모의 계약을 거부하지 않습니다. 절대 "구현되지 않음" 또는 "지원되지 않는 연산"을 알리기 위해 메서드를 재정의하지 마십시오. 재정의에서 절대 사전 조건을 강화하거나 사후 조건을 약화시키지 마십시오. 그렇게 해야 한다면 상속이 잘못된 것입니다. (LSP)
- 추상화는 클라이언트와 함께 있고, 구현과 함께 있지 않습니다. 인터페이스, 프로토콜 또는 추상 계약을 도입할 때, 구체 클래스 옆이 아니라 그것을 소비하는 패키지에 넣으십시오. (DIP)
DRY, KISS, YAGNI
- 중복된 텍스트가 아닌 중복된 지식을 삭제합니다. 비슷해 보이지만 다른 규칙을 인코딩하는 두 함수는 DRY 위반이 아닙니다. 코드 + 문서 + 스키마로 표현된 하나의 규칙은 DRY 위반입니다. (Pragmatic Programmer, "DRY")
- 잘못된 추상화는 중복보다 나쁩니다. 추상화가 각 호출자의 특수 사례를 위한 분기를 축적했다면, 호출자로 다시 인라인한 다음, 다시 추상화하기 전에 죽은 분기를 삭제하십시오. (Sandi Metz, "The Wrong Abstraction")
- 복잡도 상한: 순환 복잡도 ≤10, 중첩 깊이 ≤5. 초과하기 전에 리팩터링하십시오. (McCabe 1976)
- 추측성 어떤 것도 없습니다. 현재의 호출자 없이 선택적 매개변수, 설정 플래그, 환경 변수, 기능 토글, 인터페이스, 팩토리 또는 기본 클래스를 추가하지 마십시오.
enable_*,use_*_v2또는*_mode를 추가하고 있다면 삭제하고 구체적인 동작을 출시하십시오. (Fowler, "Yagni")
AI 특화 가드레일 — 가장 영향력이 큰 섹션
- 광범위한 catch-all 처리로 오류를 절대 삼키지 마십시오. 복구할 수 있는 특정 오류 유형만 포착하십시오. 복구할 수 없으면 오류를 전파시키십시오. catch 핸들러에서 null/none/빈 성공을 반환하는 것은 함수 계약이 해당 동작을 문서화하지 않는 한 금지됩니다. (Karpathy)
- 경계를 보호하고 계약을 신뢰하십시오. 신뢰 경계(외부 입력, 요청/API 페이로드, 역직렬화 또는 프로세스 간 데이터, 신뢰할 수 없는 출처의 모든 것)에서는 행복 경로가 괜찮아 보여도 검증하십시오. 경계 내부에서는 선언된 타입 또는 호출자 계약이 이미 해당 경우를 배제하는 값에 대해 null 검사 또는 런타임 타입 검사를 추가하지 마십시오. 가드의 테스트는 "이론적으로 이것이 잘못될 수 있는가"가 아니라 "신뢰할 수 없는 데이터가 여기에 도달할 수 있는가"입니다. (arXiv 2409.19182)
- 모든 임포트 및 외부 호출을 확인하십시오. 라이브러리의 메서드를 호출하기 전에 설치된 버전에 존재하는지 확인하십시오(패키지 읽기, 잠금 파일 확인, 또는 임포트 및 검사). API가 "어떻게 생겼어야 하는지"에 기반하여 코드를 생성하지 마십시오. (USENIX Security '25)
- 프로덕션 코드에 하드코딩된 "성공" 반환 또는 모의 픽스처가 없습니다. 사양이 실제 작업을 수행한다고 말하는 함수에서
{"status": "ok", ...}또는 캔 데이터를 절대 반환하지 마십시오. 구현할 수 없으면 언어의 미구현 또는 지원되지 않는 연산 메커니즘으로 명시적으로 실패하고 그렇게 말하십시오. 절대 테스트를 비활성화, 건너뛰기 또는 약화시켜 통과시키지 마십시오. (Fowler, Claude Code issue #6984) - 유사한 것으로부터 복사하지 말고, 다시 유도하십시오. 함수를 복사하여 수정하고 싶은 유혹이 들면 중단하십시오. 사양에서 다시 유도하십시오. 1차이 오류 및 잘못된 null 의미 체계 버그는 거의 항상 유사한 것으로부터 복사를 통해 들어옵니다. (arXiv 2411.01414)
- 경계 사례를 작성하기 전에 열거하십시오. 모든 범위, 1차이, null/빈/하나/다수, 짝수/홀수 또는 유니코드/바이트 경계에 대해 먼저 주석에 사례 목록을 작성하십시오. 다음으로 넘어가기 전에 코드에서 각 사례를 다루십시오.
- 전달 전에 죽은 코드를 제거하십시오. 린터 또는 grep 패스를 실행하여 사용되지 않는 임포트, 사용되지 않는 심볼, 도달할 수 없는 분기 및 "만약을 대비한" 내보내기를 확인하십시오. 제거하십시오. 오늘 아무것도 호출하지 않는 함수는 "언젠가"를 위해 살 수 없습니다.
- 쓰기 전에 읽으십시오. 익숙하지 않은 저장소에서 작성하기 전에 편집할 파일, 하나의 이웃 파일 및 모든 프로젝트 규칙 파일(CLAUDE.md, AGENTS.md, README의 "관례" 섹션)을 읽으십시오. 프로젝트의 기존 헬퍼, 오류 타입 및 로깅을 사용하십시오.
- 몇 줄로 해결되는 것에 새 종속성을 추가하지 마십시오. 패키지를 추가하기 전에 표준 라이브러리, 이미 설치된 종속성 및 몇 줄의 로컬 코드로 작업을 수행할 수 있는지 확인하십시오. 새 종속성은 영구적인 유지보수 및 공급망 표면입니다. 재구현해서는 안 되는 실제 복잡성을 소유할 때만(암호화, 구문 분석, 시간대 — 예시일 뿐이며 완전하지 않음) 추가하고, 절대 10줄을 절약하기 위해 추가하지 마십시오. references/dry-kiss-yagni.md를 참조하십시오.
최소 기준 — 단순화를 위해 이것들을 절대 삭제하지 마십시오
규칙 16은 경계 내부의 계약을 신뢰합니다. 아래 항목은 추측(14), 방어적 가드(16) 및 죽은 코드(21)를 제거하는 동안에도 유지됩니다. 이 중 하나를 제거하는 것은 정리 작업이 아닌 동작 변경입니다. 유지하거나 플래그를 지정하고 물어보십시오.
- 모든 신뢰 경계에서의 검증 및 살균 — 외부 입력, 요청/API 페이로드, 역직렬화 또는 프로세스 간 데이터.
- 데이터 손실을 방지하는 오류 처리.
- 보안 조치 — 권한 부여, 출력 이스케이프, 매개변수화된 쿼리, 비밀 처리.
- 사용자가 명시적으로 요청한 동작. 무심코 언급한 것 ≠ 요청했지만, 요청된 것을 삭제하지 마십시오.
리팩터링 규율
- 리팩터링 시 관찰 가능한 동작을 유지하십시오. 사용자가 기존 코드를 정리, 단순화 또는 리팩터링하도록 요청할 때, 계약을 변경하지 마십시오. 동일한 입력이 동일한 출력, 동일한 예외 발생, 동일한 부수 효과, 동일한 순서 보장을 생성합니다. 리팩터링 중에 버그를 발견하면 별도로 플래그를 지정하고 변경하기 전에 물어보십시오. 리팩터링은 "관찰 가능한 동작을 변경하지 않으면서 소프트웨어의 내부 구조를 이해하기 쉽게 만들고 수정 비용을 낮추기 위해 변경하는 것" (Fowler, Refactoring)으로 정의됩니다. 버그 수정과 리팩터링은 두 가지 작업입니다. 절대 단일 변경에 함께 묶지 마십시오.
전달 전 자체 점검
사용자에게 작업을 표시하기 전에 다음 체크리스트를 실행하십시오. 하나라도 빠뜨리면 수정한 후에야 전달하십시오. 이 체크리스트는 조건부가 아닙니다. 모든 코드가 리뷰 모드가 아닌 가드 패스 및 라이브 모드 전달에 대해 통과해야 합니다.
- 지식 중복 확인: 로직, 데이터 스키마 또는 비즈니스 규칙이 여러 위치에서 이미 정의되었습니까? (DRY)
- 가상의 미래 확인: 지정되지 않은 미래 요구 사항을 지원하는 플래그, 매개변수, 인터페이스 또는 레이어가 추가되었습니까? (YAGNI)
- 오류 전파 확인: 복구할 수 없는 오류가 catch되어 null/none/빈 성공으로 대체되고 있습니까, 아니면 단순히 기록되고 무시되고 있습니까? (규칙 15)
- 경계 검증 확인: 모든 신뢰할 수 없는 입력이 처리 시점에 검증되고 있습니까? (규칙 16)
- 죽은 코드 확인: 사용되지 않는 임포트, 심볼 또는 분기가 남아 있습니까? (규칙 21)
- 마지막 규칙 확인: 모든 규칙을 기억할 수 없습니까? 지금 references/를 읽으십시오.
- 인용 확인: 함수의 동기는 응집력 있고 단일 목적입니까? 크기는 약 20줄 이내입니까? (규칙 1, 2)
- 의존성 확인: 새 패키지가 추가되었습니까? 그것이 소유한 복잡성이 가치가 있으며 기존 라이브러리로는 충분하지 않습니까? (규칙 23)
- 픽스처 확인: 프로덕션 코드에 나중에 교체하기 위한 하드코딩된 성공 또는 모의 데이터가 있습니까? (규칙 18)
- 이름 확인: 모든 이름이 의도를 드러내고 임시 또는 일반 이름을 가지고 있지 않습니까? (규칙 1)
- 리팩터링 확인: 리팩터링 변경이 관찰 가능한 동작을 정확히 유지했습니까? 별도로 플래그가 지정되지 않은 버그 수정이 포함되어 있습니까? (규칙 24)
제외
다음 작업 유형의 경우 이 스킬을 활성화하지 마십시오(또는 활성화된 경우 기본적으로 침묵하고 기존 규칙을 무시하십시오):
- 저장소 설정 질문.
- CI 파이프라인 및 git 워크플로.
- 프로젝트 문서, 마크다운 또는 산문.
- 데이터 분석, 통계 모델 피팅, 플롯 생성.
- 테스트 실행 및 CI 로그 읽기.
- 개념적 질문에 대한 답변(코드 검토가 아님).