AI 코드 어시스턴트에게 "React 컴포넌트 만들어줘"라고 말하면, 코드는 나옵니다. 하지만 내 팀의 컨벤션대로 나올까요? props 네이밍, 폴더 구조, 상태관리 패턴, 테스트 방식 — 매번 같은 피드백을 반복하고 있다면, 문제는 AI가 아니라 컨텍스트의 부재입니다.
Claude Code에는 이 문제를 해결하는 기능이 있습니다. 스킬(Skill) 시스템입니다. 스킬은 .claude/skills/ 디렉토리에 마크다운 파일로 정의하는 규칙 세트로, Claude가 코드를 작성할 때 자동으로 참조합니다.
이 글에서는 직접 만든 load28-react 스킬의 설계 의도, 구조, 사용법, 그리고 확장 방법을 다룹니다.
React 프로젝트에서 반복되는 문제가 있었습니다.
사람이 리뷰할 때도 이런 패턴을 매번 잡아내기 어렵습니다. 78개의 규칙을 머릿속에 유지하면서 코드를 검토하는 건 비현실적입니다. 그래서 이 검증 과정 자체를 Claude에게 위임하기로 했습니다.
핵심 원칙은 하나입니다: "기억에 의존하지 마라. 검증을 강제하라."
load28-react 스킬은 3단계 프로토콜과 6개 카테고리의 규칙, 그리고 레퍼런스 코드로 구성됩니다.
.claude/skills/load28-react/
├── SKILL.md # 3단계 프로토콜 정의
├── architecture.md # 아키텍처 규칙 (A-01~10)
├── component-patterns.md # 컴포넌트 패턴 (C-01~15)
├── naming-conventions.md # 네이밍 규칙 (N-01~08)
├── state-and-data.md # 상태관리 & 데이터 흐름 (S-01~17)
├── performance.md # 성능 최적화 (P-01~14)
├── testing-a11y.md # 테스트 & 접근성 (T-01~15)
└── reference-code/ # 패턴별 레퍼런스 구현
├── _tags.md # 태그 정의서
├── compound-component--context--generic.md
├── http-client--acl--dependency-inversion.md
├── msw--mock--integration-test.md
└── ... (28개 레퍼런스 파일)SKILL.md가 전체 워크플로우를 정의합니다. Claude는 코드를 작성할 때 반드시 이 순서를 따릅니다.
Phase 1: 레퍼런스 조회 — 구현을 시작하기 전에 reference-code/ 디렉토리에서 관련 패턴을 검색합니다. 파일명이 태그 형식(tag1--tag2--tag3.md)으로 되어 있어 필요한 패턴을 빠르게 찾을 수 있습니다.
Phase 2: 검증 — 코드 작성 후 78개 규칙을 기준으로 검증합니다. 모든 규칙을 매번 확인하는 것은 아니고, 고빈도 위반 규칙(C-01, C-02, S-02, S-06, P-04, P-05, T-04, N-03, N-04)은 반드시 확인합니다.
Phase 3: 리포팅 — 적용한 규칙, 수정한 내용, 완료 상태를 구조화된 형식으로 보고합니다.
각 규칙은 분류(ALWAYS/NEVER), WHY(이유), 코드 예시, 검증 기준으로 구성됩니다. 몇 가지 대표적인 규칙을 살펴보겠습니다.
A-01: 단방향 의존성
허용: app → features → shared
금지: shared → features, features → features양방향 의존성은 순환 참조를 만들고, 하나의 변경이 예측 불가능한 곳에 전파됩니다. 이 규칙으로 Feature 간 직접 import를 차단합니다.
S-02: useEffect 내 파생 상태 계산 금지
// ❌ useEffect로 파생 상태 → 이중 렌더
const [items, setItems] = useState<Item[]>([]);
const [total, setTotal] = useState(0);
useEffect(() => {
setTotal(items.reduce((sum, item) => sum + item.price, 0));
}, [items]);
// ✅ 렌더 중 직접 계산
const total = items.reduce((sum, item) => sum + item.price, 0);useEffect로 파생 상태를 계산하면 렌더가 두 번 발생합니다. 렌더 본문에서 직접 계산하거나, 비용이 크면 useMemo를 사용합니다.
C-01: 컴포넌트 내부 컴포넌트 정의 금지
// ❌ 매 렌더마다 Child가 새 타입으로 생성 → state 소실
function Parent() {
const Child = () => <input />;
return <Child />;
}
// ✅ 외부에 정의
const Child = () => <input />;
function Parent() {
return <Child />;
}렌더 함수 안에서 컴포넌트를 정의하면 매 렌더마다 새로운 함수 참조가 생성됩니다. React reconciler가 이를 다른 타입으로 인식해 state가 소실됩니다.
reference-code/ 디렉토리에는 28개의 패턴별 구현 예시가 있습니다. 파일명 자체가 태그 역할을 합니다.
compound-component--context--generic.md
http-client--acl--dependency-inversion.md
controlled--uncontrolled--discriminated-union.md
msw--mock--integration-test.md레퍼런스 코드의 핵심 제약은 도메인 비의존성입니다. workspace, chat, order 같은 프로젝트 특화 용어 대신 Entity, Resource 같은 범용 플레이스홀더를 사용합니다. "이 레퍼런스를 다른 프로젝트에 그대로 복사할 수 있는가?"가 판단 기준입니다.
CRUD, 인증, 검색, 리스트 필터링 같은 공통 시나리오는 별도 디렉토리로 분류되어 있어, 복잡한 기능을 구현할 때 여러 레퍼런스를 조합할 수 있습니다.
스킬은 .claude/skills/ 디렉토리에 두는 것만으로 활성화됩니다. Claude Code가 프로젝트를 열면 자동으로 스킬을 인식합니다.
# 레포지토리에 스킬 추가
git clone https://github.com/load28/remote.git
cp -r remote/.claude/skills/load28-react .claude/skills/이후 Claude에게 React 코드를 요청하면, 3단계 프로토콜에 따라 레퍼런스를 참조하고, 규칙을 검증한 결과를 함께 보고합니다.
Claude가 컴포넌트를 작성하면 다음과 같은 리포트가 함께 나옵니다.
[Phase 2 검증 결과]
✅ C-01: 외부에 컴포넌트 정의 — 통과
✅ S-02: 파생 상태 렌더 본문에서 계산 — 통과
✅ N-03: 이벤트 핸들러 handle* 접두사 — 통과
⚠️ C-04: props 8개 → 7개 이하로 분리 필요
→ UserCard에서 avatar 관련 props를 AvatarProps로 그룹화단순히 코드를 생성하는 것이 아니라, 왜 그렇게 작성했는지를 규칙 번호와 함께 설명합니다.
기존 카테고리에 새 규칙을 추가하는 것이 가장 간단합니다. 규칙은 일관된 포맷을 따릅니다.
## S-18: 새로운 상태관리 규칙
**분류:** NEVER
**WHY:** 이 패턴이 왜 문제인지 한 문장으로 설명합니다.
// ❌ BAD: 안티패턴 코드
// ✅ GOOD: 권장 패턴 코드
**검증:** 이 규칙 위반을 어떻게 탐지하는지 기준을 기술합니다.각 규칙에 WHY가 반드시 포함되어야 합니다. "왜"가 없는 규칙은 맹목적인 관례가 되고, Claude도 상황에 맞게 유연하게 적용하지 못합니다.
새로운 패턴이 필요하면 reference-code/에 태그 형식의 파일을 추가합니다.
_tags.md에 새 태그를 등록합니다tag1--tag2--tag3.md 형식으로 파일을 생성합니다# 예: React Hook Form + Zod 검증 패턴 추가
touch reference-code/react-hook-form--zod--validation.md프로젝트에 특화된 규칙이 필요하다면 새 마크다운 파일을 추가합니다. 예를 들어 Next.js App Router 규칙이라면 nextjs-app-router.md를 추가하고, SKILL.md의 검증 목록에 새 카테고리를 포함시킵니다.
load28-react는 React에 특화되어 있지만, 같은 구조로 다른 기술 스택의 스킬을 만들 수 있습니다.
.claude/skills/
├── load28-react/ # React 컨벤션
├── load28-nestjs/ # NestJS 백엔드 컨벤션
└── load28-infra/ # 인프라/배포 컨벤션3단계 프로토콜(레퍼런스 조회 → 검증 → 리포팅)은 기술 스택과 무관하게 재사용할 수 있는 프레임워크입니다. 규칙 내용만 바꾸면 됩니다.
코딩 컨벤션은 문서화만으로는 부족합니다. 문서는 읽히지 않고, 읽혀도 잊히고, 잊히면 리뷰에서 매번 같은 피드백이 반복됩니다. load28-react 스킬은 이 반복을 자동화된 검증 프로세스로 전환합니다.
78개의 규칙이 많아 보일 수 있지만, 핵심은 단순합니다. 컴포넌트 설계, 상태관리, 성능, 테스트에서 자주 발생하는 실수를 패턴으로 정리하고, 코드 작성 시점에 자동으로 검증하는 것입니다.
AI 코드 어시스턴트의 가치는 코드를 빠르게 생성하는 데 있는 것이 아닙니다. 팀의 기준에 맞는 코드를 일관되게 생성하는 것이 진짜 가치입니다. 스킬 시스템은 그 기준을 코드로 표현할 수 있게 해줍니다.