실전 예제: 선언과 Helper JSON

01 · 작은 연동 하나와 확인 지점

목표: 자체 서비스의 읽기 전용 status.read 작업을 기술합니다. 입력은 서비스 이름, 선언한 출력은 서비스 이름과 Boolean 상태 값입니다. 아래 문서부터 시작해 결과·오류 예제로 Helper가 확인하는 내용을 배웁니다.

대상 명시
소스 설명
검사 결과 해석
입력 교정

지금 할 수 있는 일: 소스 문서 다운로드·수정, JSON 문법 확인, 실제 로컬 결과 확인, AI 에이전트를 활용한 검토 준비입니다.

로컬 예제 범위: 기존 macOS Helper 바이너리로 소스 문서 발견을 확인했습니다. 정확한 빌드 리비전과 고객 배포는 미입증입니다. 완전한 고객 요청 봉투·대상 연결·실제 실행은 대기이며 다운로드만으로 전체 Helper 실행을 재현할 수는 없습니다.

02 · Contract 선언: 의도와 대상 참조

작업 개요는 자체 서비스가 하는 일을 기록합니다. CUSTOM_API 문서는 그 입력·출력 형태를 지원되는 제한 형식으로 표현합니다. 제품 Contract는 Helper가 일치 여부를 확인해야 하는 공급자 관리 대상입니다. JSON에 새 이름을 적는다고 생성되지 않습니다. Contract 참조 조각은 공급자가 제공할 값의 자리를 명시합니다. 완전한 요청이 아니며 대상 검증을 통과한 예제가 아닙니다.

작업 개요 작성다운로드

계획용 개요이며 제품 스키마나 요청이 아닙니다.

# Status read integration brief

Illustrative requirements brief; this Markdown is not a VibePackr parser input.

- Goal: read the health status of one service.
- Caller input: `service`, a string such as `catalog`.
- Result: `service` (string) and `healthy` (boolean).
- Operation: read only; no restart or configuration changes.
- Credentials: none in this offline example; do not paste tokens into the document.
- Target contract and adapter: obtain the exact supported identifiers and revisions from the supplier.
- Completion for this example: a source document is accepted for discovery. No live service is called.

아래 조각은 지원 제품 패키지가 제공해야 하는 대상 값을 설명합니다. 소스 문서와 분리하세요. 이 키를 status-document.json 에 붙여 넣으면 입력 형태가 바뀝니다.

기존 Contract 참조다운로드

불완전한 대상 참조 조각입니다. SUPPLIER_PUBLISHED_*는 정확히 제공된 값으로만 바꾸며 통과한 요청이 아닙니다.

{
  "capability_id": "SUPPLIER_PUBLISHED_CAPABILITY_ID",
  "contract_id": "SUPPLIER_PUBLISHED_CONTRACT_ID",
  "contract_revision": "SUPPLIER_PUBLISHED_CONTRACT_REVISION",
  "adapter_id": "SUPPLIER_PUBLISHED_ADAPTER_ID",
  "adapter_revision": "SUPPLIER_PUBLISHED_ADAPTER_REVISION",
  "operation_id": "status.read"
}

필드	값의 출처
`capability_id` / `contract_id`	지원 연동용으로 제공된 정확한 식별자입니다.
`contract_revision`	제공된 대상 리비전이며 자체 소스 문서 리비전이 아닙니다.
`adapter_id` / `adapter_revision`	지원 어댑터의 식별자와 호환 리비전입니다.
`operation_id`	선언한 소스에서 고른 작업이며 여기서는 `status.read` 입니다.

완료 확인: 모든 대상 참조를 제공 패키지에서 찾을 수 있어야 합니다. 대상이 제공되지 않으면 누락된 표준 입력으로 기록하고, 진행하려고 임의 Contract 이름을 만들지 않습니다.

03 · Document 선언: 완전한 소스 예제

자체 서비스의 상태를 읽기 전용으로 조회하는 작업을 기술합니다. 예제는 서비스 이름을 입력으로 받고 결과의 service와 healthy 두 필드를 설명합니다. 새로 작성한 합성 문서이며 실제 제공자 지원을 선언하지 않습니다. status-document.json을 내려받고 필드 설명을 확인한 뒤 수정하세요.

