Guard Skills: 배포 전 실패 모드를 포착하는 AI 코드 품질 대안

만약 기존 도구들을 대체할 진지한 **AI 코드 품질 대안 (AI code quality alternative)**을 찾고 있다면, Guard Skills는 당신의 AI 보조 개발 파이프라인에서 빠져 있던 마지막 조각입니다. 환각을 일으키는 API (Hallucinated APIs), Mock 오용 (mock abuse), 성급한 추상화 (premature abstraction), 그리고 존재하지 않는 함수를 참조하는 문서화는 AI 보조 개발에서 일상적인 문제가 되고 있습니다. 이 오픈 소스 품질 게이트 (quality gates) 컬렉션은 에이전트의 출력물과 프로덕션 저장소 (production repository) 사이에서 역할을 수행합니다.

1. 문제점: AI 생성 코드는 체계적인 실패 모드를 가지고 있음

우리가 처한 상황에 대해 솔직해져 봅시다. Claude Code, Codex, Cursor, OpenCode와 같은 도구들은 몇 초 만에 작동하는 100줄의 코드를 생성할 수 있습니다. 하지만 작동하는 코드가 곧 _프로덕션 품질 (production-quality)_의 코드를 의미하지는 않습니다.

Guard Skills 프로젝트에서 인용한 연구는 LLM 출력에서의 중복 증가, 패키지 환각 (package hallucination) 비율, 그리고 테스트 실패에도 불구하고 성공을 선언하는 에이전트의 경향성에 관한 발표된 조사 결과들을 참조합니다. 이것들은 예외적인 사례가 아닙니다. 대규모 언어 모델 (Large Language Models, LLM)이 코드를 생성하는 방식에 내재된 **체계적인 실패 모드 (systematic failure modes)**입니다.

실제 사례로는 어떤 것들이 있을까요?

• 성급한 추상화 (Premature abstraction) — 에이전트가 학습 과정에서 높은 점수를 받았던 패턴 때문에 모든 것을 인터페이스 (interfaces)와 팩토리 (factories)로 감싸버리는 경우
• 광범위한 오류 삼키기 (Broad error swallowing) — 모델이 '처리'보다 '완성'을 우선시하도록 학습되었기 때문에, 모든 함수가 try { ... } catch { return ok } 형태가 되는 경우
• 환각을 일으키는 의존성 (Hallucinated dependencies) — 에이전트가 존재하지 않는 라이브러리를 임포트(import)하거나, 서로 다른 버전에서 혼동된 API를 사용하는 경우
• Mock 오용 (Mock abuse) — 자체 데이터 객체를 Mocking하거나, 테스트 로그 메시지를 Mocking하며, 리팩토링할 때마다 변경되는 구현 세부 사항에 대해 단언(assert)하는 테스트 스위트
• 문서 드리프트 (Documentation drift) — 기능을 주장하거나, 존재하지 않는 함수를 참조하며, 첫 실행 시 충돌을 일으킬 샘플 코드를 포함하는 README 및 docstring

이러한 문제들은 린터 (Linters)를 회피하고, SonarQube를 통과하며, 수동 리뷰 (Manual review)에서도 살아남습니다. 왜냐하면 이 코드들이 올바르게 보이기 때문입니다. 즉, 구조적으로는 유효한 코드이지만, 실제 사용 사례(use case) 측면에서는 구조적으로 잘못된 코드인 것입니다.

2. Guard Skills란 무엇인가?

Guard Skills는 AI가 생성한 코드를 위해 특별히 설계된 2차 품질 게이트 (second-pass quality gates) 오픈 소스 컬렉션입니다. 이를 일반적인 소프트웨어 엔지니어링 원칙과 LLM이 생성하는 특유의 실패 패턴을 모두 이해하는 전문 코드 리뷰어라고 생각하면 됩니다.

각 가드 (guard)는 Skills CLI를 통해 설치할 수 있는 단일 스킬 파일입니다. 디프 (diff) 또는 코드베이스 (codebase)에 가드를 호출하면, 다음 다섯 가지 차원에서 위반 사항을 스캔합니다:

가드 (Guard)	최적의 용도	포착하는 내용
clean-code-guard	프로덕션 코드 (Production code), 모든 언어	LLM 코드 스멜 (code smells), 과도한 추상화 (over-abstraction), 잘못된 명명 (bad names), SOLID 원칙 위반
...

