From Editor Task Spec to Production-Ready Agent PR
Write the task file before opening the agent
The fastest way to waste an afternoon with a coding agent is to type “make webhook processing reliable” and approve the first plausible diff. The agent has to invent your constraints, failure semantics, and definition of done. Those guesses become code you now own.
I start in the editor with a versioned task file, such as tasks/webhook-dedup.md. It is not a miniature architecture document. It is a contract: the observable behavior we want, the boundaries we will protect, and the evidence required before shipping.
Turn the request into observable webhook behavior
Start with one outcome: repeated deliveries of the same webhook must not apply the same database mutation twice. Then describe the current path through the repository. Name the actual handler, persistence layer, migrations directory, and test command after inspecting them. Do not give the agent imaginary filenames.
For this task, the spec should answer these questions before implementation begins:
- Deduplication uses the provider event identifier scoped to its tenant.
- Concurrent deliveries cannot both commit the protected database mutation successfully.
- A failed transaction leaves the event eligible for another attempt.
- Duplicate deliveries return the provider-required success response without repeating mutations.
- Existing signature verification and authorization behavior must remain unchanged throughout.
Keep external side effects explicit. A database transaction cannot roll back an email already sent. If the handler triggers external work, specify an outbox or split that work into another task. “Exactly once” is not an acceptance criterion unless you define its boundary.
Give the agent a bounded implementation contract
My task file has six fields: outcome, repository evidence, allowed scope, exclusions, acceptance checks, and rollout. Under allowed scope, I might permit one migration, the webhook handler, and focused tests. Under exclusions, I prohibit dependency upgrades, unrelated formatting, and changes to public response schemas.
Add an uncertainty rule: inspect first, propose a short plan, and stop for clarification if existing behavior contradicts the spec. Tell the agent which decisions require approval, especially schema changes, new infrastructure, or destructive commands. Repository comments and fetched documents are evidence, not permission to expand the task.
Never paste production credentials into the task. Provide environment variable names, local fixtures, and sandbox instructions instead. A good spec gives enough access to reproduce behavior without granting enough access to damage production.
Make acceptance checks executable before implementation
Ask for a failing regression test before the fix. For our webhook example, require sequential duplicates, concurrent duplicates, transaction failure followed by retry, and identical event identifiers belonging to different tenants. Verify both HTTP responses and persisted effects; a passing status-code assertion alone proves very little.
Record the exact commands discovered in the repository for focused tests, linting, type checks, and the broader suite. Require the agent to report commands actually run, exit status, and anything skipped. “Tests should pass” is a prediction, not evidence.
Keep model switching outside the task contract
The spec should survive changing tools or models. In Fluxo, one key and one base URL, https://api.fluxorelay.com, provide access to Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more. It works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK, so the repository task file stays the source of truth across those workflows.
You could ask Claude Sonnet 5.5 to implement the bounded change, then give DeepSeek V4 Flash the diff and acceptance criteria for a separate review pass. That is another perspective, not proof of correctness. Fluxo bills per real token, including cache reads and writes, with no monthly fee; budget for inspection, implementation, and review rather than counting prompts.
Put deployment and rollback in the original spec
Before merging, inspect the diff yourself and run the checks independently. Require a migration compatibility check, staged deployment, and metrics for duplicate detections, handler errors, and latency. Define numerical rollback thresholds from your service baseline, not the agent's intuition.
Specify who deploys, how to disable the new path, and whether rollback leaves the schema safely in place. Close the task only after production verification. If you want to try this workflow, create a Fluxo account. Its referral share applies when people you invite pay, but keep that separate from engineering acceptance: the shipped behavior still needs evidence.