# NomadCode Project Rules

## 응답 언어

- 기본 응답 언어는 한국어다.
- 코드, 식별자, 커밋 scope, 명령어, 파일 경로는 기존 프로젝트 언어와 표기를 유지한다.

## 프로젝트 개요

NomadCode는 AI 병렬 작업 운용을 위한 원레포다. 백엔드 오케스트레이션, Flutter 앱, 공유 계약, 작업 운영 스크립트를 하나의 작업 흐름으로 묶는다.

## 주요 구조

- `services/core/` — Go 기반 백엔드, workflow, scheduler, persistence, 외부 adapter.
- `apps/client/` — Flutter 기반 제품 UI source of truth, 모바일/데스크톱/선택적 web 클라이언트와 알림 연동.
- `packages/contracts/` — 서비스와 클라이언트가 공유하는 API/schema 계약.
- `bin/` — 원레포 공통 test/build/lint/dev entrypoint.
- `docs/` — 아키텍처와 운영 문서.
- `agent-ops/` — 에이전트 공통 규칙, project/domain rules, roadmap, 반복 작업 skill.
- `agent-test/` — local 테스트 rules와 실행 산출물.

## 기술 스택

- Backend: Go, chi, pgx, River, SQLC, PostgreSQL.
- Mobile: Flutter/Dart, Firebase Messaging, local notifications, HTTP.
- Workspace: shell scripts under `bin/`, Git subtree-imported history.

## 프로젝트 특화 컨벤션

- 원레포 루트에서 가능한 작업은 `bin/test`, `bin/lint`, `bin/build`, `bin/dev`를 우선 사용한다.
- cross-boundary 변경은 계약, 서비스, 클라이언트 반영을 같은 브랜치에서 닫는다.
- `services/core` 변경은 `go test ./...` 또는 `bin/test`로 확인한다.
- `apps/client` 변경은 `flutter test`와 필요 시 `flutter analyze --no-fatal-infos`로 확인한다.
- `packages/contracts`가 실제 계약을 갖기 전에는 API 형태를 서비스/클라이언트에 중복 고정하지 말고 계약 후보를 문서화한다.
- 하위 앱/서비스에 별도 `agent-ops`나 AI entry 파일을 만들지 않는다. 루트 `agent-ops`와 루트 entry 파일만 사용한다.
- Plane 관련 core 작업은 `agent-ops/rules/project/domain/core/rules.md`의 `Plane dev 작업 메모`를 먼저 확인한다. Plane API 토큰은 ignored local secret file `.env.plane.local`에서 로드하며, 토큰 값은 규칙/로드맵/문서에 직접 기록하지 않는다.

## 도메인 매핑

| 경로 패턴 | 도메인 | rules.md |
|----------|--------|----------|
| `services/core/**` | core | `agent-ops/rules/project/domain/core/rules.md` |
| `apps/client/**` | mobile | `agent-ops/rules/project/domain/mobile/rules.md` |
| `packages/contracts/**` | contracts | `agent-ops/rules/project/domain/contracts/rules.md` |
| `bin/**`, `docs/**`, `README.md`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `opencode.json`, `agent-ops/.version`, `agent-ops/bin/**`, `agent-roadmap/**`, `agent-test/**`, `agent-ops/rules/project/**` | workspace-ops | `agent-ops/rules/project/domain/workspace-ops/rules.md` |

## 스킬 라우팅

| 요청 키워드 | SKILL.md |
|------------|----------|
| agent-ops 초기화, 에이전트 설정 | `agent-ops/skills/common/init-agent-ops/SKILL.md` |
| 도메인 룰 생성 | `agent-ops/skills/common/create-domain-rule/SKILL.md` |
| 도메인 룰 업데이트 | `agent-ops/skills/common/update-domain-rule/SKILL.md` |
| 계획 세워줘, 작업 분해 | `agent-ops/skills/common/plan/SKILL.md` |
| 코드 리뷰 | `agent-ops/skills/common/code-review/SKILL.md` |
| 커밋/푸시 | `agent-ops/skills/common/commit-push/SKILL.md` |

## 주의사항

- `agent-task/archive/**`는 읽지 않는다. 필요 시 사용자가 명시적으로 요청했을 때만 본다.
- `.gitignore`에 `agent-task/archive/**`를 추가하지 않는다.
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`는 framework 동기화 영역이므로 프로젝트 특화 내용을 넣지 않는다.
- 도메인별 세부 규칙은 `agent-ops/rules/project/domain/**`에 둔다.