---
name: update-contract
version: 1.0.0
description: agent-contract inner/outer 계약 문서를 갱신하고 흩어진 계약 설명을 정리한다. 계약 업데이트해, 프로젝트 계약 업데이트해, 계약 갱신/수정/정리, contract update 요청에서 사용한다.
---

# update-contract

## 목적

기존 `agent-contract/`의 inner/outer 계약 문서를 최신 코드와 문서 기준으로 갱신한다.
계약 원문은 한 곳에 모으고, README/docs/rules에는 포인터와 경계 규칙만 남긴다.

## 언제 호출할지

- 사용자가 계약 업데이트, 프로젝트 계약 업데이트, 계약 갱신, 계약 수정, 계약 정리를 요청할 때
- API, runtime 호출, wire protocol, event/config schema 변경이 기존 계약에 영향을 줄 때
- 계약 설명이 README/docs/rules/code review 과정에서 다시 흩어진 것을 정리할 때
- legacy `provided/consumed` 계약을 `inner/outer` 모델로 점진 정리할 때

## 입력

- `contract-id`: 갱신할 계약 식별자 (선택, 없으면 index와 변경 diff에서 탐색)
- `change`: 바뀐 내용 또는 정리할 문제 요약 (선택, 없으면 최근 변경/요청 맥락에서 산출)
- `boundary`: `inner` 또는 `outer` (선택, 기존 문서 우선)
- `canonical-path`: 갱신 기준이 되는 proto/OpenAPI/config/code 원본 경로 (선택)

## 먼저 확인할 것

- [ ] `agent-contract/index.md` 존재 여부를 확인한다. 없으면 create-contract 흐름으로 전환할지 판단한다.
- [ ] index에서 대상 계약 문서를 찾는다. 없으면 새 계약 생성 대상인지 판단한다.
- [ ] 대상 계약 문서와 원본 경로를 읽는다.
- [ ] 변경 범위와 관련된 코드, proto, config, 테스트를 읽어 실제 동작을 확인한다.
- [ ] README/docs/rules에 계약 본문이 새로 중복 작성되었는지 검색한다.
- [ ] legacy `provided/consumed/` 구조가 남아 있으면 현재 요청이 구조 migration인지 단순 계약 갱신인지 구분한다.

## 실행 절차

1. **대상 확정**
   - index의 `Outer Contracts`/`Inner Contracts`에서 계약을 찾는다.
   - `contract-id`가 없으면 요청 키워드, 변경 파일, 코드 diff, README/docs/rules의 계약 설명을 기준으로 영향을 받는 계약을 좁힌다.
   - legacy index만 있으면 `provided`는 outer 후보, 프로젝트 내부 runtime/wire 계약은 inner 후보로 분류하되 즉시 이동하지 말고 변경 범위와 함께 판단한다.
   - 대상이 없고 요청이 계약 생성/정리까지 허용하면 create-contract 흐름으로 전환한다.
   - 대상이 없고 사용자가 특정 기존 계약 갱신만 요청했다면 대상 부재를 보고한다.

2. **코드 우선 분석**
   - 원본 경로를 먼저 확인한다.
   - 실제 parser/handler/DTO/interface/test에서 필드 의미와 허용/거부 동작을 확인한다.
   - 문서와 코드가 다르면 코드를 근거로 계약 문서를 갱신하고, 코드가 틀렸을 가능성이 있으면 사용자에게 후보를 제시한다.

3. **계약 문서 갱신**
   - 필드 의미, 금지 사항, 읽는 조건, 변경 시 테스트를 최신 상태로 맞춘다.
   - schema 원본 전체를 복제하지 않고 핵심 의미와 원본 경로를 유지한다.
   - 불확실한 값은 단정하지 않고 `확인 필요`로 남긴다.
   - `last updated` 같은 날짜 메타가 이미 있는 문서에서만 갱신한다. 없는 문서에 날짜 관례를 새로 만들지 않는다.

4. **index 갱신**
   - 읽는 조건이 새 API/field/message/protocol 이름을 포함하는지 확인한다.
   - path, 원본 경로, boundary가 실제 문서와 일치하는지 확인한다.
   - 중복 id, dead path, 존재하지 않는 원본 경로를 제거하거나 수정한다.
   - 프로젝트 전용 path trigger가 필요하면 `agent-contract/index.md` 또는 project/domain rule 포인터에 둔다. common rule에는 넣지 않는다.

5. **흩어진 문서 정리**
   - README/docs/rules에 계약 본문이 들어간 경우 계약 문서 포인터로 축소한다.
   - domain rule에는 책임 경계와 금지 사항만 남기고 상세 요청/응답 schema를 반복하지 않는다.
   - 테스트 문서에는 검증 기준만 남기고 계약 본문을 복제하지 않는다.
   - common rule에 특정 프로젝트 경로, 계약 id, API 이름이 새로 들어갔으면 제거하고 프로젝트 문서로 옮긴다.

6. **검증 판단**
   - 계약 문서만 바꿨으면 링크/path/index 정합성을 확인한다.
   - 원본 schema 또는 runtime 코드를 함께 바꿨으면 해당 domain/test rule의 검증 기준을 따른다.
   - proto/config schema를 바꿨으면 생성물 갱신 명령과 관련 테스트를 실행한다.

7. **결과 보고**
   - 수정한 계약 문서와 index
   - 코드 분석 근거
   - 중복 제거한 문서
   - 실행한 검증
   - 남은 확인 필요 항목

## 실행 결과 검증

- [ ] index가 대상 계약의 최신 path와 읽는 조건을 가리키는가
- [ ] 계약 문서의 원본 경로가 실제 코드/proto/config와 맞는가
- [ ] README/docs/rules에 같은 계약 본문이 중복 남아 있지 않은가
- [ ] inner/outer boundary가 계약의 실제 소비자와 맞는가
- [ ] 코드 분석 없이 문서만 추측해 갱신하지 않았는가
- [ ] 변경 범위에 필요한 테스트 또는 링크 검증을 실행했는가
- 검증 실패 시: index/path/원본 경로/중복 문서/테스트 누락을 보완한다.

## 출력 형식

```md
## 계약 업데이트 완료

- contract: agent-contract/<inner|outer>/<contract-name>.md
- index: agent-contract/index.md
- code evidence: <확인한 코드/proto/config/test>
- pointers: <갱신한 README/docs/rules 경로 또는 없음>
- verification: <실행한 명령 또는 생략 사유>
- 확인 필요: <항목 또는 없음>
```

## 금지 사항

- 코드와 원본 경로를 확인하지 않고 계약 문서만 고치지 않는다.
- README/docs/rules에 계약 본문을 새로 복제하지 않는다.
- 프로젝트 전용 path trigger를 common rule에 넣지 않는다.
- 사용자 요청 없이 전체 계약 구조를 대량 migration하지 않는다.
- 한 패키지 내부 구현 세부를 inner 계약으로 승격하지 않는다.
- 계약 갱신과 무관한 리팩터링을 함께 수행하지 않는다.