78 lines
5.2 KiB
Markdown
78 lines
5.2 KiB
Markdown
# 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 파일만 사용한다.
|
|
- 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/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/**`에 둔다.
|