Coding Assistants: How to Scope a Task Well

A freelance developer asks his coding assistant: "Add a CSV export of invoices." Twenty minutes later, the tool has touched eleven files, added a library, reformatted two unrelated modules, and written an export that forgets credit notes. Nothing is visibly broken, and yet everything has to be reread.

Today's coding assistants no longer just complete a line. They read the project, edit several files, and run commands and tests. The more the tool acts on its own, the more your request needs to look like a brief you'd give to a contractor you won't see again until delivery.

What a task brief contains

Five elements are enough in most cases.

1. The goal, stated as an outcome: what the user or the system will be able to do afterward.
2. The scope: the files or folders involved, and what must not be touched.
3. The constraints: required technologies, conventions, forbidden dependencies.
4. The success criterion: how you'll know it's done, preferably a command or a test.
5. The way of working: propose a plan before changing anything, or move in small steps.

Here is the developer's brief, cleaned up:

Goal: add a CSV export of the invoices for a given month, accessible from the Billing page.

Scope: you may modify the billing/ module and the Billing page. Do not touch other modules or the project configuration.

Constraints: no new dependency, use the csv module from the standard library. Same style as the existing exports (see export_customers).

Business rules: the export contains the month's invoices and credit notes. Credit notes are negative. Amounts are stored in cents in the database and written in euros with two decimals in the file.

Success criterion: the existing tests pass, and you add a test that checks a month containing one invoice and one credit note.

Before changing anything, describe your plan in five lines maximum and wait for my approval.

The last sentence pays off the most. A wrong plan is fixed in ten seconds; wrong code is fixed in ten minutes.

What the tool can't guess

Business rules aren't written anywhere in the code, or only indirectly. The fact that credit notes go into the export, that amounts are in cents, that the page is called Billing: the assistant can recover some of this by reading the project, but it's faster for you to write it down. It's better to state one obvious thing too many than to end up with an export that is wrong but plausible.

Everything you repeat from one task to the next (conventions, test commands, folders to avoid) can go in an instructions file that the tool reads automatically. The file's name and location depend on the assistant you use. The article on instructions for AI agents explains how to write it without turning it into a novel.

One change at a time

The temptation, when the tool is fast, is to stack requests: the export, then a filter, then a page redesign, all in the same session. Each addition makes the result harder to review. Get into the habit of breaking things down, as with a prompt chain:

• one task, one goal, one verifiable result;
• a backup of your work (a commit) before each task, so you can roll back;
• a fresh session when the subject changes, because the conversation gets heavier and the tool ends up losing details from the beginning.

If the task is too big for a one-page brief, ask for a breakdown first:

I want to migrate the application's authentication to [NEW METHOD]. Don't modify anything for now. Go through the project, list the files involved, and propose a breakdown into independent steps, each testable on its own. For each step, state the main risk.

You then pick the step to launch and write its brief.

Reviewing the result

The work doesn't end when the tool says "done." Four checks, in this order.

The diff first. Look at the list of modified files before opening a single one. If it contains files outside the scope, ask why, or undo.

The tests next, run by you if possible. An assistant can claim the tests pass without having run them properly, or edit a test to make it pass. Check that the existing tests haven't been changed without reason.

The edge cases. Take the business rules from your brief and test them by hand: the month with no invoices, the credit note larger than the invoice, the zero value.

The quiet additions. A new dependency, a configuration file, the deletion of a piece of code it judged useless: ask the tool to list them if it hasn't.

Summarize what you changed, file by file, one line each. State what you deleted, added as a dependency, or changed outside the requested scope. Then list the edge cases you did not test.

This summary doesn't replace your review of the diff, because the tool may forget to mention a change. It simply tells you where to look.

When it doesn't work

If the assistant goes in circles, fix the cause rather than repeating the request. Often it's missing context or a contradictory instruction in the brief. Start over in a fresh session with a corrected brief, rather than adding "no, not like that" twenty times. For review, debugging, or test-generation tasks outside this framework, the article on prompts for developers gives other templates, and the one on GitHub Copilot details working in the editor.

And keep control over what the tool can do: run commands, delete files, access the network. Read what your assistant asks you to authorize before accepting, and avoid giving it access to keys or production databases for a task that doesn't need them.

Before your next task

Take a task you're going to hand to the assistant this week. Write the five lines of the brief, including the command that will prove it's done. If you can't write that command, the task isn't clear enough yet, and now is the time to find out.