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

스킬 계약 및 실행 원칙

상위 원칙:

• 0_VALUE Coding Principles
• 0_VALUE Writing Principles
• 0_VALUE Agents Guide
• AI 에이전트 시대의 CLI·스킬·인터페이스 진화

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 식별자 계약을 스킬 호출 컨텍스트에 적용합니다.
• 스킬 간, 스킬-본체 간 파라미터 전달 시 식별자 형식은 해당 원칙을 따릅니다.

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으로 처리합니다.

6.5 LLM tool 파라미터 형식 명시 원칙

• LLM에게 노출하는 tool(함수 호출·도구 스키마)을 정의할 때, 각 파라미터의 형식 제한을 해당 파라미터의 description(또는 동등한 계약 필드)에 반드시 명시합니다. 예: 저장소 식별 owner/name, 시각 ISO 8601, 허용 값이 정해진 경우 enum 값 목록 등.
• 형식 설명에는 올바른 값 예시를 1개 이상 포함합니다. (예: ISO 8601 → 2026-03-27T12:00:00Z, owner/name → ivada_Ro-being/rb8001.)
• 형식·예시가 불충분해 LLM이 규약에 맞지 않는 값을 넣은 경우, 우선 tool 정의(스키마·설명)의 결함으로 간주하고 정의를 보강합니다. 모델 출력만 탓하지 않습니다.

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
• 360_로빙_컨테이너_경량화_전략.md
• 로빙 에이전트 루프, 스킬 훅, LLM 실행 구조 리서치