Skill을 시스템으로 만드는 구조

프로젝트마다 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 승격

원칙 요약

복붙용 설정 파일

1. ~/.claude/CLAUDE.md에 추가

## Learnings Loop

프로젝트에 `learnings.md`가 있으면 아래 규칙을 적용할 것.

### 피드백 감지 → 기록
- 사용자가 결과물을 수정하거나 불만을 표현하면 ("너무 길어", "톤이 다르잖아", "이건 빼") 이것은 피드백이다
- 피드백에서 **조건 + 기대 행동**을 추출하여 `learnings.md`에 기록
- 모호한 피드백("별로야")은 기록하지 말고, 구체적으로 무엇이 문제인지 되물을 것

### learnings.md 포맷
- 스킬별로 `##` (h2)으로 섹션을 나눈다
- 각 항목은 `- YYYY.MM.DD : 내용` 형식으로 해당 스킬 섹션 아래에 추가
- 스킬 섹션이 없으면 새로 만들고, 있으면 기존 섹션에 추가
- 예시:

  ## write-blog
  - 2026.03.15 : 본문 800자 초과 → 800자 이내로 제한
  - 2026.03.22 : "~입니다" 체 안 맞음 → "~해요" 체로 통일

  ## okabang-archive
  - 2026.03.29 : 배경 섹션이 추상적 → 구체적 문제 상황으로 시작할 것

### 스킬 실행 전 참조
- 스킬 실행 시 `learnings.md`에서 해당 스킬 관련 항목을 먼저 읽고 반영
- `knowledge/` 폴더가 있으면 SKILL.md에 명시된 파일만 읽을 것. 전부 읽지 말 것
- 기본 지식(톤, 타겟)은 `.claude/rules/`에 있으므로 자동 로드됨

### 컨텍스트 위생
- 지금 작업에 필요한 파일만 읽을 것. "혹시 몰라서" 미리 읽지 말 것
- 서브태스크 완료 후 원본 내용은 요약으로 대체하고 다음으로 넘어갈 것

2. ~/.claude/commands/project-init.md

이 프로젝트에 스킬 시스템 표준 구조를 세팅해줘.

## 생성할 것

### 1. .claude/rules/ 폴더 (자동 로드되는 기본 지식)
빈 폴더로 생성. 필요할 때 규칙 파일을 추가하면 됨.

### 2. learnings.md
프로젝트 루트에 생성:
```
# Learnings
피드백이 쌓이면 여기에 기록됩니다. /wrap-up으로 정리.
```

### 3. .claude/skills/ 폴더 (프로젝트 스킬)
프로젝트 전용 스킬을 넣는 폴더. 빈 폴더로 생성.

### 4. .claude/commands/ 폴더 (프로젝트 명령어)
프로젝트 전용 슬래시 명령어를 넣는 폴더. 빈 폴더로 생성.

### 5. knowledge/ 폴더 (선택적 참조 지식)
스킬이 명시할 때만 읽히는 참조용 지식 폴더. 빈 폴더로 생성.

### 6. CLAUDE.md 확인
프로젝트 루트에 CLAUDE.md가 이미 있으면 아래 내용이 포함되어 있는지 확인하고, 없으면 추가:

```
## Knowledge
- knowledge/ 파일은 SKILL.md에 명시된 것만 읽을 것
```

CLAUDE.md가 없으면 새로 생성.

## 생성 후
- 생성한 파일 목록을 보여줄 것
- "필요한 규칙이 있으면 .claude/rules/에 추가하면 됩니다" 라고 안내

3. ~/.claude/commands/wrap-up.md

이번 세션의 대화를 리뷰하고 learnings를 정리해줘.

## 1단계: 피드백 수집
이번 대화에서 사용자가 결과물을 수정하거나 지적한 부분을 모두 찾아라.
각각에서 추출할 것:
- 어떤 작업/스킬에서 발생했는지
- 뭐가 잘못됐는지
- 어떻게 해야 맞는지 (조건 → 기대 행동)

## 2단계: learnings.md 업데이트
프로젝트 루트에 learnings.md가 있으면 거기에 추가. 없으면 새로 생성.
스킬별로 ## (h2)으로 섹션을 나누고, 각 항목은 아래 형식으로 추가:

## 스킬명
- YYYY.MM.DD : 조건 → 기대 행동

이미 있는 항목과 중복이면 추가하지 말고, 기존 항목에 횟수 표시를 갱신.

## 3단계: 성숙한 교훈 승격
learnings.md에서 같은 패턴이 3회 이상 반복된 항목을 확인.
해당 항목이 있으면:
1. 관련 SKILL.md (또는 CLAUDE.md)의 지시문에 규칙으로 추가
2. learnings.md에서 해당 항목에 [승격됨] 표시

## 4단계: 요약 보고
- 이번 세션에서 새로 기록한 교훈 수
- 승격된 항목이 있으면 어떤 스킬에 반영했는지
- 다음 세션에서 주의할 점