복잡한 온보딩 문서가 있어도 신규 팀원이 혼자 따라가기는 어렵다. Test Double의 개발자 Chris는 1,000줄 이상의 Markdown 온보딩 가이드를 보유한 Ruby on Rails 데이터 인제스트 플랫폼 팀을 위해 Claude Skills로 단계별 설정 마법사(wizard-like skill)를 만들었다. 이 글은 그 과정에서 얻은 6가지 실용적인 교훈을 정리한다. Claude Code를 처음 사용하는 개발자, AI 동반자 도구를 만들려는 엔지니어링 팀에게 유용하다.

배경

대규모 Rails 모노리스에서 데이터 웨어하우스로 비즈니스 데이터를 복제하는 플랫폼에는 여러 저장소에 걸친 추상 클래스 구현, 콜백 설정, 데이터 품질 감사 등 복잡한 절차가 있었다. 온보딩 가이드가 1,000줄을 넘어가면서 “도구가 필요하다”는 결론에 도달했다. 선택한 해법: 도메인 전문 지식이 내재된 Claude 스킬.

교훈 1: 컨텍스트가 전부다

처음엔 스킬에 1,000줄 Markdown 문서 전체를 읽히도록 했다. 결과: 시작부터 대규모 토큰 소비, 빠른 컴팩션, 할루시네이션 급증.

핵심 원칙: Claude는 문서를 통해 당신의 맥락을 마법처럼 흡수하지 않는다.

❌ 전체 문서를 한 번에 읽히기
✅ 섹션별로 필요한 부분만 청크로 로드

실천 방법

• 문서를 헤딩 단위로 나눠 단계별 로드
• 각 섹션마다 “이 섹션에서 데이터 인제스트와 관련된 부분만 집중하라”는 방향 제시

교훈 2: 방향을 제시하라

문서를 청크로 나눴어도, Claude가 어떤 역할을 하고 무엇을 중시해야 하는지 명시적으로 알려줘야 한다.

핵심 원칙: 문서 로드만으로는 부족하다. 문서로 무엇을 해야 하는지 지시하라.

# 스킬 지시 예시
이 섹션에서는 개발자가 설정할 ActiveRecord 모델과 콜백을 식별해야 한다.
설정 가이드의 "데이터 소스 섹션"을 읽고, 다음에만 집중하라: ...

교훈 3: 컨텍스트를 파일로 영속화하라

세션이 길어지면 누적 토큰이 폭발한다. 소프트웨어 팀이 큰 작업을 작은 PR로 나눠 처리하듯, 스킬도 진행 상태를 파일로 유지해야 한다.

해법: 진행 파일(progress file)

스킬이 매 세션 시작 시 진행 파일을 확인하고, 이전 결정 사항을 이어받는다.

# progress_file_template.md 형태
## 인제스트 대상 도메인: [도메인명]

### 완료 단계
- [x] ActiveRecord 모델 식별
- [ ] 콜백 구현
- [ ] 데이터 품질 감사

### 설계 결정 사항
- 사용 모델: Order, LineItem
- 이벤트: after_commit 콜백

### 도메인 데이터 필드
- ...

장점: 개발자가 작업을 여러 세션에 나눌 수 있고, 새 세션의 Claude가 이전 결정 맥락을 즉시 파악한다.

교훈 4: 간극을 연결하라

문서만으로는 개발자가 “내 도메인에서 어떤 데이터를 인제스트해야 하나”를 판단하기 어렵다. 스킬이 직접 Rails 앱을 탐색해 모델, 속성, 기존 콜백을 발견하고 추천을 제시하면 초기 진입 장벽이 크게 낮아진다.

핵심 원칙: 문서와 개발자의 실제 컨텍스트 사이의 간극을 스킬이 메워라.

1. 스킬이 Rails 앱에서 관련 모델·속성·콜백 자동 탐색
2. 도메인 언어로 추천 제시
3. 개발자가 확인·수정
4. 설정 시작

교훈 5: 구체적으로 명시하라

컨텍스트를 줄이려다 보면 스킬이 지나치게 간결해지고, 그러면 ActiveRecord 컬럼 발견, 명명 규칙, 테스트 실행 방법에서 불일치가 생긴다.

해법: 컨벤션 섹션과 특정 명령어를 명시적으로 지정한다.

## 컨벤션
- 모든 타임스탬프 컬럼은 UTC 기준
- 모델 파일 경로: app/models/<domain>/

## 중요 명령어
- 테스트 실행: `bundle exec rspec spec/data_ingest/`
- 컬럼 조회: `bin/rails runner "puts <Model>.column_names"`

주의: **IMPORTANT**를 과용하면 아무것도 중요하지 않은 것과 같다. 정말 중요한 것 3~5가지만 강조하라.

교훈 6: 책임을 분리하라

단일 스킬에 너무 많은 책임(탐색 + 구현 + 검토 + 테스트)을 주면 할루시네이션과 비일관성이 늘어난다. 해법은 멀티 에이전트 워크플로우다.

에이전트 팀 구성 예시:

팀 리더 (코디네이터)
├── 탐색 에이전트 — Rails 앱 도메인 분석
├── 구현 에이전트 — 각 데이터 인제스트 단계 구현
└── QA 에이전트 — 수용 기준 대비 구현 검토

서브 에이전트 vs 에이전트 팀:

• 서브 에이전트: 병렬 처리, 메인 세션 토큰 절약. 단일 작업의 세부 처리에 적합
• 에이전트 팀: 전문화된 역할 분리, 에이전트 간 직접 통신 가능. Claude 사용량 증가하지만 복잡한 파이프라인에 효과적

핵심 원칙 요약

관련 문서

• agent-skills — 에이전트 스킬 작성 8가지 팁
• claude-agent-sdk — .claude/ 폴더를 프로덕션 에이전트로 활용하는 방법
• claude-code-routines — Claude Code 루틴·자동화 기능

참고 자료

• Building a documentation companion with Claude skills — Test Double (2026-04-14)