AI 코딩 어시스턴트 Skill 구성 전략: CLAUDE.md부터 AGENTS.md까지

이 글은 AI 코딩 어시스턴트의 Skill 시스템 시리즈의 일부다.

원칙: 적게, 정확하게, 단계적으로

Skill 구성의 핵심은 필요한 정보를 필요한 시점에 정확한 양만큼 제공하는 것이다. LLM은 지시사항이 150~200개를 넘어가면 신뢰성 있게 따르기 어렵다. 정보를 많이 넣는다고 좋은 게 아니다.

세 가지 원칙:

적게: 하나의 파일에 하나의 주제. 300줄을 넘기지 않는다.
정확하게: 모호한 표현 대신 구체적인 규칙과 예시를 준다.
단계적으로: 항상 필요한 정보 → 자주 필요한 정보 → 가끔 필요한 정보 순으로 분리한다.

CLAUDE.md 잘 쓰는 법

CLAUDE.md는 모든 대화에 자동으로 포함되는 유일한 파일이다. 그만큼 내용 선별이 중요하다.

포함해야 하는 것

WHAT — 프로젝트가 무엇인가:

# my-project
Next.js 16 기반 블로그. Velite + MDX로 콘텐츠 관리.

HOW — 어떻게 빌드하고 실행하는가:

## Commands
bun dev         # 개발 서버
bun run build   # 프로덕션 빌드
bun run test    # 테스트

WHY — 핵심 결정과 그 이유:

## Key Decisions
- Tailwind v4: CSS 변수 기반 다크모드를 위해 선택
- Velite: MDX를 JSON으로 변환하는 빌드 파이프라인 필요

규칙 — 반드시 지켜야 할 것:

## Conventions
- UI 문자열은 한국어
- 컴포넌트 임포트는 "@/components/" 경로 사용
- 새 페이지에는 generateMetadata 필수

포함하지 말아야 하는 것

린팅 수준의 규칙: ESLint, Prettier, Biome 같은 도구가 처리할 일. "세미콜론을 써라" 같은 건 .eslintrc에 넣는다.
전체 API 문서: CLAUDE.md가 아니라 별도 Skill의 참조 파일로 분리한다.
임시적인 정보: "현재 버그 수정 중" 같은 세션 종속 정보는 넣지 않는다.
너무 상세한 코드 예시: 핵심 패턴 1~2개면 충분. 나머지는 코드베이스 자체가 예시다.

크기 가이드

프로젝트 규모	CLAUDE.md 권장 크기
소규모 (개인 프로젝트)	50~100줄
중규모 (팀 프로젝트)	100~200줄
대규모 (모노레포)	150~300줄 + 하위 CLAUDE.md

300줄을 넘어가면 모든 대화에 불필요한 컨텍스트가 포함된다는 뜻이다. Skill로 분리할 시점이다.

Skill 폴더 설계

참조형 Skill 구조

코딩 컨벤션, 아키텍처 가이드처럼 "이런 걸 알아두라" 는 지식:

.claude/skills/api-conventions/
  SKILL.md            ← 핵심 규칙 요약 (200줄 이내)
  references/
    error-handling.md ← 에러 처리 상세 가이드
    pagination.md     ← 페이지네이션 패턴
    auth.md           ← 인증/인가 플로우

SKILL.md에는 핵심 원칙만 넣고, 상세 내용은 참조 파일로 분리한다. Claude가 실제로 에러 핸들링 코드를 작성할 때만 error-handling.md를 로딩한다.

작업형 Skill 구조

배포, 리뷰, 커밋처럼 "이렇게 해라" 는 워크플로우:

.claude/skills/deploy/
  SKILL.md            ← 배포 절차 정의
  scripts/
    health-check.sh  ← 배포 후 헬스체크 스크립트

작업형 Skill은 /deploy처럼 직접 호출한다. 단계별 절차를 명확하게 정의하고, 필요한 스크립트를 함께 둔다.

모노레포에서의 Skill 배치

모노레포에서는 근접성 원칙을 활용한다:

monorepo/
  CLAUDE.md                     ← 전체 프로젝트 공통 규칙
  .claude/skills/
    ci-cd/SKILL.md             ← 공통 CI/CD 워크플로우

  packages/
    api/
      CLAUDE.md                ← API 서비스 특화 규칙
      .claude/skills/
        db-migrations/SKILL.md ← DB 마이그레이션 절차

    web/
      CLAUDE.md                ← 웹 프론트엔드 특화 규칙
      .claude/skills/
        component-guide/SKILL.md ← 컴포넌트 작성 가이드

Claude는 현재 작업 중인 파일의 위치를 기준으로 가장 가까운 CLAUDE.md와 Skill을 우선 적용한다. packages/api/ 아래에서 작업하면 API 특화 규칙이 우선이다.

Skill 작성 팁

1. 구체적인 예시를 준다

# BAD
에러 핸들링을 잘 해주세요.
 
# GOOD
## 에러 핸들링 규칙
비즈니스 에러는 커스텀 클래스를 사용한다:
 
// GOOD
throw new InsufficientBalanceError({ required: 1000, current: 500 });
 
// BAD
throw new Error("잔액이 부족합니다");

"잘 해주세요"는 아무 효과가 없다. 좋은 예시와 나쁜 예시를 함께 보여주면 모델이 패턴을 명확히 이해한다.

2. 하나의 주제에 하나의 파일

# BAD: 하나의 SKILL.md에 모든 것
## 에러 핸들링
...
## 데이터베이스 규칙
...
## API 설계
...
## 테스트 패턴
...
(500줄+)
 
# GOOD: 주제별 분리
.claude/skills/
  error-handling/SKILL.md
  database/SKILL.md
  api-design/SKILL.md
  testing/SKILL.md

주제별로 분리하면 관련 있는 Skill만 로딩되어 컨텍스트를 절약하고, 유지보수도 쉬워진다.

3. 명령형으로 쓴다

# BAD (설명적)
이 프로젝트에서는 일반적으로 TypeScript를 사용하며,
타입 안전성을 위해 strict 모드가 활성화되어 있습니다.
 
# GOOD (명령형)
TypeScript strict 모드 사용. any 타입 금지.
타입 단언(as)보다 타입 가드를 우선 사용한다.

Skill은 기술 문서가 아니라 지시사항이다. 간결한 명령형이 모델의 준수율을 높인다.

4. 동적 컨텍스트를 활용한다

Claude Code Skill에서는 !`command` 문법으로 셸 명령의 출력을 동적으로 주입할 수 있다:

---
name: review-pr
description: PR 코드 리뷰
---
현재 PR의 diff를 리뷰한다:
 
!`gh pr diff`
 
리뷰 기준:
1. 타입 안전성 확인
2. 에러 핸들링 패턴 준수
3. 테스트 커버리지

이렇게 하면 Skill이 호출될 때 gh pr diff의 실제 출력이 컨텍스트에 포함된다. 정적 지시사항 + 동적 데이터의 조합이다.

5. 금지 사항을 명시한다

## 절대 하지 말 것
- `git push --force` 사용 금지 (--force-with-lease 사용)
- `.env` 파일을 커밋에 포함하지 않음
- `any` 타입 사용 금지
- `console.log` 프로덕션 코드에 남기지 않음

"이렇게 해라"보다 "이건 절대 하지 마라" 가 더 확실하게 작동한다. 특히 위험한 명령어나 보안 관련 규칙은 반드시 금지 사항으로 명시한다.

팀 공유 전략

Git으로 버전 관리

Skill 파일은 코드와 함께 Git으로 관리한다. 이것이 RAG 대비 가장 큰 운영 장점이다:

변경 이력 추적: 누가 언제 왜 규칙을 바꿨는지 Git 로그로 확인
PR 리뷰: Skill 변경도 코드 리뷰와 동일한 프로세스
브랜치별 실험: 새 규칙을 브랜치에서 먼저 테스트
롤백: 문제 있으면 이전 커밋으로 복원

git log --oneline .claude/skills/
# a1b2c3d 에러 핸들링 규칙에 타임아웃 처리 추가
# d4e5f6g API 응답 포맷 v2로 업데이트
# g7h8i9j 초기 Skill 구조 설정