워크플로우는 간단합니다: 에이전트 (agent)가 작업을 수행하게 한 다음, 제시, 커밋 (commit) 또는 머지 (merge)하기 전에 관련 가드를 호출하세요. 또한 생성 과정 중에 에이전트의 행동을 제한하기 위해 가드를 사전에 실행할 수도 있습니다.

3. 기존 품질 도구들이 충분하지 않은 이유

각 가드를 자세히 살펴보기 전에, 근본적인 질문을 던져보겠습니다: 왜 이미 가지고 있는 도구들을 그냥 사용하면 안 되는 걸까요?

수동 코드 리뷰 (Manual Code Review)

인간의 리뷰 속도가 AI 출력 속도를 따라잡지 못하고 있습니다. Claude Code를 사용하는 개발자 한 명은 과거보다 10배 더 많은 코드를 생성할 수 있지만, 리뷰 대역폭 (bandwidth)은 확장되지 않았습니다. 더 결정적으로, 인간 리뷰어들은 AI가 생성한 코드가 언뜻 보기에 올바르게 보이기 때문에 무심코 승인(rubber-stamp)하는 경향이 있으며, 이는 LLM이 가진 실패 모드와 동일합니다. Guard Skills는 절대 지치지 않고, 무심코 승인하지 않으며, 인간이 놓치는 미묘한 패턴을 포착합니다.

린터 (Linters: ESLint, Pylint, PHPCS)

린터 (Linters)는 구문 (syntax), 포맷팅 (formatting), 그리고 제한된 범위의 베스트 프랙티스 (best practices)를 점검합니다. 하지만 눈에 보이는 모든 객체를 모킹 (mock)하는 테스트가 유지보수의 악몽이 될 수 있다는 점은 이해하지 못합니다. 또한, 실제 API에서는 User::findByEmail()을 사용하고 있음에도 문서 섹션에서 get_user_by_email()을 참조하고 있는 상황을 잡아내지 못합니다. Guard Skills는 의미론적 (semantic) 수준에서 작동합니다. 즉, 코드, 테스트, 그리고 문서를 서로 연결된 시스템으로 이해합니다.

SonarQube

SonarQube는 코드 중복 (code duplications), 보안 핫스팟 (security hotspots), 그리고 복잡도 지표 (complexity metrics)를 탐지하는 데 탁월합니다. 하지만 이는 AI 이전의 세상에서 만들어졌습니다. SonarQube는 패키지 환각 (package hallucination), 독스트링-API 드리프트 (docstring-API drift), 또는 에이전트가 과도하게 추상화 (over-abstract)하려는 경향과 같은 LLM 특유의 실패 모드 (failure modes)를 알지 못합니다. Guard Skills는 바로 그 간극을 메워줍니다. 이를 AI 시대를 위한 SonarQube라고 생각하거나, 더 정확하게는 SonarQube가 놓치는 것을 잡아내는 보완재라고 생각하십시오.

이 도구들은 함께 사용할 때 매우 훌륭하게 작동합니다. 하지만 AI가 생성한 실패 모드를 포착하기 위해 단 하나의 도구에만 의존하고 있다면, 당신은 기회를 놓치고 있는 것입니다. Guard Skills는 현대의 코딩 에이전트가 만들어내는 특정한 실패 패턴을 겨냥하는 **AI 코드 품질 대안 (AI code quality alternative)**이자, 빠져 있던 마지막 조각입니다.

4. clean-code-guard: LLM 코드 스멜을 입구에서 차단하기

clean-code-guard는 이 컬렉션의 핵심 동력입니다. 이 도구는 모든 언어의 생성된 코드에 클린 코드 (Clean Code), SOLID, DRY/KISS/YAGNI 원칙을 적용하며, 여기에 LLM 출력물에서 나타나는 고유한 패턴을 포착하는 **AI 특화 레이어 (AI-specific layer)**를 더합니다.

포착하는 항목:

• Catch-all error swallowing (포괄적 오류 삼킴) — 모든 함수가 try/catch로 감싸져 있어 일반적인 성공(success)을 반환하는 경우
• Hardcoded success returns (하드코딩된 성공 반환) — return true 뒤에

