guard-skills: Claude Code diff에 catch-all 오류·환각 import·HPOS 패턴을 잡는 5개 리뷰 Skill

guard-skills의 구조는 단순합니다. 에이전트가 코드를 생성한 직후 Use $clean-code-guard on the diff you just produced를 입력하면, 동일 에이전트가 14가지 AI 실패 패턴 목록을 들고 diff를 재검토합니다. 이 구조의 약점은 명확합니다 — 리뷰 자체도 같은 모델이 실행하므로 오적용이나 환각이 발생할 수 있습니다. 그러나 각 규칙이 GitClear 2025 리포트, USENIX Security '25, Karpathy 관찰, claude-code issue #6984 등 출판된 근거에 결박되어 있어, 규칙을 검증하거나 반박할 기준선이 있다는 점은 일반 체크리스트와 다릅니다.

왜 생성 직후인가 — 타이밍 설계의 논리

README는 사용 원칙을 명시합니다: "let your agent do the work, then invoke the relevant guard on the diff before you present, commit, or merge it." 코드 작성 중이 아니라 생성 후 diff 단계에 개입하는 것이 설계의 핵심입니다. GitClear 2025 리포트의 측정값이 이 선택의 배경입니다 — 211M LoC 종단 분석에서 5줄 이상 복사-붙여넣기 블록이 2021~2024년 사이 8배 증가했고, AI 지원 커밋의 함수 크기는 142 LoC에서 267 LoC로, 순환 복잡도는 4.2에서 8.1로 올랐습니다. 생성 단계에 규칙을 주입하는 것만으로는 이 패턴이 잡히지 않는다는 판단입니다.

guard-skills가 ESLint나 PHPCS 같은 정적 린터와 구조적으로 다르다는 점을 이해하는 것이 중요합니다. 정적 린터는 도구가 AST를 분석해 결과를 반환합니다. guard-skills는 SKILL.md가 에이전트 컨텍스트에 로드되고, 에이전트가 직접 diff를 읽어 규칙을 적용합니다 — 도구 호출이 아니라 에이전트 지시입니다. README에 The SKILL.md stays small so it loads cheaply라고 명시된 설계 원칙처럼, 깊은 가이드는 references/ 디렉터리에서 필요할 때만 로드되는 progressive-disclosure 구조를 취합니다. 이 구조는 토큰 비용과 규칙 깊이 사이의 트레이드오프입니다.

주의해야 할 경계가 있습니다. clean-code-guard의 frontmatter는 CI 설정, git 워크플로, 테스트 실행, 순수 개념 토론에는 이 skill을 쓰지 말라고 명시합니다. 잘못된 태스크 유형에 skill이 활성화되면 유용한 지적이 아니라 노이즈가 나오고, 정작 코드 리뷰가 필요한 컨텍스트에서는 묻힙니다.

clean-code-guard의 AI 실패 패턴 규칙층 — 린터가 아닌 판단층

clean-code-guard는 두 층으로 구성됩니다. Clean Code, SOLID, DRY/KISS/YAGNI의 전통 규칙(imperative 1~14)과 references/ai-failure-modes.md의 AI-특화 14가지 실패 패턴(imperative 15~22)입니다. 이 파일의 첫 줄은 "**Read this one first if you are an AI agent reading this skill.**"이라고 씁니다 — 인간이 아니라 에이전트에게 우선 독해를 지시하는 메타 설계입니다.

14가지 패턴 중 세 개가 실무에서 즉각적인 가치가 있습니다. 규칙 15(catch-all error swallowing)는 Karpathy가 직접 관찰한 현상을 다루는데, 훈련 보상 신호가 예외 전파에 불이익을 주어 모델이 try/catch -> return ok 패턴을 학습한다는 분석을 포함합니다. 규칙 18(hardcoded "success" returns)은 Fowler의 "declaring success despite failing tests" 패턴과 claude-code issue #6984를 함께 인용합니다. 규칙 17(모든 import 검증)의 근거는 Spracklen 등 USENIX Security '25 — 16개 모델 테스트에서 패키지 환각 비율 평균 19.6%(상용 모델 ~5%, 오픈소스 ~21%)입니다. references/ai-failure-modes.md의 교차 관찰은 8개 패턴의 공통 뿌리를 지목합니다: 모델이 spec이 요구하는 최소 이상의 코드·파라미터·가드·추상화를 생성하는 편향 — 지식 부재가 아니라 자제(restraint)의 문제.

