rara/agent-ops/rules/project/domain/platform-common/rules.md

domain	last_rule_review_commit	last_rule_updated_at
platform-common	null	2026-07-18

platform-common

목적 / 책임

각 plane이 공유하는 설정, PostgreSQL 연결, HTTP lifecycle, 관측성, artifact 저장, 외부 integration port를 제공한다. 도메인 로직이 특정 인프라 제품에 결합되지 않도록 adapter 경계를 유지한다.

포함 경로

• packages/go/artifact/ — 교체 가능한 artifact store 계약과 filesystem 구현
• packages/go/config/ — 서비스별 YAML 설정 로딩과 검증
• packages/go/database/ — pgx 연결 lifecycle과 sqlc 생성 adapter
• packages/go/httpserver/ — 공통 health/readiness와 HTTP server lifecycle
• packages/go/integration/ — source, retrieval, embedding, reranking, generation, secret의 product-neutral port
• packages/go/observability/ — logging, metrics, tracing 조립
• configs/, deploy/ — 로컬 설정 예시와 배포 자산

제외 경로

• packages/go/controlplane/, db/ — 수명주기 상태 모델과 쿼리 원본
• packages/go/rag/ — 온라인 RAG 요청 의미와 응답 계약
• packages/go/workflow/, packages/python/ — workflow와 adaptation 실행 의미

주요 구성 요소

• database.Store — pgx pool과 생성된 sqlc query 접근점
• artifact.Store / artifact.Filesystem — artifact 저장 port와 로컬 구현
• integration.Ports — 외부 capability의 제품 중립 계약
• httpserver.Start — 공통 HTTP lifecycle
• observability.SetupTracing — trace exporter 설정

유지할 패턴

• 공통 패키지는 plane별 정책을 소유하지 않고 작은 port와 lifecycle adapter에 집중한다.
• integration instance는 versioned capability와 secret reference로 구성한다.
• artifact URI와 content hash를 유지해 lineage를 추적할 수 있게 한다.
• readiness는 실제 필수 dependency 상태를 반영하고 health와 구분한다.
• 설정 예시에는 로컬 기본값만 두며 운영 secret을 포함하지 않는다.

다른 도메인과의 경계

• control-plane: 공통 persistence adapter를 제공하되 스키마와 수명주기 규칙은 control-plane이 소유한다.
• rag-data-plane: retrieval/generation port를 제공하되 release 해석과 응답 의미는 rag-data-plane이 소유한다.
• workflow-execution: config, database, artifact adapter를 제공하되 lease와 executor 상태 전이는 workflow-execution이 소유한다.

금지 사항

• 공통 패키지에 control-plane, RAG, workflow의 유즈케이스 정책을 넣지 않는다.
• integration port를 특정 vendor의 request/response 타입으로 노출하지 않는다.
• config, log, trace, 예제 배포 파일에 secret이나 credential 원문을 남기지 않는다.