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/client는 NomadCode 제품 UI의 기준 Flutter 앱이며 모바일/데스크톱/선택적 web target, Firebase Messaging, local notifications, HTTP client 의존성을 포함합니다. 현재 top titlebar, 우측 activity rail, 우측 Agent dock panel을 가진 workbench shell scaffold가 들어가 있고, Agent dock은 공통 agent_shell package를 사용합니다. IOP는 우측 rail 하단 아이콘으로 분리되어 있으며, IOP package/widget이 없을 때도 빌드가 깨지지 않는 선택적 iopContent slot으로 조립합니다.
• apps/web은 이전 React/Vite 운영 콘솔 scaffold였으며, Flutter-first 통합에 따라 완전히 폐기 및 제거되었습니다.
• packages/contracts는 향후 OpenAPI, protobuf, generated client, fixture, compatibility asset을 담을 공유 계약 공간입니다.
• 활성 계획과 Milestone 상태는 agent-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
• top titlebar, 우측 activity rail, 중앙 content 전환, 우측 Agent dock, 하단 IOP section slot으로 구성되는 workbench shell
• IOP 관리 page/tab에 외부 IOP console package 또는 widget을 선택적으로 mount하는 제품 조립 경계
• 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/client
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입니다.
client 테스트	cd apps/client && flutter test	Flutter test suite입니다.

구조

경로	역할
services/core/	Go backend. orchestration, persistence, scheduling, HTTP API, 외부 service adapter를 담당합니다.
apps/client/	Flutter 기반 제품 UI source of truth, workbench shell, 우측 Agent dock, 모바일/데스크톱/선택적 web 클라이언트와 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입니다.
agent-test/local/	local 테스트 profile과 runner별 검증 규칙입니다.

작업 맥락

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-roadmap/current.md

로드맵 상세 상태는 agent-roadmap/에, 도메인별 세부 규칙은 agent-ops/rules/project/domain/에 둡니다. 사용자가 명시적으로 요청하지 않는 한 agent-task/archive/**와 agent-roadmap/archive/**는 읽지 않습니다.

IOP 경계가 걸린 작업은 같은 workspace에 sibling IOP repository가 있을 때 함께 확인합니다. NomadCode roadmap은 제품/워크플로우 범위의 기준 문서이고, IOP roadmap은 실행/runtime 범위의 기준 문서입니다.

agent_shell은 제품 표면이 아니라 공통 chat/agent shell package입니다. NomadCode는 이 package를 우측 Agent dock UI에 사용하고, IOP 자체 기능은 NomadCode 코드에 직접 복제하지 않고 별도 IOP console package/widget 경계로 조립하는 방향을 유지합니다.

개발 흐름

• 전체 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 값은 문서에 기록하지 않습니다.

참고 문서

• services/core/README.md
• apps/client/README.md
• packages/contracts/README.md
• agent-roadmap/current.md