온보딩 효과

새 팀원이 합류하면:

레포를 클론한다
CLAUDE.md와 Skills가 함께 받아진다
첫날부터 팀의 규칙을 알고 있는 AI 어시스턴트를 사용한다

별도의 RAG 파이프라인 설정, 벡터 DB 접근 권한 설정이 필요 없다. 코드가 있는 곳에 지식도 있다.

AGENTS.md로 크로스 도구 표준화

팀에서 Claude Code, Cursor, Copilot을 섞어 쓰는 경우가 흔하다. 각 도구마다 별도 설정 파일을 관리하면 동기화가 어렵다.

AGENTS.md 활용

AGENTS.md는 25개 이상의 AI 코딩 도구에서 인식하는 벤더 중립 표준이다:

# AGENTS.md
 
## Project Overview
Next.js 16 blog with Velite + MDX.
 
## Build
bun dev      → development server
bun run build → production build
 
## Conventions
- TypeScript strict mode, no `any`
- UI strings in Korean
- Import components from "@/components/"

이 파일 하나로 Claude Code, Cursor, Copilot, Codex 모두에게 같은 지시를 준다.

근접성 기반 우선순위

AGENTS.md의 핵심 원칙은 근접성이다:

project/
  AGENTS.md              ← 전체 프로젝트 기본 규칙
  src/
    api/
      AGENTS.md          ← API 코드에만 적용되는 규칙
    frontend/
      AGENTS.md          ← 프론트엔드에만 적용되는 규칙

src/api/handler.ts를 편집할 때 src/api/AGENTS.md가 project/AGENTS.md보다 우선한다. 충돌 시 더 가까운 파일이 이긴다.

도구별 추가 설정

AGENTS.md로 공통 규칙을 관리하고, 도구 특화 기능이 필요하면 해당 도구의 설정을 추가한다:

project/
  AGENTS.md                      ← 공통 (모든 도구)
  CLAUDE.md                      ← Claude Code 추가 설정
  .claude/skills/deploy/SKILL.md ← Claude Code 전용 워크플로우
  .cursor/rules/react.mdc        ← Cursor 전용 규칙

점진적 Skill 확장 전략

Skill의 핵심 강점은 처음부터 완벽할 필요가 없다는 것이다. 작게 시작해서 점진적으로 키운다.

4단계 성장 모델

1단계: 씨앗 (1일차)

CLAUDE.md에 최소한의 정보만 넣는다:

# my-project
Node.js API 서버. TypeScript + Express.
 
## 명령어
npm run dev    # 개발 서버
npm run test   # 테스트
npm run build  # 빌드

이것만으로도 AI가 프로젝트를 인식하고 올바른 명령어를 사용한다.

2단계: 반응형 성장 (1~2주차)

AI가 실수할 때마다 CLAUDE.md에 규칙을 추가한다:

## 규칙
- import 경로는 "@/" alias 사용 (상대 경로 금지)
- 에러 응답은 { error: { code, message } } 형태
- DB 쿼리는 반드시 트랜잭션 안에서 실행

이 단계에서 CLAUDE.md는 "AI가 틀렸던 것들의 기록" 이 된다. 실수가 곧 규칙이 되는 피드백 루프다.

3단계: 구조화 (1개월차)

CLAUDE.md가 100줄을 넘으면 Skill로 분리한다:

CLAUDE.md (50줄)           ← 핵심 정보만 유지
.claude/skills/
  api-patterns/SKILL.md   ← API 설계 규칙 (CLAUDE.md에서 분리)
  db-conventions/SKILL.md  ← DB 관련 규칙 (CLAUDE.md에서 분리)
  deploy/SKILL.md          ← 배포 워크플로우 (새로 추가)

4단계: 성숙 (3개월+)

팀의 워크플로우와 지식이 Skill로 체계화된다:

.claude/skills/
  api-patterns/
    SKILL.md              ← 핵심 원칙
    references/
      error-codes.md      ← 에러 코드 목록
      pagination.md       ← 페이지네이션 패턴
  testing/
    SKILL.md              ← 테스트 전략
    references/
      fixtures.md         ← 테스트 픽스처 가이드
  deploy/SKILL.md
  review/SKILL.md
  onboarding/SKILL.md     ← 새 팀원용 가이드

