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

domain	last_rule_review_commit	last_rule_updated_at
operations	704f1eb232	2026-06-24

operations

목적 / 책임

로컬 개발, remote verification routing, workspace orchestration, operator CLI/headless scenario fixtures, generated output checks, KIS smoke wrappers, 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
• secrets/ - local/private secret material used by wrappers, not tracked operational guidance

주요 구성 요소

• 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
• bin/kis-paper-daily-smoke - secret-redacting KIS daily price smoke wrapper for paper/real env credentials
• bin/kis-sops-env - decrypts local SOPS KIS env and execs a command without writing tracked secrets
• deployments/local/docker-compose.yml - PostgreSQL and Redis local stack
• apps/cli/cmd/alt/main.go - operator CLI scaffold
• apps/cli/internal/cli - CLI command dispatch and exit-code contract
• apps/cli/internal/operator.APIClient - proto-socket client for headless operator scenarios
• apps/cli/internal/operator.Scenario - strict YAML schema and dry-run validation for operator workflows
• apps/cli/internal/operator.RunScenario - scenario runner for market, backtest, paper, live, and scheduler actions
• apps/cli/internal/operator.Writer - machine-readable text/jsonl step and summary output
• apps/cli/testdata/operator/ - headless scenario fixtures and expected JSONL outputs
• 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.
• Keep operator CLI stdout machine-readable; send usage and human-readable error detail to stderr.
• Keep operator scenario validation strict: unsupported actions, enum strings, malformed duration/date fields, and expectation typos should fail before runtime execution.
• Keep KIS wrappers redacting tokens, app secrets, account numbers, and provider response snippets before printing diagnostics.

다른 도메인과의 경계

• 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.
• private rules/secrets: operations can reference secret-loading wrappers, but secret values and machine-specific endpoints remain untracked/private.

금지 사항

• 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.
• Do not make operator scenario fixtures depend on live credentials unless the command explicitly routes through a private/env wrapper.