Write an agentic coding task brief that produces a reviewable change

A worked example: where the task becomes difficult

A fictional scheduling app sends duplicate reminders when an appointment is edited. “Fix notifications” is too broad: it does not identify whether the duplicate comes from saving, queueing or delivery. A useful brief includes a controlled appointment, the edit performed, the two reminder references and the expected single reminder. Remove customer details while preserving the sequence needed to reproduce the issue.

Decisions to make before implementation

Separate facts from hypotheses. “Two queue records were observed” is stronger than “the frontend probably saves twice.” Describe what the agent may inspect and what it may modify, including the active branch and permitted test environment. Name external side effects that need explicit authorization. Set an exit condition for missing evidence so the agent asks for a precise input instead of rewriting an unrelated subsystem.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Capture the smallest reproducible example and its expected result.
• List architecture constraints, affected users and allowed files or investigation boundaries.
• Ask for a cause supported by code or runtime evidence before the edit.
• Require a concise change explanation and a check that exercises the reported failure.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Investigate duplicate reminders for the controlled appointment described below. Establish whether duplication begins at save, queue creation or delivery. Preserve the existing provider and public API. Edit only after finding a supported cause. Test one appointment edit and one retry. Report changed files, observed results and remaining uncertainty; do not send reminders to actual customers.

Failure modes that an attractive preview can hide

Prescribing a patch before identifying the cause can hide the duplicate rather than prevent it. A client-only debounce, for example, may not affect two server jobs. Avoid giving an agent contradictory goals such as “change nothing” and “replace the notification system.” Keep unrelated improvements in another task so completion has an unambiguous meaning.

Technical references: GitHub: getting useful results from coding tasks

Acceptance checks and the evidence to retain

The final brief should remain understandable to another developer without chat history. Keep reproduction inputs, constraints, accepted behavior and verification evidence together with the changed revision.

Specific answers

Common questions