toki/nomadcode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nomadcode/agent-ops/rules/project/domain/contracts/rules.md

3 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
contracts a95fc27151 2026-06-24

contracts

목적 / 책임

NomadCode 런타임 사이의 공유 계약 도메인이다. API schema, event schema, roadmap/work item sync 후보, generated client boundary, compatibility note를 관리한다.

포함 경로

  • packages/contracts/ — OpenAPI/protobuf/schema, generated clients, fixtures, compatibility notes.
  • packages/contracts/notes/ — source schema 승격 전 core/client 계약 후보와 compatibility note.

제외 경로

  • services/core/internal/http/ — API implementation은 core 도메인이다.
  • apps/client/lib/ — Flutter client/service code는 mobile 도메인이다.
  • apps/web/ — [Legacy/Retired] 이전 React/Vite web scaffold 경로는 완전히 제거되어 제외 대상입니다.

주요 구성 요소

  • packages/contracts/README.md — 현재 contracts 도메인의 역할과 사용 방향.
  • packages/contracts/notes/flutter-core-api-candidates.md — Flutter/Core REST compatibility map, proto-socket semantic envelope, task channel, Gito branch event consumer, roadmap/work item sync, roadmap operations control plane, workspace metadata, client integration 설정 후보.

유지할 패턴

  • 계약 변경은 additive를 우선한다.
  • breaking change는 core와 Flutter 앱 반영을 같은 branch에서 조율한다.
  • schema가 추가되면 sample payload나 compatibility note를 함께 둔다.
  • generated client가 생기면 생성 명령과 source schema를 문서화한다.
  • 내부 런타임 통신은 proto-socket channel/action을 우선 기준으로 삼고, REST/HTTP 유지나 신규 추가는 health/readiness, 외부 provider compatibility, smoke/curl, public callback, 단순 정적 조회 같은 예외 사유를 기록한다.
  • source schema가 아직 없는 계약은 compatibility note로 표시하고, 실제 schema/generator 도입 전까지 단일 source-of-truth인 것처럼 다루지 않는다.
  • Gito branch event와 roadmap/work item sync 후보는 외부 원문 계약과 Core 구현 경계를 함께 링크하고, source-of-truth branch/revision과 wakeup hint의 차이를 명시한다.

다른 도메인과의 경계

  • core: contracts는 API/proto-socket 의미 계약의 source-of-truth 후보를 관리하고 core는 이를 구현한다.
  • mobile: mobile은 contracts를 소비하되 platform behavior와 connector lifecycle은 mobile 도메인에서 다룬다.
  • web: [Legacy/Retired] React web 도메인은 완전히 제거되었습니다.
  • workspace-ops: contracts 생성/검증 명령이 root script가 되면 workspace-ops와 함께 갱신한다.

금지 사항

  • 구현 코드의 임시 type을 contracts로 승격하지 않는다.
  • 실제 소비자가 없는 schema를 과도하게 선행 설계하지 않는다.
  • generated output만 수정하고 source schema를 누락하지 않는다.
  • compatibility note의 후보 계약을 실제 source schema와 혼동하지 않는다.