1. 시스템 경계에서만 모킹 (Mock only at system boundaries) — 자신의 객체는 절대 모킹하지 말고, 외부 의존성(external dependencies)만 모킹하세요.
2. 자신의 상태 객체를 절대 모킹하지 마세요 (Never mock your own state objects) — 만약 테스트가 도메인의 데이터 클래스(data class)를 모킹한다면, 이는 동작(behavior)이 아닌 구현(implementation)을 테스트하는 것입니다.
3. 복사-붙여넣기 대신 매개변수화 (Parametrize instead of copy-pasting) — 서로 다른 입력을 가진 중복된 테스트 본문은 하나의 매개변수화된 테스트 (parametrized test)로 구성해야 합니다.
4. 아무것도 잡아내지 못하는 테스트는 삭제하세요 (Delete tests that catch nothing) — 테스트가 실패할 수 없다면, 그것은 불필요한 짐일 뿐입니다.
5. 프로덕션 회귀 테스트를 신성하게 여기세요 (Treat production regression tests as sacred) — 명확한 근거 없이 회귀 테스트 (regression tests)를 수정하거나 삭제하지 마세요.
6. 구현 세부 사항에 대한 단언(assertion)을 피하세요 (로그 메시지, 내부 호출 또는 프라이빗 상태(private state)에 대해 단언하지 마세요)
7. 자신의 코드에 대해서는 깊은 모킹 (deep mocking)보다 실제 통합 (real integration)을 선호하세요
8. 내부가 아닌 결과(outcomes)를 테스트하세요
9. 무엇을 테스트하는지가 아니라, 테스트를 하고 있다는 사실이 아닌 '무엇'을 테스트하는지를 명시하는 테스트 설명을 작성하세요

프레임워크별 점진적 공개 (progressive-disclosure) 참조에는 pytest, PHPUnit/Pest, Jest/Vitest, Go tests, 그리고 WordPress/WooCommerce 테스트 패턴이 포함됩니다.

6. docs-guard: 더 이상의 환각된 심볼(Hallucinated Symbols)은 없다

문서화는 AI가 생성한 코드가 가장 큰 피해를 주는 영역입니다. 존재하지 않는 get_user_premium_status() 함수를 참조하는 README는 단순히 오해를 불러일으키는 데 그치지 않고, 코드베이스 전체에 대한 신뢰를 떨어뜨립니다.

docs-guard는 문서를 **주장 목록 (list of claims)**으로 취급하며, 모든 주장을 실제 코드와 대조하여 검증합니다:

• 문서에서 참조되는 모든 함수/클래스/메서드의 존재 여부를 확인합니다.
• 코드 샘플이 코드베이스와 일치하지 않는 API를 사용하는 경우 플래그를 표시합니다.
• @param 및 @return 태그가 실제 시그니처 (signatures)와 일치해야 합니다.
• 변경 로그 (Changelog) 항목을 커밋 히스토리 (commit history)와 대조하여 검증합니다.
• 검증 불가능한 주장 ("blazingly fast", "enterprise-grade" 등)은 삭제 대상으로 플래그를 표시합니다.

이는 README, API 참조, PHPDoc/JSDoc 어노테이션 (annotations), 변경 로그, 그리고 튜토리얼을 모두 포함합니다.

7. WordPress 전용 가드: wp-guard 및 woo-guard

WordPress 생태계에서 작업한다면, 일반적인 품질 게이트(quality gates)가 놓치는 플랫폼 특화 실패 모드(failure modes)를 처리하는 두 가지 전문 가드(guards)가 있습니다.

wp-guard는 다음 사항을 포착합니다: 누락된 이스케이핑(escaping) 및 새니타이제이션(sanitization), nonce 및 권한(capability) 체크 누락, $wpdb->prepare() 대신 사용하는 생(raw) SQL 쿼리, 커스텀 파이프라인 구축 전 Core API 사용 미흡, 번역 준비가 되지 않은 문자열, 그리고 대규모 사이트에서 posts_per_page => -1과 같은 쿼리/캐싱 실수.

woo-guard (wp-guard를 기반으로 구축됨)는 다음 사항을 포착합니다: CRUD 메서드 대신 직접적인 주문 메타(order meta) 접근, HPOS 호환성 파괴, 기능 호환성 선언 누락, 클라이언트 측 검증에 의존하는 체크아웃 우회, 금전 처리 오류, 그리고 훅(hooks) 대신 사용하는 템플릿 오버라이드(template overrides).

이 두 가드는 함께 작동하여 AI 지원 WordPress 개발을 프로덕션 환경에서도 안전하게 만듭니다.

8. Guard Skills vs. 대안들: 현실적인 비교

Guard Skills를 가장 일반적인 세 가지 품질 접근 방식과 함께 맥락 속에서 비교해 보겠습니다.

