nomadcode/agent-ops/rules/project/domain/contracts/rules.md

domain	last_rule_review_commit	last_rule_updated_at
contracts	e3b5dae725	2026-05-21

contracts

목적 / 책임

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

포함 경로

• packages/contracts/ — OpenAPI/protobuf/schema, generated clients, fixtures, compatibility notes.

제외 경로

• services/core/internal/http/ — API implementation은 core 도메인이다.
• apps/mobile/lib/ — mobile-specific client/service code는 mobile 도메인이다.
• apps/web/src/api/ — legacy web-specific API client wrapper는 web 도메인이다.

주요 구성 요소

• packages/contracts/README.md — 현재 contracts 도메인의 역할과 사용 방향.

유지할 패턴

• 계약 변경은 additive를 우선한다.
• breaking change는 core와 Flutter 앱 반영을 같은 branch에서 조율한다. legacy web은 제거 전 필요한 경우에만 함께 조율한다.
• schema가 추가되면 sample payload나 compatibility note를 함께 둔다.
• generated client가 생기면 생성 명령과 source schema를 문서화한다.

다른 도메인과의 경계

• core: contracts는 API shape의 source-of-truth이고 core는 이를 구현한다.
• mobile: mobile은 contracts를 소비하되 platform behavior는 mobile 도메인에서 다룬다.
• web: legacy web은 제거 전 필요한 경우에만 contracts를 소비하거나 generated client를 감싼다.
• workspace-ops: contracts 생성/검증 명령이 root script가 되면 workspace-ops와 함께 갱신한다.

금지 사항

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