EP6. 구조 기반 스킬 생성 실습
Ep5에서 우리는 AI에게 "jsondb를 만들어줘"라고 요청했을 때, Cocrates가 어떻게 ADR과 Spec을 거쳐 구조 기반으로 산출물을 생성하는지 살펴봤다. 그 과정에서 AI의 제안을 무조건 믿지 않고, 검토하고 설계하는 법을 배웠다.
오늘은 한 걸음 더 나아간다. Ep5가 "AI가 코드를 만들게 하는 법" 이었다면, Ep6는 "AI에게 일하는 법을 가르치는 법" 이다.
부제를 보자. "보고서 쓰는 법"을 AI에게 가르친다. 즉, 일회성 요청을 넘어서 AI의 행동 방식 자체를 설계하는 방법을 배운다.
🎣 "보고서 써줘" vs "보고서 쓰는 법"
두 가지 접근법을 비교해보자.
일반적인 접근법: "보고서 써줘"
매번 요청할 때마다 AI는 매번 다른 품질의 결과물을 준다. 오늘은 괜찮은데 내일은 형편없고, 같은 주제인데도 구조가 제각각이다. 반복 피로가 쌓인다. 이것이 일회성 요청의 한계다.
Cocrates의 접근법: "보고서를 작성하는 스킬을 만들어줘"
한 번 만들어두면 영원히 재사용할 수 있다. 같은 유형의 요청이 들어오면 AI가 항상 같은 워크플로우로 작업을 수행하고, 일관된 품질을 보장한다.
마치 "물고기를 잡아달라" 고 매번 부탁하는 것과, "물고기 잡는 법" 을 가르치는 것의 차이와 같다.
스킬이란 AI의 행동 규범, 즉 표준 워크플로우다. 같은 유형의 요청에 대해 AI가 일관된 방식으로 작업하도록 만드는 규칙이 바로 스킬이다.
오늘 우리가 만들 것은 document-authoring 이라는 스킬이다. 보고서나 설명문 작성을 자동화하는 워크플로우다.
🎯 Kernel — 핵심 목적을 단 한 문장으로 압축
모든 스킬 생성은 Kernel에서 시작한다. Kernel이란 이 스킬이 무엇을 하는지 한 문장으로 정의하는 것이다.
Cocrates가 던진 세 가지 질문:
- "무엇을 생성하는 스킬인가요?"
- "누가 사용하나요?"
- "어떤 형태로 결과물이 나오나요?"
이 질문에 대한 답변을 통해 Kernel 문장이 도출되었다.
"이 스킬은 일반적인 상황에서 Markdown 설명문이나 보고서를, 검토 가능한 단계를 거쳐 생성하도록 돕는다."
한 문장으로 스킬의 핵심을 정의했다. 이 Kernel이 이후 모든 설계의 기준이 된다.
🏗️ Frame — 뼈대를 세우다
Kernel이 정의되면, 다음은 Frame 단계다. 문서의 계층 구조와 생성 단계를 설계한다.
문서 계층 구조:
Meta (메타 정보) → Outline (개요) → Body (본문) → Conclusion (결론) → Appendix (부록)
생성 단계 (P1~P5):
P1: 요구사항 분석 → P2: 개요 작성 → P3: 섹션별 내용 작성 → P4: 통합 및 검토 → P5: 최종 포맷팅
각 단계는 명확한 입력과 출력, 승인 조건을 가진다.
🎯 Outline — 가장 극적인 순간
여기서 가장 중요한 일이 벌어졌다.
Outline 단계에서 Cocrates는 문서 구성을 "서론 → 본론 → 결론" 이라는 전형적인 패턴으로 제안했다. 매우 일반적이고 무난한 선택이다.
하지만 사용자가 브레이크를 밟았다.
"항상 서론 → 본론 → 결론 순서는 아니잖아? 보고서 종류에 따라 서론이 아예 필요 없을 수도 있고, 결론을 먼저 쓰는 게 더 효과적일 수도 있어."
이 한마디가 AI의 침묵의 기본값(Silent Default) 을 깨뜨렸다. Cocrates는 기존의 고정관념을 버리고, 6가지 맞춤형 문서 구성 방식을 설계했다.
- 표준형: 서론 → 본론 → 결론
- 두괄형: 결론 → 본론 → 요약
- 문제해결형: 문제 → 원인 → 해결책
- 시간순형: 배경 → 전개 → 결과
- 비교형: 주제 A → 주제 B → 종합
- 자유형: 사용자가 직접 구조 정의
💡 교훈: AI의 첫 제안이 항상 옳은 것은 아니다. AI는 가장 일반적인 패턴을 제시할 뿐이다. 사용자의 맥락과 통찰이 더 나은 구조를 만든다. "항상 서론→본론→결론 순서는 아니다" 라는 사용자의 통찰이 AI의 고정관념을 깨고, 더 유연하고 강력한 아키텍처로 진화시켰다.
📋 Spec — 설계의 완성
Outline이 확정된 후, Cocrates는 모든 결정을 Spec으로 통합했다.
5가지 핵심 원칙:
- 단계별 승인 게이트 — 각 단계마다 사용자 검토 필요
- Snowflake 점진적 확장 — 작게 시작해서 점진적으로 구체화
- 자체 완결성 — Spec만으로 생성 가능해야 함
- 검증 가능성 — 각 항목은 통과/실패를 판단할 수 있어야 함
- 사용자 주도 — AI가 아닌 사용자가 최종 결정
6가지 맞춤형 구성 방식: 위에서 언급한 6가지 문서 구조
7가지 금지사항:
- 장황한 산문 금지
- 사용자 확인 없는 단계 진행 금지
- Spec에 없는 내용 생성 금지
- ...
5가지 완료 조건:
- 모든 단계의 사용자 승인 완료
- 각 섹션이 Spec과 일치
- ...
📄 Skill 생성 — 그리고 검증
Spec이 완성된 후, Cocrates는 .opencode/skills/document-authoring/SKILL.md 파일을 생성했다.
그리고 7개 검증 항목으로 생성된 스킬을 검증했다.
결과: 전원 PASS ✅
| 검증 항목 | 결과 |
|---|---|
| Kernel이 명확히 정의되었는가? | ✅ |
| Frame이 설계되었는가? | ✅ |
| Outline이 구체화되었는가? | ✅ |
| Spec이 자체 완결적인가? | ✅ |
| 승인 게이트가 각 단계에 있는가? | ✅ |
| 금지사항이 명확한가? | ✅ |
| 완료 조건이 검증 가능한가? | ✅ |
🔄 스킬 완성 후의 변화
스킬이 만들어지고 나면, 이전과 완전히 다른 경험을 하게 된다.
Before: "보고서 써줘" → AI가 마구잡이로 생성 → 사용자가 수동적으로 수용
After: "프로젝트 회고록을 작성해줘" → document-authoring 스킬이 발동 → P1(요구사항 분석)부터 단계별로 사용자와 협력 → 매 단계 검토와 승인 → 일관된 품질의 결과물
사용자는 더 이상 AI가 주는 결과물을 수동적으로 기다리지 않는다. 스스로 설계하고 통제하는 능동적 설계자가 된다.
❄️ Snowflake 공통 패턴
Ep4(학습), Ep5(생성), Ep6(스킬 생성) — 이 세 실습은 모두 Snowflake 공통 패턴을 공유한다.
| 단계 | Ep4 (학습) | Ep5 (생성) | Ep6 (스킬) |
|---|---|---|---|
| 작게 시작 | 개념 브리핑 | 요구사항 명확화 | Kernel 정의 |
| 점진 확장 | 3단계 미션 | 3개 ADR | Frame→Outline→Spec |
| 검토와 승인 | 매 미션 후 확인 | 각 ADR 승인 | 각 단계별 승인 |
| 파일 저장 | kb/bloom-taxonomy.md | spec/jsondb.md | skills/document-authoring/SKILL.md |
이 패턴이 Cocrates의 모든 활동에 일관되게 적용된다.
📌 오늘의 핵심
- 스킬은 AI의 일하는 방식을 설계하는 것이다. 일회성 요청을 넘어, AI의 행동 규범을 정의한다. 한 번 만들면 영원히 재사용 가능한 지속 가능한 자산이다.
- AI의 제안을 검토 없이 수용하지 마라. AI는 가장 쉽고 일반적인 결정을 내리는 경향이 있다. 사용자의 맥락에 맞는 더 나은 선택을 위해 반드시 U→A→E→A의 4단계를 거쳐야 한다.
- Snowflake는 공통 패턴이다. 작게 시작해서 점진적으로 확장하고, 단계별로 검토하고 승인받는 방식은 학습, 생성, 스킬 모든 활동에 적용된다.
- 스킬이 만들어지면 사용자는 능동적 설계자가 된다. 더 이상 AI가 주는 결과물을 수동적으로 기다리지 않고, 스스로 설계하고 통제한다.
스스로에게 질문하자.
- 일회성 요청과 스킬의 차이를 설명할 수 있는가?
- 스킬 생성 파이프라인 6단계를 말할 수 있는가?
- Snowflake 점진적 확장이 Ep4, Ep5, Ep6에 어떻게 각각 적용되는지 설명할 수 있는가?
🎬 다음 편 예고
지금까지 우리는 세 개의 실습 에피소드를 통해 Cocrates의 핵심 활동을 마스터했다.
Ep4에서는 학습 — Education, Knowledge Capture, Reflection. Ep5에서는 생성 — ADR, Spec, Generation, Verification. Ep6에서는 스킬 생성 — Kernel, Frame, Outline, Spec, Skill, Verification.
이제 세 가지 핵심 활동을 모두 경험했다.
다음 편, Ep7에서는 완전히 새로운 관점으로 들어간다. Cocrates 프레임워크 구조와 원리 — 아키텍처 딥다이브다.
지금까지는 Cocrates를 사용하는 법을 배웠다면, Ep7부터는 Cocrates가 내부적으로 어떻게 돌아가는지 내부 구조를 뜯어본다. Agent와 Skills 구조, Harness의 설계 원리, Intent-To-Skill Routing 등 시스템의 핵심을 파헤친다.
"당신은 AI에게 '물고기를 달라고' 할 것인가, '물고기 잡는 법을 배우라고' 할 것인가?"
여러분의 선택이 무엇이든, Cocrates는 그 여정을 함께한다.
이 시리즈는 Cocrates Harness 프레임워크를 소개합니다. Cocrates는 소크라테스식 대화로 사용자가 주도권을 잡고 성장하도록 설계된 에이전트 하네스입니다.