nomadcode/agent-ops/skills/common/agent-contract/SKILL.md

name	version	description
agent-contract	1.0.0	agent-contract index와 제공/소비 계약 문서를 생성하거나 갱신한다.

agent-contract

목적

프로젝트 간 API, 런타임 호출, 요청/응답 스키마 계약을 agent-contract/ 구조로 관리한다. 계약 원문을 한 곳에 두고, README/docs/rules에는 라우팅 포인터만 남긴다.

언제 호출할지

• 외부 프로젝트가 참조할 API 또는 런타임 계약을 생성하거나 갱신할 때
• 다른 프로젝트의 계약을 소비 계약으로 등록할 때
• agent-contract/index.md의 제공/소비 계약 라우팅을 정리할 때
• 계약 원문을 수정한 뒤 index, README, docs 포인터와 정합성을 확인할 때

입력

• contract-id: 계약 식별자, 예: billing.public-api 또는 auth.session-events (필수)
• mode: provided 또는 consumed (필수)
• contract-path: 계약 원문 경로 또는 외부 source 경로 (필수)
• trigger-conditions: 계약 문서를 읽어야 하는 조건 목록 (필수)

먼저 확인할 것

• agent-contract/index.md가 있는지 확인하고, 없으면 최초 생성 대상으로 본다.
• 동일 contract-id가 이미 제공 또는 소비 계약에 있는지 확인한다.
• 계약 원문이 docs/, README, rules.md에 중복 복제되어 있지 않은지 확인한다.
• agent-ops 공통 규칙에는 특정 계약명이 아니라 agent-contract/index.md 조건부 진입 규칙만 있는지 확인한다.

실행 절차

1. 초기 구조 확인

   • agent-contract/index.md가 없으면 생성한다.
   • agent-contract/provided/가 없으면 생성한다.
   • 소비 계약 원문을 저장하지 않는 한 agent-contract/consumed/는 만들지 않는다.
   • index에는 읽기 규칙, 제공 계약 표, 소비 계약 표를 둔다.

2. 계약 위치 결정

   • 제공 계약은 agent-contract/provided/<contract-name>.md에 둔다.
   • 소비 계약은 agent-contract/index.md의 소비 계약 표에 외부 source만 둔다.
   • 소비 계약 원문을 현재 프로젝트에 복제하지 않는다.

3. index 갱신

   • agent-contract/index.md의 읽기 규칙을 유지한다.
   • 제공 계약 표는 id, 읽는 조건, path 열을 유지한다.
   • 소비 계약 표는 id, 읽는 조건, source 열을 유지한다.
   • 제공 계약 또는 소비 계약 표에 id, 읽는 조건, 경로를 추가하거나 갱신한다.
   • 매칭 조건은 agent가 판단할 수 있는 API 이름, field 이름, runtime 이름, protocol 이름을 포함한다.

4. 계약 원문 갱신

   • 계약 원문에는 범위, 최소 요청/응답 형태, 필드 의미, 금지 사항, 구현 메모를 둔다.
   • 사람용 설명 문서에는 계약 원문을 복제하지 않고 링크만 둔다.
   • 기존 계약을 수정할 때는 index의 읽는 조건과 path/source가 수정 후 계약 원문과 여전히 맞는지 확인한다.

5. 읽기 흐름 확인

   • 계약 확인 작업은 common rule이 agent-contract/index.md를 조건부로 읽고, index가 매칭 계약 원문으로 라우팅한다.
   • 읽기 전용 작업에서는 계약 원문이나 index를 수정하지 않는다.
   • 매칭 계약이 없으면 계약을 추정하지 않고 사용자에게 확인한다.

6. 라우팅 문서 갱신

   • README/docs/rules에는 계약 원문 경로만 남긴다.
   • common rule에는 특정 계약 id나 프로젝트명을 넣지 않는다.
   • project rule에는 해당 프로젝트 고유 코드/도메인 규칙만 두고 agent-contract 공통 라우팅을 반복하지 않는다.

7. 결과 보고

   • 변경한 계약 index와 원문 경로를 보고한다.
   • 중복 제거한 문서와 남긴 포인터를 보고한다.

실행 결과 검증

• agent-contract/index.md가 계약 id와 경로를 포함하는가
• agent-contract/index.md가 없던 프로젝트에서는 읽기 규칙, 제공 계약 표, 소비 계약 표가 생성되었는가
• 제공 계약 원문이 agent-contract/provided/ 아래에 있는가
• 소비 계약 원문을 복제하지 않았는가
• 소비 계약은 source만 가리키는가
• 수정된 계약의 index 조건과 path/source가 계약 원문과 일치하는가
• README/docs/rules가 계약 본문을 반복하지 않고 원문 경로만 가리키는가
• common rule에 특정 계약명이 들어가지 않았는가
• project rule에 agent-contract 공통 라우팅을 반복하지 않았는가
• 검증 실패 시: 계약 원문을 한 곳으로 모으고 나머지 문서는 포인터로 축소한다.

출력 형식

계약 정리 완료

- index: agent-contract/index.md
- contract: agent-contract/provided/<contract-name>.md
- pointers: <갱신한 README/docs/rules 경로>

금지 사항

• 같은 계약 본문을 docs/, README, rules.md에 복제하지 않는다.
• common rule에 특정 계약 id, 특정 프로젝트명, 특정 API 이름을 추가하지 않는다.
• 소비 계약 원문을 현재 프로젝트에 복사하지 않는다.
• 계약과 무관한 코드나 로드맵 상태를 함께 수정하지 않는다.