From 39dfab20304f33e4c76626ffee37556a4fd102a0 Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 27 Jun 2026 07:11:59 +0900 Subject: [PATCH] sync: agent-ops from agentic-framework v1.1.158 --- .clinerules | 5 +- .cursorrules | 5 +- AGENTS.md | 5 +- CLAUDE.md | 5 +- GEMINI.md | 5 +- agent-ops/.version | 2 +- agent-ops/rules/common/rules.md | 5 +- .../skills/common/agent-contract/SKILL.md | 102 --------------- .../skills/common/create-contract/SKILL.md | 121 ++++++++++++++++++ agent-ops/skills/common/router.md | 3 +- .../skills/common/update-contract/SKILL.md | 111 ++++++++++++++++ 11 files changed, 253 insertions(+), 116 deletions(-) delete mode 100644 agent-ops/skills/common/agent-contract/SKILL.md create mode 100644 agent-ops/skills/common/create-contract/SKILL.md create mode 100644 agent-ops/skills/common/update-contract/SKILL.md diff --git a/.clinerules b/.clinerules index c34b043..258ee50 100644 --- a/.clinerules +++ b/.clinerules @@ -12,7 +12,7 @@ - `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. -- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. +- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -32,7 +32,7 @@ - skill 생성 - agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test -- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 +- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리 - README 생성 - 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기 - 로드맵/마일스톤 생성·갱신 @@ -48,3 +48,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev-corp: `agent-test/dev-corp/rules.md` diff --git a/.cursorrules b/.cursorrules index c34b043..258ee50 100644 --- a/.cursorrules +++ b/.cursorrules @@ -12,7 +12,7 @@ - `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. -- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. +- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -32,7 +32,7 @@ - skill 생성 - agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test -- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 +- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리 - README 생성 - 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기 - 로드맵/마일스톤 생성·갱신 @@ -48,3 +48,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev-corp: `agent-test/dev-corp/rules.md` diff --git a/AGENTS.md b/AGENTS.md index c34b043..258ee50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ - `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. -- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. +- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -32,7 +32,7 @@ - skill 생성 - agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test -- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 +- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리 - README 생성 - 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기 - 로드맵/마일스톤 생성·갱신 @@ -48,3 +48,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev-corp: `agent-test/dev-corp/rules.md` diff --git a/CLAUDE.md b/CLAUDE.md index c34b043..258ee50 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,7 @@ - `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. -- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. +- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -32,7 +32,7 @@ - skill 생성 - agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test -- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 +- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리 - README 생성 - 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기 - 로드맵/마일스톤 생성·갱신 @@ -48,3 +48,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev-corp: `agent-test/dev-corp/rules.md` diff --git a/GEMINI.md b/GEMINI.md index c34b043..258ee50 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -12,7 +12,7 @@ - `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. -- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. +- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -32,7 +32,7 @@ - skill 생성 - agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test -- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 +- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리 - README 생성 - 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기 - 로드맵/마일스톤 생성·갱신 @@ -48,3 +48,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev-corp: `agent-test/dev-corp/rules.md` diff --git a/agent-ops/.version b/agent-ops/.version index 546dc6a..87b00c6 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.157 +1.1.158 diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index c34b043..258ee50 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -12,7 +12,7 @@ - `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**`와 `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다. - agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. - tracked `docs/`는 사람용 최신 가이드와 공개 설명만 둔다. -- 외부 API, 런타임 호출, 프로젝트 간 연동, 요청/응답 스키마 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. +- API, wire protocol, 런타임 호출, event/config schema, 프로젝트 간 또는 내부 프로세스/컴포넌트 간 요청/응답 계약을 확인해야 하는 작업은 `agent-contract/index.md` 파일이 있을 때만 세션 1회 읽고, 매칭되는 계약 문서만 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. @@ -32,7 +32,7 @@ - skill 생성 - agent-ui 생성/갱신/검증/코드 동기화, UI 스캐폴드, 화면 정의서, view/component/frame/wireframe 정의, agent-ui USER_REVIEW - 테스트 룰 작성/생성/수정, 도메인별/검증 시나리오별 테스트 문서, create-test/update-test -- agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 +- 계약 생성/업데이트, agent-contract 생성/갱신, inner/outer 계약 문서 작성/정리, 계약 포인터 관리 - README 생성 - 핸즈오프 작성 / handoff / 인수인계 / 다른 세션에서 이어가기 - 로드맵/마일스톤 생성·갱신 @@ -48,3 +48,4 @@ **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.** - local: `agent-test/local/rules.md` (없으면 `create-test`) +- dev-corp: `agent-test/dev-corp/rules.md` diff --git a/agent-ops/skills/common/agent-contract/SKILL.md b/agent-ops/skills/common/agent-contract/SKILL.md deleted file mode 100644 index 82a8bbd..0000000 --- a/agent-ops/skills/common/agent-contract/SKILL.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -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`: 계약 식별자, 예: `billing.public-api` 또는 `auth.session-events` (필수) -- `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/create-contract/SKILL.md b/agent-ops/skills/common/create-contract/SKILL.md new file mode 100644 index 0000000..799dc3f --- /dev/null +++ b/agent-ops/skills/common/create-contract/SKILL.md @@ -0,0 +1,121 @@ +--- +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//.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//.md +- boundary: (<근거>) +- 원본 경로: +- pointers: <갱신한 README/docs/rules 경로 또는 없음> +- 확인 필요: <항목 또는 없음> +``` + +## 금지 사항 + +- 모든 내부 interface를 계약 문서로 만들지 않는다. +- 원본 schema 전체를 계약 문서에 장황하게 복제하지 않는다. +- 코드/proto/config/test 확인 없이 필드 의미를 단정하지 않는다. +- README/docs/rules에 계약 본문을 계속 중복 유지하지 않는다. +- 프로젝트 전용 path trigger를 common rule에 넣지 않는다. +- legacy `provided/consumed/` 구조가 있어도 사용자 요청 없이 대량 이동하지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 3f617d1..8ace4fd 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -18,7 +18,8 @@ | agent-ui와 코드 동기화, agent-ui와 코드 전체 동기화, 화면정의서대로 코드 반영, 화면 정의서 변경사항 구현, wireframe 변경사항 구현 | `agent-ops/skills/common/sync-agent-ui/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` | +| 계약 생성해, 프로젝트 계약 생성해, 프로젝트 계약 생성, contract 생성, agent-contract 생성, 계약 문서 생성, inner 계약 생성, outer 계약 생성 | `agent-ops/skills/common/create-contract/SKILL.md` | +| 계약 업데이트해, 프로젝트 계약 업데이트해, 프로젝트 계약 업데이트, 계약 갱신해, 계약 갱신, 계약 수정, 계약 정리, contract update, agent-contract 갱신, inner 계약 갱신, outer 계약 갱신 | `agent-ops/skills/common/update-contract/SKILL.md` | | README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` | | 핸즈오프 남겨, handoff 작성, 인수인계 작성, 다른 세션에서 이어가게 정리, 작업을 이어받도록 기록 | `agent-ops/skills/common/create-handoff/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | diff --git a/agent-ops/skills/common/update-contract/SKILL.md b/agent-ops/skills/common/update-contract/SKILL.md new file mode 100644 index 0000000..caec6b2 --- /dev/null +++ b/agent-ops/skills/common/update-contract/SKILL.md @@ -0,0 +1,111 @@ +--- +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//.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 계약으로 승격하지 않는다. +- 계약 갱신과 무관한 리팩터링을 함께 수행하지 않는다.