nomadcode/agent-ops/rules/project/domain/core/rules.md

domain	last_rule_review_commit	last_rule_updated_at
core	e3b5dae725	2026-05-21

core

목적 / 책임

NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduling, persistence, HTTP API, 외부 서비스 adapter를 통해 AI 작업 실행 상태와 자동화 흐름을 관리한다.

포함 경로

• services/core/cmd/ — 서버 실행 entrypoint.
• services/core/internal/agent/ — agent 모델과 실행 단위.
• services/core/internal/config/ — 환경 변수 기반 core 설정 로딩.
• services/core/internal/model/ — 모델 호출 추상 인터페이스와 입출력 타입.
• services/core/internal/workflow/ — workflow 모델과 서비스.
• services/core/internal/scheduler/ — River 기반 작업 스케줄링과 job 정의.
• services/core/internal/notification/ — task notification 모델과 발행 서비스.
• services/core/internal/http/ — HTTP router, handlers, middleware.
• services/core/internal/db/ — SQLC 생성 코드, DB pool, persistence 모델.
• services/core/internal/storage/ — 저장소 abstraction.
• services/core/internal/adapters/ — OpenAI, A2A, Mattermost, Plane 등 외부 통합.
• services/core/migrations/, services/core/queries/, services/core/sqlc.yaml — DB schema/query 계약.
• services/core/go.mod, services/core/go.sum — core Go module dependency boundary.
• services/core/README.md, services/core/goose.env.example — core 실행/운영 문서와 설정 예시.
• services/core/bin/, services/core/Makefile, services/core/Dockerfile, services/core/docker-compose.yml — backend-local 개발/배포 도구.

제외 경로

• apps/web/ — backend API를 사용하는 웹 UI이며 core 구현을 직접 소유하지 않는다.
• apps/mobile/ — 모바일/데스크톱 클라이언트이며 core 내부 패키지를 직접 참조하지 않는다.
• packages/contracts/ — 공유 API/schema 계약의 소유 영역이다.

주요 구성 요소

• internal/http/router.go — HTTP route 조립.
• internal/http/handlers.go — API handler.
• internal/config/config.go — 환경 변수 기반 설정 로딩.
• internal/model/model.go — 모델 client interface와 generation DTO.
• internal/scheduler/river.go — River scheduler 연결.
• internal/scheduler/jobs.go — background job 정의.
• internal/notification/service.go — task 완료 notification 발행.
• internal/adapters/openai/client.go — OpenAI integration.
• internal/adapters/a2a/client.go — A2A integration.
• internal/db/tasks.sql.go — SQLC generated query boundary.

유지할 패턴

• Go package 경계는 internal/<domain> 단위로 유지한다.
• DB 변경은 migration, query, generated code, test를 함께 갱신한다.
• 외부 서비스 호출은 internal/adapters/<provider> 아래에 격리한다.
• 환경 변수 기본값과 alias는 internal/config에서 관리하고 README의 실행 예시와 어긋나지 않게 유지한다.
• scheduler 변경은 가능한 한 job 단위 테스트를 추가한다.
• HTTP API 변경은 web/mobile 영향과 contracts 반영 필요성을 함께 판단한다.

다른 도메인과의 경계

• contracts: API shape가 클라이언트와 공유되면 contracts에 먼저 표현하거나 문서화한다.
• web: web은 HTTP/API client를 통해 core와 통신한다. core 내부 Go package를 전제하지 않는다.
• mobile: mobile은 public API와 notification/auth 계약만 의존한다.
• workspace-ops: root helper 변경은 workspace-ops 소유이고, core-local bin 변경만 core 소유다.

금지 사항

• apps/**의 UI 상태나 라우팅을 core 변경에 끼워 넣지 않는다.
• 외부 provider별 세부 구현을 workflow/service 레이어에 직접 흘리지 않는다.
• SQLC 생성 파일만 수동 수정하지 않는다.
• 테스트 없이 scheduler, persistence, adapter behavior를 크게 바꾸지 않는다.