CUSTOM_API 문서: status.read다운로드

완전한 소스 문서이며 내부 시험 봉투에서 로컬 발견에 허용됐습니다. 완전한 CLI 요청은 아닙니다.

{
  "document_kind": "CUSTOM_API",
  "protocol_revision": "1",
  "operations": {
    "status.read": {
      "input_schema": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          }
        },
        "required": [
          "service"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          },
          "healthy": {
            "type": "boolean"
          }
        },
        "required": [
          "service",
          "healthy"
        ]
      }
    }
  }
}

JSON 구조와 프로토콜 리비전을 유지하세요. 작업 이름·속성 이름·원시 타입은 실제 자체 서비스에 맞춥니다. 속성 이름을 바꾸면 모든 required 목록도 수정합니다. 이 제한된 문서 형식에는 주석이나 설명용 description 키를 추가하지 않습니다. JSON은 대소문자를 구분합니다.

04 · 필드 참조와 자주 하는 수정 실수

필드	예제 값	편집 방법
`document_kind`	`CUSTOM_API`	제한된 사용자 API 문서 입력을 선택합니다. OpenAPI 문서를 뜻하지 않습니다.
`protocol_revision`	`1`	지원되는 문서 형식 리비전입니다. 이 예제에서는 그대로 유지합니다.
`operations.status.read`	`operation name`	자체 작업 식별자입니다. 소스를 기술하며 등록된 제품 기능을 생성하지 않습니다.
`input_schema`	`service: string`	기술한 작업이 받는 값의 형태입니다. 선언만으로 작업을 호출하지 않습니다.
`output_schema`	`service: string, healthy: boolean`	결과 형태를 선언하며 실제 서비스 결과를 관측한 것은 아닙니다.
`type`	`object / primitive`	최상위 스키마는 object입니다. 이 제한 형식의 속성은 string, integer, number, boolean을 사용합니다.
`properties`	`named primitive fields`	모든 필수 필드 이름이 여기에 있어야 합니다. 이 예제 경로는 배열, 중첩 객체, 추가 JSON Schema 키워드를 지원하지 않습니다.
`required`	`field-name list`	필수 필드 이름 목록이며 값 자체가 아닙니다. 이름을 중복하지 않고 properties에 존재하도록 합니다.

스키마는 값의 형태를 기술합니다. 실제 요청 {"service":"demo-service"} 이나 관측한 서비스 응답이 아닙니다. 예제는 출력 두 필드가 모두 필수이므로 healthy 가 없으면 선언한 형태와 맞지 않습니다.

05 · 로컬 준비: 문법·요청 봉투·결과

status-document.json 을 새 폴더에 내려받고 원본을 남긴 뒤 사본을 수정합니다.
Python 3이 있으면 해당 폴더에서 아래 문법 검사를 실행합니다. 제품·네트워크 호출은 없습니다. 출력 없이 종료 코드 0이면 JSON 문법 파싱 성공입니다.
위 필드를 확인합니다. 문법 검사로 제품 Contract가 검증되지는 않습니다.
버전이 맞는 공급자 요청 봉투가 있을 때만 전체 요청을 사용합니다. 두 번째 명령은 그 문법 참조이며 소스 문서 다운로드는 해당 봉투가 아닙니다.

로컬 준비: 문법·요청 봉투·결과

python3 -m json.tool status-document.json > /dev/null

status-document.json은 완전한 소스 문서이며 완전한 CLI 요청은 아닙니다. R2는 request_id, correlation_id, draft가 있는 요청 봉투를 읽고 이 문서는 draft.source에 들어갑니다. 로컬 발견 검사는 대상 참조를 연결하지 않고 fixture도 실행하지 않은 별도 내부 봉투로 수행했습니다. status-document.json을 r2-discover에 바로 전달하거나 조각을 합쳐 유효한 요청이라고 간주하지 마세요. 완전한 고객 요청 패키지에는 승인된 대상 연결과 배포용 최소 투영이 더 필요합니다.

로컬 준비: 문법·요청 봉투·결과

packr-integration-helper r2-discover request.json

