EP7. Cocrates Harness 구조
Ep6에서 우리는 AI에게 "보고서 써줘" 대신 "보고서 쓰는 법"을 가르치는 스킬 생성을 배웠다.
그런데 문득 이런 생각이 들지 않는가?
"Cocrates 자체는 어떻게 만들어져 있길래, 이렇게 다양한 일을 할 수 있는 거지?"
Ep4에서 배우고, Ep5에서 만들고, Ep6에서 스킬을 만들었다. 이제는 도구의 내부를 들여다볼 시간이다. 마치 자동차 운전을 마스터한 후, 보닛을 열어 엔진을 살펴보는 것처럼.
🔪 "칼 하나로 모든 요리를 할 수 있을까?"
주방을 상상해보자. 토마토를 썰고, 빵을 자르고, 생선을 손질해야 한다.
과연 칼 하나로 이 모든 작업을 해낼 수 있을까?
가능은 하다. 하지만 토마토는 으깨지고, 빵은 부서지고, 생선은 비늘이 제거되지 않을 것이다. 결과는 엉망이다. 전문 주방에는 식도, 빵칼, 회칼, 과도가 따로 있는 이유가 있다.
Cocrates도 마찬가지다.
누군가는 "블룸 분류학에 대해 알려줘" 하고, 누군가는 "보고서 작성해줘", 또 누군가는 "발표자료 만들어줘"라고 요청한다. 이 모든 요청을 하나의 프롬프트로 처리하려면 어떻게 해야 할까?
답은 간단하다. 못 한다.
산출물마다 구조적 접근 방식이 완전히 다르기 때문이다. 보고서에는 목차와 논리 흐름이 필요하고, 발표자료에는 페이지 단위 거버닝 메시지가 필요하며, 학습 활동에는 턴제 미션이 필요하다. 하나의 프롬프트에 이 모든 것을 담으면, 프롬프트는 너무 거대해져 유지보수가 불가능해진다.
여기서 Cocrates의 설계 철학이 드러난다.
🏛️ Cocrates = Agent + Skills
Cocrates는 하나의 거대한 프롬프트가 아니다. 두 개의 계층으로 구성된 하네스다.
Cocrates Agent — 공통 원칙과 제어를 담당한다. 의도를 인식하고, 어떤 스킬을 쓸지 결정하고, 전체 흐름을 관리한다. 마치 지휘관이 전장의 상황을 판단하고 적절한 부대를 투입하는 것과 같다.
Skills — 각 작업의 구체적인 절차를 담당한다. 각 스킬은 독립된 파일(.opencode/skills/*/SKILL.md)로 존재하며, 언제든 추가·수정·확장할 수 있다. 마치 각 분야의 전문가 팀과 같다.
이 구조의 핵심은 분리다.
- 공통 원칙은 Agent에, 작업별 절차는 Skills에 위임한다
- Skills는 서로 독립적이라 하나를 수정해도 다른 것에 영향이 없다
- 새로운 요청 유형이 필요하면 Skills만 추가하면 된다. Agent는 그대로
🔍 Cocrates Agent — 여섯 개의 섹션
cocrates.md는 여섯 개의 섹션으로 구성된 프롬프트다.
1. 정체성 (Persona): 에이전트가 자신을 어떻게 정의하는지 선언한다. "불확실성을 체계적인 탐구로 전환하고, 사용자가 결과물을 완전히 이해할 때까지 구조 기반 설계, 검토, 승인을 안내하는 존재." 이것이 Cocrates의 정체성이다.
2. 핵심 원칙 (Principle): 가장 중요한 것은 Harness Ignorance — 무지의 통제다. 사용자가 이해하지 못한 상태에서 산출물을 받아들이지 않게 하고, 질문을 통해 스스로 가정과 공백을 드러내게 한다.
3. 구조 (Harness Architecture): "Cocrates is a core agent plus skills harness." Agent가 원칙·의도 인식·스킬 선택·태스크 관리·가드레일을 담당하고, Skills가 작업별 절차를 담당한다는 원칙을 명시한다.
4. 요청 처리 (Request Handling): 사용자의 의도를 추론하고, 의도에 적합한 스킬을 로드하고, 스킬의 워크플로우를 실행한다. 이를 위해 Intent-To-Skill Routing이라는 매핑 테이블을 사용한다. 학습 의도 → education, 기록 의도 → knowledge-capture, 평가 의도 → reflection, 결정 의도 → adr-writing 등 8개 의도가 8개 스킬로 매핑된다.
5. 핵심 활동 (Core Activities): 두 가지 파이프라인을 정의한다.
- Generation Pipeline: 설계(ADR → Spec) → Spec 기반 생성 → Spec 기반 검증
- Learning Pipeline: Education → Knowledge Capture → Reflection
6. 성공 기준 (Success Criteria): 대화가 끝났을 때 사용자가 자신이 무엇을 알고 모르는지 더 분명히 알게 되었는가, 산출물의 구조를 스스로 설명할 수 있는가, 모든 단계에 주체적으로 참여했는가를 확인한다.
💡 "사용 → 이해 → 진화"
Cocrates의 가장 중요한 특징은 이것이다. Cocrates는 완성된 하네스가 아니다.
사용자가 직접 진화시킨다.
처음에는 제공된 스킬만 사용한다. 사용하다 보면 "이 스킬의 워크플로우가 내 상황에 안 맞는데?"라는 생각이 든다. 그러면 스킬을 수정한다. 새로운 유형의 작업이 필요하면 직접 스킬을 만든다.
이 순환이 Cocrates의 진짜 가치다.
사용한다 → 이해한다 → 진화시킨다
Agent의 원칙과 정체성은 유지하면서, Skills를 통해 계속 확장해 나간다. 하나의 거대한 프롬프트로 모든 것을 해결하려는 접근은 처음에는 단순해 보이지만, 시간이 지날수록 유지보수가 어려워진다. Agent + Skills 구조는 이 문제를 처음부터 해결한다.
📌 오늘의 핵심
- 하나의 프롬프트로 모든 산출물을 다룰 수 없다. 산출물마다 구조적 접근이 다르고, 하나의 거대한 프롬프트는 유지보수가 불가능하다.
- Cocrates = Cocrates Agent + Skills. Agent는 공통 원칙과 제어를, Skills는 작업별 절차를 담당한다. 이 분리가 핵심이다.
- Cocrates는 완성품이 아니라 진화하는 하네스다. 사용 → 이해 → 진화의 순환을 통해 사용자가 직접 시스템을 발전시킨다.
스스로에게 질문하자.
- 내가 지금 쓰는 AI 도구는 '하나의 프롬프트'인가, 'Agent + Skills' 구조인가?
- 새로운 요청 유형이 생겼을 때, 얼마나 쉽게 확장할 수 있는가?
🎬 다음 편 예고
오늘 우리는 Cocrates의 전체 구조를 살펴봤다. Agent + Skills, 두 개의 핵심 파이프라인 — Generation과 Learning.
다음 편부터는 이 두 파이프라인의 깊은 곳으로 들어간다. 먼저 Learning Pipeline부터.
"알려줘." — 이 세 글자가 왜 가장 위험한지, Cocrates는 왜 질문으로 답하는지, 그 철학과 원리를 파헤쳐 본다.
이 시리즈는 Cocrates Harness 프레임워크를 소개합니다. Cocrates는 소크라테스식 대화로 사용자가 주도권을 잡고 성장하도록 설계된 에이전트 하네스입니다.