EP6. 구조 기반 워크플로우 생성 실습
🛠️ "보고서 써줘" 대신 "보고서 쓰는 법"을 AI에게 가르치는 법
"인공지능아, 설명문이나 보고서 같은 거 잘 쓰는 스킬(Skill) 하나 만들어 줄래?"
만약 평범한 AI였다면 "네! 보고서 작성 팁을 알려드릴게요. 1. 두괄식으로 작성하기..." 하며 뻔한 글짓기 요령을 나열했을 것입니다.
하지만 Cocrates는 이 요청을 '일회성 문서 작성'이 아닌 '앞으로 모든 문서를 구조적으로 생산할 수 있는 표준화된 워크플로우 엔진(템플릿) 설계'로 정확히 이해합니다. 유저가 매번 문서를 만들 때마다 시행착오를 겪지 않도록, AI 스스로 따를 공동의 행동 규범을 정의하는 것이죠.
이번 에피소드에서는 사용자의 아이디어가 어떻게 Kernel → Frame → Outline → Spec → Skill → Verification이라는 6단계의 철저한 빌드업을 거쳐 강력한 문서 자동화 스킬인 document-authoring으로 태어나는지 그 전 과정을 살펴보겠습니다.
🏎️ 1단계. Kernel — 핵심 목적을 단 한 문장으로 압축하기
Cocrates는 모호하고 둥구름 잡는 프롬프트를 극도로 싫어합니다. 사용자가 "일반적인 문서 스킬"이라고 툭 던지자, 곧바로 날카로운 질문 3종 세트가 날아옵니다.
🦉 Cocrates: "어떤 종류의 보고서를 주로 쓰실 건가요? 주요 독자는 누구인가요? 산출물은 최종적으로 어떤 파일 형태로 저장되나요?" 👤 사용자: "일반적인 문서고, 누구나 독자가 될 수 있어. 확장자는 마크다운(.md) 파일로 해줘."
이 뼈대를 바탕으로 이 스킬의 존재 이유를 정의하는 단 하나의 헌법적 문장, Kernel이 수립됩니다.
🎯 Kernel: 이 스킬은 Markdown 형식의 설명문/보고서를 검토 가능한 단계를 거쳐 생성하도록 돕는다.
🧱 2단계. Frame — 산출물의 뼈대와 작업 파일 트리 설계하기
방향이 정해졌으니 글의 계층 구조를 짤 차례입니다. Cocrates는 메타정보, 개요, 본문(섹션/서브섹션), 결론, 부록으로 이어지는 탄탄한 문서 레이아웃을 제안했습니다.
특히 대화창 안에서 글을 통째로 주고받다가 유실되는 일을 막기 위해, 로컬 디렉토리에 중간 산출물을 단계별로 격리 저장하는 파일 트리 규칙을 확정했습니다.
docs/{slug}/
├── outline.md # 1단계: 문서의 개요 및 메타정보
├── structure.md # 2단계: 섹션별 핵심 포인트를 담은 구조 도면
├── sections/ # 3단계: 쪼개서 작성하는 섹션별 본문 저장소
│ ├── 01-introduction.md
│ └── 02-main-point-1.md
└── {slug}.md # 4단계: 최종 통합본 문서
"한 번에 통으로 쓰는 것보다 섹션 단위로 쪼개어 검토하며 작성하는 게 안전하겠죠?"라는 Cocrates의 물음에 사용자가 동의하면서 작업의 최소 단위가 확정되었습니다.
📈 3단계. Outline — AI의 무의식적 가정을 부수다 (가장 극적인 순간)
절차적 동선(P1~P5 단계)을 구체화하던 중, Cocrates가 은연중에 자신의 '침묵의 기본값(고정관념)'을 드러냈습니다.
🦉 Cocrates: "문서를 작성할 때는 당연히 서론 → 본론 → 결론 순서로 순차적으로 뽑아내는 게 자연스럽겠죠?"
이때 사용자가 아주 강력한 브레이크를 밟습니다.
👤 사용자: "항상 그런 순서로 정형화된 건 아니야. 글의 목적에 따라 스토리 중심의 기승전결이 될 수도 있고, 문제 해결 중심의 구성이 될 수도 있어. 목적에 맞게 구성을 유연하게 채택할 수 있어야 해."
이 한마디는 단순한 피드백이 아니었습니다. Cocrates는 즉시 이 깨달음을 스킬 아키텍처의 핵심 원칙으로 승격시켰습니다. "문서의 목적에 따라 아키텍처(구성 방식)를 매번 다르게 커스텀 매핑한다!" AI의 굳은 머리를 인간의 직관이 유연하게 깨부순 완벽한 협업 모먼트입니다.
📜 4단계. Spec — 룰북과 금지 조항 선포하기
합의된 사안들을 모아 Cocrates는 최종 Spec(명세서)을 작성했습니다. 여기에는 사용자의 통찰이 그대로 반영된 6가지 맞춤형 구성 방식 선택지가 명문화되었습니다.
- 설득/제안: 서론-본론-결론
- 스토리/사례: 기승전결
- 문제 해결: 문제-원인-해결-제안
- 비교/분석: 기준-대안-평가-결론
여기에 강력한 안전장치인 7가지 금지 사항(Anti-Patterns)도 명시되었습니다.
🛑 "유저의 개요(P1) 및 구조(P2) 승인 게이트를 통과하기 전에는 절대 본문 작성을 시작하지 말 것", "중간 산출물을 파일로 저장하지 않고 채팅창에만 훌쩍 남겨두지 말 것" 등이 꼼꼼하게 못 박혔습니다.
🛠️ 5~6단계. Skill 생성 및 Verification (검증 점검)
최종 승인된 스펙을 기반으로 Cocrates 시스템 내부에 .opencode/skills/document-authoring/SKILL.md 파일이 정식 생성되었습니다.
만들어지자마자 자체 하네스 검증(Verification)이 가동되었고, 다음 7가지 엄격한 자격시험을 치렀습니다.
- 최종본보다 중간 구조 산출물을 먼저 강제하는가? → ✅ PASS
- 사용자 승인 없이는 진도를 못 나가게 막는 게이트가 확실한가? → ✅ PASS
- 완료 조건과 금지 사항이 모호하지 않고 구체적인가? → ✅ PASS
7개 항목 전원 통과! 이로써 새로운 워크플로우 스킬이 정식 등록되었습니다.
🚀 스킬 빌딩 완료: 이제 "보고서 써줘"라고 말하면 일어나는 변화
이제 이 스킬이 탑재된 Cocrates에게 무심하게 "블록체인 시장 조사 보고서 하나 써줘"라고 던지면, 과거처럼 웹 검색 내용을 짜깁기한 무의미한 글을 던지지 않습니다. 새로 배운 스킬의 룰에 맞춰 단계별로 사용자를 리드하기 시작합니다.
- [P1 단계] "보고서의 핵심 타겟 독자와 궁극적인 목적부터 정하시죠.
outline.md를 승인해 주세요." - [P2 단계] "이 보고서는 기술 분석이 위주니 '비교/분석(기준-대안-평가-결론)' 포맷이 좋겠습니다. 동의하십니까?"
- [P3 단계] "1번 섹션(기준 설정)을 작성해 파일로 구웠습니다. 검토 의견을 주세요."
사용자는 더 이상 AI가 주는 복권 같은 결과물에 의존하지 않고, 자신이 설계 단계를 꼼꼼히 통제하고 최종 승인한 고품질의 산출물을 손에 쥐게 됩니다.
📝 세 줄 요약
- 스킬 생성을 통해 AI에게 '일하는 방식'을 가르칠 수 있습니다. 이는 일회성 답변을 얻는 것보다 훨씬 지속 가능하고 강력한 자산이 됩니다.
- 인간의 개입이 스킬의 클래스를 결정합니다. "항상 서론-본론-결론은 아니다"라는 인간의 한마디가 AI의 굳어있던 뼈대를 유연한 마스터 아키텍처로 진화시켰습니다.
- 검토되지 않은 산출물은 생성할 가치가 없습니다. 단계를 쪼개고(Snowflake), 중간 산출물을 저장하며, 승인 게이트를 두는 것이 구조 기반 워크플로우의 핵심입니다.
🎬 다음 편 예고
학습(Ep4), 산출물 생성(Ep5), 그리고 스킬 생성(Ep6)까지 — 우리는 Cocrates Harness가 자랑하는 핵심 사이클을 전부 마스터했습니다!
엔진의 강력함을 온몸으로 체감했으니, 이제 이 기계가 도대체 내부적으로 어떻게 맞물려 돌아가는지 그 아키텍처 구조와 원리를 뜯어볼 시간입니다. 다음 에피소드에서는 Cocrates 프레임워크의 심장부와 코어 구조를 시원하게 파헤쳐 드리겠습니다.
"도구의 주인이 되려면, 도구의 내부 아키텍처를 볼 수 있어야 합니다."
이 시리즈는 Cocrates Harness 프레임워크를 소개합니다. Cocrates는 소크라테스식 대화로 사용자가 주도권을 잡고 성장하도록 설계된 에이전트 하네스입니다.