From 3aacf6e1028589278a5e7259419ac8be74c40b7b Mon Sep 17 00:00:00 2001 From: happybell80 Date: Fri, 27 Mar 2026 12:28:46 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs(316):=20=EC=84=9C=EB=B9=84=EC=8A=A4=20?= =?UTF-8?q?=EA=B0=84=20=ED=8C=8C=EB=9D=BC=EB=AF=B8=ED=84=B0=20=EA=B3=84?= =?UTF-8?q?=EC=95=BD=20=EC=84=B9=EC=85=98=20=EC=B6=94=EA=B0=80=20=E2=80=94?= =?UTF-8?q?=20user=5Fid=20UUID=20=EC=A0=95=EC=B1=85=20=EB=B0=8F=20?= =?UTF-8?q?=EC=98=88=EC=95=BD=EC=96=B4=20=EA=B8=88=EC=A7=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - §6 서비스 간 파라미터 계약 신설 (user_id: RFC 4122 UUID 또는 None만 허용) - "system", "external_service" 등 비-UUID 예약어 금지 명시 - coding-principles.md 식별자 계약 상위 원칙으로 참조 연결 - 기존 §6 구현 원칙 → §7, §7 현재 적용 → §8, §8 검증 → §9 로 번호 재정렬 Co-Authored-By: Claude Sonnet 4.6 --- ...skill-contract-and-execution-principles.md | 44 ++++++++++++++++--- 1 file changed, 37 insertions(+), 7 deletions(-) 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..4dcb7a5 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,62 @@ - 따라서 스킬 실행 로그는 단순 성공/실패만이 아니라, 가치 판단과 측정 기준 개선의 입력으로 남겨야 합니다. - 가치 측정 기준이 바뀌면 프롬프트 임시 수정이 아니라 문서화된 정책과 계약부터 갱신합니다. -## 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`으로 처리합니다. + +## 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 응답 또는 실행 로그로 계약 일치 여부를 검증해야 합니다. - 스킬 설명서가 없거나 계약이 누락된 상태에서는 "스킬 사용 가능"이라고 단정하지 않습니다. From a062ca7497f16a1c7159f61ac66eaf8cdbfaa32f Mon Sep 17 00:00:00 2001 From: happybell80 Date: Fri, 27 Mar 2026 12:50:50 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs(316):=20LLM=20tool=20=ED=8C=8C?= =?UTF-8?q?=EB=9D=BC=EB=AF=B8=ED=84=B0=20=ED=98=95=EC=8B=9D=C2=B7=EC=98=88?= =?UTF-8?q?=EC=8B=9C=20description=20=EB=AA=85=EC=8B=9C=20=EC=9B=90?= =?UTF-8?q?=EC=B9=99(6.5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Made-with: Cursor --- .../316_skill-contract-and-execution-principles.md | 5 +++++ 1 file changed, 5 insertions(+) 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 4dcb7a5..edcfa66 100644 --- a/book/300_architecture/316_skill-contract-and-execution-principles.md +++ b/book/300_architecture/316_skill-contract-and-execution-principles.md @@ -106,6 +106,11 @@ - 스킬은 금지된 예약어 문자열을 수신하면 `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 단일 기준