공급자가 제공하는 완전한 요청 봉투를 사용할 때의 명령 형식입니다. 단독 문서 다운로드가 request.json은 아닙니다. 검증 실행에는 내부 봉투를 사용했으므로 이 줄은 공개 다운로드만으로 재현하는 절차가 아니라 명령 참조입니다.

관측한 발견 결과 — 선택 필드다운로드

실제 로컬 출력의 일부입니다. 생략한 필드는 재구성하지 않았으며 실제 서비스 응답은 아닙니다.

{
  "operation": "DISCOVER",
  "request_id": "example-status-discover-001",
  "status": "PASSED",
  "reason": "NONE",
  "lifecycle_stage": "DISCOVERED"
}

PASSED와 lifecycle_stage DISCOVERED는 소스 문서가 발견 단계에서 허용되었음을 뜻합니다. 대상 Contract 검증, status.read 호출, 연결 확인, 권한 부여를 뜻하지 않습니다. 결과 조각은 로컬 실행에서 선택한 실제 필드 값이며 나머지 봉투 필드는 생략했습니다. 연결하지 않은 대상을 정규화했을 때는 DENIED / CONTRACT_INCOMPATIBLE이 반환됐습니다.

미연결 대상의 관측 결과다운로드

의도적으로 연결하지 않은 대상의 실제 로컬 정규화 결과입니다.

{
  "operation": "NORMALIZE",
  "request_id": "example-status-discover-001",
  "status": "DENIED",
  "reason": "CONTRACT_INCOMPATIBLE",
  "lifecycle_stage": null
}

JSON의 status와 reason을 항상 확인하세요. R2는 의미상 거부해도 프로세스 종료 코드 0을 반환할 수 있습니다. 종료 코드만으로 성공을 판단하지 않습니다.

06 · MCP 문서: 저장한 관측 기록 확인

MCP 예제는 지원되는 정확한 리비전 2025-03-26의 initialize 및 tools/list 기록입니다. 동일한 status.read 입출력 형태를 사용하며 제한된 로컬 발견에서 허용됐습니다. MCP 서버 시작, 에이전트 확장 설치, 임의 에이전트 호환성을 입증하지 않습니다. 실제 관측된 협상 리비전을 유지하세요. 문자열을 바꾼다고 새로운 기록이 호환되는 것은 아닙니다.

MCP initialize 및 tools/list 예제다운로드

2025-03-26의 합성 저장 기록이며 로컬 문서 발견만 확인했습니다. 실제 MCP 연결은 없습니다.

{
  "document_kind": "MCP_TRANSCRIPT",
  "initialize": {
    "request": {
      "jsonrpc": "2.0",
      "id": "example-init-1",
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-03-26",
        "capabilities": {},
        "clientInfo": {
          "name": "example-doc-client",
          "version": "1.0"
        }
      }
    },
    "response": {
      "jsonrpc": "2.0",
      "id": "example-init-1",
      "result": {
        "protocolVersion": "2025-03-26",
        "capabilities": {
          "tools": {}
        },
        "serverInfo": {
          "name": "example-status-service",
          "version": "1.0"
        }
      }
    }
  },
  "tools_list": {
    "request": {
      "jsonrpc": "2.0",
      "id": "example-tools-2",
      "method": "tools/list",
      "params": {}
    },
    "response": {
      "jsonrpc": "2.0",
      "id": "example-tools-2",
      "result": {
        "tools": [
          {
            "name": "status.read",
            "inputSchema": {
              "type": "object",
              "properties": {
                "service": {
                  "type": "string"
                }
              },
              "required": [
                "service"
              ]
            },
            "outputSchema": {
              "type": "object",
              "properties": {
                "service": {
                  "type": "string"
                },
                "healthy": {
                  "type": "boolean"
                }
              },
              "required": [
                "service",
                "healthy"
              ]
            }
          }
        ]
      }
    }
  }
}

initialize 요청 → 협상된 initialize 응답 → tools/list 요청 → 기술된 도구 스키마 순으로 읽습니다. 요청·응답 ID가 각 쌍을 식별합니다. 실행 중인 transport가 없는 저장 예제이므로 도구 이름으로 서버 URL을 추정하지 않습니다.

MCP 문서 발견 관측 결과다운로드

실제 로컬 출력 일부이며 tools/call 실행은 아닙니다.

