alt/agent-ops/rules/project/rules.md

ALT 프로젝트 규칙

응답 언어

• 기본 응답은 한국어로 작성한다.
• 코드 식별자, 명령어, 경로, 에러 메시지는 원문 영어를 유지한다.
• 설계 선택을 설명할 때는 ALT의 quant workspace 맥락과 연결해서 짧게 근거를 남긴다.

프로젝트 개요

ALT는 개인 quant system workspace다. Go 서비스와 도구는 루트 go.work로 묶고, Flutter가 web/mobile/desktop 클라이언트 표면을 담당한다. 실시간 전송은 sibling workspace인 ../proto-socket/go의 proto-socket 모듈을 사용하며, ALT 애플리케이션 계약은 packages/contracts/proto의 protobuf schema가 원천이다.

주요 구조

경로	역할
services/api/	클라이언트-facing proto-socket API endpoint
services/worker/	import, normalization, backtest, scheduled job worker surface
apps/cli/	로컬/운영자 작업용 Go CLI
apps/client/	Flutter client for web/mobile/desktop
packages/contracts/	ALT protobuf contracts and compatibility notes
packages/domain/	shared Go domain model for market and backtest concepts
deployments/local/	local PostgreSQL and Redis development environment
bin/	workspace-level helper entrypoints

기술 스택

• Go 1.22 multi-module workspace via go.work.
• git.toki-labs.com/toki/proto-socket/go is consumed through a local replace to ../proto-socket/go.
• services/api uses nhooyr.io/websocket through proto-socket server/client wrappers.
• Contracts are protobuf schemas under packages/contracts/proto/alt/v1.
• Flutter client uses Material 3, Riverpod, and go_router.
• Local infrastructure uses Docker Compose with PostgreSQL 17 and Redis 7.

통신 규칙

• ALT가 소유한 runtime boundary 사이의 application message 통신은 proto-socket과 packages/contracts/proto의 ALT protobuf payload로 통일한다.
• 기본 runtime topology는 client -> services/api -> services/worker다. client는 worker를 직접 제어하지 않고 services/api를 단일 operator-facing control plane으로 사용한다.
• client-api, api-worker, worker-sidecar처럼 별도 process나 service 사이에서 ALT domain request/response, event, command를 주고받으면 기본값은 proto-socket이다.
• 같은 process 안의 함수 호출, Go interface, Dart provider 호출은 runtime 통신부로 보지 않는다.
• PostgreSQL SQL, Redis command/queue/cache, filesystem, process/stdout, local migration/codegen/dev tooling은 해당 목적의 native protocol을 사용한다.
• KIS, Mattermost, Firebase, Nexo plugin, OS platform channel처럼 ALT 외부 시스템이나 platform integration과 통신할 때는 해당 외부 protocol을 adapter 경계 안에서 사용한다.
• proto-socket이 아닌 ALT-owned runtime protocol을 새로 도입하려면 구현 전에 프로젝트 규칙 또는 명시적 architecture 문서를 갱신하고 예외 사유를 남긴다.

프로젝트 컨벤션

• 루트 작업은 bin/dev, bin/test, bin/lint, bin/build를 우선 사용한다.
• Go 모듈 경계를 넘는 import는 go.work에 등록된 모듈 기준으로 유지한다.
• protobuf generated client/server 코드는 schema에서 생성하고 손으로 편집하지 않는다.
• packages/domain은 business vocabulary와 value object를 담고, transport나 persistence detail에 의존하지 않는다.
• services/api는 socket/session boundary를 담당하고, domain 계산이나 worker job 실행을 직접 떠안지 않는다.
• services/api는 얇은 control plane으로서 client-facing 요청을 받고 worker 실행/조회 경계로 중계한다.
• services/worker는 데이터 수집, 정규화, backtest 실행, scheduled job처럼 오래 걸리거나 비동기적인 일을 담당한다.
• Flutter client는 lib/src/app에 앱 shell/router를 두고, 기능 화면은 lib/src/features/feature-name/presentation 패턴 아래에 둔다.
• runtime configuration은 환경변수를 우선하고 로컬 개발 fallback을 둔다.

도메인 매핑

경로 패턴	도메인	rules.md
packages/domain/**	domain-model	agent-ops/rules/project/domain/domain-model/rules.md
packages/contracts/**	contracts	agent-ops/rules/project/domain/contracts/rules.md
services/api/**	api	agent-ops/rules/project/domain/api/rules.md
services/worker/**	worker	agent-ops/rules/project/domain/worker/rules.md
apps/client/**	client	agent-ops/rules/project/domain/client/rules.md
apps/cli/**, bin/**, deployments/local/**, go.work, go.work.sum, .gitignore	operations	agent-ops/rules/project/domain/operations/rules.md

검증 명령

• 전체 테스트: bin/test
• 전체 lint/analyze: bin/lint
• 전체 build: bin/build
• 로컬 실행 안내: bin/dev

스킬 라우팅

현재 프로젝트 전용 skill은 만들지 않는다. 반복 작업이 안정되면 agent-ops/skills/project/ 아래에 추가한다.