---
domain: operations
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
last_rule_updated_at: 2026-06-01
---

# operations

## 목적 / 책임

로컬 개발, remote verification routing, workspace orchestration, operator CLI, generated output checks, and infrastructure entrypoints를 관리한다. 개발자와 agent가 반복적으로 쓰는 root-level commands, local/remote test rules, and service entrypoints stay discoverable here.

## 포함 경로

- `bin/` - workspace helper scripts
- `go.work` - Go workspace module membership
- `go.work.sum` - Go workspace dependency checksum
- `apps/cli/` - Go operator CLI for local/admin workflows
- `deployments/local/` - local Docker Compose infrastructure
- `agent-test/local/` - local profile test routing that executes on the remote test host
- `.gitignore` - repository-level ignore policy

## 제외 경로

- `services/api/` - API runtime implementation
- `services/worker/` - worker runtime implementation
- `apps/client/` - Flutter client code
- `packages/domain/` and `packages/contracts/` - shared model and schema sources

## 주요 구성 요소

- `bin/dev` - prints local development entrypoints
- `bin/test` - runs Go tests and Flutter tests
- `bin/lint` - runs Go vet and Flutter analyze
- `bin/build` - builds Go binaries and Flutter web
- `bin/contracts-gen` - regenerates contract outputs
- `bin/contracts-check` - checks generated contract outputs are current
- `bin/infra-check` - checks PostgreSQL/Redis availability for the configured environment
- `bin/worker-storage-gen` - regenerates worker sqlc outputs
- `bin/worker-storage-check` - checks worker sqlc generated output drift
- `deployments/local/docker-compose.yml` - PostgreSQL and Redis local stack
- `apps/cli/cmd/alt/main.go` - operator CLI scaffold
- `agent-test/local/rules.md` - local profile routing with remote host execution policy

## 유지할 패턴

- Keep root helper scripts executable, idempotent where practical, and `set -euo pipefail`.
- Prefer root `bin/*` commands for whole-workspace workflows.
- Keep contract codegen/check scripts under `bin/` and route schema ownership back to `packages/contracts`.
- Keep worker storage codegen/check scripts under `bin/` and route schema/query ownership back to `services/worker/internal/storage/postgres`.
- Keep local infrastructure defaults aligned with worker/API environment fallback values.
- Add new Go modules to `go.work` when they are part of local development.
- Treat `agent-test/local` as a local profile whose commands run from the remote ALT checkout; do not imply local shell execution when local testing is forbidden.
- Keep root scripts explicit: generated drift checks should fail loudly and tell the user which generation command to run.

## 다른 도메인과의 경계

- **api** and **worker**: operations starts, tests, and builds services; service behavior belongs to each service domain.
- **client**: operations invokes Flutter commands; UI implementation stays under `apps/client`.
- **contracts**: operations may run codegen later; schema design remains in contracts.
- **agent-test**: operations owns routing to test profiles, but domain-specific smoke criteria remain in each `agent-test/local/*-smoke.md` document.

## 금지 사항

- Do not put application business logic in shell scripts.
- Do not commit local secrets or machine-specific state.
- Do not make root scripts silently skip failing module checks.
- Do not record raw remote paths, tokens, passwords, account numbers, or personal endpoints in tracked test rules or command output.