기준	수동 코드 리뷰 (Manual Code Review)	린터 (Linters, ESLint 등)	SonarQube	Guard Skills
구문 오류 포착	예	예	예	아니요 (역할이 아님)
...

핵심 통찰: Guard Skills는 이러한 도구 중 어느 것도 대체하지 않습니다. 대신 이들을 **보완(complements)**합니다. 구문을 위해서는 린터를, 복잡도(complexity)를 위해서는 SonarQube를 실행하고, 기존 파이프라인이 무시하는 AI 특화 실패 모드(failure modes)를 위해서는 Guard Skills를 실행하십시오.

9. 60초 만에 시작하는 방법

Guard Skills는 MIT 라이선스이며 몇 초 안에 설치할 수 있습니다.

# 모든 가드 설치
skills add amElnagdy/guard-skills

...

Claude Code, Codex, Cursor, 그리고 OpenCode와 함께 작동합니다. 설치 후, 모든 diff(차이점)에 대해 가드를 호출하십시오:

방금 생성한 diff에 $clean-code-guard를 사용하세요.
방금 작성한 테스트에 $test-guard를 사용하세요.
배포하기 전에 이 README 업데이트에 $docs-guard를 사용하세요.

가드는 코드를 스캔하여 일반적인 조언이 아닌, 구체적이고 실행 가능한 피드백을 반환합니다.

CTA: AI 실패 모드(failure modes)의 배포를 중단하세요. 지금 Guard Skills 설치하기 — 무료이며, 오픈 소스이고, 단 하나의 명령어로 설치할 수 있습니다.

10. 결론: AI 지원 개발(AI-Assisted Development)의 빠진 조각

AI 코딩 에이전트(AI coding agents)는 사라지지 않을 것입니다. 매달 에이전트들은 더 빨라지고, 더 유능해지며, 우리의 워크플로우(workflows)에 더 깊숙이 통합되고 있습니다. 하지만 그 강력한 힘과 함께 새로운 종류의 품질 문제들이 발생하고 있습니다. 이는 기존 도구들이 포착하도록 설계되지 않았으며, 인간의 검토(human review)만으로는 따라잡을 수 없는 문제들입니다.

Guard Skills가 그 간극을 메워줍니다. Guard Skills는 에이전트의 출력물과 프로덕션 저장소(production repository) 사이에서 작동하는 **AI 코드 품질 대안(AI code quality alternative)**으로, 환각된 API(hallucinated APIs), 모의 객체 오용(mock abuse), 문서 드리프트(documentation drift), 그리고 WordPress 보안 취약점을 배포 전에 포착합니다.

다섯 가지 가드(guards) — clean-code-guard, test-guard, docs-guard, wp-guard, 그리고 woo-guard — 는 일반 코드, 테스트, 문서, 그리고 WordPress 생태계 전반에 걸친 AI 생성 실패 모드(failure modes)의 전체 스펙트럼을 다룹니다. 이들은 빠르고 구체적이며, 여러분이 이미 사용 중인 워크플로우에 맞게 설계되었습니다.

오늘 바로 설치하세요:

skills add amElnagdy/guard-skills

CTA: 내일 더 나은 코드를 배포하세요. GitHub에서 Guard Skills 가져오기 — MIT 라이선스, 60초 이내 설정 완료, 모든 주요 AI 코딩 에이전트와 호환됩니다.

자주 묻는 질문 (Frequently Asked Questions)

Q: Guard Skills가 기존의 린터(linter)나 CI 파이프라인(CI pipeline)을 대체하나요?

아니요. Guard Skills는 린터와 정적 분석 도구(static analysis tools)가 놓치는 **AI 특화 실패 모드(AI-specific failure modes)**를 타겟팅합니다. Guard Skills는 구문 계층(syntax layer) 상위에서 발생하는 의미론적 문제(semantic issues) — 환각된 API, 문서 드리프트, 모의 객체 오용 등 — 를 포착함으로써 ESLint, PHPCS, SonarQube와 같은 도구들을 보완합니다.

Q: 어떤 AI 코딩 에이전트들을 지원하나요?

Guard Skills는 Claude Code, OpenAI의 Codex, Cursor, OpenCode를 포함하여 Skills CLI가 지원하는 모든 에이전트와 함께 작동합니다. 가드(guards)는 에이전트 불가지론적(agent-agnostic)입니다. 즉, 에이전트의 내부 구조가 아닌 코드와 텍스트를 분석합니다.

Q: AI가 생성하지 않은 코드에도 Guard Skills를 사용할 수 있나요?