nexo/agent-ops/rules/project/rules.md

nexo 프로젝트 규칙

응답 언어

• 기본 응답은 한국어로 작성한다.
• 파일명, 명령어, 패키지명, API 이름, 코드 식별자는 원문 그대로 유지한다.

프로젝트 개요

nexo는 여러 Flutter 앱이 메시징/푸시 기능을 사용할 수 있게 하는 packages/messaging_flutter 패키지를 중심으로 관리하는 프로젝트다. Mattermost 원본은 앱, 서버, push 서버 repository clone 단위로 둔다. 이 저장소에 별도 nexo 제품 앱을 싣지 않는다.

주요 경계는 다음과 같다.

• packages/messaging_flutter/ — nexo의 메인 산출물인 메시징/알림 Flutter 플러그인 패키지
• apps/flutter-test/ — 플러그인을 검증하는 테스트용 Flutter 앱
• apps/mattermost/ — 원래 Mattermost 앱 repository clone
• services/core/ — Mattermost 서버 repository clone
• services/push-proxy/ — Mattermost push-proxy repository clone
• docs/, bin/ — 워크스페이스 공통 문서와 helper entrypoint

기술 스택

• Flutter / Dart sdk: ^3.11.3
• Android native plugin: Kotlin, Java, Gradle
• iOS / macOS plugin scaffold: Swift
• Server core: Go 1.24.13, messaging server module
• Mattermost mobile app: React Native 0.83.9, Expo 55, Node.js, npm, TypeScript, Detox
• Mattermost API tooling: Node.js, npm workspaces, TypeScript, Redocly
• Push proxy: Go 1.24.6, Docker
• Local runtime: Docker Compose under services/core/compose/

작업 원칙

• packages/messaging_flutter/를 제품 중심으로 본다. 앱별 제품 UI와 business logic은 이 저장소가 아니라 패키지를 소비하는 앱의 책임이다.
• apps/flutter-test/는 플러그인 integration 검증용 앱으로만 본다. 플러그인 integration 검증을 넘는 제품 기능을 키우지 않는다.
• apps/mattermost, services/core, services/push-proxy는 Mattermost 원본 repository clone으로 유지한다. nexo 제품 앱이나 독자 서버 제품으로 재정의하지 않는다.
• upstream 작업 clone은 이 저장소 밖의 sibling/external mattermost/ staging 폴더에 원본 repository별로 둔다.
• staging clone은 repository별 기록된 upstream branch를 따라간다. mattermost-mobile은 main, mattermost와 mattermost-push-proxy는 master를 기준으로 하며, 해당 branch 변경 시점 또는 의도적으로 정한 refresh 시점에 snapshot을 떠서 이 저장소로 merge 요청한다.
• 이 저장소에 들어오는 snapshot은 원본 repository별 commit SHA를 기록한다.
• merge 요청은 원칙적으로 upstream repository별로 분리한다. 앱, 서버, push-proxy snapshot을 한 요청에 섞지 않는다.
• staging pull 결과를 이 저장소에 자동 반영하지 않는다. snapshot diff 확인과 관련 smoke 검증 후 merge 요청한다.
• nexo-specific patch는 가능한 한 upstream snapshot 밖의 compose, 문서, wrapper, 작은 명시 patch로 둔다.
• upstream 기능 단위 추적이나 잦은 자동 반영은 하지 않는다.
• services/core/UPSTREAM.md의 baseline 정보를 임의로 바꾸지 않는다.
• Flutter 플러그인의 public package/import/native identifier는 nexo 계열 이름으로 전환한다. 전환은 소비 앱과 native 등록 지점을 함께 다루는 계획 작업으로 진행한다.
• 푸시 알림 처리 책임은 packages/messaging_flutter/에 두고, apps/flutter-test에는 검증과 host integration만 둔다.
• build/, .dart_tool/, Android/iOS/macOS 생성물, upstream bulk 파일은 요청 범위 밖이면 건드리지 않는다.
• 모듈별 README가 있는 경우 해당 모듈 안의 설명을 우선한다.

검증 명령

• 전체 기본 검증: bin/test
• 전체 lint: bin/lint
• 전체 build: bin/build
• 서버 Go test: NEXO_CORE_GO_TEST=1 bin/test
• 서버 Go vet: NEXO_CORE_GO_LINT=1 bin/lint
• 서버 Go build: NEXO_CORE_GO_BUILD=1 bin/build

bin/* 명령은 로컬 도구가 없으면 일부 검증을 skip할 수 있다. skip 출력이 있으면 최종 보고에 명시한다.

도메인 룰 로딩

• 아래 도메인 매핑에 해당하는 작업에서 해당 domain 최초 진입 시 domain rule을 1회 읽는다.
• 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다.

도메인 매핑

경로 패턴	도메인	rules.md
services/core/**	core-service	agent-ops/rules/project/domain/core-service/rules.md
packages/messaging_flutter/**	messaging-flutter	agent-ops/rules/project/domain/messaging-flutter/rules.md
apps/flutter-test/**	client-app	agent-ops/rules/project/domain/client-app/rules.md
apps/mattermost/**	mattermost-app	agent-ops/rules/project/domain/mattermost-app/rules.md
services/push-proxy/**	push-proxy-service	agent-ops/rules/project/domain/push-proxy-service/rules.md
docs/**, bin/**, root docs/config	workspace-ops	agent-ops/rules/project/domain/workspace-ops/rules.md

스킬 라우팅

현재 프로젝트 전용 skill은 없다. 반복 작업이 안정적으로 드러나면 agent-ops/skills/project/<skill-name>/SKILL.md로 추가한다.