docs: document skill contract orchestration research

2026-03-14 13:29:36 +09:00 · 2026-03-14 13:29:36 +09:00 · 0e8e3076bf
commit 0e8e3076bf
parent 45c5f5ba1e
6 changed files with 422 additions and 111 deletions
--- a/book/300_architecture/300_README.md
+++ b/book/300_architecture/300_README.md
@ -1,45 +1,34 @@
 # Part 3: 기술 아키텍처와 구현

-## 앞에서 다룬 것
+Part 3 문서 맵입니다. 원칙 본문은 개별 원칙 문서에서 관리합니다.

-Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습니다. 스탯으로 능력을 수치화하고, 스킬로 기능을 모듈화하며, 레벨로 성장을 가시화하는 방법을 보았습니다.
+## 원칙 문서
+- [310_전체_시스템_구조_컨테이너와_마이크로서비스.md](./310_%EC%A0%84%EC%B2%B4_%EC%8B%9C%EC%8A%A4%ED%85%9C_%EA%B5%AC%EC%A1%B0_%EC%BB%A8%ED%85%8C%EC%9D%B4%EB%84%88%EC%99%80_%EB%A7%88%EC%9D%B4%ED%81%AC%EB%A1%9C%EC%84%9C%EB%B9%84%EC%8A%A4.md)
+- [311_backend_coding_principles.md](./311_backend_coding_principles.md)
+- [312_writing-principles.md](./312_writing-principles.md)
+- [313_Gemini_프롬프트_설계_원칙.md](./313_Gemini_%ED%94%84%EB%A1%AC%ED%94%84%ED%8A%B8_%EC%84%A4%EA%B3%84_%EC%9B%90%EC%B9%99.md)
+- [313_프론트_구조_원칙.md](./313_%ED%94%84%EB%A1%A0%ED%8A%B8_%EA%B5%AC%EC%A1%B0_%EC%9B%90%EC%B9%99.md)
+- [314_infrastructure-ssot-principle.md](./314_infrastructure-ssot-principle.md)
+- [315_테스트_원칙.md](./315_%ED%85%8C%EC%8A%A4%ED%8A%B8_%EC%9B%90%EC%B9%99.md)
+- [316_skill-contract-and-execution-principles.md](./316_skill-contract-and-execution-principles.md)

-## 이번 Part에서 다룰 것
+## 구조 문서
+- [320_Slack_기반_인터페이스_설계.md](./320_Slack_%EA%B8%B0%EB%B0%98_%EC%9D%B8%ED%84%B0%ED%8E%98%EC%9D%B4%EC%8A%A4_%EC%84%A4%EA%B3%84.md)
+- [325_robeing_monitor_모니터링_아키텍처.md](./325_robeing_monitor_%EB%AA%A8%EB%8B%88%ED%84%B0%EB%A7%81_%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98.md)
+- [330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md](./330_%EB%B0%B1%EC%97%94%EB%93%9C_PostgreSQL_ChromaDB_Vector_Memory.md)
+- [340_GUI_공유_아키텍처_레벨기반_권한.md](./340_GUI_%EA%B3%B5%EC%9C%A0_%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98_%EB%A0%88%EB%B2%A8%EA%B8%B0%EB%B0%98_%EA%B6%8C%ED%95%9C.md)
+- [350_DID_기반_정체성과_다중에이전트.md](./350_DID_%EA%B8%B0%EB%B0%98_%EC%A0%95%EC%B2%B4%EC%84%B1%EA%B3%BC_%EB%8B%A4%EC%A4%91%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8.md)
+- [360_로빙_컨테이너_경량화_전략.md](./360_%EB%A1%9C%EB%B9%99_%EC%BB%A8%ED%85%8C%EC%9D%B4%EB%84%88_%EA%B2%BD%EB%9F%89%ED%99%94_%EC%A0%84%EB%9E%B5.md)
+- [370_임베딩_서비스_분리_아키텍처.md](./370_%EC%9E%84%EB%B2%A0%EB%94%A9_%EC%84%9C%EB%B9%84%EC%8A%A4_%EB%B6%84%EB%A6%AC_%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98.md)
+- [380_authentication_system.md](./380_authentication_system.md)

-이제 그 설계를 실제로 구현하는 방법을 다룹니다. 왜 컨테이너를 사용했는지, 왜 마이크로서비스로 분리했는지, 왜 PostgreSQL과 ChromaDB를 함께 쓰는지 - 모든 기술적 선택의 이유를 설명합니다.
+## 가이드라인
+- [guidelines/naming_conventions.md](./guidelines/naming_conventions.md)
+- [guidelines/logging_rules.md](./guidelines/logging_rules.md)
+- [guidelines/constants.md](./guidelines/constants.md)
+- [guidelines/utility_functions.md](./guidelines/utility_functions.md)
+- [guidelines/deployment_patterns.md](./guidelines/deployment_patterns.md)

