DOCS/book/300_architecture/316_skill-contract-and-execution-principles.md

# 스킬 계약 및 실행 원칙

**상위 원칙**:
- [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.0 식별자 계약 상위 원칙
- 본 섹션은 [coding-principles.md](../../../../0_VALUE/02_Governance/coding-principles.md) 식별자 계약을 스킬 호출 컨텍스트에 적용합니다.
- 스킬 간, 스킬-본체 간 파라미터 전달 시 식별자 형식은 해당 원칙을 따릅니다.

### 6.1 user_id 계약
- 스킬 호출 시 `user_id`는 **UUID(RFC 4122, 버전 무관)** 또는 **`None`/`null`** 만 허용합니다.
- 허용 예시: `"550e8400-e29b-41d4-a716-446655440000"`, `None`
- 금지: 문자열 예약어(`"system"`, `"external_service"`, `"anonymous"` 등 의미를 가진 비-UUID 문자열)
- 이유: 예약어 문자열은 식별자와 상태를 혼용해 계약 해석을 모호하게 만들고, 스킬 간 SSOT를 깨뜨립니다.

### 6.2 예약어 금지 목록
다음 문자열 값은 `user_id`를 포함한 식별자 파라미터에 사용을 금지합니다.

| 금지 값 | 이유 |
|---|---|
| `"system"` | 시스템 행위자와 실제 사용자 혼용 방지 |
| `"external_service"` | 외부 서비스 행위자를 식별자로 은닉하는 패턴 금지 |
| 기타 비-UUID 의미 문자열 | 식별자 계약 일관성 유지 |

### 6.3 None/null 허용 조건
- `user_id`가 `None`/`null`인 경우, 해당 스킬은 "사용자 컨텍스트 없음" 상태로 처리해야 합니다.
- `None` 상태에서 사용자 귀속 데이터를 기록하거나 조회하면 안 됩니다.
- 스킬은 `None` 수신 시 조용히 진행하지 않고 설명서에 명시된 처리 방침을 따릅니다.

### 6.4 위반 처리
- 스킬은 금지된 예약어 문자열을 수신하면 `400 Bad Request` 또는 동등한 오류로 거부합니다.
- 본체(`rb8001`)는 예약어 문자열을 스킬에 전달하지 않습니다. 판단 불가 시 `None`으로 처리합니다.

## 7. 구현 원칙

### 7.1 단일 기준
- 스킬 선택 기준과 실행 계약은 문서와 코드에서 같은 의미를 가져야 합니다.
- 설명서와 실제 API/CLI 동작이 다르면 문서가 아니라 런타임 SSOT가 깨진 상태로 봅니다.

### 7.2 표준화 우선
- 신규 스킬은 기존 스킬 계약 문서 구조를 재사용합니다.
- 스킬마다 설명 형식이 제각각인 상태를 방치하지 않습니다.

### 7.3 README 비중 축소
- README는 스킬 원칙 본문을 소유하지 않습니다.
- 스킬 원칙과 계약 구조는 전용 원칙 문서나 스킬별 `SKILL.md`에 둡니다.
- README에는 스킬 문서 진입 링크만 둡니다.

### 7.4 Reference 경계 고정
- 외부 또는 참고 구현체는 workspace `reference` 계층에서 참조할 수 있습니다.
- reference 저장소의 코드와 문서는 아이디어/패턴 비교 대상으로만 사용합니다.
- reference에서 가져온 스킬 구조나 컨텍스트 주입 방식은 로빙 문서에 다시 고정되고, `rb8001` 및 `skill-*` 실제 검증을 통과하기 전에는 로빙 기준으로 간주하지 않습니다.

## 8. 현재 로빙에 대한 적용 해석
- `skill-email`, `skill-news`, `skill-slack`, `skill-rag-file`, `skill-embedding`, `skill-calendar`, `skill-publish`는 로빙의 실행 스킬 서비스입니다.
- `rb8001`은 이 스킬들의 계약을 읽고 선택하는 오케스트레이터여야 합니다.
- 스킬별 세부 동작 설명은 각 서비스 문서와 `SKILL.md`로 분리하고, 본 문서는 공통 해석 규칙만 유지합니다.

## 9. 검증 기준
- 새 스킬 추가 시 본 문서의 필수 항목이 문서화되어 있어야 합니다.
- 스킬 연동 변경 시 실제 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)