From 88afb6c379b5730fe1e0d9f2807ec2d81d7c350a Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 13 Jun 2026 11:26:53 +0900 Subject: [PATCH] sync: from iop v1.1.137 --- agent-ops/.version | 2 +- agent-ops/rules/common/rules.md | 2 + .../skills/common/agent-contract/SKILL.md | 102 ++++++++++++++++++ agent-ops/skills/common/router.md | 1 + 4 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 agent-ops/skills/common/agent-contract/SKILL.md diff --git a/agent-ops/.version b/agent-ops/.version index 8b8c523..88cf65e 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.135 +1.1.137 diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index d0488a8..a6ece7e 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -11,6 +11,7 @@ - `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. +- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -29,6 +30,7 @@ - domain rule 생성 - skill 생성 - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test +- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 - 로드맵 현지점 / 현재 작업 지점 확인 diff --git a/agent-ops/skills/common/agent-contract/SKILL.md b/agent-ops/skills/common/agent-contract/SKILL.md new file mode 100644 index 0000000..b254647 --- /dev/null +++ b/agent-ops/skills/common/agent-contract/SKILL.md @@ -0,0 +1,102 @@ +--- +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`: 계약 식별자, 예: `iop.openai-compatible-api` (필수) +- `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/.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/.md +- pointers: <갱신한 README/docs/rules 경로> +``` + +## 금지 사항 + +- 같은 계약 본문을 `docs/`, `README`, `rules.md`에 복제하지 않는다. +- common rule에 특정 계약 id, 특정 프로젝트명, 특정 API 이름을 추가하지 않는다. +- 소비 계약 원문을 현재 프로젝트에 복사하지 않는다. +- 계약과 무관한 코드나 로드맵 상태를 함께 수정하지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 6fd0c69..2a5df8c 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -7,6 +7,7 @@ | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | | create-test, 테스트 룰 작성, 테스트 룰 생성, 테스트 규칙 작성, 테스트 규칙 생성, 테스트 환경 생성, 상황별 테스트 문서 생성, 도메인별 테스트 문서 생성, 검증 시나리오별 테스트 문서 생성, test rule 생성, agent-test 생성 | `agent-ops/skills/common/create-test/SKILL.md` | | update-test, 테스트 룰 수정, 테스트 룰 갱신, 테스트 규칙 수정, 테스트 규칙 갱신, 테스트 환경 수정, 상황별 테스트 문서 수정, 도메인별 테스트 문서 수정, 검증 시나리오별 테스트 문서 수정, test rule 수정, agent-test 수정 | `agent-ops/skills/common/update-test/SKILL.md` | +| agent-contract 생성, agent-contract 갱신, 계약 문서 작성, 계약 문서 정리, 제공 계약 추가, 소비 계약 추가, 외부 계약 포인터 관리 | `agent-ops/skills/common/agent-contract/SKILL.md` | | README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | | 로드맵 업데이트, roadmap 갱신, 로드맵에 추가, 로드맵 작업 추가, 로드맵 기능 추가, 로드맵 Epic 추가, 로드맵 에픽 추가, 로드맵 Task 추가, 로드맵 태스크 추가, 로드맵 테스크 추가, 로드맵 TODO 추가, 마일스톤에 추가, 마일스톤 추가, 마일스톤 갱신, 마일스톤 아카이브, phase 추가, phase 변경, 페이즈 추가, 페이즈 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` |