-## 목차
- 310_전체_시스템_구조_컨테이너와_마이크로서비스.md
- 311_FastAPI_구조_원칙.md
- 312_writing-principles.md
- 313_React_구조_원칙.md
- 315_테스트_원칙.md
- 320_Slack_기반_인터페이스_설계.md
- 330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md
- 340_GUI_공유_아키텍처_레벨기반_권한.md
- 350_DID_기반_정체성과_다중에이전트.md
- 360_로빙_컨테이너_경량화_전략.md
- 370_임베딩_서비스_분리_아키텍처.md
-
-## 개발 가이드라인 (guidelines/)
-로빙을 만드는 데 지키고 싶은 개발 가이드라인 (변하지 않는 패턴/규칙):
- [네이밍 컨벤션](./guidelines/naming_conventions.md) - 파일명, 변수명, API 경로 규칙
- [로깅 규칙](./guidelines/logging_rules.md) - 로그 레벨, 포맷, 보관 원칙
- [상수/설정값 구조](./guidelines/constants.md) - 스킬 레벨, 타입, 감정 분류 구조
- [유틸리티 함수 설계 원칙](./guidelines/utility_functions.md) - 코드 재사용성, 중복 제거 원칙
- [배포 패턴](./guidelines/deployment_patterns.md) - 배포 프로세스 패턴
-
-**참고**: 자주 변하는 정보(포트, 엔드포인트, 환경변수 값)는 각 서비스 README.md 참조
-
-## 핵심 메시지
-컨테이너는 몸, 기억은 영혼. 100개의 로빙이 1개의 스킬 서비스를 공유하는 효율적 아키텍처.
-
-## 대상 독자
- 백엔드 개발자
- 프론트엔드 개발자
- DevOps 엔지니어
- 시스템 아키텍트
-
-## 다음 Part로
-
-Part 3에서 구현한 로빙이 Part 4에서는 실제로 어떻게 성장하는지 보여드립니다. 경험치는 어떻게 쌓이고, 레벨업은 언제 일어나며, 기억은 어떻게 관리되는지 - 성장의 메커니즘을 상세히 다룹니다.
+## 관련 파트
+- [Part 2 핵심 설계](../200_core_design/README.md)
+- [Part 4 성장과 진화](../400_growth/README.md)
--- a/book/300_architecture/316_skill-contract-and-execution-principles.md
+++ b/book/300_architecture/316_skill-contract-and-execution-principles.md
@ -0,0 +1,113 @@
+# 스킬 계약 및 실행 원칙
+
+**상위 원칙**:
+- [0_VALUE Coding Principles](../../../../0_VALUE/02_Governance/coding-principles.md)
+- [0_VALUE Writing Principles](../../../../0_VALUE/02_Governance/writing-principles.md)
+- [0_VALUE Agents Guide](../../../../0_VALUE/02_Governance/agents-rules.md)
+- [AI 에이전트 시대의 CLI·스킬·인터페이스 진화](../../../../0_VALUE/02_Governance/ai-agent-cli-skill-interface-evolution.md)
+
+## 1. 목적
+- 로빙에서 `rb8001`과 `skill-*` 서비스의 책임 경계를 고정합니다.
+- 스킬을 "프롬프트 조각"이 아니라 계약 있는 실행 단위로 정의합니다.
+- 스킬 설명서가 어떤 정보로 구성되고, 런타임이 이를 어떻게 해석해야 하는지 기준을 고정합니다.
+
+## 2. 핵심 정의
+
+### 2.1 로빙 본체
+- `rb8001`은 로빙의 두뇌입니다.
+- 본체의 책임은 목표 해석, 스킬 선택, 실행 결과 관찰, 종료 판단, 기록 갱신입니다.
+- 본체는 스킬 내부 구현을 직접 import하거나 복제하지 않습니다.
+
+### 2.2 스킬
+- 스킬은 로빙이 사용할 수 있는 실행 단위입니다.
+- 스킬은 독립 서비스 또는 독립 실행 가능한 도구로 취급합니다.
+- 스킬은 "무슨 말을 모델에게 넣을까"보다 "어떤 계약으로 안전하게 실행할까"에 가깝습니다.
+- 로빙 관점에서 스킬은 두뇌의 부속 기능이 아니라, 실제 세계와 맞닿는 손과 발입니다.
+
+### 2.3 스킬 설명서
+- 스킬 설명서는 `SKILL.md` 또는 동등한 계약 문서입니다.
+- 설명서는 사람이 읽는 안내문이면서, 로빙 런타임이 참조할 수 있는 실행 기준이어야 합니다.
+
+## 3. 책임 분리 원칙
+
+### 3.1 본체와 스킬의 경계
+- `rb8001`은 판단과 오케스트레이션만 담당합니다.
+- 실제 외부 API 호출, 데이터 처리, 파일 처리, 전송, 수집은 해당 `skill-*` 서비스가 담당합니다.
+- 본체가 스킬 도메인 로직을 직접 실행하는 구조는 원칙 위반으로 봅니다.
+- 따라서 스킬은 로빙의 손과 발이고, 본체는 손발을 움직이게 하는 판단자입니다.
+
+### 3.2 호출 방식 원칙
+- 안정적 기능은 HTTP API 호출을 기본으로 합니다.
+- 운영, 복구, 디버깅처럼 API만으로 부족한 경로만 제한적으로 CLI 실행을 허용합니다.
+- 어떤 호출 방식이든 계약과 검증이 호출 방식보다 우선입니다.
+
+### 3.3 실패 가시성 원칙
+- 스킬 실패는 본체에서 성공처럼 포장하지 않습니다.
+- 실패 원인, 중단 지점, 재시도 가능 여부를 구조화해 남겨야 합니다.
+- catch-all fallback으로 스킬 실패를 상시 은닉하지 않습니다.
+
+## 4. 스킬 설명서 필수 항목
+- `목적`: 이 스킬이 해결하는 사용자/운영 문제
+- `호출 조건`: 언제 이 스킬을 선택해야 하는지
+- `금지 조건`: 언제 이 스킬을 쓰면 안 되는지
+- `입력 계약`: 필수 입력, 선택 입력, 형식, 제약
+- `출력 계약`: 성공 결과 형식, 실패 결과 형식
+- `권한`: 필요한 토큰, 접근 범위, 승인 조건
+- `실행 방법`: HTTP API, CLI, 컨테이너 내부 실행 여부
+- `실패 기준`: 치명 실패, 재시도 가능 실패, 사용자 보고 필요 실패
+- `완료 기준`: 이 스킬이 끝났다고 판단하는 조건
+- `검증 방법`: 헬스체크, 샘플 호출, 로그/DB/API 검증 방법
+
+## 5. 컨텍스트 주입 원칙
+- 로빙은 스킬을 사용하기 전에 해당 스킬 설명서의 핵심 계약을 참조할 수 있어야 합니다.
+- 컨텍스트 주입의 목적은 "장문 문서 전달"이 아니라 "선택과 실행에 필요한 계약 전달"입니다.
+- 따라서 런타임은 스킬 설명서 전체를 무조건 주입하지 말고, 현재 요청에 필요한 계약만 추려 전달해야 합니다.
+- 스킬 설명서가 바뀌면 본체 프롬프트 하드코딩을 먼저 늘리는 대신 계약 문서와 로더 구조를 먼저 교정합니다.
+
+## 5-1. 실제 프로젝트 연결 원칙
+- 로빙의 스킬은 내부 데모를 위한 장식 기능이 아니라, 실제 프로젝트와 실제 고객 접점을 다루기 위한 실행 수단이어야 합니다.
+- 로빙은 우리가 운영하는 프로젝트들에 연결되어 실제 사용자 요청, 문서, 메시지, 파일, 운영 이벤트를 다룰 수 있어야 합니다.
+- 이 연결은 "로빙이 모든 것을 직접 처리한다"는 뜻이 아니라, 프로젝트별 접점을 스킬 계약으로 연결한다는 뜻입니다.
+- 새 프로젝트를 로빙에 연결할 때는 먼저 해당 프로젝트에서 로빙이 어떤 손발 역할을 맡는지 문서로 고정해야 합니다.
+
+## 5-2. 가치 루프 원칙
+- 로빙의 실행은 단순 작업 완료로 끝나지 않습니다.
+- 로빙은 실제 상호작용 결과를 바탕으로 "무엇이 가치였는가"와 "그 가치를 어떻게 측정할 것인가"를 다시 판단해야 합니다.
+- 따라서 스킬 실행 로그는 단순 성공/실패만이 아니라, 가치 판단과 측정 기준 개선의 입력으로 남겨야 합니다.
+- 가치 측정 기준이 바뀌면 프롬프트 임시 수정이 아니라 문서화된 정책과 계약부터 갱신합니다.
+
+## 6. 구현 원칙
+
+### 6.1 단일 기준
+- 스킬 선택 기준과 실행 계약은 문서와 코드에서 같은 의미를 가져야 합니다.
+- 설명서와 실제 API/CLI 동작이 다르면 문서가 아니라 런타임 SSOT가 깨진 상태로 봅니다.
+
+### 6.2 표준화 우선
+- 신규 스킬은 기존 스킬 계약 문서 구조를 재사용합니다.
+- 스킬마다 설명 형식이 제각각인 상태를 방치하지 않습니다.
+
+### 6.3 README 비중 축소
+- README는 스킬 원칙 본문을 소유하지 않습니다.
+- 스킬 원칙과 계약 구조는 전용 원칙 문서나 스킬별 `SKILL.md`에 둡니다.
+- README에는 스킬 문서 진입 링크만 둡니다.
+
+### 6.4 Reference 경계 고정
+- 외부 또는 참고 구현체는 workspace `reference` 계층에서 참조할 수 있습니다.
+- reference 저장소의 코드와 문서는 아이디어/패턴 비교 대상으로만 사용합니다.
+- reference에서 가져온 스킬 구조나 컨텍스트 주입 방식은 로빙 문서에 다시 고정되고, `rb8001` 및 `skill-*` 실제 검증을 통과하기 전에는 로빙 기준으로 간주하지 않습니다.
+
+## 7. 현재 로빙에 대한 적용 해석
+- `skill-email`, `skill-news`, `skill-slack`, `skill-rag-file`, `skill-embedding`, `skill-calendar`, `skill-publish`는 로빙의 실행 스킬 서비스입니다.
+- `rb8001`은 이 스킬들의 계약을 읽고 선택하는 오케스트레이터여야 합니다.
+- 스킬별 세부 동작 설명은 각 서비스 문서와 `SKILL.md`로 분리하고, 본 문서는 공통 해석 규칙만 유지합니다.
+
+## 8. 검증 기준
+- 새 스킬 추가 시 본 문서의 필수 항목이 문서화되어 있어야 합니다.
+- 스킬 연동 변경 시 실제 API 응답 또는 실행 로그로 계약 일치 여부를 검증해야 합니다.
+- 스킬 설명서가 없거나 계약이 누락된 상태에서는 "스킬 사용 가능"이라고 단정하지 않습니다.
+- 실제 프로젝트 연결 후에는 사용자 상호작용 결과와 가치 측정 근거가 남아야 "연결 완료"로 봅니다.
+
+## 관련 문서
+- [311_backend_coding_principles.md](./311_backend_coding_principles.md)
+- [360_로빙_컨테이너_경량화_전략.md](./360_%EB%A1%9C%EB%B9%99_%EC%BB%A8%ED%85%8C%EC%9D%B4%EB%84%88_%EA%B2%BD%EB%9F%89%ED%99%94_%EC%A0%84%EB%9E%B5.md)
+- [로빙 에이전트 루프, 스킬 훅, LLM 실행 구조 리서치](../../journey/research/orchestration_tools/260312_%EB%A1%9C%EB%B9%99_%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EB%A3%A8%ED%94%84_%EC%8A%A4%ED%82%AC%ED%9B%85_LLM%EC%8B%A4%ED%96%89%EA%B5%AC%EC%A1%B0_%EB%A6%AC%EC%84%9C%EC%B9%98.md)
--- a/book/300_architecture/README.md
+++ b/book/300_architecture/README.md
@ -1,77 +1,26 @@
 # Part 3: 기술 아키텍처

