148 lines
8.9 KiB
Markdown
148 lines
8.9 KiB
Markdown
# NomadCode
|
|
|
|
NomadCode는 AI 기반 개발 작업을 제품 흐름으로 운영하기 위한 원레포입니다. Go 기반 core 서비스, React/Vite 웹 콘솔, Flutter 클라이언트, 공유 계약 공간, 그리고 AI 에이전트 작업 규칙과 로드맵을 한 작업 흐름으로 묶습니다.
|
|
|
|
NomadCode는 IOP를 사용하는 개발 워크플로우 셸입니다. 사용자와 외부 provider 요청을 개발 작업으로 구조화하고, project/session/workspace 상태와 실행 결과를 사용자에게 보여줍니다. 모델 런타임, 모델 라우팅, RAG, MCP 정책, output validation 엔진은 NomadCode가 직접 소유하지 않고 IOP 책임으로 둡니다.
|
|
|
|
## 현재 상태
|
|
|
|
- `services/core`는 health/readiness endpoint, task API, PostgreSQL persistence, goose migration, sqlc query 생성 구조, River job, IOP OpenAI-compatible Responses client 경로, 향후 A2A agent delegation scaffolding, Plane/Mattermost adapter stub을 포함합니다.
|
|
- `apps/web`은 Agent, Projects, Settings, browser-based project workspace 화면을 위한 React/Vite 운영 콘솔 scaffold입니다. 일부 상태와 integration status 영역은 아직 mock 또는 stub입니다.
|
|
- `apps/mobile`은 Flutter 기반 모바일/데스크톱 클라이언트 scaffold이며 Firebase Messaging, local notifications, HTTP client 의존성을 포함합니다.
|
|
- `packages/contracts`는 향후 OpenAPI, protobuf, generated client, fixture, compatibility asset을 담을 공유 계약 공간입니다.
|
|
- 활성 계획과 Milestone 상태는 `agent-ops/roadmap/`에서 관리합니다. README에는 현재 작업 상태를 복사하지 않고 진입 문서만 연결합니다.
|
|
|
|
## 제품 경계
|
|
|
|
NomadCode는 제품과 워크플로우 계층을 소유합니다.
|
|
|
|
- agent chat, project workspace 관리, task queue 상태, 실행 상태 표시
|
|
- Plane/Jira 스타일 work item intake, provider projection, comment, status update
|
|
- 사용자에게 노출되는 file change, diff, branch, commit, PR 흐름
|
|
- 데스크톱/모바일 project management surface
|
|
- IOP 호출에 넘길 task metadata 구성
|
|
|
|
IOP는 실행과 최적화 계층을 소유합니다.
|
|
|
|
- OpenAI-compatible model call, 현재 NomadCode 통합 목표인 Responses API 지원
|
|
- local/cloud model routing, model profile, runtime selection, usage log, quality signal
|
|
- OpenCode, Aider, Claude Code, Gemini CLI, Codex CLI 같은 CLI agent/runtime adapter
|
|
- RAG, context compression, MCP/tool policy, output validation, retry/fallback, token/speed/quality optimization
|
|
|
|
NomadCode는 IOP가 제공하는 외부 표면을 통해 IOP를 호출합니다. 현재 기본 경로는 IOP의 OpenAI-compatible Responses API입니다. A2A는 향후 외부 agent delegation 작업을 위한 표면이며, IOP native protocol은 NomadCode의 기본 외부 호출 경로가 아닙니다.
|
|
|
|
## 빠른 시작
|
|
|
|
사용하는 workspace 영역에 필요한 runtime만 설치하면 됩니다.
|
|
|
|
```bash
|
|
# 사용 가능한 service/app 개발 entrypoint 확인
|
|
bin/dev
|
|
|
|
# 설치된 toolchain 기준으로 workspace 검증
|
|
bin/test
|
|
bin/lint
|
|
bin/build
|
|
```
|
|
|
|
Core service를 로컬에서 실행합니다. 스크립트는 local 기본값을 제공하지만, PostgreSQL과 Redis가 접근 가능해야 합니다. 현재 `code-server` database setup 관련 메모는 `services/core/README.md`를 확인합니다.
|
|
|
|
```bash
|
|
cd services/core
|
|
./bin/migrate-up
|
|
./bin/run
|
|
```
|
|
|
|
Web console을 실행합니다.
|
|
|
|
```bash
|
|
cd apps/web
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Flutter 앱을 실행합니다.
|
|
|
|
```bash
|
|
cd apps/mobile
|
|
flutter pub get
|
|
flutter run
|
|
```
|
|
|
|
## 주요 명령
|
|
|
|
| 목적 | 명령 | 비고 |
|
|
|------|------|------|
|
|
| 개발 entrypoint 확인 | `bin/dev` | core, web, mobile 실행 명령을 출력합니다. |
|
|
| workspace 테스트 | `bin/test` | `go test ./...`, web check 또는 test, `flutter test`를 실행하고 없는 toolchain은 건너뜁니다. |
|
|
| workspace lint | `bin/lint` | `go vet ./...`, web lint, `flutter analyze --no-fatal-infos`를 실행하고 없는 toolchain은 건너뜁니다. |
|
|
| workspace build | `bin/build` | core `go build ./...`, web build, Flutter web build를 실행하고 없는 toolchain은 건너뜁니다. |
|
|
| core 실행 | `cd services/core && ./bin/run` | 스크립트 기본값을 사용하며 env로 override할 수 있습니다. |
|
|
| core DB migration | `cd services/core && ./bin/migrate-up` | goose로 PostgreSQL migration을 적용합니다. |
|
|
| core 테스트 | `cd services/core && ./bin/test` | `go test ./...` wrapper입니다. |
|
|
| core build | `cd services/core && ./bin/build` | 기본 출력 경로는 `.build/nomadcode-core`입니다. |
|
|
| web dev server | `cd apps/web && npm run dev` | Vite 개발 서버입니다. |
|
|
| web type check | `cd apps/web && npm run check` | TypeScript `--noEmit` 검증입니다. |
|
|
| web verify | `cd apps/web && npm run verify` | type check와 production build를 함께 실행합니다. |
|
|
| mobile 테스트 | `cd apps/mobile && flutter test` | Flutter test suite입니다. |
|
|
|
|
## 구조
|
|
|
|
| 경로 | 역할 |
|
|
|------|------|
|
|
| `services/core/` | Go backend. orchestration, persistence, scheduling, HTTP API, 외부 service adapter를 담당합니다. |
|
|
| `apps/web/` | React/Vite 운영 콘솔과 agent/project workspace UI입니다. |
|
|
| `apps/mobile/` | Flutter 모바일/데스크톱 클라이언트와 notification 연동 표면입니다. |
|
|
| `packages/contracts/` | 서비스와 클라이언트가 공유할 API/schema 계약 공간입니다. |
|
|
| `docs/` | 아키텍처와 운영 문서입니다. |
|
|
| `bin/` | root test, lint, build, dev helper 명령입니다. |
|
|
| `agent-ops/` | AI 에이전트 규칙, 도메인 라우팅, 로드맵, 반복 작업 skill입니다. |
|
|
|
|
## 작업 맥락
|
|
|
|
AI 에이전트는 파일을 변경하기 전에 루트 지침과 프로젝트 규칙을 먼저 확인합니다.
|
|
|
|
- `AGENTS.md`
|
|
- `agent-ops/rules/project/rules.md`
|
|
- `agent-ops/rules/private/rules.md`가 있으면 해당 파일
|
|
|
|
README 같은 workspace-level 파일을 다룰 때는 아래 문서를 함께 확인합니다.
|
|
|
|
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
|
|
- `agent-ops/skills/common/create-readme/SKILL.md`
|
|
- `agent-ops/roadmap/current.md`
|
|
|
|
로드맵 상세 상태는 `agent-ops/roadmap/`에, 도메인별 세부 규칙은 `agent-ops/rules/project/domain/`에 둡니다. 사용자가 명시적으로 요청하지 않는 한 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 읽지 않습니다.
|
|
|
|
IOP 경계가 걸린 작업은 같은 workspace에 sibling IOP repository가 있을 때 함께 확인합니다. NomadCode roadmap은 제품/워크플로우 범위의 기준 문서이고, IOP roadmap은 실행/runtime 범위의 기준 문서입니다.
|
|
|
|
## 개발 흐름
|
|
|
|
- 전체 workspace 작업은 가능한 한 root `bin/test`, `bin/lint`, `bin/build`, `bin/dev` entrypoint를 우선 사용합니다.
|
|
- 변경은 소유 도메인 규칙 범위에 맞춰 좁게 유지합니다.
|
|
- contract, service, client 경계가 함께 움직이는 변경은 같은 브랜치에서 닫습니다.
|
|
- core DB 변경은 `services/core/migrations/`와 `services/core/queries/`를 기준으로 반영하고, `services/core/internal/db/`의 생성 파일은 직접 수정하지 않습니다.
|
|
- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`는 framework 동기화 영역입니다. 프로젝트 특화 규칙은 `agent-ops/rules/project/**`에 둡니다.
|
|
|
|
## 환경 변수
|
|
|
|
| Runtime | 이름 | 필수 | 설명 |
|
|
|------|------|------|------|
|
|
| Core | `DATABASE_URL` | 스크립트 사용 시 선택 | Core script는 local 기본값을 제공합니다. 다른 PostgreSQL을 쓰거나 binary를 직접 실행할 때 설정합니다. |
|
|
| Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | 스크립트 사용 시 선택 | worker/queue 상태에 사용할 Redis 주소와 key prefix입니다. |
|
|
| Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | 선택 | `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. |
|
|
| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | 선택 | worker execution에서 사용할 IOP Edge OpenAI-compatible Responses endpoint 설정입니다. |
|
|
| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | 선택 | 향후 A2A-compatible agent delegation 경로 설정입니다. 현재 기본 실행 경로는 아닙니다. |
|
|
| Core | `WORKFLOW_TASK_TIMEOUT_SEC` | 선택 | workflow task timeout 기본값을 조정합니다. |
|
|
| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | 선택 | Mattermost adapter 연동용 설정입니다. |
|
|
| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | 선택 | Plane work item 조회, comment, state update 연동용 설정입니다. token 값은 문서에 기록하지 않습니다. |
|
|
| Web | `VITE_NOMADCODE_API_BASE_URL` | 선택 | web client API base URL입니다. 기본값은 `http://localhost:8080`입니다. |
|
|
|
|
## 참고 문서
|
|
|
|
- `docs/monorepo.md`
|
|
- `services/core/README.md`
|
|
- `apps/web/README.md`
|
|
- `apps/mobile/README.md`
|
|
- `packages/contracts/README.md`
|
|
- `agent-ops/roadmap/current.md`
|