Home › Temporal workflows › Temporal workflows AGENTS.md

Temporal workflows AGENTS.md

AGENTS.md for Temporal applications: deterministic workflows, idempotent activities, retries and timeouts, versioning safe changes, and replay tests.

AGENTS.mdTemporal workflows

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Temporal workflows

## Commands
- Local server: `temporal server start-dev` (UI at http://localhost:8233)
- Run worker: see `package.json`/`Makefile` (e.g. `npm run worker`, `go run ./worker`, `python -m app.worker`)
- Tests: the SDK's test environment (time-skipping) via the normal test command.
- Inspect: `temporal workflow list`, `temporal workflow show --workflow-id <id>`.

## Code map
`workflows/` (orchestration only) · `activities/` (all I/O) · `worker` entrypoint registering both on a named task queue · `client` code that starts workflows.

## Workflow rules (determinism)
- Workflow code must be deterministic: no network, DB, file I/O, random numbers, system time, threads or non-deterministic iteration. Use SDK APIs instead (`workflow.now()`, `workflow.sleep()`, SDK random/UUID helpers).
- All side effects happen in activities. Workflows only orchestrate: call activities, child workflows, timers, signals, queries and updates.
- Changing workflow code that already has running executions needs versioning (`patched`/`GetVersion`/Worker Versioning). Never reorder or remove activity calls without it.
- Keep workflow inputs and history small: pass IDs, not large payloads; use `continueAsNew` for long-running or looping workflows.
- Use stable, business-meaningful workflow IDs to get deduplication.

## Activity rules
- Activities are idempotent (safe to retry): use idempotency keys or upserts.
- Always set `startToCloseTimeout` (and `heartbeatTimeout` + heartbeats for long activities); configure `RetryPolicy` with backoff and mark permanent failures non-retryable.
- No business secrets in workflow inputs or results; payloads are stored in history (use a codec for encryption if needed).

## Tests
Unit-test activities directly; test workflows with the SDK test environment and mocked activities; add a replay test against saved histories when changing workflow code.

## Done
Tests and replay tests pass and the worker starts against the dev server.