Give an AI Coding Assistant a Task Spec, Not a Wish

A practical approach

Step 1

State the goal in one or two sentences from the user's point of view, such as 'learners can reset their password by email'.

Step 2

Point to the relevant files and an existing example of the pattern to follow, such as an existing route or component.

Step 3

List constraints: libraries to use or avoid, security rules, performance limits and files that must not be modified.

Step 4

Define done as observable checks: the tests that must pass, the behaviour to demonstrate and any documentation to update.

Step 5

Ask for a plan first on non-trivial work, review it, then let the assistant implement one step at a time.

Worked example

A developer asks an assistant to 'add pagination to the courses API'. The result introduces a new query library, changes the response shape and breaks the mobile client. A second attempt includes a spec: use the existing cursor helper in lib/pagination.ts, keep the current response fields, add nextCursor, limit page size to 50 and add tests for the first page, last page and an invalid cursor. The resulting change is small, consistent with the codebase and passes review.

A mistake to avoid

Do not paste secrets, production data or private customer information into a prompt to give the assistant 'context'. Describe the shape of the data or use synthetic examples, and follow your organisation's policy on which tools may see which code.

Try it yourself

Write a task spec for a small feature in your project using the five headings goal, files, constraints, done and plan. Give it to an assistant, and compare the result with what you get from a one-line request for the same feature.

Your implementation checklist

• Every task starts with a user-focused goal
• Relevant files and an example pattern are referenced
• Constraints and off-limits areas are explicit
• Done is defined as checks that can be run
• Sensitive data never goes into prompts