7.2 KiB
7.2 KiB
| 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에 길게 복제하고 있는지 확인한다.
실행 절차
-
필요성 판정
- 둘 이상의 프로젝트/프로세스/앱/도메인이 맞춰야 하는 안정 경계인지 확인한다.
- 단일 패키지 내부 구현이면 계약 문서를 만들지 않고 이유를 보고한다.
- 단건
contract-id가 없으면 코드와 문서에서 계약 후보를 수집하고, 안정 경계가 확인된 후보만 생성한다. - 후보는 있지만 boundary나 원본 경로가 불명확하면 문서를 억지로 만들지 않고
확인 필요로 보고한다.
-
구조 생성
agent-contract/index.md가 없으면 생성한다.agent-contract/inner/와agent-contract/outer/가 없으면 생성한다.- legacy
provided/consumed/가 있으면 덮어쓰지 않고, 이번 생성 결과와 충돌하는지 보고한다.
-
코드와 문서 분석
- 관련 schema 원본을 먼저 찾는다. 우선순위는 proto/OpenAPI/schema 파일, config struct, public DTO/interface, handler/parser, 테스트 fixture 순서다.
- README/docs/rules에 흩어진 계약 설명을 찾고, 계약 문서에 필요한 내용만 추린다.
- 필드 의미는 코드와 테스트에서 확인한 것만 쓴다. 추측은
확인 필요로 남긴다.
-
계약 문서 작성
- 경로는
agent-contract/<inner|outer>/<contract-name>.md로 둔다. - 여러 계약을 생성해야 하면 각 문서는 독립된 경계 단위로 나누고, 공통 설명은 index가 아니라 각 계약의 원본 경로 포인터로 해결한다.
- 문서는 짧게 유지하고 다음 항목을 포함한다.
- 계약 메타: id, boundary, 원본 경로, status(필요한 경우)
- 읽는 조건
- 범위와 비범위
- 최소 요청/응답 또는 message/event 형태
- 필드 의미와 금지 사항
- 변경 시 확인할 코드/테스트
- 원본 schema 전체를 복제하지 않는다. 긴 schema는 원본 경로와 핵심 필드 의미만 둔다.
- 경로는
-
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 포인터로 둔다.
-
흩어진 문서 정리
- README/docs/rules에 계약 본문이 중복되어 있으면 원문 경로 포인터로 줄인다.
- domain rule에는 소유권, 경계, 금지 사항만 남기고 상세 schema는 계약 문서 또는 원본 경로를 가리킨다.
- common rule에는 특정 프로젝트 경로, 계약 id, API 이름을 추가하지 않는다. common rule은
agent-contract/index.md조건부 진입까지만 담당한다. - 사람용 최신 가이드가 필요한 README 문구는 유지하되 계약 원문과 충돌하지 않게 축소한다.
-
결과 보고
- 생성한 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/구조가 있어도 사용자 요청 없이 대량 이동하지 않는다.