From aaeb65d24d57850a07e06e9b61a6ffca04b8dacb Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 16 May 2026 22:09:04 +0900 Subject: [PATCH] update agent-ops rules: add testing domain and update project rules --- agent-ops/rules/project/domain/edge/rules.md | 1 + agent-ops/rules/project/domain/node/rules.md | 1 + .../project/domain/platform-common/rules.md | 1 + .../rules/project/domain/testing/rules.md | 48 +++++++++++++++++++ agent-ops/rules/project/rules.md | 6 +++ 5 files changed, 57 insertions(+) create mode 100644 agent-ops/rules/project/domain/testing/rules.md diff --git a/agent-ops/rules/project/domain/edge/rules.md b/agent-ops/rules/project/domain/edge/rules.md index ac253bd..4c5e747 100644 --- a/agent-ops/rules/project/domain/edge/rules.md +++ b/agent-ops/rules/project/domain/edge/rules.md @@ -41,6 +41,7 @@ - NodeStore는 설정 파일에서 한 번 seed되며 런타임 중 변경하지 않는다; token 중복·빈 token은 LoadFromConfig에서 즉시 거부한다. - adapter config 변환(mapper)은 `node.BuildConfigPayload()`에서만 수행하고 transport 레이어에 변환 로직을 두지 않는다. - 내부 실행 요청은 `adapter + target`으로 표현한다. 외부 API 호환 경계의 `model` 표현을 edge 내부 책임 전체로 확장하지 않는다. +- `apps/edge/cmd/edge/**`, `apps/edge/internal/bootstrap/**`, `apps/edge/internal/transport/**`, `apps/edge/internal/service/**`, `apps/edge/internal/node/**`, console 입출력/명령 처리, run event relay를 바꾼 뒤에는 `testing` domain rule의 작업 후 검증 기준을 따른다. ## 다른 도메인과의 경계 diff --git a/agent-ops/rules/project/domain/node/rules.md b/agent-ops/rules/project/domain/node/rules.md index ababd7a..5a28381 100644 --- a/agent-ops/rules/project/domain/node/rules.md +++ b/agent-ops/rules/project/domain/node/rules.md @@ -47,6 +47,7 @@ Edge에 연결되어 실제 adapter execution을 수행하는 IOP 노드 에이 - `adapters.Registry`의 start/stop은 bootstrap lifecycle에서만 호출하고 개별 adapter에서 직접 호출하지 않는다. - cli adapter의 출력 format별 파싱 로직은 `lineEmitter` 구현체로 분리하고 `node.Node`에 분기문으로 박지 않는다. - node 내부 변경은 가능한 대상 패키지 테스트를 먼저 추가하거나 갱신한다. +- `apps/node/cmd/node/**`, `apps/node/internal/bootstrap/**`, `apps/node/internal/transport/**`, `apps/node/internal/node/**`, `apps/node/internal/router/**`, `apps/node/internal/adapters/**`의 실행 요청/응답/stream/cancel/status 경로를 바꾼 뒤에는 `testing` domain rule의 작업 후 검증 기준을 따른다. ## 다른 도메인과의 경계 diff --git a/agent-ops/rules/project/domain/platform-common/rules.md b/agent-ops/rules/project/domain/platform-common/rules.md index e23d8a3..cc0c0c6 100644 --- a/agent-ops/rules/project/domain/platform-common/rules.md +++ b/agent-ops/rules/project/domain/platform-common/rules.md @@ -41,6 +41,7 @@ - 생성 파일(`proto/gen/iop/*.pb.go`)은 사람이 직접 편집하지 않는다. - 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다. - `RunRequest`, `ExecutionSpec`, `NodeCommandRequest`, job/history 계열 계약을 변경할 때 내부 실행 용어는 `target`을 우선하고, `model`은 외부 호환 경계인지 확인한다. +- `packages/config/**`, `configs/**`, `proto/iop/**`처럼 edge-node 실행 설정이나 메시지 계약에 영향을 주는 작업을 한 뒤에는 `testing` domain rule의 작업 후 검증 기준을 따른다. ## 다른 도메인과의 경계 diff --git a/agent-ops/rules/project/domain/testing/rules.md b/agent-ops/rules/project/domain/testing/rules.md new file mode 100644 index 0000000..c1a9b5a --- /dev/null +++ b/agent-ops/rules/project/domain/testing/rules.md @@ -0,0 +1,48 @@ +# testing + +## 목적 / 책임 + +작업 완료 후 어떤 테스트와 E2E smoke 검증을 거쳐야 하는지 정리한다. 테스트 파일을 바꿨는지가 아니라, 변경 작업이 어떤 사용자 실행 파이프라인에 닿았는지를 기준으로 검증 범위를 정한다. + +## 포함 경로 + +- `Makefile` — 공식 test target과 향후 E2E smoke target을 선언하는 위치이다. +- `bin/edge.sh` — 사용자가 edge console/server를 실행하는 shell entrypoint이며 E2E smoke의 검증 대상이다. +- `bin/node.sh` — 사용자가 node를 edge에 연결하는 shell entrypoint이며 E2E smoke의 검증 대상이다. + +## 제외 경로 + +- `apps/node/` — node 실행 구현의 소유자는 node 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다. +- `apps/edge/` — edge 실행 구현의 소유자는 edge 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다. +- `packages/` 및 `proto/` — 공통 계약의 소유자는 platform-common 도메인이다. testing 도메인은 해당 변경 후 필요한 검증 기준만 정의한다. + +## 주요 구성 요소 + +- 대상 패키지 테스트 — 변경한 패키지와 인접한 패키지의 빠른 회귀 검증이다. +- `go test ./...` — 저장소 전체 Go 테스트 회귀 검증이다. +- `bin/edge.sh` + `bin/node.sh` E2E smoke — 사용자가 실행하는 entrypoint를 통해 edge-node 등록, console 입력, adapter 실행, event/message 출력을 확인하는 검증이다. +- real CLI opt-in 검증 — `claude`, `gemini`, `codex`, `opencode`, `cline`처럼 외부 CLI 설치와 계정/환경이 필요한 검증이다. + +## 유지할 패턴 + +- 테스트는 테스트 파일 변경 여부가 아니라 작업 영향 범위로 결정한다. +- 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 일반 Go 테스트와 `bin/edge.sh` + `bin/node.sh` 기반 E2E smoke 흐름을 반드시 검증한다. +- 사용자 실행 파이프라인에는 `bin/**`, `apps/*/cmd/**`, `apps/*/internal/bootstrap/**`, edge-node transport/service/registry, adapter 실행/stream/cancel/status 경로, `configs/**`, `packages/config/**`, 관련 protobuf 계약 변경이 포함된다. +- 기본 E2E smoke는 mock adapter와 임시 설정/포트를 사용해 외부 CLI 의존성 없이 수행한다. +- E2E smoke에서는 최소한 node 등록, `/nodes` 확인, console 메시지 전송, delta/message 출력, complete event를 확인한다. +- `make test-e2e` 같은 고정 명령이 생기면 그 명령을 우선 사용한다. 아직 고정 명령이 없으면 동일한 내용을 수동 smoke 절차로 검증하거나, 실행하지 못한 이유를 최종 보고에 명시한다. +- 실제 외부 CLI profile 검증은 사용자가 명시했거나 환경이 준비된 경우에만 opt-in으로 수행한다. +- 작업 최종 보고에는 실행한 테스트 명령과 E2E smoke 수행 여부를 명시한다. 수행하지 못한 필수 검증은 이유와 남은 위험을 함께 적는다. + +## 다른 도메인과의 경계 + +- **node**: node는 adapter 실행과 edge 연결 구현을 소유한다. testing은 node 변경 후 어떤 검증을 거칠지 정한다. +- **edge**: edge는 registry, service, transport, console 구현을 소유한다. testing은 edge 변경 후 사용자 실행 흐름을 어떻게 확인할지 정한다. +- **platform-common**: platform-common은 config/proto 계약을 소유한다. testing은 해당 계약 변경이 edge-node 실행 흐름에 닿을 때 필요한 검증을 정한다. + +## 금지 사항 + +- 사용자 실행 파이프라인에 닿는 변경을 하고 유닛/패키지 테스트만으로 완료 처리하지 않는다. +- 기본 E2E smoke를 외부 CLI 설치, 로그인, 네트워크 계정 상태에 의존하게 만들지 않는다. +- E2E smoke를 위해 기본 `configs/*.yaml`을 임시값으로 오염시키지 않는다. 임시 설정 파일이나 환경 변수 override를 사용한다. +- 필수 검증을 실행하지 못했는데 조용히 생략하지 않는다. diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 92e8f45..1130890 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -22,6 +22,8 @@ - `proto/iop/` — IOP 메시지 계약 원본이다. - `proto/gen/iop/` — protobuf 생성물이다. - `configs/` — 앱별 YAML 설정 예시이다. +- `bin/` — 사용자가 직접 실행하는 edge/node shell entrypoint이다. +- `Makefile` — 빌드와 테스트 진입점을 정의한다. - `docs/` — 아키텍처 및 운영 방향 문서이다. ## 기술 스택 @@ -46,12 +48,14 @@ - protobuf 계약 변경 시 `proto/iop/*.proto`를 먼저 수정하고 `make proto`로 `proto/gen/iop/*.pb.go`를 갱신한다. 생성 파일은 직접 수정하지 않는다. - 앱 설정 구조 변경 시 `packages/config`의 struct/default와 `configs/*.yaml` 예시를 함께 확인한다. - 테스트는 변경 범위에 맞춰 `go test ./...` 또는 대상 패키지 테스트를 실행한다. +- 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 `agent-ops/rules/project/domain/testing/rules.md`의 검증 기준을 따른다. - 상세 DB schema, event schema, permission/policy/audit model, federation, mTLS 구현 세부, Control Plane UI 세부 기획은 각 작업에서 별도로 결정한다. ## 도메인 룰 로딩 - 아래 도메인 매핑에 해당하는 작업에서 해당 domain 최초 진입 시 domain rule을 1회 읽는다. - 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다. +- 사용자 실행 파이프라인에 닿는 작업의 검증 단계에서는 `testing` domain rule을 1회 읽는다. ## 도메인 매핑 @@ -62,6 +66,8 @@ | `packages/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` | | `proto/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` | | `configs/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` | +| `bin/**` | testing | `agent-ops/rules/project/domain/testing/rules.md` | +| `Makefile` | testing | `agent-ops/rules/project/domain/testing/rules.md` | ## 도메인 후보