121 lines
7.2 KiB
Markdown
121 lines
7.2 KiB
Markdown
---
|
|
name: create-contract
|
|
version: 1.0.0
|
|
description: 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, 문서 메타, 포인터, 원본 경로만 보완한다.
|
|
|
|
## 출력 형식
|
|
|
|
```md
|
|
## 계약 생성 완료
|
|
|
|
- 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/` 구조가 있어도 사용자 요청 없이 대량 이동하지 않는다.
|