Auto Memory 활용하기

Claude Code의 Auto Memory(~/.claude/projects/*/memory/MEMORY.md)를 적극 활용한다. 세션에서 중요한 패턴을 발견하면 Claude에게 기억하라고 말하면 된다:

사용자: "이 프로젝트에서 날짜는 항상 dayjs를 써. 기억해둬."
→ Claude가 MEMORY.md에 기록
→ 다음 세션부터 자동 적용

Auto Memory에 적합한 것:

프로젝트 특화 패턴 ("이 프로젝트는 date-fns 대신 dayjs 사용")
반복되는 디버깅 인사이트 ("이 에러는 대부분 환경 변수 누락")
사용자 선호 ("커밋 메시지는 한국어로")

Auto Memory와 Skill의 차이:

Auto Memory: 개인적, 자동으로 축적, 가벼운 메모
Skill: 팀 공유, 의도적으로 작성, 구조화된 지식

Auto Memory에서 반복적으로 나타나는 패턴이 보이면 Skill로 승격시킨다.

커뮤니티 Skill 활용

처음부터 모든 Skill을 직접 만들 필요는 없다. 커뮤니티에서 검증된 Skill을 가져다 쓸 수 있다:

awesome-cursorrules: 기술 스택별 Cursor 규칙 모음
cursor.directory: 커뮤니티 공유 규칙 검색
Anthropic skills 저장소: 공식 Skill 템플릿

커뮤니티 Skill을 가져온 뒤 프로젝트에 맞게 커스터마이즈하는 것이 가장 효율적이다. 그대로 쓰면 프로젝트 맥락과 맞지 않을 수 있다.

자주 하는 실수

1. CLAUDE.md에 모든 걸 넣는다

300줄을 넘는 CLAUDE.md는 모든 대화를 느리게 만든다. Skill로 분리할 수 있는 내용은 분리한다.

2. 너무 추상적으로 쓴다

"코드 품질을 높여주세요"는 아무 의미가 없다. "함수는 20줄 이내, 매개변수는 3개 이내, 중첩 if는 2단계까지"처럼 측정 가능한 기준을 준다.

3. 상충하는 규칙을 만든다

프로젝트 CLAUDE.md에서 "간결한 코드를 작성하라"고 하면서 Skill에서 "모든 에러 케이스에 대해 상세한 로깅을 추가하라"고 하면 모델이 혼란스러워한다. 규칙 간 일관성을 유지한다.

4. 한 번 쓰고 방치한다

프로젝트가 발전하면 규칙도 변한다. 분기마다 Skill을 리뷰하고 오래된 규칙을 정리한다. 코드와 Skill이 괴리되면 AI가 엉뚱한 코드를 작성한다.

5. Skill로 린팅을 대체하려 한다

"세미콜론을 써라", "들여쓰기는 2칸"은 ESLint/Prettier의 영역이다. Skill은 도구로 강제할 수 없는 고차원 규칙(아키텍처 패턴, 비즈니스 로직 구조, 네이밍 컨벤션)에 집중한다.

체크리스트: Skill 도입 시 점검 사항

CLAUDE.md가 300줄 이내인가?
하나의 SKILL.md가 하나의 주제만 다루는가?
모든 규칙에 구체적인 예시(GOOD/BAD)가 있는가?
상세 참조 문서가 별도 파일로 분리되어 있는가?
금지 사항이 명시되어 있는가?
Git으로 버전 관리되고 있는가?
다른 도구 사용자를 위해 AGENTS.md가 있는가?
분기별 리뷰 일정이 잡혀 있는가?

RAG vs Skill: 언제 무엇을 쓸까에서 다룬 것처럼, Skill이 적합한 영역과 RAG가 필요한 영역을 구분한 뒤, 이 가이드에 따라 Skill을 구성하면 벡터 DB 없이도 AI 어시스턴트에게 풍부한 도메인 지식을 줄 수 있다.