{
  "operation": "DISCOVER",
  "request_id": "example-mcp-discover-001",
  "status": "PASSED",
  "reason": "NONE",
  "lifecycle_stage": "DISCOVERED"
}

같은 파일의 에이전트 검토에는 MCP 관측 안내를 사용하세요.

07 · R0와 R2의 서로 다른 입력

R0 소스 메타데이터와 R2 프로토콜 문서는 서로 다른 입력입니다. R0 메타데이터 조각은 선언된 엔드포인트와 미확인 관측값을 표현하며 완전한 R0 입력은 아닙니다. 완전한 로컬 R0 실험에서는 discover와 normalize가 통과했고 연결 상태를 알 수 없어 validate가 ENDPOINT_UNREACHABLE로 실패했습니다. 예제를 통과시키기 위해 미확인 관측값을 true로 바꾸지 말고 실제 제한된 관측을 확보하세요. example.invalid 엔드포인트는 의도적으로 작동하지 않는 예시 주소이며 접속하지 않았습니다.

R0 소스 메타데이터 — 비교다운로드

조각입니다. 미확인 관측은 null로 두며 .invalid 주소에 접속하지 않았습니다.

{
  "schema_version": "packr.integration-helper.v1",
  "integration_class": "HTTP_REST",
  "source_kind": "SERVICE_METADATA",
  "source_reference": "status-document.json",
  "source_revision": "example-1",
  "source_digest_sha256": "5844f2cce8405450a782f50a0b62210a417a5ef66139be138fa78761559440b5",
  "declared_protocol": "HTTPS",
  "declared_endpoint": "https://status.example.invalid/status",
  "read_only": true,
  "reachable": null,
  "security_validated": null,
  "identity_satisfied": null
}

완전한 R0 입력을 제공받으면 R0 명령 계열, 완전한 R2 요청 봉투를 제공받으면 R2 명령 계열에 사용합니다. 파일 이름을 바꾸는 것으로 형식이 변환되지는 않습니다.

메타데이터 조각 다운로드만으로 실행할 수 없습니다.

08 · 오류 예제: 진단·수정·재확인

통제된 변경	관찰된 결과	최소 수정
output_schema.required에 uptime을 추가하고 properties에는 정의하지 않음	`DENIED / SCHEMA_INCOMPATIBLE`	실제로 필수라면 대응하는 원시 타입 속성을 추가하고, 아니라면 required에서 uptime을 제거한 뒤 수정 문서를 다시 확인합니다.
프로토콜 문서에 description 필드 추가	`DENIED / INVALID_REQUEST`	설명 문장은 가이드나 개요에 두고 기계 입력에서 지원하지 않는 필드를 제거합니다.
지원하지 않는 MCP 리비전 2099-01-01 사용	`DENIED / PROTOCOL_REVISION_MISMATCH`	지원되는 리비전으로 협상한 실제 기록을 사용합니다. 다른 프로토콜 기록의 버전 이름만 바꾸지 않습니다.
연결되지 않은 example.unbound.contract 대상 사용	`DENIED / CONTRACT_INCOMPATIBLE`	지원되는 연동에 대해 공개된 정확한 대상 Contract와 어댑터 참조를 확보합니다. 제품 측 표준화가 필요한 단계이며 새 이름을 지어내 해결할 수 없습니다.

필수 속성 오류 관측 결과다운로드

문서에 설명한 변형에 대한 실제 로컬 거부 결과입니다.

{
  "operation": "DISCOVER",
  "request_id": "example-status-discover-001",
  "status": "DENIED",
  "reason": "SCHEMA_INCOMPATIBLE",
  "lifecycle_stage": null
}

지원하지 않는 필드 오류 관측 결과다운로드

예상 형식이 아닌 실제 로컬 파싱 결과입니다.

{
  "operation": "DISCOVER",
  "request_id": "UNAVAILABLE",
  "status": "DENIED",
  "reason": "INVALID_REQUEST",
  "lifecycle_stage": null
}

MCP 리비전 오류 관측 결과다운로드

지원되지 않는 리비전으로 바꾼 뒤의 실제 로컬 결과입니다.

{
  "operation": "DISCOVER",
  "request_id": "example-mcp-discover-001",
  "status": "DENIED",
  "reason": "PROTOCOL_REVISION_MISMATCH",
  "lifecycle_stage": null
}

