클로드 코드 스킬 만들기: 쓸수록 좋아지는 시스템 구조

프로젝트마다 Claude Code 스킬을 쓸 때 적용하는 표준 구조입니다. 스킬이 프로젝트 맥락을 공유하고, 피드백을 기억하고, 쓸수록 좋아지는 환경을 만듭니다. MindStudio의 Four Pattern Framework에서 가져온 개념을 Anthropic 표준 구조 위에 얹어서 정리한 것입니다.

프로젝트 표준 구조

my-project/
├── CLAUDE.md               ← 프로젝트 기술 규칙
├── learnings.md            ← 피드백 축적소
├── knowledge/              ← 참조 지식 (스킬이 명시할 때만 읽힘)
└── .claude/
    ├── rules/              ← 기본 지식 (자동 로드, Anthropic 표준)
    │   ├── voice.md        ← 톤, 문체, 금지 표현
    │   └── audience.md     ← 타겟 독자/사용자
    ├── skills/             ← 개별 기능 단위
    └── commands/           ← 스킬을 엮은 워크플로우

각 파일의 역할

• .claude/rules/: 항상 자동 로드되는 기본 지식 (Anthropic 표준)
  • voice.md, audience.md 등 모든 결과물에 영향을 주는 것을 여기에 둔다.
  • CLAUDE.md에 별도 규칙 없이도 매 세션 자동 적용.
• knowledge/: 스킬이 필요할 때만 읽는 참조 지식 (선택적)
  • SKILL.md에 "knowledge/pricing.md 참조"처럼 명시한 스킬만 읽는다.
  • 규칙이 바뀌면 해당 파일만 수정 → 참조하는 스킬들에 자동 반영.
• learnings.md: 피드백이 쌓이는 곳
  • "너무 길어", "톤이 다르잖아" 같은 수정 사항이 스킬별 섹션으로 기록된다.
• .claude/commands/: 스킬을 순서대로 엮은 워크플로우
  • 커맨드 하나로 리서치 → 작성까지 한 세션에서 이어진다.
• CLAUDE.md: 기술적 규칙. 빌드 명령, 린트, 아키텍처 결정.

글로벌 설정 설명

하단에 복붙 설정이 있습니다.

~/.claude/CLAUDE.md에 추가된 규칙

Learnings Loop 섹션:

• 사용자 피드백 감지 → learnings.md에 기록
• 기록 형식: 스킬별 h2 섹션 + YYYY.MM.DD : 내용
• 모호한 피드백은 기록 안 하고 되물음
• 스킬 실행 전 learnings.md 참조, knowledge/는 SKILL.md에 명시된 것만
• 기본 지식(톤, 타겟)은 .claude/rules/에서 자동 로드
• 컨텍스트 위생: 필요한 것만 읽기, 끝난 건 요약으로 대체

글로벌 커맨드 2개

~/.claude/commands/
├── wrap-up.md         ← /wrap-up
└── project-init.md    ← /project-init

사용법

새 프로젝트 시작

/project-init

표준 구조를 생성합니다:

• .claude/rules/ (voice.md, audience.md)
• knowledge/ (빈 폴더, 필요할 때 추가)
• learnings.md
• CLAUDE.md에 knowledge 참조 규칙 추가

생성 후 .claude/rules/voice.md부터 채웁니다. 가장 효과가 큽니다.

작업 중

피드백을 주면 글로벌 CLAUDE.md 규칙에 의해 learnings.md에 기록됩니다. 별도 조작 필요 없음.

세션 마무리

/wrap-up

이번 대화의 피드백을 정리합니다:

1. 대화에서 수정/지적 사항 수집
2. learnings.md에 스킬별 섹션으로 정리
3. 같은 패턴이 3회 이상 반복 → SKILL.md 지시문에 승격
4. 요약 보고

흐름 한눈에

  /project-init
       │
       ▼
  .claude/rules/ 채우기 (voice.md 우선)
       │
       ▼
  ┌────────────────────────────────────┐
  │         평소 작업 세션                │
  │                                    │
  │  스킬 실행                           │
  │    └─ .claude/rules/ 자동 참조       │
  │    └─ learnings.md 참조             │
  │    └─ knowledge/ 명시된 것만 참조      │
  │         │                          │
  │  피드백 발생                          │
  │    └─ learnings.md에 기록 (자동)      │
  │                                    │
  └────────────────────────────────────┘
       │
       ▼
  /wrap-up (세션 끝)
       │
       ├─ learnings 정리
       └─ 성숙한 교훈 → SKILL.md 승격

원칙 요약