102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
---
|
|
name: agent-contract
|
|
version: 1.0.0
|
|
description: 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 공통 라우팅을 반복하지 않았는가
|
|
- 검증 실패 시: 계약 원문을 한 곳으로 모으고 나머지 문서는 포인터로 축소한다.
|
|
|
|
## 출력 형식
|
|
|
|
```text
|
|
계약 정리 완료
|
|
|
|
- index: agent-contract/index.md
|
|
- contract: agent-contract/provided/<contract-name>.md
|
|
- pointers: <갱신한 README/docs/rules 경로>
|
|
```
|
|
|
|
## 금지 사항
|
|
|
|
- 같은 계약 본문을 `docs/`, `README`, `rules.md`에 복제하지 않는다.
|
|
- common rule에 특정 계약 id, 특정 프로젝트명, 특정 API 이름을 추가하지 않는다.
|
|
- 소비 계약 원문을 현재 프로젝트에 복사하지 않는다.
|
|
- 계약과 무관한 코드나 로드맵 상태를 함께 수정하지 않는다.
|