# NomadCode Project Rules

## 응답 언어

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

## 프로젝트 개요

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

## 주요 구조

- `services/core/` — Go 기반 백엔드, workflow, scheduler, persistence, 외부 adapter.
- `apps/web/` — React/Vite 기반 운영 콘솔과 agent/project workspace UI.
- `apps/mobile/` — Flutter 기반 모바일/데스크톱 클라이언트와 알림 연동.
- `packages/contracts/` — 서비스와 클라이언트가 공유하는 API/schema 계약.
- `bin/` — 원레포 공통 test/build/lint/dev entrypoint.
- `docs/` — 아키텍처와 운영 문서.
- `agent-ops/` — 에이전트 공통 규칙, project/domain rules, roadmap, 반복 작업 skill.

## 기술 스택

- Backend: Go, chi, pgx, River, SQLC, PostgreSQL.
- Web: TypeScript, React, Vite, TanStack Router, TanStack Query, Zustand.
- 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/web` 변경은 `npm run check` 또는 `npm run verify`로 확인한다.
- `apps/mobile` 변경은 `flutter test`와 필요 시 `flutter analyze --no-fatal-infos`로 확인한다.
- `packages/contracts`가 실제 계약을 갖기 전에는 API 형태를 서비스/클라이언트에 중복 고정하지 말고 계약 후보를 문서화한다.
- 하위 앱/서비스에 별도 `agent-ops`나 AI entry 파일을 만들지 않는다. 루트 `agent-ops`와 루트 entry 파일만 사용한다.

## 도메인 매핑

| 경로 패턴 | 도메인 | rules.md |
|----------|--------|----------|
| `services/core/**` | core | `agent-ops/rules/project/domain/core/rules.md` |
| `apps/web/**` | web | `agent-ops/rules/project/domain/web/rules.md` |
| `apps/mobile/**` | 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-ops/roadmap/**`, `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-ops/roadmap/current.md`를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다.
- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다.
- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다.
- 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.

## 주의사항

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