NomadCode

NomadCode는 AI 기반 개발 작업을 제품 흐름으로 운영하기 위한 원레포입니다. Go 기반 core 서비스, 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/mobile은 NomadCode 제품 UI의 기준 Flutter 앱이며 모바일/데스크톱/선택적 web target, Firebase Messaging, local notifications, HTTP client 의존성을 포함합니다.
• apps/web은 이전 React/Vite 운영 콘솔 scaffold였으며, Flutter-first 통합에 따라 완전히 폐기 및 제거되었습니다.
• 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 흐름
• 모바일/데스크톱/선택적 web target의 Flutter 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만 설치하면 됩니다.

# 사용 가능한 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를 확인합니다.

cd services/core
./bin/migrate-up
./bin/run

Flutter 앱을 실행합니다.

cd apps/mobile
flutter pub get
flutter run

주요 명령

목적	명령	비고
개발 entrypoint 확인	bin/dev	core와 Flutter app 실행 명령을 출력합니다.
workspace 테스트	bin/test	go test ./..., flutter test를 실행하고 없는 toolchain은 건너뜁니다.
workspace lint	bin/lint	go vet ./..., flutter analyze --no-fatal-infos를 실행하고 없는 toolchain은 건너뜁니다.
workspace build	bin/build	core go 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입니다.
mobile 테스트	cd apps/mobile && flutter test	Flutter test suite입니다.

구조

경로	역할
services/core/	Go backend. orchestration, persistence, scheduling, HTTP API, 외부 service adapter를 담당합니다.
apps/mobile/	Flutter 기반 제품 UI source of truth, 모바일/데스크톱 클라이언트와 notification 연동 표면입니다.
apps/web/	[Legacy/Retired] React/Vite 운영 콘솔 scaffold입니다. Flutter-first 클라이언트 통합에 따라 완전히 폐기 및 제거되었습니다.
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 값은 문서에 기록하지 않습니다.

참고 문서

• docs/monorepo.md
• services/core/README.md
• apps/mobile/README.md
• packages/contracts/README.md
• agent-ops/roadmap/current.md