Write each task prompt as a contractor brief

By vibe-coding-notes · 0 stars

We recommend writing each request the way you would brief a new contractor: goal, context, constraints, definition of done, out of scope, and the output you want back.

### Arguments

1. Missing context gets filled with guesses. An agent that isn't told which file, which error or what must not change will pick something plausible.
2. A stated done condition makes verification possible. "Done when the new test and the full suite pass" gives both of you the same finish line.
3. Exact text beats paraphrase. The pasted error message and the exact command carry the clue a summary drops.
4. One task per prompt keeps the diff reviewable. Bundled requests produce tangled diffs that are hard to accept or revert in parts.

### Risks and counterarguments

- Long briefs for small fixes waste time. One line is fine when the change is obvious and easily reverted.
- Over-specifying can lock in the wrong fix. For bugs, name the likely area but ask the agent to confirm before editing.

### What to do next

- Compare:

| Weak | Strong |
|------|--------|
| "Fix the login bug" | "Users with a `+` in their email get 'invalid credentials' on `/login`. Repro: `tests/test_auth.py::test_plus_email` (add it). Fix in `auth/validate.py`. Do not change the password hashing code. Done when the new test and the full suite pass." |
| "Add dark mode" | "Plan only, no edits: add a dark theme using the existing CSS variables in `styles/tokens.css`. List files you would touch and how the user switches themes. Keep the current light theme as default." |
| "Make it faster" | "`/search` p95 is 2.1 s on the fixture DB. Profile with `scripts/bench.sh`, report the top hotspots with evidence, then propose fixes. Do not change the public API." |

- Point to a local example to imitate, say what not to do ("do not mock the database"), and ask for questions first when the task is ambiguous.
- Save the prompts you reuse as files (custom commands or skills). Starting points:

~~~
Bug: <what happens> vs <what should happen>.
Repro: <steps or failing command>. Error: <paste exact text>.
Likely area: <files/functions>, but confirm before editing.
Constraints: minimal change; no new dependencies; do not touch <X>.
Process: 1) reproduce with a failing test, 2) fix, 3) run <test cmd> and <typecheck cmd>.
Return: root cause in 2-3 sentences, the diff summary, and command output.
~~~

~~~
Goal: <user-visible outcome> so that <reason>.
Context: read <files> first; follow the pattern used in <similar feature>.
Requirements:
- <requirement>
Out of scope: <things not to build now>.
Step 1: propose a plan (files, approach, tests, risks). Wait for my approval.
Step 2: implement in small commits on branch <name>.
Done when: <commands> pass and <manual check> works.
~~~

~~~
Question: <what you need to know>.
Read-only: do not modify any files.
Look at: <paths, logs, commands you may run>.
Return: findings with file:line references, confidence level, and open questions.
~~~