46 lines
1.7 KiB
Markdown
46 lines
1.7 KiB
Markdown
# Agent-issue template
|
||
|
||
Every issue intended for a dev agent should follow this shape. The `dev-task.sh`
|
||
wrapper reads `Model:` to pick the model and ignores the rest of the headings;
|
||
they're for the agent and for any auditor that later reviews the PR.
|
||
|
||
```markdown
|
||
## Goal
|
||
|
||
<One paragraph. State what the agent must produce, not how.>
|
||
|
||
## Done criteria
|
||
|
||
- [ ] <Specific, verifiable check — file exists / endpoint returns X / test passes>
|
||
- [ ] <…>
|
||
|
||
## Hints
|
||
|
||
<Freeform context. Constraints, things to NOT do, references to existing code.>
|
||
|
||
## Model
|
||
|
||
sonnet
|
||
```
|
||
|
||
## Rules of thumb
|
||
|
||
- **Scope tight.** An issue should fit in 30 min of agent time. If it feels
|
||
like a full feature, decompose it into 2–3 smaller issues with `depends_on`.
|
||
- **Done criteria are how the auditor checks the PR.** If a criterion can't
|
||
be verified mechanically (or by reading the diff), it's the wrong shape.
|
||
- **Don't tell the agent how**, tell it what the result must look like. Hints
|
||
are for constraints (e.g. "no new dependencies", "match existing style").
|
||
- **Pick `opus` only when the task involves design tradeoffs.** Routine
|
||
scaffolding, CRUD endpoints, and well-specified refactors are sonnet work.
|
||
- **Avoid taste calls.** "Make the UI look good" is not an agent task; "use
|
||
Tailwind utility classes for spacing" is.
|
||
|
||
## Anti-patterns
|
||
|
||
- ❌ "Refactor the whole repo for clarity" (no criterion — no PR will satisfy this)
|
||
- ❌ "Write a TODO app" (too broad — decompose)
|
||
- ❌ "Improve performance" (no measurable target)
|
||
- ✅ "Add GET /todos endpoint returning 2 hardcoded items as JSON"
|
||
- ✅ "Replace bcrypt with argon2id in auth/password.ts; existing tests must still pass"
|