compound

compound 스킬

목적: 작업 과정에서 검증된 인사이트를 즉시 문서화하여, 검색 가능한 지식 베이스를 구축한다.

개요

이 스킬은 인사이트가 확인되는 즉시 포착하여, YAML frontmatter 기반의 구조화된 문서로 저장한다. 카테고리별 단일 파일 아키텍처를 사용하며, 각 인사이트는 knowledge/[category]/[filename].md에 저장된다.

---

<critical_sequence name="insight-capture" enforce_order="strict">

7단계 프로세스

### Step 1: 트리거 감지

자동 감지 문구 (대화에서 인식):

• "이거 잘 됐다"
• "이 방식이 좋네"
• "다음에도 이렇게 하자"
• "이건 기록해두자"
• "이 포맷이 먹혔다"
• "이게 효과가 있었어"
• "이렇게 하니까 됐어"
• "기억해둬야 해"

OR 수동: /compound 커맨드

Non-trivial만 (재사용 가치 있는 인사이트):

• 반복할 수 있는 패턴
• 다른 상황에도 적용 가능한 교훈
• 시행착오 끝에 발견한 방법
• 실전에서 검증된 접근법
• 구조적 개선을 가져온 발견

스킵 기준:

• 이 상황에서만 통하는 일회성 방법
• 단순 사실 기록 (수치, 날짜 등)
• 이미 문서화된 내용의 반복
• 아직 검증되지 않은 가설

### Step 2: 컨텍스트 수집

대화 이력에서 추출:

필수 정보:

• domain: work / learning / project / tool / personal
• insight_type: 인사이트 유형 (schema.yaml enum 참조)
• component: 도메인 내 하위 컴포넌트 (schema.yaml enum 참조)
• context: 어떤 상황에서 나온 인사이트인가 (1-3문장)
• key_learning: 핵심 교훈 한 문장 (다른 상황에도 일반화 가능하게)
• impact: critical / high / medium / low
• tags: 검색 키워드 (소문자, 하이픈 구분)

추가 수집 항목:

• 배경: 어떤 프로젝트/활동 중이었는가
• 시도한 것들: 효과 없었던 접근들
• 효과 있었던 것: 실제로 작동한 방법
• 작동 이유: 왜 효과적이었는가
• 재현 조건: 언제 이 방법을 쓸 수 있는가

BLOCKING 요건: domain, insight_type, 핵심 인사이트가 불분명한 경우 사용자에게 질문하고 응답을 기다린다:

문서화를 위해 몇 가지 확인이 필요합니다:

1. 어떤 도메인인가요? (work/learning/project/tool/personal)
2. 인사이트 유형은? (예: workflow_pattern, problem_solving, tool_discovery...)
3. 핵심 교훈을 한 문장으로 정리하면?

[응답 후 계속 진행]

### Step 3: 기존 문서 검색

knowledge/ 에서 유사 인사이트 검색:

# domain, tags, insight_type 기준으로 병렬 검색
Grep: pattern="domain: [domain]" path=knowledge/ output_mode=files_with_matches
Grep: pattern="tags:.*[keyword]" path=knowledge/ output_mode=files_with_matches -i=true
Grep: pattern="insight_type: [type]" path=knowledge/ output_mode=files_with_matches

유사 문서 발견 시 사용자에게 선택지 제시 후 대기:

유사 문서 발견: knowledge/[path]

어떻게 할까요?
1. 새 문서 생성 + 교차 참조 추가 (권장)
2. 기존 문서 업데이트 (동일한 인사이트의 보완인 경우)
3. 기타

선택 (1-3): _

사용자 응답 대기 후 선택한 액션 실행.

유사 문서 없으면 Step 4로 바로 진행.

### Step 4: 파일명 생성

형식: YYYYMMDD-[sanitized-insight-slug].md

Sanitization 규칙:

• 소문자
• 공백 → 하이픈
• 특수문자 제거 (하이픈 제외)
• 80자 미만으로 truncate

예시:

• 20260304-claude-code-skill-structure.md
• 20260304-mcp-server-debugging-pattern.md
• 20260304-prompt-iteration-framework.md

### Step 5: YAML 검증 (BLOCKING)

schema.yaml 기반으로 모든 필수 필드 검증.

