mayak: Instructions file for Claude Code

CLAUDE.md

The shared Mayak agent rules, rendered for Claude Code.

Generated from docs/agent_rules.md via scripts/sync_agent_docs.py. Do not edit this file manually.

Quick Start

• Copy the reference_task vertical. It is the one worked example and it exists to be copied — eleven files plus three wiring edits; .agents/skills/add-vertical carries the order and the removal list for when your own vertical replaces it. A project that has replaced it edits this line and nothing else: the wrapper's Quick Start is generated from these bullets.
• If .env is missing: make init-project. Nothing else creates it, and the app does not start without it. Idempotent — it never overwrites an existing .env.
• make quality-gates before committing. When the diff touched persistence, endpoints or wiring, make test-e2e too — the gates run none of your queries.
• Reach for uv run python scripts/query_ai_context.py bootstrap when you need the wiring map, and workset diff when you already have local edits — not as a ritual.

Running the service needs one more decision: the shipped .env points at PostgreSQL with placeholder credentials, so make run-local fails until either a database is up (docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d db) or the project declares it needs none (POSTGRES_ENABLED=false in .env).

Common Commands

# Validation
make ai-autofix              # Auto-format + fix lint + CBM
make quality-gates           # The validation suite — run it before committing
make security-scan           # bandit security scan over project/
make ci-local                # Everything CI runs, locally: gates, both Postgres modes, audit, e2e

# Testing
make test                    # Unit + integration (skip functional)
make test-all                # All tests including functional
make test-e2e                # Functional tests only (Docker)

# Refresh generated artifacts
make refresh-ai-context      # Regenerate AI context maps
make refresh-agent-docs      # Regenerate CLAUDE.md and AGENTS.md
make refresh-project-map     # Regenerate docs/project_map.md
make refresh-generated-docs  # All of the above, in dependency order

# Reading a running service
make format-trace            # Render a local NDJSON file: ARGS="<logfile>"
make logs                    # Render the container's semantic log as a trace tree
make logs-raw                # Dump the container's raw NDJSON under logs/

# Run
make smoke                   # Docker-based health check
make migrate                 # Apply pending Alembic migrations
make run-local               # Migrate, then start the app locally (needs a reachable PostgreSQL unless POSTGRES_ENABLED=false)

# Scaffolding
make autogenerate-migration  # Alembic migration: MSG="description"