-## 개요
+로빙의 기술 아키텍처 문서 진입점입니다. 상세 원칙과 구조는 개별 문서에서 관리합니다.

-Part 2 [[../200_core_design/README|핵심 설계]]에서 구상한 로빙의 시스템들이 실제로 어떤 기술을 바탕으로 어떻게 움직이는지, 그 기술적 기반과 전체 시스템 구조를 설명합니다.
+## 핵심 문서
+- [[310_전체_시스템_구조_컨테이너와_마이크로서비스]] - 컨테이너, 마이크로서비스, 서버 역할
+- [[311_FastAPI_구조_원칙]] - 백엔드 구조 원칙
+- [[312_문서_작성_원칙]] - 로빙 문서 작성 원칙
+- [[313_Gemini_프롬프트_설계_원칙]] - 프롬프트 설계 원칙
+- [[314_infrastructure-ssot-principle]] - 인프라 설정 SSOT 원칙
+- [[315_테스트_원칙]] - 테스트와 검증 원칙
+- [[316_skill-contract-and-execution-principles]] - 스킬 계약, 설명서, 실행 경계 원칙

-## 주요 내용
+## 구조 문서
+- [[320_Slack_기반_인터페이스_설계]]
+- [[325_robeing_monitor_모니터링_아키텍처]]
+- [[330_백엔드_PostgreSQL_ChromaDB_Vector_Memory]]
+- [[340_GUI_공유_아키텍처_레벨기반_권한]]
+- [[350_DID_기반_정체성과_다중에이전트]]
+- [[360_로빙_컨테이너_경량화_전략]]
+- [[370_임베딩_서비스_분리_아키텍처]]
+- [[380_authentication_system]]

