Skip to content

Commerce Recommendations agent guide

Start here

Read CONTEXT.md before changing product behavior. It defines the canonical commerce-recommendation language and isolation boundary. Check the working tree before editing and preserve unrelated changes already present.

Use the documentation route that matches the change:

  • observable product behavior: specs/commerce-recommendation-service.md;
  • implemented components, data flow, storage, and failure behavior: docs/technical-implementation.md;
  • pre-implementation decisions: design/commerce-recommendation-service.md and the relevant file under design/;
  • simulation behavior: docs/commerce-simulation-harness.md and docs/commerce-simulation-requirement-matrix.md;
  • personalization: docs/shopper-personalization.md;
  • observability and operations: docs/recommendations-operations.md and operations/recommendations.toml;
  • repository workflow, tests, CI, packaging, or agent guidance: docs/testing.md and docs/agent-readiness.md.

Source code, migrations, configuration schemas, and executable tests are authoritative for current behavior. Approved specifications define intended behavior. When they disagree, report the drift and update the stale side in the same change.

Change loop

  1. Locate the affected contract and its existing tests before editing.
  2. Make the smallest cohesive change that preserves Commerce Scope isolation and source/serving boundaries.
  3. Add or update an observable test at the lowest suitable layer.
  4. Run the narrowest applicable check, then widen through the repository gates for that boundary.
  5. Inspect the final diff and update the governing documentation when a public API, migration, configuration, evidence schema, or operational contract changes.

Invariants

  • Scope every source read, run, snapshot, and served result by Data Source, Tracking ID, and Catalog ID; never combine evidence across Commerce Properties or Catalogs.
  • Serving reads only published Recommendation Snapshots and personalization projections. It never reads the merchant Relational Data Source or trains synchronously.
  • Raw interaction rows may be streamed and reduced, but never staged, logged, exported, or retained by the service.
  • Snapshot publication remains complete and atomic; a failed run cannot replace the last successful serving head.
  • Keep credentials, bearer material, Shopper identifiers, raw Order IDs, and raw Browsing Session IDs out of logs, metrics, fixtures, generated evidence, and committed configuration.
  • Keep queues, group state, retries, leases, request bodies, simulation traffic, and diagnostic artifacts bounded.
  • serving_limits remains reusable and must not import the recommendations package.
  • The application may import the sibling telemetry package only through configuration and the recommendations.observability adapter boundary.

Verification

Use the committed Make targets; they are the supported local command surface:

make setup
make doctor
make test-focused TEST=tests/path.py::test_name
make test-static
make test-unit
make test-contract
make test-integration
make test
make smoke
make verify

Run make migration-check when migrations change and make compose-check when Docker or Compose artifacts change. PostgreSQL-only tests require an explicitly disposable TEST_CONTROL_DATABASE_URL; make test-postgres refuses to run without it. See docs/testing.md for the feedback ladder and generated-artifact rules.

CI runs on a self-hosted Apple Silicon macOS runner. It checks out the pinned sibling telemetry repository beside this one because uv.lock resolves ../telemetry. Hosted settings and the required cross-repository read token are described in docs/testing.md.

Handoff

Report the behavior changed, contract evidence added or updated, and every command run with its result. For work crossing a session or agent boundary, use docs/agents/handoff.md. Name checks not run and why. Do not publish packages, deploy services, mutate external data, or change hosted settings without explicit authority.