<validation_gate name="yaml-schema" blocking="true">

검증 항목:

• domain: schema.yaml의 enum 값 중 하나
• date: YYYY-MM-DD 형식
• insight_type: schema.yaml의 enum 값 중 하나
• component: 해당 domain에 매핑된 enum 값 중 하나 (domain_component_mapping 확인)
• context: 20-300자, 구체적 상황 서술
• key_learning: 10-200자, 일반화 가능한 교훈
• impact: critical / high / medium / low
• tags: 1-8개, 소문자 하이픈 구분

검증 실패 시 Step 6 차단:

YAML 검증 실패

오류:
- domain: 허용된 값이 아님 → work, learning, project, tool, personal 중 하나
- component: domain에 허용되지 않는 컴포넌트 → schema.yaml 참조
- tags: 대문자 포함 → 소문자로 변환 필요

수정된 값을 제공해주세요.

GATE 강제: 모든 검증 통과 전까지 Step 6 진행 금지.

</validation_gate>

### Step 6: 문서 작성

카테고리 디렉토리 결정: schema.yaml의 category_mapping으로 insight_type → 저장 경로 매핑.

문서 생성:

INSIGHT_TYPE="[검증된 YAML에서]"
CATEGORY_DIR="[category_mapping에서 매핑]"
FILENAME="[Step 4에서 생성]"
DOC_PATH="${CATEGORY_DIR}${FILENAME}"

# 디렉토리 없으면 생성
mkdir -p "${CATEGORY_DIR}"

# assets/resolution-template.md 기반으로 문서 작성
# (Step 2에서 수집한 컨텍스트 + Step 5에서 검증한 YAML frontmatter)

결과:

• 카테고리 디렉토리에 단일 파일 생성
• Enum 검증으로 일관된 분류 보장

### Step 7: 교차 참조 & 패턴 감지

Step 3에서 유사 문서 발견된 경우:

# 기존 문서에 Related 섹션 추가
# 새 문서에도 기존 문서 링크 추가

패턴 후보 감지:

동일 카테고리에 유사 인사이트 3개 이상 존재하면:

패턴 문서 후보 감지: [카테고리]에 유사 인사이트 X개
→ patterns/ 문서로 종합하시겠습니까?

Critical Pattern 승격 조건 (자동 승격 금지, 사용자 결정):

• impact가 critical인 경우
• 여러 도메인에 횡단 적용 가능한 경우
• 반드시 기억해야 하는 경우

이 경우 Decision Menu에서 "2. 크리티컬 패턴에 추가" 옵션에 주석 추가:

이 인사이트는 크리티컬 패턴 승격을 고려해볼 만합니다

</critical_sequence>

---

<decision_gate name="post-documentation" wait_for_user="true">

キャプチャ後の選択メニュー

ドキュメント化の成功後に選択肢を提示し、ユーザーの応答を待ちます。

인사이트가 기록되었습니다.

파일 생성:
- knowledge/[category]/[filename].md

다음 작업:
1. 계속 진행 (권장)
2. 크리티컬 패턴에 추가 - critical-patterns.md에 승격
3. 관련 문서 연결 - 유사 인사이트와 교차 참조
4. 기존 스킬에 추가 - .claude/skills/에 연결
5. 문서 확인 - 생성된 내용 보기

선택: _

各オプションの処理：

Option 1: 続行

• 現在の作業／ワークフローに戻ります
• ドキュメント化は完了です

Option 2: クリティカルパターンに追加

ユーザーが選択した場合：

• 繰り返し適用されるパターン
• 絶対に忘れてはならない教訓
• 直感に反するものの、必須のルール

アクション：

1. ドキュメントからパターンを抽出します
2. assets/critical-pattern-template.md の形式に沿って構造化します
3. knowledge/patterns/critical-patterns.mdに追加します（連番を維持）
4. 該当ドキュメントに相互参照を追加します
5. 確認：「クリティカルパターンに追加されました。」

Option 3: 関連ドキュメントをリンク

• プロンプト：「どのドキュメントにリンクしますか？（ファイル名またはトピックの説明）」
• knowledge/から対象のドキュメントを検索します
• 双方向の相互参照を追加します
• 確認：「相互参照が追加されました」

