iop/agent-ops/skills/common/create-contract/SKILL.md

name	version	description
create-contract	1.0.0	agent-contract 구조와 inner/outer 계약 문서를 생성한다. 계약 생성해, 프로젝트 계약 생성해, contract 생성, agent-contract 생성, inner/outer 계약 생성 요청에서 사용한다.

create-contract

목적

프로젝트에 계약 관리가 필요해진 시점에 agent-contract/ 구조를 생성하고, 흩어진 문서와 코드에서 확인한 계약을 inner/outer 기준으로 정리한다. 계약 문서는 schema 원본을 복제하지 않고, agent가 읽을 수 있는 라우팅, 원본 경로, 필드 의미, 변경 규칙, 검증 포인터를 한 곳에 모은다.

언제 호출할지

• 사용자가 계약 생성, 프로젝트 계약 생성, contract 생성, agent-contract 생성을 요청할 때
• API, runtime 호출, wire protocol, event/config schema 같은 계약을 처음 문서화할 때
• 프로젝트에 agent-contract/가 없고, 둘 이상의 프로젝트/프로세스/앱/도메인이 맞춰야 하는 요청/응답 경계가 확인될 때
• 기존 README/docs/rules/code에 흩어진 계약 설명을 새 계약 구조로 모아야 할 때

입력

• contract-id: 계약 식별자, kebab-case 또는 dotted id (선택, 없으면 분석으로 후보 산출)
• boundary: inner 또는 outer (선택, 없으면 실제 소비자와 경계로 판정)
• scope: 계약 범위 요약. 예: public HTTP API, worker-runtime protocol, app-server wire (선택, 없으면 코드/문서에서 산출)
• canonical-path: proto/OpenAPI/config/code 등 schema 원본 경로 (선택, 없으면 분석으로 찾음)
• trigger-conditions: 계약 문서를 읽어야 하는 조건 목록 (선택)

분류 기준

• outer: 프로젝트 바깥 caller나 다른 프로젝트가 직접 맞춰야 하는 계약이다. 예: 공개 HTTP API, webhook, 외부 SDK, 외부 agent handoff.
• inner: 같은 프로젝트 안이어도 프로세스, 앱, 도메인, runtime 경계를 넘는 계약이다. 예: controller-worker proto, service-service wire, app-server WebSocket, runtime request/event/config schema.
• 제외: 한 패키지 내부 private interface, 코드만 보면 충분한 DTO, 안정화되지 않은 실험 구조, 단일 구현 내부 helper.

먼저 확인할 것

• agent-contract/ 존재 여부를 확인한다.
• agent-contract/index.md가 있으면 읽고 기존 구조와 중복 id를 확인한다.
• 요청 범위와 관련된 코드, proto, config, README/docs/rules를 읽어 원본 경로와 흩어진 계약 설명을 찾는다.
• 계약 원문을 이미 docs/README/rules에 길게 복제하고 있는지 확인한다.

실행 절차

1. 필요성 판정

   • 둘 이상의 프로젝트/프로세스/앱/도메인이 맞춰야 하는 안정 경계인지 확인한다.
   • 단일 패키지 내부 구현이면 계약 문서를 만들지 않고 이유를 보고한다.
   • 단건 contract-id가 없으면 코드와 문서에서 계약 후보를 수집하고, 안정 경계가 확인된 후보만 생성한다.
   • 후보는 있지만 boundary나 원본 경로가 불명확하면 문서를 억지로 만들지 않고 확인 필요로 보고한다.

2. 구조 생성

   • agent-contract/index.md가 없으면 생성한다.
   • agent-contract/inner/와 agent-contract/outer/가 없으면 생성한다.
   • legacy provided/consumed/가 있으면 덮어쓰지 않고, 이번 생성 결과와 충돌하는지 보고한다.

