Skill을 점진적으로 키우는 법: 컨텍스트 파이프라이닝과 정제 워크플로우
AI 코딩 어시스턴트의 Skill을 작게 시작해서 체계적으로 키워나가는 방법. 컨텍스트 파이프라이닝, Claude A/B 패턴, Auto Memory 승격, 평가 기반 정제까지 실전 워크플로우를 정리한다.
이 글은 AI 코딩 어시스턴트의 Skill 시스템 시리즈의 일부다.
Skill은 한 번에 완성되지 않는다
Skill을 처음 도입하려면 "어디서부터 시작하지?"라는 막막함이 있다. 프로젝트의 모든 규칙을 한 번에 정리하려고 하면 금방 지친다. 실제로 잘 동작하는 Skill은 작게 시작해서 실수를 먹으면서 자라난 것들이다.
이 글에서는 Skill을 점진적으로 키워나가는 구체적인 워크플로우를 다룬다. 핵심은 두 가지다:
- 컨텍스트 파이프라이닝: 지식을 계층적으로 배치하여 필요한 정보가 필요한 시점에 로딩되도록 설계
- 정제 루프: AI의 실수를 관찰하고, 그 실수가 반복되지 않도록 Skill을 개선하는 순환 과정
컨텍스트 파이프라이닝
3계층 파이프라인
Skill은 단순히 파일을 나열하는 게 아니다. 넓은 것에서 좁은 것으로, 정적인 것에서 동적인 것으로 흘러가는 파이프라인으로 설계해야 한다.
Tier 1: CLAUDE.md (항상 로딩)
"이 프로젝트는 무엇이고, 핵심 명령어는 뭔가"
→ 50~100줄, ~2% 컨텍스트 사용
│
▼
Tier 2: Skills / Rules (필요 시 로딩)
"이 작업은 어떤 규칙을 따르는가"
→ 주제별 분리, 관련 태스크에서만 로딩
│
▼
Tier 3: Auto Memory + 참조 파일 (동적)
"이전에 뭘 배웠고, 상세 스펙은 뭔가"
→ 세션 간 학습, 상세 레퍼런스
각 계층이 독립적으로 성장한다. Tier 1이 비대해지면 Tier 2로 분리하고, Tier 3에서 반복되는 패턴이 보이면 Tier 2로 승격시킨다.
왜 파이프라인인가
200K 토큰 컨텍스트 윈도우가 있다고 해서 다 채워 넣으면 안 된다. 컨텍스트 윈도우의 40~60%만 사용하는 것이 최적이다. 나머지는 대화 중 발생하는 예상치 못한 상황(긴 에러 메시지, 큰 파일 읽기 등)에 대비해야 한다.
파이프라인의 각 계층은 이 예산을 효율적으로 관리하는 전략이다:
| 계층 | 토큰 예산 | 로딩 시점 |
|---|---|---|
| CLAUDE.md | ~2,000 (상시) | 항상 |
| 활성 Skill 1~2개 | ~5,000 (태스크별) | LLM 판단으로 선택 |
| 참조 파일 | ~10,000 (필요 시) | 서브태스크에서만 |
| Auto Memory | ~1,000 (상시) | MEMORY.md 첫 200줄 |
합치면 약 18,000토큰, 200K 윈도우의 ~9%. 나머지 91%가 실제 작업에 활용된다.
KV-Cache를 고려한 설계
LLM API에서 캐시된 입력 토큰은 일반 입력 토큰보다 10배 저렴하다. CLAUDE.md와 Skill 구조가 세션 간에 안정적이면 캐시 적중률이 높아져 비용이 크게 절감된다.
실전 팁:
- CLAUDE.md를 자주 바꾸지 않는다 (캐시 무효화 방지)
- Skill의 순서와 구조를 일관되게 유지한다
- 동적 내용(
!`command`)은 Skill 끝에 배치한다 (앞부분 캐시 유지)
정제 워크플로우
1단계: 즉시 캡처
AI가 실수하거나 반복적으로 같은 질문에 답하고 있으면, 그 자리에서 바로 캡처한다. 마찰을 최소화하는 것이 핵심이다.
방법 1: 직접 말하기
사용자: "앞으로 이 프로젝트에서는 date-fns 대신 dayjs를 써. 기억해."
→ Claude가 MEMORY.md에 기록
방법 2: # 단축키 (Claude Code)
세션 중 #을 입력하면 CLAUDE.md를 직접 편집할 수 있다. 떠오르는 규칙을 즉시 기록한다.
방법 3: PR 리뷰에서 캡처
코드 리뷰 중 "이건 원래 이렇게 하는 건데..."라는 말이 나오면, 그 규칙을 CLAUDE.md나 Skill에 추가하는 커밋을 같은 PR에 포함시킨다.
2단계: Claude A/B 패턴으로 정제
Anthropic이 권장하는 Skill 정제 방법이다:
Claude A (전문가) Claude B (테스터)
│ │
│ 1. Skill 없이 작업 수행 │
│ 2. 반복 제공하는 정보 파악 │
│ 3. Skill 초안 작성 │
│ │
│ Skill 전달 ──────────▶│
│ │ 4. Skill만으로 같은 작업 수행
│ │ 5. 실패/부족한 부분 관찰
│◀──────── 피드백 전달 │
│ │
│ 6. Skill 개선 │
│ 재전달 ──────────────▶│
│ │ 7. 재테스트
└──────────────────────────────┘
핵심 포인트: Claude A에게 "이 Skill을 쓴 다른 Claude가 날짜 필터링을 빼먹었어"처럼 구체적인 실패 사례를 알려준다. 추상적인 "더 좋게 만들어줘"는 효과가 없다.
3단계: 평가 기반 개선
Skill이 커지면 "잘 동작하는지" 감으로 판단하기 어렵다. 평가를 도입한다.
간단한 평가 방법:
- Skill이 해결해야 할 대표 태스크 3개를 정한다
- Skill 없이 실행 → 결과 기록 (기준선)
- Skill 있이 실행 → 결과 비교
- 개선이 없으면 Skill을 수정
# 예: 배포 Skill 평가
# 태스크 1: "프로덕션에 배포해줘" → 올바른 절차를 따르는가?
# 태스크 2: "스테이징에 배포해줘" → 환경을 구분하는가?
# 태스크 3: "롤백해줘" → 롤백 절차를 아는가?자동화된 평가:
Skill이 트리거되었는지(활성화율), 올바른 Skill이 선택되었는지(선택 정확도)를 자동으로 측정할 수 있다. cc-plugin-eval 같은 프레임워크가 이를 지원한다.
Auto Memory에서 Skill로의 승격
모든 지식이 처음부터 Skill이 될 필요는 없다. Auto Memory → CLAUDE.md → Skill로 자연스럽게 승격되는 경로가 있다.
승격 기준
| 신호 | 현재 위치 | 승격 대상 |
|---|---|---|
| 3회 이상 같은 메모가 MEMORY.md에 등장 | Auto Memory | CLAUDE.md 또는 Rules |
| CLAUDE.md가 200줄을 넘어감 | CLAUDE.md | Skill로 분리 |
| 단일 규칙이 참조 파일과 예시가 필요 | Rules 파일 | 독립 Skill (폴더) |
| 워크플로우에 스크립트가 결합됨 | Skill | Skill + scripts/ |
승격 예시
[1주차] MEMORY.md에 기록됨:
"이 프로젝트는 API 응답에서 snake_case를 쓴다"
[2주차] 같은 내용이 반복 등장 → CLAUDE.md로 이동:
## API 규칙
- 응답 필드는 snake_case
[1개월] API 규칙이 10줄로 늘어남 → Rules 파일로 분리:
.claude/rules/api-conventions.md
[2개월] 에러 코드 목록, 페이지네이션 패턴 추가 → Skill로 승격:
.claude/skills/api-conventions/
SKILL.md
references/
error-codes.md
pagination.md
각 단계에서 이전 위치의 내용은 삭제한다. 같은 정보가 여러 곳에 있으면 충돌이 생긴다.
Skill 수명 관리
언제 업데이트하는가
- AI가 같은 실수를 반복할 때 → 규칙을 더 구체적으로 강화
- 코드가 변경되었을 때 → 코드와 함께 같은 PR에서 Skill 업데이트
- 새 팀원이 같은 질문을 할 때 → FAQ성 지식을 Skill에 추가
- 평가 점수가 떨어졌을 때 → Skill이 낡았다는 신호
언제 합치거나 삭제하는가
- 두 Skill의 내용이 70% 이상 겹치면 → 합치기
- 6개월 이상 트리거되지 않은 Skill → 삭제 검토
- 코드에서 해당 패턴이 사라졌으면 → 삭제
Skill 수가 많아질수록 LLM이 올바른 Skill을 선택하기 어려워진다. 시스템 프롬프트에 모든 Skill의 메타데이터가 포함되므로, 불필요한 Skill은 적극적으로 정리한다.
도구 활용
직접 관리가 번거로우면 도구의 도움을 받을 수 있다.
Rulesync: 한 번 쓰고 여러 도구에 배포
팀에서 Claude Code, Cursor, Copilot을 섞어 쓸 때, rulesync.md 하나를 작성하면 각 도구의 설정 파일을 자동 생성한다:
npx rulesync
# → .claude/CLAUDE.md, .cursor/rules/*.mdc,
# .github/copilot-instructions.md 동시 생성규칙을 한 곳에서 관리하고, 도구별 포맷 변환은 자동화한다.
PreCompact Hook: 컨텍스트 압축 전 지식 보존
Claude Code의 컨텍스트가 압축될 때 핵심 내용이 사라질 수 있다. PreCompact Hook을 설정하면 압축 직전에 대화 요약을 자동으로 파일에 저장한다:
{
"hooks": {
"PreCompact": [{
"command": "claude -p 'Summarize key decisions and learnings from this conversation' > .claude/handover-$(date +%F).md"
}]
}
}이렇게 보존된 핸드오버 파일은 나중에 Skill 개선의 재료가 된다.
커뮤니티 메모리 확장
Claude Code의 기본 Auto Memory 외에 더 강력한 메모리 시스템도 있다:
- claude-mem: 세션 활동을 자동 캡처하고 AI로 압축하여 다음 세션에 주입
- episodic-memory: 벡터 DB로 과거 세션을 시맨틱 검색. "지난번에 Redis 설정 어떻게 했지?"에 답할 수 있다
이런 도구는 Auto Memory의 한계(200줄, 키워드 매칭만 가능)를 보완한다.
실전 정제 사이클 예시
실제로 Skill을 키워나가는 과정을 시나리오로 보자.
Day 1: 프로젝트 시작
# CLAUDE.md
Python FastAPI 서버. PostgreSQL + SQLAlchemy.
## 명령어
uv run dev # 개발 서버
uv run test # 테스트
uv run migrate # DB 마이그레이션Day 3: 첫 번째 실수 발견
Claude가 pip install을 사용했다. 이 프로젝트는 uv를 쓴다.
# CLAUDE.md에 추가
## 규칙
- 패키지 매니저는 uv. pip 사용 금지.Day 7: 코드 리뷰에서 패턴 발견
PR 리뷰에서 "API 응답은 항상 Pydantic 모델로 직렬화해야 한다"는 규칙이 나왔다.
# CLAUDE.md에 추가
- API 응답은 반드시 Pydantic ResponseModel 사용. dict 직접 반환 금지.Day 14: CLAUDE.md가 커짐
API 관련 규칙이 15줄로 늘었다. Skill로 분리한다.
# .claude/rules/api-conventions.md 생성
## API 규칙
- 응답은 Pydantic ResponseModel 사용
- 에러는 HTTPException으로 처리
- 경로 파라미터는 snake_case
- 인증이 필요한 엔드포인트는 Depends(get_current_user) 사용
...
# CLAUDE.md에서 API 규칙 삭제, 대신:
## 참고
- API 규칙: .claude/rules/api-conventions.md
Day 30: 배포 워크플로우 Skill 생성
배포를 5번쯤 하고 나니 패턴이 잡혔다. Task Skill로 만든다.
# .claude/skills/deploy/SKILL.md
---
name: deploy
description: 프로덕션 배포
---
1. uv run test 실행 (실패 시 중단)
2. uv run build
3. docker build -t app:latest .
4. kubectl apply -f k8s/
5. kubectl rollout status deployment/app
6. 헬스체크: curl https://api.example.com/healthDay 60: Claude A/B로 정제
배포 Skill을 다른 Claude에게 테스트시켰더니, 스테이징과 프로덕션을 구분하지 못했다. Claude A에게 피드백:
"이 Skill을 쓴 Claude가 스테이징 배포인데 프로덕션에 배포했어.
환경 구분 규칙을 추가해줘."
Skill이 환경 파라미터를 받도록 개선된다.
정리
Skill을 키우는 핵심 흐름:
실수 발견 → 즉시 캡처 → Auto Memory/CLAUDE.md에 기록
↓
패턴 반복 → 구조화 → Skill 파일로 분리
↓
Skill 성장 → 테스트 → Claude A/B 패턴으로 정제
↓
정기 리뷰 → 불필요한 Skill 정리 → 파이프라인 최적화
효과적인 Skill 구성 전략과 팁에서 다룬 구조 설계 원칙과 결합하면, 처음에는 CLAUDE.md 10줄로 시작해서 몇 달 안에 팀의 암묵적 지식을 체계화한 Skill 시스템을 구축할 수 있다. 벡터 DB도, 임베딩 파이프라인도 필요 없다. 마크다운 파일과 Git이면 충분하다.