You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
104 lines
3.7 KiB
104 lines
3.7 KiB
2 months ago
|
# Prompt templates
|
||
|
|
|
||
|
|
The prompt passed via `-Prompt` is what the coding agent sees on every iteration. It is the single
|
||
|
|
biggest lever on overnight quality. Fill the placeholders; do not send a bare one-liner.
|
||
|
|
|
||
|
|
## Worker prompt (new run)
|
||
|
|
|
||
|
|
```text
|
||
|
|
Objective: <one concrete outcome>.
|
||
|
|
|
||
|
|
Work in this repository. Treat this as a long-running unattended task — nobody is watching, so
|
||
|
|
never wait for confirmation and never leave the tree in a broken state between commits.
|
||
|
|
|
||
|
|
Before changing anything, read the relevant code, docs, and recent commits to understand current
|
||
|
|
behavior. Preserve existing user work. Do not refactor anything outside <scope>.
|
||
|
|
|
||
|
|
Non-goals: <what must not change — files, APIs, behavior, dependencies>.
|
||
|
|
|
||
|
|
After each meaningful slice, run: <verification command>. If it fails, fix it before moving on.
|
||
|
|
|
||
|
|
If you hit a genuine blocker, stop and write the blocker plus the evidence into your notes. Never
|
||
|
|
fabricate success, never disable or skip a test to make something pass, and never commit a change
|
||
|
|
you have not verified.
|
||
|
|
|
||
|
|
Stop only when: <observable completion condition>.
|
||
|
|
```
|
||
|
|
|
||
|
|
### Writing the scope and non-goals
|
||
|
|
|
||
|
|
Vague scope is the main cause of a morning spent reading an unwanted refactor. Be concrete:
|
||
|
|
|
||
|
|
- Good scope: "only files under `src/utils/`"
|
||
|
|
- Good non-goal: "do not change any public export signature; do not add dependencies"
|
||
|
|
- Bad: "don't break anything"
|
||
|
|
|
||
|
|
### Writing the stop condition
|
||
|
|
|
||
|
|
It must be checkable by looking at the repo, not by asking an opinion.
|
||
|
|
|
||
|
|
| Bad | Good |
|
||
|
|
|---|---|
|
||
|
|
| the code is cleaner | `npm test` exits 0 and no file outside `src/utils/` is modified |
|
||
|
|
| tests look fine | the full suite passes with zero skipped tests |
|
||
|
|
| done with the refactor | `npm run typecheck` and `npm test` both exit 0, and `git diff --stat` shows no change to `package.json` |
|
||
|
|
|
||
|
|
## Steering prompt (continue after a partial success)
|
||
|
|
|
||
|
|
```text
|
||
|
|
Continue from the current repository state. A previous run partially succeeded: <specific evidence
|
||
|
|
— commits, files, what now works>.
|
||
|
|
|
||
|
|
Do not redo that completed work and do not revisit <areas already settled>.
|
||
|
|
|
||
|
|
Focus only on: <single bounded correction>.
|
||
|
|
|
||
|
|
The specific problem to fix is: <observed issue, with file and line where known>.
|
||
|
|
|
||
|
|
Verify with: <commands or checks>.
|
||
|
|
|
||
|
|
Stop only when: <observable condition for this correction alone>.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Findings prompt (user rejected the result)
|
||
|
|
|
||
|
|
One finding per run. Bundling corrections is how scope drift restarts.
|
||
|
|
|
||
|
|
```text
|
||
|
|
Continue from the current repository state on this branch.
|
||
|
|
|
||
|
|
A review found this blocking issue: <finding, in the user's own words, with severity and file/line
|
||
|
|
scope preserved>.
|
||
|
|
|
||
|
|
Keep all other completed work intact — do not revert or rewrite anything unrelated to this finding.
|
||
|
|
|
||
|
|
Fix only that issue. Verify with: <commands>.
|
||
|
|
|
||
|
|
Stop only when: <the finding is demonstrably no longer true>.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Research-first prompt (exploratory work)
|
||
|
|
|
||
|
|
Use when the objective is not yet well understood. Forces investigation before edits.
|
||
|
|
|
||
|
|
```text
|
||
|
|
Objective: <outcome>.
|
||
|
|
|
||
|
|
First deliverable, before any code change: investigate <question> and write your findings into your
|
||
|
|
notes — what you examined, what you concluded, and which approach you chose with the reason.
|
||
|
|
|
||
|
|
Only after recording that, implement the chosen approach in <scope>.
|
||
|
|
|
||
|
|
Verify with: <command>. Non-goals: <...>.
|
||
|
|
|
||
|
|
Stop only when: <observable condition>.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Anti-patterns
|
||
|
|
|
||
|
|
- **No verification command.** The agent grades its own homework and always passes.
|
||
|
|
- **Unbounded scope.** "Improve the codebase" produces a diff nobody wants to review.
|
||
|
|
- **Opinion stop conditions.** The run either never stops or stops arbitrarily.
|
||
|
|
- **Multiple objectives in one prompt.** Split them into separate runs, or use `-Worktree`.
|
||
|
|
- **Omitting non-goals.** Agents reformat, upgrade dependencies, and rename things when unconstrained.
|