이 규칙층의 한계는 구조적입니다. SKILL.md가 명시하듯 This skill does not replace project linters, formatters, type checkers, or test runners — 기계적 검증 위의 판단층입니다. guard-pass 중에 에이전트가 규칙을 오적용하거나 검토 자체를 할루시네이션할 수 있습니다. 각 규칙에 출처(Karpathy, Fowler, arXiv, claude-code 이슈)를 명시한 이유가 여기에 있습니다: 규칙을 반박하거나 검증할 수 있는 기준선을 제공합니다.

test-guard와 docs-guard — AI 생성물의 흔한 두 함정

test-guard의 9개 규칙 중 실제 차별화 포인트는 Rule 2(시스템 경계에서만 mock)와 Rule 8(상태 객체·DTO·엔티티 절대 mock 금지)입니다. Rule 2는 "내부 클래스나 헬퍼 함수를 'unit'으로 격리하려고 mock하지 말라 — 그 seam이 잡을 가치 있는 통합 버그를 숨긴다"고 지시합니다. AI 생성 테스트에서 MagicMock 남발이 흔한 이유는 에이전트가 테스트 격리를 위해 가능한 모든 의존성을 mock하려는 경향 때문입니다. LLM 애플리케이션을 구성하는 경우 references/llm-app-testing.md의 Rule 12가 직접 적용됩니다: agent flow 테스트는 "state in → state out"을 검증해야 하며, 프롬프트 문자열이나 LLM 호출 횟수를 assert하면 모델·프롬프트 업그레이드 시마다 테스트가 깨집니다. 이는 표준 테스트 가이드라인 어디에도 없는 항목입니다.

docs-guard는 references/verification.md에 구체적인 검증 절차를 정의합니다: 문서를 claim 목록으로 변환(함수명, CLI 플래그, 엔드포인트, config 키 등)하고 각 claim을 코드베이스에서 직접 확인합니다. SKILL.md의 문제 진단은 명확합니다 — 에이전트는 앞에 있는 코드가 아니라 "API가 보통 어떻게 생겼는지"에 대한 기억에서 문서를 작성하며, "half of AI answers to programming questions contain incorrect information, and models produce valid invocations for infrequent APIs barely a third of the time." Rule 6은 코드 변경 시 grep으로 모든 문서 표면에서 구 심볼을 찾아 동기화할 것을 지시합니다.

두 guard의 한계는 명확히 구분해야 합니다. test-guard는 테스트를 실행하지 않고("It does not run tests"), docs-guard는 docs-code 불일치를 자동 수정하지 않습니다. 플래그를 세우면 개발자가 결정합니다.

wp-guard와 woo-guard — 플랫폼 특화 게이트와 HPOS 문제

woo-guard가 존재하는 이유는 references/hpos-and-crud.md가 명확히 설명합니다: "Code written 'from memory' almost always targets the legacy storage, because that is what most training-era tutorials show." HPOS(High-Performance Order Storage)는 2022년 이후 새 WooCommerce 스토어의 기본값이지만, AI 학습 데이터의 대부분을 차지하는 Stack Overflow 답변과 튜토리얼은 이전 wp_posts/wp_postmeta 기반 스토리지를 다룹니다. 이는 단순한 스타일 문제가 아니라 특정 시간적 편향을 겨냥한 설계입니다. woo-guard의 self-check는 diff에서 get_post_meta( $order_id 또는 post_type => 'shop_order' grep 결과를 즉시 Rule 1 위반으로 플래그합니다. 올바른 패턴은 wc_get_order( $order_id ) + $order->get_total()이며 HPOS·레거시 양쪽에서 동작합니다. Rule 3은 모든 extension이 FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true )으로 호환성을 명시적으로 선언해야 함을 요구합니다 — 선언 누락 시 모든 스토어 관리자 화면에 플러그인 이름이 붙은 경고 배너가 나타납니다.

wp-guard는 WordPress 보안 층을 다룹니다: 모든 출력에 컨텍스트 맞는 esc_* 함수, wp_unslash() + sanitize 쌍, nonce + current_user_can() 이중 검사, $wpdb->prepare()로 모든 변수 쿼리 처리. Rule 3은 "REST permission_callback이 __return_true인 쓰기 경로는 리뷰 실패"라고 명시합니다. AI가 생성하는 WordPress REST 엔드포인트에서 흔히 나오는 패턴입니다.