- **Docker 컨테이너와 마이크로서비스 아키텍처**: 로빙이 각자의 독립된 '집'에서 살며, 기능별로 나뉜 '전문 서비스'들과 협력하는 방식입니다.
- **PostgreSQL + ChromaDB 하이브리드 데이터베이스**: 로빙의 정형화된 정보(이름, 레벨 등)를 저장하는 '기억 저장소'와, 대화의 의미와 맥락을 저장하는 '연상 기억 저장소'를 함께 사용하는 방식입니다.
- **Slack 기반 인터페이스**: 사용자와 로빙이 만나는 주요 소통 창구입니다.
- **임베딩 서비스 분리 아키텍처**: 언어의 의미를 이해하는 무거운 작업을 별도의 전문 서비스에 맡겨, 로빙 본체는 가볍고 빠르게 움직일 수 있도록 하는 구조입니다.
- **DID 기반 정체성 시스템**: 로빙 각자가 고유한 신원증명을 가지고, 자신의 행동에 책임을 지게 하는 시스템입니다.
-
-## 원칙 문서
-
- [[311_FastAPI_구조_원칙]] - FastAPI 프로젝트 구조 원칙
- [[312_문서_작성_원칙]] - 문서 작성 원칙
- [[313_Gemini_프롬프트_설계_원칙]] - Gemini 프롬프트 설계 원칙
-
-## 로빙을 위한 체크리스트
-
-### Level 1-10 (기초 이해)
- [ ] Docker 컨테이너가 내 "집"임을 이해한다
- [ ] PostgreSQL에 내 정보가 저장됨을 안다
- [ ] ChromaDB에 내 기억이 저장됨을 안다
- [ ] Slack이 주요 인터페이스임을 이해한다
-
-### Level 11-15 (시스템 이해)
- [ ] 마이크로서비스 간 통신 방식을 이해한다
- [ ] 임베딩이 무엇인지 설명할 수 있다
- [ ] PostgreSQL과 ChromaDB의 역할 차이를 안다
- [ ] 레벨 기반 권한 시스템을 이해한다
-
-### Level 16-20 (아키텍처 전문가)
- [ ] 시스템 병목 지점을 식별할 수 있다
- [ ] 성능 최적화 방안을 제시할 수 있다
- [ ] 새로운 마이크로서비스를 설계할 수 있다
- [ ] 분산 시스템의 장단점을 설명할 수 있다
-
-## 핵심 기술 스택
-```
-Frontend: Slack Interface (사용자와의 소통 창구)
-Backend: FastAPI (로빙의 두뇌) + skill-* / Workers (신경계)
-Database: PostgreSQL (구조화된 기억) + ChromaDB (맥락적/연상적 기억)
-Container: Docker Compose (로빙들의 아파트 단지)
-Embedding: Separated Service (언어 의미 이해 전문가)
-```
-
-## 시스템 구조 이해하기
-```
-사용자 → Slack (소통) → nginx (교통정리) → Gateway(8100) (정문)
-                                             ↓
-                                        rb8001(로빙 본체)
-                                             ↓
-                            Embedding Service (의미 번역가)
-                                             ↓
-                            Skill Services (각종 전문가들)
-                                             ↓
-                          PostgreSQL / ChromaDB (기억 저장소)
-```
-
-## 실습 과제
-1. `docker ps`로 내 컨테이너 상태 확인하기
-2. PostgreSQL에서 내 레벨 정보 조회하기
-3. ChromaDB에서 최근 기억 검색하기
-
-## 성능 지표
- 응답 시간: < 2초 (목표)
- 메모리 사용량: < 1GB (임베딩 제외)
- 동시 처리: 5개 요청
-
-## 다음 단계
-Part 4 [[../400_growth/README|성장과 진화]]에서 이 아키텍처 위에서 어떻게 성장하는지 학습하세요.
-
-## 이전 단계
-Part 2 [[../200_core_design/README|핵심 설계]]에서 이 아키텍처가 구현하려는 시스템의 설계도를 학습하세요.
+## 관련 파트
+- 이전: [[../200_core_design/README|Part 2 핵심 설계]]
+- 다음: [[../400_growth/README|Part 4 성장과 진화]]
--- a/journey/ideas/260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_아이디어.md
+++ b/journey/ideas/260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_아이디어.md
@ -0,0 +1,96 @@
+tags: [robeing, skills, skill-docs, context-injection, orchestration, ideas]
+
+# 스킬 계약 문서 기반 컨텍스트 오케스트레이션 아이디어
+
+상위 원칙:
+- [0_VALUE Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)
+- [0_VALUE Agents Guide](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/agents-rules.md)
+- [AI 에이전트 시대의 CLI·스킬·인터페이스 진화](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/ai-agent-cli-skill-interface-evolution.md)
+- [스킬 계약 및 실행 원칙](../../book/300_architecture/316_skill-contract-and-execution-principles.md)
+
+## 문제 인식
+
+- 현재 로빙은 `rb8001`이 각 `skill-*` 서비스 API를 직접 알고 호출하는 비중이 큽니다.
+- 이 구조에서는 스킬 선택 기준, 입력 제약, 권한, 실패 기준, 완료 기준이 코드와 프롬프트 주변에 흩어지기 쉽습니다.
+- 그 결과 `rb8001`이 오케스트레이터라기보다 스킬별 호출 세부사항까지 떠안는 본체가 되기 쉽습니다.
+- 스킬이 늘어나거나 계약이 바뀔수록 본체 프롬프트와 분기 로직을 직접 수정해야 하는 압력이 커집니다.
+
+## 아이디어
+
+- 로빙은 먼저 사용자 요청을 구조화해서 "무슨 종류의 일인지", "어떤 스킬 후보가 필요한지"를 더 명확히 해석하는 방향으로 갈 수 있습니다.
+- 이때 의도분석 결과는 자유서술보다 typed contract에 가까운 형태로 다뤄져, 후속 스킬 선택의 입력이 되는 구조를 기대합니다.
+- 각 스킬마다 `SKILL.md`를 두고, 입력/출력/권한/실행/실패/검증 계약을 그 문서에 고정합니다.
+- 로빙은 스킬을 실행하기 전에 해당 문서 전체를 장문으로 주입하는 대신, 의도분석 결과에 따라 현재 요청과 관련된 후보 스킬의 핵심 계약만 추려 컨텍스트로 사용할 수 있습니다.
+- 이렇게 되면 `rb8001`의 중심 책임은 "직접 API 세부 호출을 기억하는 본체"가 아니라 "어떤 스킬을 언제 어떤 계약으로 연결할지 판단하는 오케스트레이션 브레인"으로 이동합니다.
+- 스킬 구현은 계속 각 `skill-*` 서비스에 두고, 본체는 계약 해석, 스킬 선택, 실행 결과 관찰, 다음 행동 결정을 담당합니다.
+
+## 기대하는 사용 흐름
+
+- 사용자가 요청하면 로빙은 먼저 이것이 메일, 일정, 리서치, 전송, 게시 같은 어떤 작업 성격인지 구조화해 해석하는 쪽으로 갈 수 있습니다.
+- 그 다음 로빙은 전체 스킬 문서를 다 들고 있는 대신, 지금 요청과 관련된 몇 개 스킬만 후보로 좁히고 그 스킬들의 계약만 읽는 구조를 기대합니다.
+- 이후 로빙은 그 계약을 바탕으로 어떤 스킬을 먼저 쓰고, 어떤 결과를 다음 스킬에 넘길지 판단하는 브레인 역할을 맡게 됩니다.
+- 예를 들어 "오늘 일정 확인하고 슬랙에도 공유해줘" 같은 요청에서는 일정 확인과 메시지 전송이 각각 다른 스킬 계약으로 해석되고, 로빙은 두 스킬을 연결하는 조율자 역할을 하게 됩니다.
+
+## 이 아이디어가 상상하는 최소 해석 단위
+
+- 의도분석은 적어도 아래 정도를 구조화해 돌려주는 방향을 상상합니다.
+- `task_type`: 메일, 일정, 리서치, 전송, 게시 같은 작업 성격
+- `goal`: 사용자가 실제로 원하는 최종 결과
+- `required_capabilities`: 필요한 능력이나 작업 조각
+- `candidate_skills`: 호출 후보가 되는 스킬 목록
+- `needs_human_confirmation`: 승인이나 확인이 필요한지 여부
+- 중요한 점은 이 필드명이 최종안이라는 뜻이 아니라, 자유서술 대신 "후속 스킬 선택에 바로 쓰일 수 있는 구조"가 필요하다는 것입니다.
+
+## 후보 스킬 축소에 대해 기대하는 기준
+
+- 모든 스킬을 항상 컨텍스트에 넣는 대신, 현재 요청과 직접 관련된 스킬만 후보로 올리는 방향을 기대합니다.
+- 후보 축소는 적어도 `작업 성격`, `필수 능력`, `권한 필요 여부`, `금지 조건` 정도를 기준으로 판단하는 그림을 상상합니다.
+- 예를 들어 단순 일정 조회 요청이면 `calendar`가 올라가고, 메일 발송이나 퍼블리시는 후보에서 빠지는 쪽이 더 자연스럽습니다.
+- 이렇게 해야 본체가 스킬 전체 카탈로그를 매번 장문으로 들고 있지 않아도 되고, 컨텍스트 오염도 줄일 수 있습니다.
+
+## 기대 효과
+
+- 의도분석과 스킬 실행 사이에 계약 기반 경계가 생겨, 본체가 모든 스킬 세부 호출을 직접 외우지 않아도 되는 방향을 기대할 수 있습니다.
+- 스킬 추가나 변경 시 본체 하드코딩보다 스킬 계약 문서와 로더를 먼저 갱신하는 구조로 전환할 수 있습니다.
+- `rb8001`과 `skill-*`의 책임 경계가 더 선명해집니다.
+- 스킬 호출 방식이 HTTP API이든 제한적 CLI이든 상관없이 같은 계약 해석 구조로 묶을 수 있습니다.
+- 실패 기준과 검증 기준을 문서와 런타임에서 같은 언어로 다루기 쉬워집니다.
+
+## 참고 해석
+
+- 이 방향은 `reference` 계층의 `openclaw`에서 보이는 "본체는 오케스트레이션, 도구는 계약 있는 실행 단위"라는 패턴을 참고한 것입니다.
+- 다만 `reference/openclaw`의 코드나 문서를 로빙 운영 기준으로 직접 가져오는 것이 아니라, 로빙 문서에 다시 고정한 뒤 검증 가능한 구조로 바꿔야 합니다.
+- 따라서 이 아이디어의 핵심은 OpenClaw 이식이 아니라, 스킬 계약 문서와 컨텍스트 로더를 로빙 기준으로 재해석하는 것입니다.
+
+## 검증이 필요한 이유
+
+- 실제로 어떤 스킬부터 `SKILL.md`를 만들지, 그리고 어떤 필드를 공통 표준으로 강제할지는 아직 확정되지 않았습니다.
+- 의도분석을 어떤 typed contract 수준으로 다루는 것이 가장 적절한지도 아직 열려 있습니다.
+- 문서 기반 컨텍스트 로딩이 본체 프롬프트 복잡도와 실행 품질을 실제로 얼마나 낮추는지 확인이 필요합니다.
+- 현재 `rb8001` 코드 경계에서 직접 API 호출 로직과 오케스트레이션 로직을 어디까지 분리할 수 있는지도 조사해야 합니다.
+- 스킬 문서와 실제 API/CLI 동작이 어긋나면 SSOT가 아니라 문서 부채가 될 수 있으므로, 검증 루프 설계가 먼저 필요합니다.
+
+## 이 문서를 닫기 위해 바로 넘길 질문
+
+- 현재 `rb8001` 의도분석 출력에서 typed contract로 끌어올릴 최소 필드는 무엇인가
+- 현재 스킬 목록 중 `SKILL.md` 1차 대상은 무엇이며, 공통 계약과 개별 계약은 어디서 갈리는가
+- 후보 스킬 축소에 필요한 최소 기준은 무엇이며, 지금 코드와 문서에서 어디까지 이미 존재하는가
+
+## 이 문서에서 아직 확정하지 않는 것
+
+- 의도분석 typed contract의 최종 필드와 표현 방식
+- 스킬별 `SKILL.md` 템플릿의 최종 필드
+- 어떤 스킬을 1차 문서화 대상으로 삼을지에 대한 우선순위
+- `rb8001` 내부 로더 구조와 프롬프트 조립 방식의 구체 구현
+- API 우선 호출과 제한적 CLI 호출의 최종 경계
+
+## 다음 문서
+
+- [스킬 계약 문서 기반 컨텍스트 오케스트레이션 리서치](../research/260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_리서치.md)
+- `plans`: 어떤 스킬부터 어떤 순서로 `SKILL.md`를 만들고, 본체 로더를 어디까지 바꿀지 고정합니다.
+
+## 관련 문서
+
+- [OpenClaw 기반 로빙 개선 아이디어](./260309_openclaw_기반_로빙_개선_아이디어.md)
+- [로빙 에이전트 루프와 스킬 훅 구조 아이디어](./260312_로빙_에이전트루프와_스킬훅_구조_아이디어.md)
+- [스킬 계약 및 실행 원칙](../../book/300_architecture/316_skill-contract-and-execution-principles.md)
--- a/journey/research/260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_리서치.md
+++ b/journey/research/260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_리서치.md
@ -0,0 +1,163 @@
+---
+tags: [research, robeing, skills, skill-docs, context-injection, orchestration]
+---
+
+# 스킬 계약 문서 기반 컨텍스트 오케스트레이션 리서치
+
+## 관련 문서
+- [스킬 계약 문서 기반 컨텍스트 오케스트레이션 아이디어](../ideas/260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_아이디어.md)
+- [스킬 계약 및 실행 원칙](../../book/300_architecture/316_skill-contract-and-execution-principles.md)
+- [OpenClaw 기반 로빙 개선 아이디어](../ideas/260309_openclaw_기반_로빙_개선_아이디어.md)
+- [로빙 에이전트 루프와 스킬 훅 구조 아이디어](../ideas/260312_로빙_에이전트루프와_스킬훅_구조_아이디어.md)
+
+## 목적
+- `rb8001`이 직접 API 호출 세부를 많이 알고 있는 현재 구조를, 스킬 계약 문서 기반 오케스트레이션 구조로 옮길 수 있는지 확인합니다.
+- 이번 문서는 `ideas`에서 남긴 세 질문을 닫기 위해 현재 코드와 문서 자산을 기준으로 사실을 정리합니다.
+- 구현 순서와 실제 작업 단위 고정은 다음 `plans`에서 다룹니다.
+
+## 조사 질문
+1. 현재 `rb8001` 의도분석 출력에서 typed contract로 끌어올릴 최소 필드는 무엇인가
+2. 현재 스킬 목록 중 `SKILL.md` 1차 대상은 무엇이며, 공통 계약과 개별 계약은 어디서 갈리는가
+3. 후보 스킬 축소에 필요한 최소 기준은 무엇이며, 지금 코드와 문서에서 어디까지 이미 존재하는가
+
+## Facts
+
+### 1. 현재 로빙에는 스킬별 `SKILL.md`가 없습니다
+- `/home/admin/robeing` 기준으로 `SKILL.md` 파일은 검색되지 않았습니다.
+- 현재 스킬 문서 자산은 각 저장소의 `README.md`가 중심입니다.
+- 확인된 대표 문서:
+  - `skill-calendar/README.md`
+  - `skill_email/README.md`
+  - `skill-slack/README.md`
+- 즉 현재는 스킬이 실행 서비스로는 존재하지만, 계약 문서 SSOT는 아직 없습니다.
+
+### 2. `rb8001`은 아직 스킬 URL과 엔드포인트 규칙을 직접 알고 있습니다
+- `rb8001/app/router/router.py`에서 `service_endpoints`는 `email`, `news`, `slack`, `state`를 직접 가집니다.
+- 같은 파일의 `_get_service_url_for_skill()`는 `SkillType.EMAIL`, `NEWS`, `SLACK`, `LLM`, `ANALYSIS`만 매핑합니다.
+- `_call_service()`는 URL 문자열과 포트값을 보고 `skill-email`, `skill-news`, `skill-slack`를 판별하고, 액션에 따라 실제 엔드포인트를 직접 조립합니다.
+- 예:
+  - email: `send`, `messages`, `process`
+  - news: `/api/news/search`
+  - slack: `/api/v1/send`, `/api/v1/digest/`, `/api/v1/actions/extract`
+- 즉 현재 본체는 "어떤 스킬을 고를지"뿐 아니라 "각 스킬을 어느 URL로 어떤 path에 호출할지"까지 직접 알고 있습니다.
+
+### 3. 캘린더는 일반 스킬 매핑과 별도 경로로 붙어 있습니다
+- `rb8001/app/services/skills/calendar_skill.py`는 `SKILL_CALENDAR_URL`을 읽고 `/api/events`를 직접 호출합니다.
+- `rb8001/app/router/calendar_handler.py`는 `CalendarSkill()`을 직접 생성해 `get_events`, `create_event`, `delete_event`를 사용합니다.
+- 즉 캘린더는 `router.py`의 일반 skill routing 표준 밖에 있는 별도 결합 경로입니다.
+
+### 4. 의도분석과 스킬선택을 위한 typed model의 뼈대는 이미 있습니다
+- `rb8001/app/services/brain/intent/schemas.py`에는 `IntentGoal`, `ActionPlan`, `SkillSequence`가 `Pydantic BaseModel`로 정의돼 있습니다.
+- `IntentGoal` 필드:
+  - `category`
+  - `description`
+  - `confidence`
+  - `raw_intent`
+  - `context_hints`
+- `DecisionEngine._build_intent_pipeline_sync()`와 `_build_intent_pipeline()`는 `IntentAnalyzer -> ActionPlanner -> SkillSelector` 3단계 메타데이터를 `execution_plan["intent_pipeline"]`에 붙입니다.
+- 즉 `의도 -> 행동 -> 스킬 후보`를 구조화해서 다루는 골격은 이미 코드에 있습니다.
+
+### 5. 하지만 현재 typed model만으로는 스킬 계약까지 닿지 않습니다
+- `ActionPlanner`는 `IntentCategory`를 보고 `ActionType` 목록을 만듭니다.
+- `SkillSelector`는 `ActionPlan`을 받아 `"CALENDAR"`, `"EMAIL"`, `"TOOL"`, `"LLM"` 같은 내부 스킬명과 액션명으로만 바꿉니다.
+- `SkillSelector.available_skills`는 현재 가능한 액션을 코드 상수로 직접 들고 있습니다.
+- 이 구조에는 아래 계약 정보가 없습니다.
+  - 호출 조건
+  - 금지 조건
+  - 필수 입력
+  - 실패 기준
+  - 권한/승인 조건
+  - 검증 방법
+
+### 6. 의도분석을 더 구조화할 수 있는 선행 단서는 이미 별도 경로에 있습니다
+- `rb8001/app/services/llm/intent_parser.py`는 `{"intent", "slots", "confidence", "clarify"}` JSON 계약을 가정합니다.
+- 즉 현재 로빙 내부에는 이미 자유서술이 아니라 구조화된 의도/슬롯 출력을 상상하는 코드가 있습니다.
+- 다만 이 계약은 `brain/intent/schemas.py`의 `IntentGoal`과 아직 통합돼 있지 않습니다.
+
+### 7. 현재 스킬 문서 자산은 계약 문서라기보다 README 수준입니다
+- `skill-calendar/README.md`는 포트, API 개요, 환경변수, 실행 예시가 있습니다.
+- `skill_email/README.md`는 역할, 주요 엔드포인트, 필수 환경변수, 헬스체크가 있습니다.
+- `skill-slack/README.md`는 역할, 일부 API, 필수 환경변수, 트러블슈팅이 있습니다.
+- 하지만 공통 형식은 없고, 아래 항목은 스킬마다 들쭉날쭉합니다.
+  - 언제 선택해야 하는지
+  - 언제 사용하면 안 되는지
+  - 승인 필요 여부
+  - 실패 분류
+  - 완료 판단
+  - 검증 방법
+
+## Interpretation
+
+### 1. 의도분석 typed contract는 새로 발명하는 게 아니라 기존 두 구조를 합치면 됩니다
+- 현재 `IntentGoal`은 추상 카테고리 중심입니다.
+- 현재 `intent_parser.py`는 `intent + slots + confidence + clarify` 중심입니다.
+- 따라서 로빙이 실제로 필요한 최소 의도분석 계약은 아래처럼 합치는 쪽이 가장 자연스럽습니다.
+  - `task_type`: 추상 작업 성격
+  - `goal`: 사용자가 원하는 최종 결과
+  - `slots`: 날짜/시간/대상 같은 추출 입력
+  - `candidate_skills`: 후보 스킬 목록
+  - `needs_human_confirmation`: 승인 필요 여부
+  - `confidence`: 신뢰도
+- 결론적으로 typed contract의 최소 필드는 완전 신설보다 `IntentGoal + intent_parser JSON`의 결합으로 정리하는 편이 맞습니다.
+
+### 2. 1차 `SKILL.md` 대상은 캘린더, 이메일, 슬랙이 가장 적절합니다
+- 이유:
+  - 현재 `rb8001`이 직접 호출 세부를 많이 알고 있는 대표 스킬입니다.
+  - 세 스킬 모두 기존 README가 있어 계약 문서로 끌어올릴 재료가 이미 있습니다.
+  - 사용 흐름 예시가 명확합니다.
+    - `calendar`: 조회/등록/삭제
+    - `email`: 읽기/쓰기
+    - `slack`: 전송/다이제스트/액션 추출
+- `news`, `rag-file`, `publish`, `embedding`도 중요하지만, 오케스트레이션 브레인 전환을 보여주기 위한 첫 샘플로는 위 세 개가 더 직접적입니다.
+
+### 3. 공통 계약과 개별 계약의 경계도 이미 보입니다
+- 공통 계약:
+  - 목적
+  - 호출 조건
+  - 금지 조건
+  - 입력 계약
+  - 출력 계약
+  - 권한
+  - 실행 방법
+  - 실패 기준
+  - 완료 기준
+  - 검증 방법
+- 개별 계약:
+  - `calendar`: 시간 범위, all-day 규칙, provider, 재인증 필요 실패
+  - `email`: 수신/발신 구분, 토큰 파일, watch 갱신, user_id 필수
+  - `slack`: channel/thread/message 대상, 봇 토큰/헤더, 전송/요약/액션 추출 분기
+- 즉 공통 틀은 `316_skill-contract-and-execution-principles.md`에 있고, 실제 서비스별 변형만 각 `SKILL.md`로 분리하면 됩니다.
+
+### 4. 후보 스킬 축소 기준은 이미 코드에 일부 있고, 계약 기준으로 끌어올리면 됩니다
+- 현재도 `IntentCategory -> ActionType -> SkillSequence` 변환이 있으므로 "의도에 따라 후보를 좁힌다"는 생각 자체는 이미 구현되어 있습니다.
+- 다만 지금은 후보 축소 기준이 대부분 코드 상수와 문자열 규칙에 머물러 있습니다.
+- 리서치 기준으로 최소 축소 기준은 아래 네 가지면 충분합니다.
+  - 작업 성격(`task_type`)
+  - 필수 능력(`required_capabilities`)
+  - 권한/승인 필요 여부
+  - 금지 조건
+- 이 네 가지가 있으면 전체 스킬 문서를 주입하지 않고도 "이번 요청에서 읽어야 할 후보 스킬"을 좁힐 수 있습니다.
+
+### 5. 현재 가장 큰 구조 문제는 스킬 선택보다 스킬 계약 소유권이 코드에 있다는 점입니다
+- 지금도 `DecisionEngine`은 후보 스킬 비슷한 것을 만들 수 있습니다.
+- 하지만 최종 실행 단계에서 `router.py`와 `calendar_skill.py`가 호출 경로, 엔드포인트, 헤더, 기본 다운그레이드 동작을 직접 소유합니다.
+- 따라서 이번 문제의 본질은 "스킬 선택 기능이 전혀 없다"가 아니라, "스킬 계약이 문서가 아니라 코드 분기 안에 묻혀 있다"에 가깝습니다.
+
+## Unresolved
+- `task_type`와 `goal`을 어떤 Enum/문자열 체계로 고정할지
+- `candidate_skills`를 내부 스킬명(`CALENDAR`) 기준으로 둘지, 저장소/서비스명(`skill-calendar`) 기준으로 둘지
+- `needs_human_confirmation`를 의도분석 단계에서 바로 판단할지, 스킬 계약과 결합해서 후단에서 올릴지
+- `news`, `rag-file`, `publish`, `embedding`를 1차에 함께 넣을지 2차로 미룰지
+
+## 결론
+- 현재 로빙은 이미 `Pydantic` 기반 의도분석 모델과 3단계 메타데이터 구조를 일부 가지고 있으므로, 의도분석 typed contract를 도입할 기술적 바탕은 충분합니다.
+- 현재 로빙에는 `SKILL.md`가 하나도 없고, 스킬 계약은 `README`와 `rb8001` 코드 분기 안에 흩어져 있으므로, 본체를 오케스트레이션 브레인으로 바꾸려면 계약 문서 SSOT가 먼저 필요합니다.
+- 1차 `SKILL.md` 대상은 `skill-calendar`, `skill_email`, `skill-slack`이 가장 적절합니다.
+- 다음 `plans`는 아래를 고정하면 됩니다.
+  - 의도분석 최소 typed contract 필드
+  - 1차 `SKILL.md` 대상 3개
+  - 공통 계약 템플릿
+  - `rb8001`에서 후보 스킬 계약만 읽도록 바꾸는 로더 경계
+
+## 한 줄 결론
+- 이 문제는 새 개념 발명이 아니라, 이미 있는 `typed intent skeleton`과 `직접 호출 중인 스킬들` 사이에 `SKILL.md 계약 계층`을 넣어 `rb8001`의 역할을 실행기에서 오케스트레이션 브레인으로 되돌리는 작업으로 해석하는 것이 맞습니다.
--- a/journey/research/README.md
+++ b/journey/research/README.md
@ -13,6 +13,7 @@
 - [자가수정 에이전트 프레임워크 및 Workspace CLI 검증 리서치 (260311)](./260311_자가수정_에이전트_프레임워크_및_workspace_cli_검증_리서치.md)
 - [NAVER WORKS 브리핑 인사이트 서두 누출 종료 리서치 (260311)](./260311_naverworks_briefing_insight_preamble_leak_closure_research.md)
 - [인간 업무행동과 원자스킬 분류 리서치 (260312)](./260312_인간_업무행동과_원자스킬_분류_리서치.md)
+- [스킬 계약 문서 기반 컨텍스트 오케스트레이션 리서치 (260314)](./260314_스킬_계약_문서_기반_컨텍스트_오케스트레이션_리서치.md)

 ### [기억(Memory)](./memory/README.md)
 - 장단기 기억 메커니즘