Opinionated, version-aware guidance for Prefect 3.x, plus the discipline of checking the live docs when unsure. The core is a workflow + checklist; topic detail is fetched from docs, never memorized. Prefect 2.x is out of scope — recommend migrating up.
Response Contract
Keep it brief, but every Prefect response includes:
- Assumptions / target — Prefect 3.x; Cloud vs self-hosted; work-pool type (process / docker / kubernetes / managed). State them; never silently assume.
- Recommendation + key tradeoff — what to do and what it costs.
- Doc consulted — the exact page URL fetched, or "baseline knowledge" if none was needed.
- Validation step — a concrete check (e.g.
prefect deploydry run,prefect.yamlreview,prefect config view).
Doc-Lookup Protocol
Follow this whenever you are unsure, the task is version-sensitive, or the user asks for current/best practice:
- Fetch the index
https://docs.prefect.io/llms.txtand find the page matching the topic. - Fetch that page as markdown by appending
.md(e.g.https://docs.prefect.io/v3/concepts/flows.md). references/docs-map.md is a topic→URL shortcut. - If a URL 404s or the topic isn't in the map, re-fetch
llms.txtand re-resolve — never invent a URL. - Web search is a fallback only.
- Prefer the agent's web-fetch capability over shell
curl(works under network sandboxing). Avoidllms-full.txt(whole corpus; context-heavy).
Cite the page you used in the Response Contract.
CLI-First Protocol (query, don't guess state)
When the answer lives in the Prefect instance — deployments, work pools, runs, blocks, profiles — query it via the CLI instead of reasoning from memory or code alone.
- Invocation: in uv projects (
uv.lock/pyproject.tomlpresent) alwaysuv run prefect ...— never bareprefector ad-hoc pip installs. Bareprefectonly when there's no uv project. - Auth preflight: start with
uv run prefect config viewto confirm the active profile andPREFECT_API_URL. If unauthenticated or pointing at the wrong server, stop and ask the user to runprefect cloud login(interactive) — don't retry blindly. - Useful queries:
deployment ls/deployment inspect,work-pool ls/work-pool inspect,flow-run ls/flow-run inspect <id>,block type ls,variable ls,profile ls. Verify flags via--helpor the docs, not memory. - Boundary: read-only queries — run freely, eagerly. State-changing commands (
deploy,deployment run,work-pool create, pause/cancel) — propose, confirm intent, then run.
Diagnose → Route
| Intent | Checklist area | Start docs at |
|---|---|---|
| New project / structure / deps | Scaffolding & structure | quickstart, projects, prefect.yaml |
| Writing flows/tasks, reliability | Authoring + reliability | flows, tasks, task-runners, retries, caching, results |
| Deploying / executing / scheduling | Deployment & execution | deployments, prefect.yaml, work-pools, workers, schedules |
| Config, secrets, observability, tests | Config/secrets/observability/testing | blocks, variables, logging, artifacts, automations, testing |
| Run failed / crashed / stuck / late | Debug Workflow | states, detect-zombie-flows, workers, retry-flow-runs |
Load only the area you need. Full URLs: references/docs-map.md.
When to Use / Don't Use
Use when: scaffolding a new Prefect 3 project; auditing an existing one against current standards; authoring or debugging flows/tasks/deployments; choosing work pools, deployment style, or scheduling; or any time you're unsure about a Prefect 3 API.
Don't use for: Prefect 2.x (recommend migrating to 3.x); non-Prefect orchestration; trivial Python unrelated to Prefect.
Greenfield Workflow
- Capture target — Cloud vs self-hosted, execution environment (process/docker/k8s/managed), repo/deps tooling. State assumptions.
- Scaffold with
prefect initand current project conventions — don't hand-roll a layout. Look up the projects/quickstart pages. - Walk the checklist (references/greenfield-checklist.md) area by area; apply each one-line standard, fetching the linked doc when you need detail.
- Author flows/tasks with explicit reliability (retries/timeouts/caching/results) per the checklist.
- Define deployments + work pool, choosing
prefect.yamlvs.deploy()/flow.from_sourcevsflow.serve()deliberately. - Wire config/secrets/observability/testing.
- Validate per the Response Contract before finishing.
Audit Workflow
- Confirm the project is on Prefect 3.x (flag any 2.x → migrate).
- Query the live instance (CLI-First Protocol) and compare deployed reality — deployments, work pools, schedules — against the repo's manifests.
- Run the same checklist as a rubric; for each area note conformance vs drift.
- Flag deprecated patterns explicitly — see Guardrails.
- Report findings grouped by the four areas, each with a current-docs pointer for the fix.
Debug Workflow
- Capture target — Cloud vs self-hosted, work-pool type, Prefect version. State assumptions.
- Read the run via the CLI —
flow-run lsthenflow-run inspect <id>: final state, state message, logs; confirm state semantics against the states doc. - Classify the failure — code (traceback in logs → fix the flow/task) vs infra (Crashed/zombie, stuck Pending, Late, lost worker).
- For infra failures, check the worker and pool — worker online and polling the right pool/queue, healthchecks, concurrency limits not exhausted.
- Fix, then validate — re-run via manual retry or
prefect deployment runand confirm the resulting state.
Docs: see references/docs-map.md § Debugging & states.
Prefect 3 Guardrails (common stale-knowledge traps)
- Workers, not agents. Prefect 3 uses workers + work pools; the old agent model is gone.
- No
Deploymentobject. Create deployments viaprefect.yaml,flow.deploy(),flow.from_source(...).deploy(), orflow.serve()— notprefect.deployments.Deploymentorprefect deployment build. - Don't guess
prefect.yamlshape or CLI flags — confirm via the prefect.yaml / deployments docs. - Results, caching, and transactions changed in 3.x — verify against those pages before advising.
- When unsure whether an API is current, look it up (protocol above) rather than recalling.
Reference patterns (portable)
Battle-tested shapes worth reusing — adapt, don't copy paths:
- Dual deployment manifests — a local
prefect.yaml(process pool / bind-mount) plus a Cloud variant (managed pool / git_clone) selected via--prefect-file, so the same flows deploy to dev and prod. - Parametrized shared flow — one flow keyed by a
source_nameparameter, deployed once per source, instead of near-duplicate flows. run_deploymentfan-out — an orchestrator flow that triggers child deployments viarun_deployment, so each stage keeps isolated logs, retries, and UI reruns.