3. 코드와 문서 분석

   • 관련 schema 원본을 먼저 찾는다. 우선순위는 proto/OpenAPI/schema 파일, config struct, public DTO/interface, handler/parser, 테스트 fixture 순서다.
   • README/docs/rules에 흩어진 계약 설명을 찾고, 계약 문서에 필요한 내용만 추린다.
   • 필드 의미는 코드와 테스트에서 확인한 것만 쓴다. 추측은 확인 필요로 남긴다.

4. 계약 문서 작성

   • 경로는 agent-contract/<inner|outer>/<contract-name>.md로 둔다.
   • 여러 계약을 생성해야 하면 각 문서는 독립된 경계 단위로 나누고, 공통 설명은 index가 아니라 각 계약의 원본 경로 포인터로 해결한다.
   • 문서는 짧게 유지하고 다음 항목을 포함한다.
     • 계약 메타: id, boundary, 원본 경로, status(필요한 경우)
     • 읽는 조건
     • 범위와 비범위
     • 최소 요청/응답 또는 message/event 형태
     • 필드 의미와 금지 사항
     • 변경 시 확인할 코드/테스트
   • 원본 schema 전체를 복제하지 않는다. 긴 schema는 원본 경로와 핵심 필드 의미만 둔다.

5. index 갱신

   • Outer Contracts와 Inner Contracts 섹션을 둔다.
   • outer/inner 표는 id, 읽는 조건, 원본 경로, path를 둔다.
   • 매칭 조건은 agent가 검색/판단할 수 있는 API 이름, message 이름, field 이름, runtime 이름, protocol 이름을 포함한다.
   • 프로젝트 전용 path trigger는 공통 rule이 아니라 agent-contract/index.md의 읽는 조건/원본 경로 또는 project/domain rule 포인터로 둔다.

6. 흩어진 문서 정리

   • README/docs/rules에 계약 본문이 중복되어 있으면 원문 경로 포인터로 줄인다.
   • domain rule에는 소유권, 경계, 금지 사항만 남기고 상세 schema는 계약 문서 또는 원본 경로를 가리킨다.
   • common rule에는 특정 프로젝트 경로, 계약 id, API 이름을 추가하지 않는다. common rule은 agent-contract/index.md 조건부 진입까지만 담당한다.
   • 사람용 최신 가이드가 필요한 README 문구는 유지하되 계약 원문과 충돌하지 않게 축소한다.

7. 결과 보고

   • 생성한 index와 계약 문서
   • boundary 판정 근거
   • 원본 경로
   • 중복 제거 또는 포인터화한 문서
   • 확인 필요 항목

실행 결과 검증

• agent-contract/index.md가 생성되고 inner/outer 라우팅 표를 포함하는가
• 계약 문서가 agent-contract/inner/ 또는 agent-contract/outer/ 아래에 있는가
• 계약 id가 index와 문서 메타에서 일치하는가
• 원본 경로가 실제 존재하거나 외부 원본으로 명확히 적혀 있는가
• README/docs/rules에 계약 본문이 중복 복제되지 않고 포인터만 남았는가
• 코드/proto/config/test 분석 없이 계약을 추정하지 않았는가
• 검증 실패 시: 누락된 index, 문서 메타, 포인터, 원본 경로만 보완한다.

출력 형식

## 계약 생성 완료

- index: agent-contract/index.md
- contracts: agent-contract/<inner|outer>/<contract-name>.md
- boundary: <inner|outer> (<근거>)
- 원본 경로: <path 또는 외부 원본>
- pointers: <갱신한 README/docs/rules 경로 또는 없음>
- 확인 필요: <항목 또는 없음>

금지 사항

• 모든 내부 interface를 계약 문서로 만들지 않는다.
• 원본 schema 전체를 계약 문서에 장황하게 복제하지 않는다.
• 코드/proto/config/test 확인 없이 필드 의미를 단정하지 않는다.
• README/docs/rules에 계약 본문을 계속 중복 유지하지 않는다.
• 프로젝트 전용 path trigger를 common rule에 넣지 않는다.
• legacy provided/consumed/ 구조가 있어도 사용자 요청 없이 대량 이동하지 않는다.