woo-guard와 wp-guard를 함께 설치할 때 파악해야 할 의존 관계가 있습니다. woo-guard SKILL.md는 i18n·asset·쿼리 성능 규칙을 "wp-guard's jurisdiction when it is installed"로 위임합니다. woo-guard 단독 설치로 WooCommerce 플러그인을 점검하면 HPOS·CRUD·결제 규칙은 적용되지만 WordPress 레이어의 i18n·성능 상세 검사는 빠집니다.

설치와 첫 실행 — 구체적인 워크플로와 도입 경계

설치는 전체 패키지 혹은 skill 단위로 가능합니다:

npx skills add amElnagdy/guard-skills --list                                          # 설치 전 목록 확인
npx skills add amElnagdy/guard-skills --skill clean-code-guard --agent claude-code    # 개별 설치
npx skills add amElnagdy/guard-skills --skill wp-guard --skill woo-guard --agent claude-code  # WordPress 세트
npx skills add amElnagdy/guard-skills --global                                        # 모든 에이전트

첫 실행 순서는 다음과 같습니다. Claude Code가 코드를 생성하거나 수정하면 즉시 Use $clean-code-guard on the diff you just produced를 입력합니다. 에이전트는 references/review-checklist.md에 정의된 구조화된 형식으로 결과를 반환합니다:

# Code review: services/payment.ts

## Summary
Needs work — two critical findings before merge.

## Critical findings
- **Catch-all error swallowing** — `services/payment.ts:58`
  Evidence: `} catch (e) { return { status: 'ok' }; }`
  Principle violated: Rule 15 + Rule 18 (references/ai-failure-modes.md)
  Suggested fix: catch only PaymentDeclinedError; propagate gateway errors

test-guard 결과는 rule-by-rule 형식입니다:

**Rule 2 violation** in `tests/services/payment.test.ts::test_charge_user`
- What: PaymentGateway(내부 클래스)를 mock해 단위 격리 시도
- Fix: 실제 PaymentGateway 인스턴스 사용; HTTP 호출만 msw로 mock

--agent 플래그는 각 skill 폴더의 agents/openai.yaml 메타데이터와 함께 skills.sh CLI가 에이전트별로 skill을 라우팅하는 방식입니다. 설치 전 전체 내용 검사는 npx skills add . --list --full-depth로 가능하며, skill 내용은 모두 markdown이고 실행 스크립트·네트워크 호출·MCP 서버 의존성이 없습니다.

건너뛰어야 하는 경우: PHPCS + PHPStan + 타입 체크 파이프라인이 이미 갖춰진 팀에서 clean-code-guard와 wp-guard는 기계적 검증 위의 판단층 추가 정도이며, 에이전트 세션마다 사람이 코드 리뷰를 수행하는 팀은 중복입니다. 핵심 제약: skills.sh CLI(vercel-labs/skills)가 없으면 npx skills add 설치 자체가 불가능합니다. skills CLI 없이 사용하려면 SKILL.md를 직접 CLAUDE.md나 AGENTS.md에 붙여넣어야 하며, 이 경우 references/ 내부 링크가 동작하지 않아 progressive-disclosure 기능이 빠집니다.

guard-skills의 실질적 가치는 Use $test-guard on the tests you just wrote 같은 단 한 줄이 Claude Code 워크플로에 자리 잡을 때 나타납니다. WooCommerce 코드를 생성하는 개발자라면 woo-guard가 잡아내는 get_post_meta() 패턴이 즉각적인 도입 근거이며, 단일 모델이 자신의 출력을 검토한다는 구조적 한계는 references/ai-failure-modes.md의 연구 출처를 통해 규칙을 검증하거나 반박함으로써 관리할 수 있습니다.

핵심 정리

npx skills add amElnagdy/guard-skills --skill clean-code-guard --agent claude-code로 설치한 뒤, 다음 Claude Code 세션에서 에이전트가 코드를 생성하거나 수정하면 바로 Use $clean-code-guard on the diff you just produced를 입력해 리뷰를 실행해 보십시오. 첫 결과에서 catch-all error handling 또는 hardcoded "success" return 지적이 나온다면 도입 효과가 있다는 신호이고, 없다면 references/ai-failure-modes.md를 열어 규칙 15·18번을 직접 확인하면 됩니다.