diff --git a/book/300_architecture/316_skill-contract-and-execution-principles.md b/book/300_architecture/316_skill-contract-and-execution-principles.md index 1fab0d1..edcfa66 100644 --- a/book/300_architecture/316_skill-contract-and-execution-principles.md +++ b/book/300_architecture/316_skill-contract-and-execution-principles.md @@ -76,32 +76,67 @@ - 따라서 스킬 실행 로그는 단순 성공/실패만이 아니라, 가치 판단과 측정 기준 개선의 입력으로 남겨야 합니다. - 가치 측정 기준이 바뀌면 프롬프트 임시 수정이 아니라 문서화된 정책과 계약부터 갱신합니다. -## 6. 구현 원칙 +## 6. 서비스 간 파라미터 계약 -### 6.1 단일 기준 +### 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`으로 처리합니다. + +### 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가 깨진 상태로 봅니다. -### 6.2 표준화 우선 +### 7.2 표준화 우선 - 신규 스킬은 기존 스킬 계약 문서 구조를 재사용합니다. - 스킬마다 설명 형식이 제각각인 상태를 방치하지 않습니다. -### 6.3 README 비중 축소 +### 7.3 README 비중 축소 - README는 스킬 원칙 본문을 소유하지 않습니다. - 스킬 원칙과 계약 구조는 전용 원칙 문서나 스킬별 `SKILL.md`에 둡니다. - README에는 스킬 문서 진입 링크만 둡니다. -### 6.4 Reference 경계 고정 +### 7.4 Reference 경계 고정 - 외부 또는 참고 구현체는 workspace `reference` 계층에서 참조할 수 있습니다. - reference 저장소의 코드와 문서는 아이디어/패턴 비교 대상으로만 사용합니다. - reference에서 가져온 스킬 구조나 컨텍스트 주입 방식은 로빙 문서에 다시 고정되고, `rb8001` 및 `skill-*` 실제 검증을 통과하기 전에는 로빙 기준으로 간주하지 않습니다. -## 7. 현재 로빙에 대한 적용 해석 +## 8. 현재 로빙에 대한 적용 해석 - `skill-email`, `skill-news`, `skill-slack`, `skill-rag-file`, `skill-embedding`, `skill-calendar`, `skill-publish`는 로빙의 실행 스킬 서비스입니다. - `rb8001`은 이 스킬들의 계약을 읽고 선택하는 오케스트레이터여야 합니다. - 스킬별 세부 동작 설명은 각 서비스 문서와 `SKILL.md`로 분리하고, 본 문서는 공통 해석 규칙만 유지합니다. -## 8. 검증 기준 +## 9. 검증 기준 - 새 스킬 추가 시 본 문서의 필수 항목이 문서화되어 있어야 합니다. - 스킬 연동 변경 시 실제 API 응답 또는 실행 로그로 계약 일치 여부를 검증해야 합니다. - 스킬 설명서가 없거나 계약이 누락된 상태에서는 "스킬 사용 가능"이라고 단정하지 않습니다.