Option 4: 既存のスキルに追加

• プロンプト：「どのスキルに追加しますか？」
• .claude/skills/[skill-name]/内の適切なファイルにリンクと説明を追加します
• 確認：「[skill-name]スキルに追加されました」

Option 5: ドキュメントを確認

• 生成されたドキュメントの内容を表示します
• Decision Menu を再度提示します

</decision_gate>

---

<integration_protocol>

統合ポイント

呼び出しトリガー：

• /compoundコマンド（メインインターフェース）
• 会話中に確認フレーズを自動検出
• ワークフロー完了後の手動呼び出し

呼び出し元のスキル／エージェント：

• なし（terminal スキル。他のスキルには委譲しません）

引き継ぎ条件： 呼び出し前の会話履歴に十分なコンテキストが必要です。

</integration_protocol>

---

<success_criteria>

成功基準

次の条件をすべて満たした場合、ドキュメント化は成功です。

• YAML frontmatter の検証に合格している（すべての必須フィールド、正しい形式、有効な enum 値）
• knowledge/[category]/[filename].mdにファイルが作成されている
• domain-component のマッピングが schema.yaml と一致している
• Context、What Worked、Why This Works の各セクションが具体的に記述されている
• 類似ドキュメントが見つかった場合、相互参照が追加されている
• ユーザーに Decision Menu が提示され、アクションが確認されている

</success_criteria>

---

エラー処理

コンテキスト不足：

• 不足している情報をユーザーに質問します
• 必要な情報を得るまで進めません

YAML 検証失敗：

• 具体的なエラー項目を表示します
• 修正した値で再試行します
• 検証に合格するまで処理をブロックします

類似インサイトが曖昧：

• 複数の候補をすべて表示します
• ユーザーが選択します：新規ドキュメント／既存ドキュメントの更新／個別にリンク

カテゴリのマッピングが不確実：

• 最も近いカテゴリを提案します
• ユーザーの確認後に進めます

---

実行ガイドライン

必ず行うこと：

• YAML frontmatter を検証します（Step 5 の validation gate はブロッキングです）
• domain-component のマッピングが有効であることを確認します
• ファイル作成前にmkdir -pでディレクトリを作成します
• コンテキストが不足している場合はユーザーに質問し、回答を待ちます
• key_learning は他の状況にも適用できるように一般化します

絶対に行わないこと：

• YAML 検証を省略する（validation gate はブロッキングです）
• 曖昧な説明でドキュメント化する（検索できなくなります）
• 仮説や未検証の内容をドキュメント化する
• クリティカルパターンへ自動的に昇格させる（ユーザーの判断が必要です）

---

実行シナリオの例

ユーザー：「Claude Code でスキルを作るとき、references/ フォルダーに例を入れたら、ずっと正確に従ってくれた。次回もこうしよう。」

スキルの有効化：

1. トリガーの検出：「次回もこうしよう」→ 自動的に有効化
2. コンテキストの収集：
   • domain: tool
   • insight_type: tool_discovery
   • component: claude-code
   • context: 「Claude Code のスキル作成時、SKILL.md だけを置くよりも、references/ フォルダーに具体的な例のファイルを一緒に置いた方が、スキルの実行精度が大幅に向上する」
   • key_learning: 「AI スキル／プロンプトの作成時、抽象的な指示よりも具体的な例のファイルを一緒に提供する方が、実行精度が高まる」
   • impact: high
   • tags: [claude-code, skill, references, accuracy, prompt-engineering]
3. **既存ドキュメントの検索：**knowledge/tool-discoveries/を検索
4. ファイル名の生成：20260304-skill-references-improve-accuracy.md
5. **YAML 検証：**合格
6. ドキュメントの作成：knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md
7. **相互参照：**なし（類似ドキュメントなし）

出力：

인사이트가 기록되었습니다.

파일 생성:
- knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md

다음 작업:
1. 계속 진행 (권장)
2. 크리티컬 패턴에 추가 - critical-patterns.md에 승격
3. 관련 문서 연결 - 유사 인사이트와 교차 참조
4. 기존 스킬에 추가 - .claude/skills/에 연결
5. 문서 확인 - 생성된 내용 보기