main_backend/.agents/skills/infra-best-practices/SKILL.md

name, description

name	description
infra-best-practices	Use when changing, reviewing, or debugging CI, deployment, environment configuration, secrets, observability, generated artifacts, or infrastructure workflows in ui_harness_manager.

Infra Best Practices

Project Guidance

Treat infrastructure as a small, explicit support layer for the Bun, React, Elysia, and Tauri surfaces. Prefer boring, reproducible workflows over clever automation.

Configuration that varies by deploy belongs in environment variables. Use API_HOST and API_PORT as granular, orthogonal settings; do not hardcode deploy hosts, ports, credentials, or machine-local paths into source. The repo should remain safe to open-source without exposing secrets.

Use Bun as the package and CI runtime. Keep bun.lock committed, install with bun ci in CI, and avoid adding npm, Yarn, or pnpm lockfiles unless the repo intentionally changes package managers.

For CI, prove build health before adding release complexity: run bun run check, then bun run build; use bun run tauri:build when native packaging, Tauri config, permissions, Rust commands, or desktop release behavior changes. Install/cache Tauri system and Rust prerequisites on each platform runner before expecting native packaging to work.

Packaged desktop builds do not automatically include the local Elysia dev server. Before release work, decide whether backend behavior moves into Rust commands, a Tauri sidecar, or an external service, then verify the packaged app can reach it.

Use IaC or checked-in config for new infrastructure changes when possible. Keep manual console steps as temporary exceptions and document the owner, reason, and rollback path.

Keep logs and observability useful but proportional. Capture startup config shape, API bind failures, build/package failures, and deployment errors without logging secrets or flooding small-app workflows with heavyweight telemetry.

Quick Reference

Area	Default
Deploy config	Env vars, especially API_HOST and API_PORT
Secrets	Secret manager or CI secrets, never source files
CI install	bun ci with committed bun.lock
First CI checks	bun run check, then bun run build
Desktop release check	Install Tauri prerequisites, then bun run tauri:build
Generated dirs	Do not treat dist, node_modules, src-tauri/gen, or src-tauri/target as source
Infra changes	Prefer IaC or reviewed config over undocumented manual changes

Common Mistakes

• Using bun install in reproducible CI instead of bun ci.
• Adding deploy-specific constants when API_HOST or API_PORT should be env-driven.
• Committing credentials, tokens, private URLs, or local absolute paths.
• Editing or reviewing generated output in dist, node_modules, src-tauri/gen, or src-tauri/target as if it were source.
• Shipping a packaged desktop build that still assumes the local Bun/Elysia dev server is running.
• Building release pipelines before CI reliably checks and builds the app.
• Adding observability that hides the important failure path behind noisy dashboards.
• Making manual infra changes without a rollback note or future IaC/config follow-up.