toki/proto-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
proto-socket/agent-ops/skills/common/update-contract/SKILL.md

6.3 KiB
Raw Blame History

name version description
update-contract 1.0.0 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/원본 경로/중복 문서/테스트 누락을 보완한다.

출력 형식

## 계약 업데이트 완료

- 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 계약으로 승격하지 않는다.
  • 계약 갱신과 무관한 리팩터링을 함께 수행하지 않는다.