사본에서 한 번에 하나씩 수정하고 원래 결과를 보존하세요. 완전한 요청 패키지가 있으면 동일한 지원 준비 단계를 다시 확인합니다. 통과시키려고 권한 오류를 우회하거나 프로토콜 리비전 이름을 바꾸거나 연결이 확인됐다고 선언하지 않습니다.

09 · 매핑 예제: 필드 대응 제안

소스 결과 필드가 service이고 승인된 대상 출력이 service_name을 사용한다고 가정합니다. 양쪽이 string이면 정확한 매핑 양식과 대상이 제공된 뒤 지원되는 IDENTITY 변환으로 이름 대응을 표현할 수 있습니다. 아래 표는 검토 자료이며 매핑 JSON이 아닙니다.

소스 출력	대상 출력	검토(Review)
`service: string`	`service_name: string`	이름 대응 가능성; 대상과 필수 여부 확인.
`healthy: boolean`	`status: string`	타입과 의미가 다름. 이 예제로 Boolean→string 변환 지원은 입증되지 않음.
`"42": string`	`42: integer`	`STRING_TO_INTEGER` 범위가 정해진 참고 자료에 존재합니다. 승인된 대상에서 요구하는 경우에만 사용하십시오.

에이전트는 이 표를 제안할 수 있지만 실제 요청은 Helper가 확인합니다. REQUIRES_IMPLEMENTATION 표시가 있는 생성 scaffold는 동작하는 어댑터가 아닙니다.

10 · 맞춤 연동 작업 없이 전달할 수 있는 지원 기록

제품·도구 버전(모르면 미확인), 문서 종류·리비전, 도달 단계, 정확한 status/reason, 기대 결과, 문제인 필드나 제공 참조 하나를 기록합니다. 지원 경로 로 짧고 민감정보를 제거한 내용을 전달하세요. 자격증명·전체 로그·고객 payload·내부 bundle은 제외합니다.

완전한 버전 지정 예제 패키지, 설치 안내, 지원 대상 참조, 등록 절차처럼 누락된 표준 제공물을 요청하세요. 고객별 맞춤 스크립트가 일반 온보딩 경로가 되어서는 안 됩니다.

11 · 완료된 부분과 셀프서비스에 남은 조건

확인 지점	현재 증거
Document 작성	완전한 CUSTOM_API·MCP 소스 예제, 필드 설명, 다운로드.
로컬 소스 발견	기존 로컬 바이너리의 긍정·부정 관측. 정확한 빌드 식별은 미입증.
복사·실행 가능한 제품 준비	완전한 공개 요청 봉투·대상 패키지·고객 설치 경로 대기.
등록·실행	미수행. 준비로 실행 권한이 부여되지 않음.
AI 및 고객 전체 과정 검증	별도 설정과 실제 연결 검증 대기.

셀프서비스 성공 경로에는 지원 대상 참조를 포함한 버전 지정 완전 요청 패키지, 승인된 고객 Helper 설치 경로, 독립 검증된 준비 결과가 필요합니다. 이번 조사는 구체적인 문서 예제의 공백을 줄였으며 제품 전달 공백까지 해소한 것은 아닙니다.

범위가 정해진 기업 평가 · 다음 단계

고객 환경에서 통제된 작업 흐름 하나를 평가하십시오.

평가할 AI 작업 흐름 하나와 대상 실행 경계·승인 요건을 정리하세요. 기록된 로컬 R234 사례와 비교하거나 구조화된 PoC 평가 순서를 따르고, 2026년 10월 18일 영문·한국어 기술 백서를 참고하세요.

평가 문의 (이메일) 11단계 PoC 가이드 시작 → 기술 백서 (2026년 10월 18일 PDF) 한국어 PDF (KR)

연락 경계 안내: “평가 문의”를 클릭하면 로컬 메일 프로그램이 다음 수신 주소로 열립니다: support@vibepackr.com 로 구조화된 문의 양식이 열립니다. 이메일 전송만으로 지원 사례가 등록되거나 어플라이언스가 구성되지는 않습니다. 자격 증명·개인정보·기밀 로그를 포함하지 마십시오.